The entity generator — produces entities with configurable components. More...

#include <entitygen.hpp>

Public Member Functions
	eg ()=default
	Default constructor creates an empty generator.

	eg (const eg &)=delete
	Not copyable.

eg &	operator= (const eg &)=delete
	Not copyable.

	eg (eg &&) noexcept=default
	Move constructor.

eg &	operator= (eg &&) noexcept=default
	Move assignment.

	~eg ()=default
	Default destructor.

Registration
eg &	add (std::unique_ptr< component > comp)
	Register a component.

template<typename T >
eg &	add (field_component< T > f)
	Register a field built with field().

eg &	add_recipe (const std::filesystem::path &path)
	Register the components a recipe declares.

eg &	add_recipe_from_string (std::string_view text, std::string source="recipe")
	Register the components a recipe in text declares.

eg &	add (std::unique_ptr< component > comp, double weight_override)
	Register a component with a weight override.

eg &	weight (const std::wstring &component_key, double weight_value)
	Set or update the weight override for a registered component.

eg &	remove (const std::wstring &component_key)
	Remove a registered component by key.

bool	has (const std::wstring &component_key) const
	Check if a component is registered by key.

eg &	clear ()
	Remove all registered components, weight overrides, and groups.

std::size_t	size () const
	Return the number of registered components.

std::vector< std::wstring >	component_keys () const
	Return all registered component keys in registration order.

Validation
eg &	max_retries (std::size_t retries)
	Set the maximum number of retries for validation (default 10).

Observers
eg &	add_observer (std::shared_ptr< generation_observer > obs)
	Add an observer to receive generation lifecycle callbacks.

eg &	remove_observer (const std::shared_ptr< generation_observer > &obs)
	Remove a specific observer by identity.

eg &	clear_observers ()
	Remove all observers.

Generation
entity	generate (const entity_request &request)
	Generate an entity using per-call options.

entity	generate (const entity_request &request, std::uint64_t call_seed) const
	Generate an entity using a request and a seed.

Batch Generation
std::vector< entity >	generate_batch (const entity_request &request)
	Generate request.count entities using per-call options.

std::vector< entity >	generate_batch (const entity_request &request, std::uint64_t call_seed) const
	Generate multiple entities using a seed.

std::vector< entity >	generate_batch (const entity_request &request, const core::batch_options &options)
	Generate a batch described by core::batch_options, from a seed drawn from the generator's engine.

