 |
Entity Generator 4.2.0
Composable, deterministic entity generation for C++23
|
|
Entity Generator 4.2.0
Composable, deterministic entity generation for C++23
|
This guide covers every feature of the entity-generator library in detail. For a quick overview, see the README. For the full API reference, run doxygen Doxyfile from the repository root and open doc/api/html/index.html.
default_to_string() handles std::wstring, std::string (read as UTF-8), bool, float, double, and the integer types int, long, long long and their unsigned forms. All other types return [?] — override to_string() for custom types. The default JSON conversion handles the same types; an unsigned value above the largest std::int64_t is written as a string so it stays exact.
Every generation method accepts a const dasmig::entity_request& first, with an optional explicit std::uint64_t seed second. Pass {} for default generation. Seeded overloads are const and do not advance the instance's internal entropy-seeded engine. Reuse or copy a request to apply the same choices to single, group, synchronous-batch, and concurrent-batch generation.
| Request field | Default | Behavior |
|---|---|---|
component_keys | std::nullopt | All registered components; an explicitly supplied empty std::vector<std::wstring>{} selects none. Unknown keys are skipped, duplicates do not duplicate components, and registration order is preserved. |
group | std::nullopt | Select a registered group instead of component_keys; supported by all generation methods and required by generate_group. Setting both selectors throws std::invalid_argument; an unknown group throws std::out_of_range. |
count | 1 | Number of entities for batch methods; 0 returns an empty vector. Single-entity methods ignore it. |
validator | Empty callable | Accept all entities after component validation. Supply a callback to validate each entity and retry on rejection. |
The request owns its keys and group name. Registration, named-group definitions, component weights, observers, and retry policy remain instance-level setup. The entity generator loads no resources of its own; any resource loading inside user components remains their setup, not a request field. A request never changes the instance's selection or validator for subsequent calls.
Behavior notes:
add() with a key that already exists replaces the component in place, preserving registration order. Any existing weight override for that key persists.remove() on a non-existent key is a no-op (does not throw).remove_group() on a non-existent group is a no-op.Components receive a generation_context that provides access to values generated by earlier components. Registration order determines generation order, unless a component declares what it reads with depends_on() (below).
The context also exposes ctx.has(key) to check whether a dependency was generated (useful when generating with a subset of components). ctx.try_get<T>(key) returns an empty optional and ctx.get_or<T>(key, fallback) the fallback when it was not; ctx.get<T>(key) throws std::out_of_range with a message that names the key.
Override depends_on() (or call .depends_on({...}) on a field) to say which components a component reads:
job (by component_keys or by group) also generates age, transitively, and the entity contains both.should_generate()), the dependent is skipped too, and observers get on_skip for it.std::invalid_argument and a cycle std::logic_error when generating; both messages name the keys.A request can carry values the components need for this call only (a country, a reference date, a forced sex), so no global is needed and generate(request, seed) stays a function of its arguments:
bool, std::int64_t, double or std::string, read with the type it was given with. ctx.input<T>(name) throws std::invalid_argument naming the input when it is missing or has another type; ctx.input_or<T>(name, fallback) and ctx.has_input(name) tolerate a missing one.std::string{"PT"}. A bare literal also works with C++23 compilers, but it is easy to get a bool.entity.signature().data, so two entities from the same seed but different inputs have different signatures. They never change the draws.Components can wrap name-generator and nickname-generator to bring in name and nickname generation:
Components can produce any type. Override to_string() on your component to enable stream output, and to_json() to write something richer than that string in entity::to_json() (see Entity Serialization):
Every generated entity and component stores the random seed that produced it. This enables replay, debugging, and logging. Results are identical on every compiler, standard library and CPU (dasmig-core), so a seed logged on one machine replays on another.
Component seeds can be used to replay individual component generation:
The seed hierarchy is fully deterministic:
Because each component's stream is split from the entity seed by its key, adding, removing or reordering components does not change the values of the others.
entity.signature().data is 0 for an entity of plain components. It becomes a hash of the request's inputs and of component::data_hash() of every component that ran (a component that calls a generator with data returns that generator's data_hash(); field().data_hash(h) sets it). A component that was skipped does not count. Two runs with the same seed and request give the same data only if the inputs and the data behind the components are the same, which is what the seed-replay rule of every dasmig library asks for.
Generate multiple entities in a single call:
Define named groups of component keys for convenient selective generation:
The eg class supports independent instances. Create one per thread for lock-free concurrent generation:
eg is move-constructible and move-assignable, so instances can be transferred between scopes. The instance() singleton is still available for single-threaded convenience.
A component that only draws from data can be written as data. A recipe is a tab-separated file with one component per row; add_recipe(path) or add_recipe_from_string(text) registers them, and they behave like components made with field(): dependencies, ordering, weights, replay and JSON are the same.
| Column | Meaning | |
|---|---|---|
key | required | The component key; dots make a path in the JSON |
kind | required | constant, choice, weighted, int or real |
values | required | What the kind draws from |
label | optional | Display name; the key by default |
depends_on | optional | Keys this component follows, separated by ; |
weight | optional | Inclusion probability, 0 to 1; 1 by default |
| Kind | values | Value |
|---|---|---|
constant | any text | std::wstring |
choice | a\|b\|c, uniform | std::wstring |
weighted | a:3\|b:1, a value and its relative weight (split at the last colon) | std::wstring |
int | lo..hi, both included | std::int64_t |
real | lo..hi, hi excluded | double |
Items are not trimmed. A row with an unknown kind, a bad range or weight, an empty value or a repeated key throws core::tsv_error naming the file, line and column, and nothing from the recipe is added; so does a key whose path clashes with an existing key (std::invalid_argument). A recipe component with the key of an existing one replaces it, so a recipe can override a default that code registered. Code fields can list recipe keys in depends_on, and recipe rows can list code keys.
The text of each row (key, kind and values) is the component's data hash, so changing a recipe changes the replay signature of every entity that used it. Recipes cover the components that draw from a list or a range. A component that reads another's value, calls a generator or computes something stays in code.
Components can declare an inclusion weight via the weight() virtual method (default 1.0). Values range from 0.0 (never included) to 1.0 (always included). The generator rolls against the weight during generation; components that fail the roll are skipped.
Weights can also be overridden at registration time or updated later, taking precedence over the component's own weight() method:
Note: When a weighted component is skipped, dependent components that call ctx.get<T>() for it will throw. Use ctx.has() to guard dependency access in weight-sensitive components.
Convert an entity to a formatted string with to_string(). Each component is rendered as "label: display" separated by two spaces; the label is component::label(), which defaults to the key. The output matches operator<<.
to_json() writes the entity as JSON (UTF-8), the form the WebAssembly layer and the game consume. Values keep their types: integers and numbers stay numbers, bool a boolean, strings strings; other types use the component's to_json() override, or its to_string().
Components appear in generation order. The signature is the replay seed in the format every dasmig library uses; data is 0 unless the request has inputs or a component reports a data_hash() (see Seed Signatures). Seeds are strings because JavaScript numbers cannot hold every 64-bit value. to_json(writer) writes into an existing dasmig::core::json_writer, for composing larger documents.
A key with dots is a path. identity.name and identity.age are written as members of one identity object, placed where its first member comes, and entity.get<T>(L"identity.age") still uses the full key:
add() throws std::invalid_argument for a key with an empty segment (a..b, .a, a.), or one that would be both a value and the parent of another (a with a.b).
dasmig::json_value holds null, a boolean, an integer, a number, a string, an array or an object. A component returns one from to_json() (or field().json(fn)) to write a richer value than its type's default:
Objects keep their members in the order given: dasmig::json_value::object{ {"city", "Lisbon"}, {"lat", 38.7} }. A non-finite number is written as null.
to_map() returns component values as a std::map<std::wstring, std::wstring> mapping keys to their display strings. This is convenient for integration with JSON, XML, or any key–value serialization format.
Custom types work seamlessly — the map uses each component's to_string() output:
generate_batch_async(request) generates entities in parallel using std::async. Entity i uses the i-th value of rng{seed}.split("batch") as its call seed, exactly as generate_batch(request) does, so the two give the same entities for the same request and seed. Each entity is generated in its own async task; results are returned in order.
Entity-level validation applies to each concurrent task independently. Observers, components, the validator callable and any captured state must be safe for concurrent invocation. Do not mutate instance setup or the request while generation is running. On WebAssembly without threads, tasks run sequentially with identical results.
Validation operates at two levels, both opt-in with zero-cost defaults.
Component-level: Override validate() on your component. If it returns false, the generator re-rolls with a new seed up to max_retries times, then throws std::runtime_error.
Entity-level: Supply a callback in the request. If it returns false, the entire entity is re-generated up to max_retries additional times. It applies only to calls using that request.
Configure the retry limit (default 10) for both levels:
Attach one or more generation_observer instances to any generator to receive lifecycle callbacks. Override only the hooks you need; all default to no-ops.
Multiple observers fire in registration order. The same observer can be added more than once.
Thread safety: Observers are not thread-safe by default. When using generate_batch_async, the caller is responsible for ensuring observer implementations are safe for concurrent invocation (e.g., using atomics or mutexes).
The full set of hooks (6 before/after pairs + 3 single-fire hooks, 15 methods):
| Event | Hook(s) |
|---|---|
| Entity generation | on_before_generate() / on_after_generate(entity) |
| Component generation | on_before_component(key) / on_after_component(key, value) |
| Component skip | on_skip(key) |
| Component retry | on_before_retry(key, attempt) / on_after_retry(key, attempt, value) |
| Component fail | on_component_fail(key) |
| Entity retry | on_before_entity_retry(attempt) / on_after_entity_retry(attempt) |
| Entity fail | on_entity_fail() |
| Registration | on_before_add(key) / on_after_add(key) |
| Removal | on_before_remove(key) / on_after_remove(key) |
For per-component filtering, check the key parameter inside your hook override.
Components can override should_generate(ctx) to conditionally skip generation based on the current context. Unlike weights (probabilistic), this is logic-driven. The default returns true.
When should_generate returns false, the component is skipped entirely — no value is produced and entity.has(key) returns false. The skip fires the same observer hooks as a weight skip (on_before_skip / on_after_skip).
Note: should_generate is checked after the weight roll. If a component is excluded by weight, should_generate is never called.
Five reusable class templates for the most common component patterns. All live in the dasmig:: namespace and accept an optional custom formatter as a trailing template parameter.
Always returns the same value.
Picks uniformly at random from a list.
Uniform random in a numeric range: [lo, hi] for integer types, [lo, hi) for floating-point types (bool is not allowed).
Wraps a callable that takes generation_context& and returns a value. Avoids subclassing for one-off or context-dependent components. Use std::function to erase the callable type for make_unique.
A CTAD deduction guide is provided for stack-allocated usage where make_unique is not needed.
field builds a component from a callable and sets the optional hooks with chained calls, so a field is one expression and needs no class. T is what the callable returns:
| Call | Sets | Default |
|---|---|---|
.label(text) | component::label() | the key |
.depends_on(keys) | component::depends_on() | none |
.format(fn) | to_string() | the standard conversion |
.json(fn) | to_json() | the standard conversion |
.validate(fn) | validate() | accept |
.when(fn) | should_generate() | always |
.weight(w) | weight() | 1.0 |
.data_hash(h) | data_hash() | 0 |
The setters work on a temporary, so chain them in one expression, and eg::add(field...) takes the result directly.
Picks from a list of values using per-option weights. Weights are relative (they don't need to sum to 1.0). A weight of 0 means the option is never selected; negative or non-finite weights are rejected. The weighted choice is dasmig-core's, built once when the component is constructed.
All generic components use default_to_string by default. Pass a custom formatter as an extra template parameter and constructor argument for types it doesn't handle:
Optional headers in dasmig/ext/ provide ready-made functionality built on the observer interface.
#include <dasmig/ext/stats_observer.hpp>
Tracks comprehensive generation statistics: counts, timing, per-component breakdowns, and value distributions. Attach it like any other observer; read the fields after generation.
Entity counters:
| Field | Description |
|---|---|
entities_generated | Successful entities produced |
entity_retries | Entity-level validation retries |
entity_failures | Entity validation exhausted (threw) |
Component counters:
| Field | Description |
|---|---|
components_generated | Total component values produced |
components_skipped | Weight or conditional skips |
component_failures | Component validation exhausted (threw) |
Per-component-key maps (all std::map<std::wstring, …>):
| Field | Value type | Description |
|---|---|---|
component_counts | size_t | Times each key was generated |
component_skip_counts | size_t | Times each key was skipped |
component_failure_counts | size_t | Times each key failed |
component_retries | size_t | Total retries per key |
component_times | duration | Cumulative wall-clock per key |
component_min_times | duration | Fastest generation per key |
component_max_times | duration | Slowest generation per key |
Entity timing:
| Field | Description |
|---|---|
total_generation_time | Sum of wall-clock across all entities |
min_entity_time | Fastest entity generation |
max_entity_time | Slowest entity generation |
Components-per-entity:
| Field | Description |
|---|---|
min_components_per_entity | Fewest components in a single entity |
max_components_per_entity | Most components in a single entity |
total_components_in_entities | Sum for computing averages |
Value distribution:
value_distribution is a map<wstring, map<wstring, size_t>> — for each component key, counts how many times each display value appeared. Common std::any types (wstring, int, double, float, long, bool) are stringified automatically; others record as <other>.
Computed helpers:
| Method | Returns |
|---|---|
avg_entity_time() | total_generation_time / entities_generated |
avg_component_time(key) | per-key average generation time |
avg_components_per_entity() | double average |
component_retry_rate() | total retries / components generated |
entity_retry_rate() | entity retries / entities generated |
dasmig/ext/entt_adapter.hpp bridges entity-generator with EnTT. It maps generator component keys to typed EnTT components via user-defined callables.
Requires: EnTT header (<entt/entt.hpp>) available on the include path.
Direct mapping (no transform, when generator value type == ECS type):
Spawn into existing entity:
Skipped components (weight = 0, conditional = false) are silently ignored — no EnTT component is emplaced for that key.
dasmig/ext/flecs_adapter.hpp bridges entity-generator with Flecs. Same mapping pattern as the EnTT adapter.
Requires: Flecs header (<flecs.h>) and compiled flecs.c linked.
API summary (identical for both adapters):
| Method | Description |
|---|---|
map<T>(key, fn) | Register a key→component mapping with transform |
map<T>(key) | Direct mapping (value type must match T) |
spawn(entity) | Create ECS entity with mapped components |
spawn_into(target, entity) | Apply mapped components to existing entity |
spawn_batch(vector) | Spawn multiple entities at once |
clear_mappings() | Remove all registered mappings |
ctx.random() is a dasmig::core::rng seeded for this component. Draw from it with the dasmig-core functions, which give the same results on every platform (the std:: distributions do not):
| Need | Call |
|---|---|
| Integer in [lo, hi] | dasmig::core::uniform_int(ctx.random(), lo, hi) |
| Real in [lo, hi) | dasmig::core::uniform_real(ctx.random(), lo, hi) |
| Element of a container | dasmig::core::pick(ctx.random(), values) (a reference into it) |
| True with probability p | dasmig::core::bernoulli(ctx.random(), p) |
| Index by weights | dasmig::core::discrete{weights}(ctx.random()) (build once, reuse) |
| Normal, log-normal | dasmig::core::normal(ctx.random(), mean, sd), lognormal(...) |
| Shuffle, sample | dasmig::core::shuffle(ctx.random(), range), sample_indices(...) |
The algorithms are specified in dasmig-core's usage guide.
Generation now has two forms for each established method: (request) and (request, seed). The old positional overloads are removed, not retained as compatibility wrappers.
| Previous call | Request-first call |
|---|---|
gen.generate() | gen.generate({}) |
gen.generate(seed) | gen.generate({}, seed) |
gen.generate({L"a", L"b"}, seed) | gen.generate({.component_keys = std::vector<std::wstring>{L"a", L"b"}}, seed) |
gen.generate_batch(n, seed) | gen.generate_batch({.count = n}, seed) |
gen.generate_batch_async(n, seed) | gen.generate_batch_async({.count = n}, seed) |
gen.generate_group(L"identity", seed) | gen.generate_group({.group = L"identity"}, seed) |
gen.set_validator(fn) followed by generation | gen.generate({.validator = fn}) |
seed, unseed, set_validator, and clear_validator no longer exist on eg. Use a caller-owned dasmig::core::rng for a deterministic sequence of call seeds, as shown under Registering and Generating, or a seeded batch. Keep max_retries, observers, registration, group definitions, and weights on the instance.
Seeded outputs, component behavior, and batch seed derivation are unchanged from the previous dasmig-core-based API when the request expresses the same choices. Replay an entity with gen.generate(request, entity.seed()), preserving the selection, validator, and instance setup. A seed signature records the seed, not the request or the registered components.
Version 4 makes the library usable as the base of a composition such as a persona generator. Draws are unchanged: a v3 component gives the same value for the same seed, and entities built from v3 components give the same JSON, so existing known answers still hold.
json_value is a class.** It was a std::variant of scalars; it now also holds arrays and objects, with implicit conversions from the usual types. Code that returned std::int64_t{n}, double, bool, nullptr or a string from to_json() compiles as it was. Code that used the variant directly (std::get, std::visit) must use json_value::write(), get_array() and get_object() instead.add(). A key with an empty path segment, or one that is also the parent of another key, throws std::invalid_argument. Keys with dots now mean a path in the JSON.entity::to_string() shows labels.** A component's label() defaults to its key, so nothing changes until you override it.generation_context::get message.** A missing key still throws std::out_of_range; the message now names it.entity_request::inputs with generation_context::input(), input_or() and has_input(); component::depends_on(); component::label(); component::data_hash(); field() and field_component<T>; generation_context::try_get() and get_or(); nested JSON from dotted keys; entity::signature().data.Version 2 moves the library onto dasmig-core.
ctx.random() returns dasmig::core::rng&** instead of effolkronium's random_local&. Replace ctx.random().get(lo, hi) with dasmig::core::uniform_int(ctx.random(), lo, hi) (or uniform_real for floating point), and *ctx.random().get(values) with dasmig::core::pick(ctx.random(), values) (see Random Numbers in Components).std::mt19937 and cut seeds to 32 bits, so seeds differing only in their high bits gave the same entity.entity::seed() is the call seed** (or the accepted attempt's), so generate(request, e.seed()) replays the entity; in v1 it was a value drawn from the call seed, which could not be passed back.generate_batch(request, seed) and generate_batch_async(request, seed) give the same entities, and each entity replays alone from its seed. Entity-validation retries no longer consume the batch's seeds.range_component<T>** requires an integer (not bool) or floating-point T; a float range stays below hi. **weighted_choice_component** builds its weighted choice once and rejects negative or non-finite weights.random.hpp with core.hpp and the core/ directory, kept next to entitygen.hpp.entity::to_json(), entity::signature(), component::to_json() (and dasmig::json_value).generate_batch takes the same core::batch_options as every other library, next to the older request.count form, which keeps working until the next major version.
i is exactly generate(request, core::item_seed(batch_seed, first + i)). A range can be generated directly (first = 1000), two batches that follow each other equal one, and the output is the same for any threads (0 means the hardware count). generate_batch_async gives the same entities.generate_batch(request, seed) and generate_batch_async(request, seed) now use core::item_seed too, so their entities differ from 4.0.x for the same seed. Each entity still replays with generate(request, e.seed())..unique = core::unique_rule::by<dasmig::entity>(key) regenerates an entity whose key already appeared in the batch.core::jsonl_writer writes one to_json() per line and core::csv_writer flattens each entity's JSON into dotted columns.The library throws standard exceptions. No custom exception types are used.
| Exception | Thrown by | Condition |
|---|---|---|
std::out_of_range | entity::get<T>(key), entity::get_any(key) | Key not present in the entity |
std::out_of_range | entity::seed(key) | Component key not found |
std::out_of_range | eg::weight(key, value) | Component not registered |
std::out_of_range | Any generation method with request.group | Group not found |
std::invalid_argument | Any generation method | Both request.group and request.component_keys are set |
std::invalid_argument | eg::generate_group(request) | No group specified |
std::runtime_error | Any generation method | Component validation exhausted after max_retries |
std::runtime_error | Any generation method | Entity validation exhausted after max_retries |
std::invalid_argument | choice_component constructor | Empty choices vector |
std::invalid_argument | weighted_choice_component constructor | Empty options vector or all weights are zero |
std::bad_any_cast | entity::get<T>(key), generation_context::get<T>(key) | Type mismatch on the stored value |
std::out_of_range | generation_context::get<T>(key) | No value was generated for the key (the message names it) |
std::invalid_argument | generation_context::input<T>(name) | The request has no such input, or it has another type |
std::invalid_argument | eg::add | A key with an empty path segment, or that collides with another key as a parent |
std::invalid_argument | Any generation method | A selected component depends on a key that is not registered |
std::logic_error | Any generation method | The selected components depend on each other in a cycle |
1.9.8