std::vector< entity >	generate_batch (const entity_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch described by core::batch_options, deterministically.

template<typename Sink >
void	for_each_entity (const entity_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of entities to a sink without holding the batch.

template<typename Sink >
void	for_each_entity (const entity_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of entities with a batch seed drawn from the generator's engine.

Concurrent Batch Generation
std::vector< entity >	generate_batch_async (const entity_request &request)
	Generate multiple entities concurrently.

std::vector< entity >	generate_batch_async (const entity_request &request, std::uint64_t call_seed) const
	Generate multiple entities concurrently using a seed.

Component Groups
eg &	add_group (const std::wstring &group_name, std::vector< std::wstring > component_keys)
	Register a named group of component keys.

eg &	remove_group (const std::wstring &group_name)
	Remove a named group.

bool	has_group (const std::wstring &group_name) const
	Check if a named group exists.

entity	generate_group (const entity_request &request)
	Generate an entity using a named group.

entity	generate_group (const entity_request &request, std::uint64_t call_seed) const
	Generate an entity using a named group with a seed.

Static Public Member Functions
static eg &	instance ()
	Access the global singleton instance.

Detailed Description

The entity generator — produces entities with configurable components.

Components are registered by implementing the component interface and adding them to the generator. Components are generated in registration order, allowing later components to access earlier ones via context.

See also: component, entity, entity_request, generation_context

Definition at line 1253 of file entitygen.hpp.

Member Function Documentation

◆ add() [1/3]

template<typename T >

eg & dasmig::eg::add ( field_component< T > f )

inline

Register a field built with field().

Template Parameters

T	The field's value type.

Parameters

f	The field (moved).

Returns: *this for chaining.

Exceptions

std::invalid_argument As add(std::unique_ptr<component>).

Definition at line 1315 of file entitygen.hpp.

◆ add() [2/3]

eg & dasmig::eg::add ( std::unique_ptr< component > comp )

inline

Register a component.

Takes ownership of the component. If a component with the same key already exists, it will be replaced. Components are generated in the order they are registered.

Parameters

comp	The component to register (moved).

Returns: *this for chaining.

Exceptions

std::invalid_argument If the key has an empty path segment (a..b, .a, a.), or would be both a value and the parent of another key (a with a.b).

Definition at line 1288 of file entitygen.hpp.

◆ add() [3/3]

eg & dasmig::eg::add	(	std::unique_ptr< component >	comp,
		double	weight_override
	)

inline

Register a component with a weight override.

The override takes precedence over the component's own weight() method.

Parameters

comp	The component to register (moved).
weight_override	Inclusion probability override (0.0–1.0).

Returns: *this for chaining.

Definition at line 1377 of file entitygen.hpp.

◆ add_group()

eg & dasmig::eg::add_group	(	const std::wstring &	group_name,
		std::vector< std::wstring >	component_keys
	)

inline

Register a named group of component keys.

Parameters

group_name	Name for the group.
component_keys	Keys in the group.

Returns: *this for chaining.

Definition at line 1691 of file entitygen.hpp.

◆ add_observer()

eg & dasmig::eg::add_observer ( std::shared_ptr< generation_observer > obs )

inline

Add an observer to receive generation lifecycle callbacks.

Parameters

obs	The observer (shared ownership).

Returns: *this for chaining.

See also: generation_observer

Definition at line 1474 of file entitygen.hpp.

◆ add_recipe()

eg & dasmig::eg::add_recipe ( const std::filesystem::path & path )

inline

Register the components a recipe declares.

A recipe is a tab-separated file with a header line and one component per row, so a component that only draws from data is written as data instead of code (see add_recipe_from_string() for the columns). The components are the ones the code makes with field(): the same dependencies, ordering, weights and replay. An invalid row throws and adds nothing.

Parameters

path	The recipe file.

Returns: *this for chaining.

Exceptions

core::tsv_error	If the file cannot be read or a row is invalid.
std::invalid_argument	As add(std::unique_ptr<component>).

Definition at line 1333 of file entitygen.hpp.

◆ add_recipe_from_string()

eg & dasmig::eg::add_recipe_from_string	(	std::string_view	text,
		std::string	source = `"recipe"`
	)

inline

Register the components a recipe in text declares.

Columns (the header names them, in any order):

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, below
`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

The kinds: constant gives values as text; choice picks uniformly from a|b|c; weighted picks from a:3|b:1 (a value and its relative weight, split at the last colon); int draws an integer from lo..hi (both included); real draws a number from lo..hi (hi excluded). Text kinds give strings in the JSON, int and real give numbers. Items are not trimmed. A component with the key of an existing one replaces it. The recipe's rows are part of the entity's replay signature.

Parameters

text	UTF-8 recipe text.
source	Name used in errors.

Returns: *this for chaining.

Exceptions

core::tsv_error	If the text is malformed or a row is invalid (an unknown kind, a bad range or weight, a repeated key).
std::invalid_argument	As add(std::unique_ptr<component>).

Definition at line 1366 of file entitygen.hpp.

◆ clear()

eg & dasmig::eg::clear ( )

inline

Remove all registered components, weight overrides, and groups.

Returns: *this for chaining.

Definition at line 1429 of file entitygen.hpp.

◆ clear_observers()

eg & dasmig::eg::clear_observers ( )

inline

Remove all observers.

Returns: *this for chaining.

Definition at line 1491 of file entitygen.hpp.

◆ component_keys()

std::vector< std::wstring > dasmig::eg::component_keys ( ) const

inline

Return all registered component keys in registration order.

Returns: A vector of component keys.

Definition at line 1442 of file entitygen.hpp.

◆ for_each_entity() [1/2]

template<typename Sink >

void dasmig::eg::for_each_entity	(	const entity_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of entities with a batch seed drawn from the generator's engine.

Template Parameters

Sink	Callable taking `(std::uint64_t, entity&)`.

Parameters

request	Selection and entity validation options.
options	Count, first index, threads and uniqueness.
sink	Receives the entities.

Definition at line 1639 of file entitygen.hpp.

◆ for_each_entity() [2/2]

template<typename Sink >

void dasmig::eg::for_each_entity	(	const entity_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

Stream a batch of entities to a sink without holding the batch.

Generates the same entities as generate_batch(request, options, batch_seed) and calls sink(index, entity&) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking `(std::uint64_t, entity&)`; for example core::jsonl_writer.

Parameters

request	Selection and entity validation options.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the entities.

Definition at line 1623 of file entitygen.hpp.

◆ generate() [1/2]

entity dasmig::eg::generate ( const entity_request & request )

inline

Generate an entity using per-call options.

Draws a call seed from the generator's engine.

Parameters

request Selection and entity validation options.

Returns: The generated entity.

Exceptions

std::runtime_error	If component or entity validation is exhausted.
std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.

Definition at line 1509 of file entitygen.hpp.

◆ generate() [2/2]

entity dasmig::eg::generate	(	const entity_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate an entity using a request and a seed.

The same seed and components give the same entity on every compiler and platform. Each component draws from a stream split from the seed by its key, so adding or removing a component does not change the others.

Parameters

request	Selection and entity validation options.
call_seed	Seed for reproducible results; does not advance the internal engine.

Returns: The generated entity.

Exceptions

std::runtime_error	If validation is exhausted.
std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.

Definition at line 1527 of file entitygen.hpp.

◆ generate_batch() [1/4]

std::vector< entity > dasmig::eg::generate_batch ( const entity_request & request )

inline

Generate request.count entities using per-call options.

Draws one call seed from the generator's engine for the batch.

Parameters

request Selection, batch count and entity validation options.

Returns: A vector of generated entities.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1545 of file entitygen.hpp.

◆ generate_batch() [2/4]

std::vector< entity > dasmig::eg::generate_batch	(	const entity_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch described by core::batch_options, from a seed drawn from the generator's engine.

Uses options.count (the request's count is ignored here; it stays for generate_batch(request) until the next major version).

Parameters

request	Selection and entity validation options.
options	Count, first index, threads and uniqueness.

Returns: The entities, in index order.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1581 of file entitygen.hpp.

◆ generate_batch() [3/4]

std::vector< entity > dasmig::eg::generate_batch	(	const entity_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch described by core::batch_options, deterministically.

Entity i is exactly generate(request, core::item_seed(batch_seed, options.first + i)), for any options.threads. With more than one thread, components, observers and the request's validator (including captured state) must be thread-safe.

Parameters

request	Selection and entity validation options.
options	Count, first index, threads and uniqueness (see core::unique_rule, made for `entity`).
batch_seed	Seed of the whole batch.

Returns: The entities, in index order.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted, or a unique batch runs out of attempts.

Definition at line 1602 of file entitygen.hpp.

◆ generate_batch() [4/4]

std::vector< entity > dasmig::eg::generate_batch	(	const entity_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate multiple entities using a seed.

Entity i uses core::item_seed(call_seed, i) as its call seed, so the result equals generate_batch_async(request, call_seed) and each entity replays with generate(request, e.seed()). Since 4.1.0 this is the same seed derivation as every other library's batch; before, entity i used the i-th value of core::rng{call_seed}.split("batch").

Parameters

request	Selection, batch count and entity validation options.
call_seed	Seed for reproducible results.

Returns: A vector of generated entities.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1564 of file entitygen.hpp.

◆ generate_batch_async() [1/2]

std::vector< entity > dasmig::eg::generate_batch_async ( const entity_request & request )

inline

Generate multiple entities concurrently.

Same entities as generate_batch(request) would give from the same engine state; each entity is generated in its own async task. Results are returned in order. Components, observers and the request's validator (including captured state) must be thread-safe. In a WebAssembly build without threads (Emscripten without -pthread) the tasks run one after another, with the same results.

Parameters

request Selection, batch count and entity validation options.

Returns: A vector of generated entities.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1662 of file entitygen.hpp.

◆ generate_batch_async() [2/2]

std::vector< entity > dasmig::eg::generate_batch_async	(	const entity_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate multiple entities concurrently using a seed.

Gives the same entities as generate_batch(request, call_seed).

Parameters

request	Selection, batch count and entity validation options.
call_seed	Seed for reproducible results.

Returns: A vector of generated entities.

Exceptions

std::invalid_argument	If both selection fields are set.
std::out_of_range	If the requested group does not exist.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1677 of file entitygen.hpp.

◆ generate_group() [1/2]

entity dasmig::eg::generate_group ( const entity_request & request )

inline

Generate an entity using a named group.

Parameters

request Options with a registered group name.

Returns: The generated entity.

Exceptions

std::out_of_range	If the group does not exist.
std::invalid_argument	If the group is absent or component_keys is set.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1721 of file entitygen.hpp.

◆ generate_group() [2/2]

entity dasmig::eg::generate_group	(	const entity_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate an entity using a named group with a seed.

Parameters

request	Options with a registered group name.
call_seed	Seed for reproducible results.

Returns: The generated entity.

Exceptions

std::out_of_range	If the group does not exist.
std::invalid_argument	If the group is absent or component_keys is set.
std::runtime_error	If component or entity validation is exhausted.

Definition at line 1734 of file entitygen.hpp.

◆ has()

bool dasmig::eg::has ( const std::wstring & component_key ) const

inline

Check if a component is registered by key.

Parameters

component_key The component key to look up.

Returns: true if a component with the key exists.

Definition at line 1420 of file entitygen.hpp.

◆ has_group()

bool dasmig::eg::has_group ( const std::wstring & group_name ) const

inline

Check if a named group exists.

Parameters

group_name The group name to look up.

Returns: true if the group exists.

Definition at line 1710 of file entitygen.hpp.

◆ instance()

static eg & dasmig::eg::instance ( )

inlinestatic

Access the global singleton instance.

For multi-threaded use, prefer creating independent eg instances.

Returns: A reference to the singleton.

Definition at line 1269 of file entitygen.hpp.

◆ max_retries()

eg & dasmig::eg::max_retries ( std::size_t retries )

inline

Set the maximum number of retries for validation (default 10).

Applies to both component-level and entity-level validation.

Parameters

retries The maximum retry count.

Returns: *this for chaining.

Definition at line 1460 of file entitygen.hpp.

◆ remove()

eg & dasmig::eg::remove ( const std::wstring & component_key )

inline

Remove a registered component by key.

Parameters

component_key The component key to remove.

Returns: *this for chaining.

Definition at line 1404 of file entitygen.hpp.

◆ remove_group()

eg & dasmig::eg::remove_group ( const std::wstring & group_name )

inline

Remove a named group.

Parameters

group_name The group to remove.

Returns: *this for chaining.

Definition at line 1701 of file entitygen.hpp.

◆ remove_observer()

eg & dasmig::eg::remove_observer ( const std::shared_ptr< generation_observer > & obs )

inline

Remove a specific observer by identity.

Parameters

obs	The observer to remove.

Returns: *this for chaining.

Definition at line 1483 of file entitygen.hpp.

◆ size()

std::size_t dasmig::eg::size ( ) const

inline

Return the number of registered components.

Definition at line 1438 of file entitygen.hpp.

◆ weight()

eg & dasmig::eg::weight	(	const std::wstring &	component_key,
		double	weight_value
	)

inline

Set or update the weight override for a registered component.

Parameters

component_key	The component key.
weight_value	New inclusion probability (0.0–1.0).

Returns: *this for chaining.

Exceptions

std::out_of_range If the component is not registered.

Definition at line 1390 of file entitygen.hpp.

The documentation for this class was generated from the following file:

dasmig/entitygen.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ add_group()

◆ add_observer()

◆ add_recipe()

◆ add_recipe_from_string()

◆ clear()

◆ clear_observers()

◆ component_keys()

◆ for_each_entity() [1/2]

◆ for_each_entity() [2/2]

◆ generate() [1/2]

◆ generate() [2/2]

◆ generate_batch() [1/4]

◆ generate_batch() [2/4]

◆ generate_batch() [3/4]

◆ generate_batch() [4/4]

◆ generate_batch_async() [1/2]

◆ generate_batch_async() [2/2]

◆ generate_group() [1/2]

◆ generate_group() [2/2]

◆ has()

◆ has_group()

◆ instance()

◆ max_retries()

◆ remove()

◆ remove_group()

◆ remove_observer()

◆ size()

◆ weight()