Owns entities, components, archetypes, queries, observers, and systems. More...

#include <world.h>

Classes
struct	EntityBuilder
	Applies structural and value changes to one entity. More...

Public Member Functions
	World (World &&)=delete

	World (const World &)=delete

World &	operator= (World &&)=delete

World &	operator= (const World &)=delete

Query	query ()
	Provides a cached query set up to work with the parent world. Cached queries use local scope by default.

Query	uquery ()
	Provides an uncached query set up to work with the parent world. Uncached queries keep only a local immutable plan and rebuild transient matches on demand.

void	set_sched (const Sched &sched)
	Installs a custom scheduler used by ECS parallel execution paths.

void	reset_sched ()
	Resets the world back to the default Gaia scheduler.

GAIA_NODISCARD const Sched &	sched () const
	Returns the resolved scheduler used by this world.

GAIA_NODISCARD EntityContainer &	fetch (Entity entity)
	Returns the internal record for entity.

GAIA_NODISCARD const EntityContainer &	fetch (Entity entity) const
	Returns the internal record for entity.

GAIA_NODISCARD bool	is_dont_fragment (Entity entity) const
	Returns whether entity is marked DontFragment.

GAIA_NODISCARD bool	relation_is_non_fragmenting (Entity relation) const
	Returns whether relation is non-fragmenting.

GAIA_NODISCARD bool	relation_uses_non_fragmenting_storage (Entity relation) const
	Returns whether relation uses non-fragmenting relation storage. Only exclusive non-fragmenting relations use this storage path.

GAIA_NODISCARD bool	relation_is_hierarchy (Entity relation) const
	Returns true for hierarchy-like relations whose targets form an exclusive traversable parent chain. ChildOf and Parent satisfy this today. DependsOn intentionally does not.

GAIA_NODISCARD bool	relation_is_fragmenting (Entity relation) const
	Returns true when the relation still participates in archetype identity. Non-fragmenting relations such as Parent are excluded.

GAIA_NODISCARD bool	relation_is_fragmenting_hierarchy (Entity relation) const
	Returns true for hierarchy relations that still fragment archetypes. ChildOf satisfies this today, while Parent intentionally does not.

GAIA_NODISCARD bool	relation_supports_depth_order (Entity relation) const
	Returns true when the relation can drive cached depth-ordered iteration. This requires a fragmenting relation whose target participates in archetype identity, such as ChildOf, DependsOn, or a custom fragmenting relation. Cycles are still invalid and are diagnosed by the depth cache itself.

GAIA_NODISCARD bool	relation_depth_order_prunes_disabled_subtrees (Entity relation) const
	Returns true when depth-ordered iteration may safely prune disabled subtrees at archetype level. Only fragmenting hierarchy relations qualify because all rows in the archetype then share the same direct parent and therefore the same ancestor chain.

GAIA_NODISCARD bool	component_uses_sparse_storage (Entity component) const
	Returns whether component stores instance data in sparse storage instead of archetype chunks. This is currently the storage path used for sparse plain generic AoS components.

GAIA_NODISCARD bool	component_is_non_fragmenting (Entity component) const
	Returns whether component is non-fragmenting. Non-fragmenting components do not participate in archetype identity.

GAIA_NODISCARD SparseStorageMode	sparse_storage_mode (Entity component) const
	Returns the sparse storage mode used by a component.

GAIA_NODISCARD bool	copies_sparse_payload_inter (Entity comp, Entity srcEntity, const SparseComponentStoreErased &store) const
	Checks whether an inter-world copy includes a sparse component payload.

GAIA_NODISCARD bool	copies_non_frag_sparse_payload_inter (Entity comp, Entity srcEntity, const SparseComponentStoreErased &store) const
	Checks whether an inter-world copy includes a non-fragmenting sparse payload.

GAIA_NODISCARD bool	sparse_copy_adds_id_inter (Entity comp) const
	Checks whether copying a sparse payload must also add its id to the destination entity.

void	sync_component_record (Entity component, Component comp)
	Updates the cached component metadata in both the component cache and the core Component storage.

void	validate_runtime_semantics (const RuntimeTypeDesc &runtimeType) const
	Validates runtime-reflection state against the live scope graph in debug builds. Verifies that every semantic entity referenced by runtimeType resolves to a reachable scope path. All checks are compiled out when assertions are disabled.

void	finalize_component_registration (const ComponentCacheItem &item, bool addSparseTrait)
	Finalizes a newly registered component entity after the cache record has been created. This synchronizes the core `Component` value stored on the component entity, registers the default symbol through the normal naming path, and optionally latches the `Sparse` trait.

void	set_component_dont_fragment (Entity component, EntityContainer &ec)
	Latches DontFragment on a component entity record. This first moves the payload out of chunks, then removes the id from archetype identity.

void	set_component_sparse_storage (Entity component)
	Latches Sparse storage on a component entity before any instances exist. This moves the payload out of chunks while keeping the id in archetype identity. Only plain generic AoS components are supported.

GAIA_NODISCARD bool	can_add_component_storage_trait (Entity component) const
	Returns whether a runtime storage trait can be attached to component. Compile-time component storage is authoritative. Runtime component descriptors remain mutable.

GAIA_NODISCARD SparseStorageMode	compile_time_sparse_storage_mode (Entity component) const
	Returns the fragmentation mode for a component known at compile time to use sparse storage.

template<typename T >
GAIA_NODISCARD bool	can_use_sparse_component_storage (Entity object) const
	Returns whether object is a usable sparse storage target for component type T.

template<typename T >
GAIA_NODISCARD SparseComponentStore< T > *	sparse_component_store (Entity component)
	Returns the sparse component store for component, or nullptr if it does not exist.

template<typename T >
GAIA_NODISCARD const SparseComponentStore< T > *	sparse_component_store (Entity component) const
	Returns the sparse component store for component, or nullptr if it does not exist.

template<typename T >
GAIA_NODISCARD SparseComponentStore< T > &	sparse_component_store_mut (Entity component)
	Returns the sparse component store for component, creating it if needed.

template<typename T >
GAIA_NODISCARD decltype(auto)	sparse_component_add_value (Entity component, Entity entity)
	Adds or returns a sparse value through the store's erased payload interface.

template<typename T >
GAIA_NODISCARD decltype(auto)	sparse_component_mut_value (Entity component, Entity entity)
	Returns a mutable sparse value through the store's erased payload interface.

template<typename T >
GAIA_NODISCARD decltype(auto)	sparse_component_get_value (Entity component, Entity entity) const
	Returns a read-only sparse value through the store's erased payload interface.

GAIA_NODISCARD const SparseComponentStoreErased *	sparse_component_store_erased (Entity component) const
	Returns the erased sparse store for component, or nullptr when absent.

GAIA_NODISCARD SparseComponentStoreErased &	sparse_component_store_erased_mut (Entity component, const ComponentCacheItem &item)
	Returns the erased sparse store for component, creating runtime-sized storage when absent.

void	finish_sparse_component_add_inter (Entity entity, Entity object, SparseStorageMode mode)
	Finishes adding a sparse component after its payload has been created. Fragmenting components also add the id directly to the entity archetype.

void	del_sparse_components (Entity entity)
	Removes all sparse component instances owned by entity.

void	del_sparse_component_store (Entity component)
	Deletes the sparse component store associated with component.

GAIA_NODISCARD const NonFragmentingRelationStore *	nonfragmenting_relation_store (Entity relation) const
	Returns the non-fragmenting relation store for relation, or nullptr when absent.

GAIA_NODISCARD NonFragmentingRelationStore &	nonfragmenting_relation_store_mut (Entity relation)
	Returns the non-fragmenting relation store for relation, creating it if needed.

void	nonfragmenting_relation_set (NonFragmentingRelationStore &store, Entity source, Entity relation, Entity target)
	Sets an exclusive non-fragmenting relation target in an existing store.

void	nonfragmenting_relation_set (Entity source, Entity relation, Entity target)
	Sets an exclusive non-fragmenting relation target, creating its store when necessary.

bool	nonfragmenting_relation_del (Entity source, Entity relation, Entity target)
	Removes an exclusive non-fragmenting relation from a source entity.

GAIA_NODISCARD bool	has_nonfragmenting_relation_pair (Entity source, Entity object) const
	Checks whether a source matches a possibly wildcarded non-fragmenting relation pair.

void	del_nonfragmenting_relation_source (Entity source)
	Removes all outgoing non-fragmenting relations from a source entity.

void	del_nonfragmenting_relation (Entity relation)
	Removes every stored source-target mapping for a non-fragmenting relation.

GAIA_NODISCARD bool	has_nonfragmenting_relation_target_cond (Entity target, Pair cond) const
	Checks whether any non-fragmenting exclusive relation targeting `target` uses an OnDeleteTarget rule.

void	set_serializer (std::nullptr_t)
	Resets runtime serializer binding to the default internal bin_stream backend.

void	set_serializer (ser::serializer serializer)
	Binds a pre-built runtime serializer handle.

template<typename TSerializer >
void	set_serializer (TSerializer &serializer)
	Binds a concrete serializer object through ser::make_serializer().

ser::serializer	get_serializer () const
	Returns the currently bound runtime serializer handle.

GAIA_NODISCARD ComponentCache &	comp_cache_mut ()
	Returns mutable access to the world component cache.

GAIA_NODISCARD const ComponentCache &	comp_cache () const
	Returns read-only access to the world component cache.

GAIA_NODISCARD Entity	symbol (const char *symbol, uint32_t len=0) const
	Finds a component entity by its exact registered symbol.

GAIA_NODISCARD util::str_view	symbol (Entity component) const
	Returns the registered symbol name for a component entity.

GAIA_NODISCARD Entity	path (const char *path, uint32_t len=0) const
	Finds a component entity by its exact scoped path.

GAIA_NODISCARD util::str_view	path (Entity component) const
	Returns the scoped path name for a component entity.

bool	path (Entity component, const char *path, uint32_t len=0)
	Assigns a scoped path name to a component entity.

GAIA_NODISCARD Entity	alias (const char *alias, uint32_t len=0) const
	Finds an entity by its exact alias.

GAIA_NODISCARD util::str_view	alias (Entity entity) const
	Returns the alias assigned to an entity.

bool	alias (Entity entity, const char *alias, uint32_t len=0)
	Assigns an alias name to an entity.

bool	alias_raw (Entity entity, const char *alias, uint32_t len=0)
	Assigns an alias name to an entity without copying the string.

GAIA_NODISCARD util::str_view	display_name (Entity entity) const
	Returns the preferred display name for a entity. This is intended for diagnostics and other pretty output, not as a stable identity key.

GAIA_NODISCARD bool	valid (Entity entity) const
	Checks if entity is valid.

GAIA_NODISCARD Entity	get (EntityId id) const
	Returns the entity located at the index id.

GAIA_NODISCARD Entity	try_get (EntityId id) const
	Returns the entity for `id` when it is still live, or EntityBad for stale cleanup-time ids.

template<typename T >
GAIA_NODISCARD Entity	get () const
	Returns the entity registered for component type T.

template<typename T >
GAIA_NODISCARD const ComponentCacheItem &	reg_comp ()
	Returns the registered component cache item for T, auto-registering it when enabled.

EntityBuilder	build (Entity entity)
	Starts a bulk add/remove operation on entity.

GAIA_NODISCARD Entity	add (EntityKind kind=EntityKind::EK_Gen)
	Creates a new empty entity.

GAIA_NODISCARD Entity	prefab (EntityKind kind=EntityKind::EK_Gen)
	Creates a new prefab entity.

template<typename Func = TFunc_Void_With_Entity>
void	add_n (uint32_t count, Func func=func_void_with_entity)
	Creates count new empty entities.

template<typename Func = TFunc_Void_With_Entity>
void	add_n (Entity entity, uint32_t count, Func func=func_void_with_entity)
	Creates count of entities of the same archetype as entity.

template<typename T >
GAIA_NODISCARD const ComponentCacheItem &	add ()
	Creates a new component if not found already.

template<typename T >
GAIA_NODISCARD const ComponentCacheItem &	add (const RuntimeTypeDesc &runtimeType)
	Registers a compile-time component with explicit runtime type metadata. Metadata is applied only during first registration. Existing component metadata remains immutable. Runtime metadata does not change typed storage, lifecycle callbacks, or the component symbol.

GAIA_NODISCARD ComponentCacheItem &	add (const ComponentDesc &desc, EntityKind kind=EntityKind::EK_Gen)
	Creates a new runtime component from a plain component descriptor if not found already.

void	add (Entity entity, Entity object)
	Attaches entity object to entity entity.

void	add (Entity entity, Pair pair)
	Attaches a relationship pair to entity.

template<typename T >
void	add (Entity entity)
	Attaches a new component T to entity.

template<typename T >
void	add (Entity entity, Entity object, T &&value)
	Attaches object to entity. Also sets its value.

template<typename T , typename U = typename actual_type_t<T>::Type>
void	add (Entity entity, U &&value)
	Attaches a new component T to entity. Also sets its value.

GAIA_NODISCARD bool	override (Entity entity, Entity object)
	Materializes an inherited id as directly owned storage on `entity`.

GAIA_NODISCARD bool	override (Entity entity, Pair pair)
	Materializes an inherited pair as directly owned storage on `entity`.

template<typename T >
GAIA_NODISCARD bool	override (Entity entity)
	Materializes an inherited typed component as directly owned storage on `entity`.

template<typename T >
GAIA_NODISCARD bool	override (Entity entity, Entity object)
	Materializes an inherited typed component associated with `object` on `entity`.

void	clear (Entity entity)
	Removes any component or entity attached to entity.

GAIA_NODISCARD Entity	copy (Entity srcEntity)
	Creates a new entity by cloning an already existing one. Does not trigger observers.

template<typename Func = TFunc_Void_With_Entity>
void	copy_n (Entity entity, uint32_t count, Func func=func_void_with_entity)
	Creates count new entities by cloning an already existing one.

GAIA_NODISCARD Entity	instantiate (Entity prefabEntity)
	Instantiates a prefab as a normal entity. The instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, and adds a direct Pair(Is, prefabEntity) edge instead. Prefab children linked through Parent or ChildOf are instantiated with the same hierarchy relation.

GAIA_NODISCARD Entity	instantiate (Entity prefabEntity, Entity parentInstance)
	Instantiates a prefab as a normal entity parented under `parentInstance`. The instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, adds a direct Pair(Is, prefabEntity) edge instead, and attaches Pair(Parent, parentInstance) to the new root instance. Prefab children linked through Parent or ChildOf are instantiated with the same hierarchy relation.

template<typename Func = TFunc_Void_With_Entity>
void	instantiate_n (Entity prefabEntity, uint32_t count, Func func=func_void_with_entity)
	Instantiates count copies of a prefab as normal root entities. Each instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, and adds a direct Pair(Is, prefabEntity) edge instead. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

void	instantiate_n (Entity prefabEntity, Entity parentInstance, uint32_t count)
	Instantiates count copies of a prefab as normal root entities parented under parentInstance. Each spawned root instance receives a direct Pair(Parent, parentInstance) relationship. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

template<typename Func >
void	instantiate_n (Entity prefabEntity, Entity parentInstance, uint32_t count, Func func)
	Instantiates count copies of a prefab as normal root entities, assigning a direct Pair(Parent, parentInstance) relationship when parentInstance is not EntityBad. The callback is invoked for each spawned root instance after its subtree has been instantiated. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

GAIA_NODISCARD uint32_t	sync (Entity prefabEntity)
	Propagates additive prefab changes to existing non-prefab instances. Missing copied ids are added to existing instances and missing prefab children are spawned with their Parent or ChildOf hierarchy relation. Existing owned instance data is left intact.

GAIA_NODISCARD Entity	find_prefab_instance (Entity instanceRoot, Entity prefabEntity) const
	Finds the entity inside instanceRoot that was instantiated from prefabEntity. The lookup checks instanceRoot first, then walks direct `Parent` and `ChildOf` descendants breadth-first. It matches the direct `Pair(Is, prefabEntity)` edge created by prefab instantiation and does not use names.

void	del (Entity entity)
	Removes an entity along with all data associated with it.

void	del (Entity entity, Entity object)
	Removes an object from entity if possible.

void	del (Entity entity, Pair pair)
	Removes an existing entity relationship pair.

template<typename T >
void	del (Entity entity)
	Removes a component T from entity.

void	as (Entity entity, Entity entityBase)
	Shortcut for add(entity, Pair(Is, entityBase)).

GAIA_NODISCARD bool	is (Entity entity, Entity entityBase) const
	Checks if entity inherits from entityBase.

GAIA_NODISCARD bool	in (Entity entity, Entity entityBase) const
	Checks if entity is located in entityBase. This is almost the same as "is" with the exception that false is returned if entity matches entityBase.

GAIA_NODISCARD bool	is_base (Entity target) const
	Checks whether an entity is the target of at least one direct Is relation.

void	child (Entity entity, Entity parent)
	Shortcut for add(entity, Pair(ChildOf, parent)).

GAIA_NODISCARD bool	child (Entity entity, Entity parent) const
	Checks whether entity has a `ChildOf` relationship to parent.

void	parent (Entity entity, Entity parentEntity)
	Adds a direct non-fragmenting `Parent` relationship to parentEntity. The relationship is non-fragmenting and does not participate in archetype identity.

GAIA_NODISCARD bool	parent (Entity entity, Entity parentEntity) const
	Checks whether entity has a direct non-fragmenting `Parent` relationship to parentEntity.

template<typename T >
void	modify (Entity entity)
	Marks the component type `T` as modified. Best used with acc_mut().sset() or set() to manually trigger an update at user's whim. If `TriggerSetEffects` is true, also triggers the component's set side effects: set hooks and `OnSet` observers.

template<typename T >
void	modify (Entity entity, Entity object)
	Marks the component associated with `object` as modified on `entity`. Best used with `mut<T>(entity, object)` or `sset<T>(entity, object)` to manually trigger an update at user's whim. If `TriggerSetEffects` is true, also triggers the component's set side effects: set hooks and `OnSet` observers.

GAIA_NODISCARD ComponentSetter	acc_mut (Entity entity)
	Starts a bulk set operation on entity.

template<typename T >
GAIA_NODISCARD auto	set (Entity entity)
	Returns a write-back proxy for the component T on entity. The proxy copies the current value, lets the caller mutate it, then writes it back at the end of the full expression or scope. `OnSet` observers and chunk-backed set hooks are triggered only after the write-back completes.

template<typename T >
GAIA_NODISCARD auto	set (Entity entity, Entity object)
	Returns a write-back proxy for the component associated with object on entity. The proxy copies the current value, lets the caller mutate it, then writes it back at the end of the full expression or scope. `OnSet` observers and chunk-backed set hooks are triggered only after the write-back completes.

template<typename T >
GAIA_NODISCARD decltype(auto)	sset (Entity entity)
	Returns silent mutable access to component type `T` on `entity`. This is a silent write and does not trigger set hooks or `OnSet` observers.

template<typename T >
GAIA_NODISCARD decltype(auto)	sset (Entity entity, Entity object)
	Sets the value of the component associated with `object` on `entity` without updating world version. This is a silent write and does not trigger set hooks or `OnSet` observers.

template<typename T >
GAIA_NODISCARD decltype(auto)	mut (Entity entity)
	Returns a mutable reference or proxy to the component on entity without triggering a world version update. This is a silent raw write path. Call `modify<T, true>(entity)` when you need hooks or `OnSet`.

template<typename T >
GAIA_NODISCARD decltype(auto)	mut (Entity entity, Entity object)
	Returns a mutable reference or proxy to the component associated with `object` on `entity`. This is a silent raw write path. Call `modify<T, true>(entity, object)` when you need hooks or `OnSet`.

GAIA_NODISCARD ComponentRawView	get_raw (Entity entity, Entity component) const
	Returns raw read-only bytes for an AoS component or exact pair payload on entity. Inherited ids resolve to the owning entity. SoA and unsupported components return an invalid view.

GAIA_NODISCARD ComponentRawMutView	mut_raw (Entity entity, Entity component)
	Returns raw mutable bytes for a directly owned AoS component or exact pair payload. This is a silent write path. Pair with modify_raw() to emit set hooks and `OnSet` observers.

GAIA_NODISCARD ComponentRawView	get_raw_field (Entity entity, Entity component, uint32_t fieldIdx) const
	Returns one read-only field value from a directly addressed SoA field array. The field index follows the registered SoA field order. Inherited ids resolve to the owning entity.

GAIA_NODISCARD ComponentRawMutView	mut_raw_field (Entity entity, Entity component, uint32_t fieldIdx)
	Returns one mutable field value from a directly owned SoA field array. This is a silent write path. Pair with modify_raw() to emit set hooks and `OnSet` observers.

GAIA_NODISCARD ComponentCursor	cursor (Entity entity, Entity component) const
	Creates a read-only cursor over a runtime component on entity. Inherited ids resolve like get_raw(). SoA roots expose fields without pretending the root is contiguous.

GAIA_NODISCARD ComponentCursor	cursor_mut (Entity entity, Entity component)
	Creates a mutable cursor over a directly owned runtime component on entity. Direct writes through mut_ptr() are silent and must be paired with modify_raw(). Writes through ComponentCursor::set_raw() finishes the root component write automatically.

bool	add_raw (Entity entity, Entity component, const void *data, uint32_t size)
	Adds an AoS component and initializes its raw payload before `OnAdd` observers run.

bool	set_raw (Entity entity, Entity component, const void *data, uint32_t size)
	Replaces raw bytes for a directly owned AoS component and finishes the write.

void	modify_raw (Entity entity, Entity component)
	Marks a raw payload or SoA field returned by a mutable raw view as modified and emits normal set side effects.

ComponentGetter	acc (Entity entity) const
	Starts a bulk get operation on an entity.

template<typename T >
GAIA_NODISCARD decltype(auto)	get (Entity entity) const
	Returns the value stored in the component T on entity.

template<typename T >
GAIA_NODISCARD decltype(auto)	get (Entity entity, Entity object) const
	Returns the value stored in the component associated with `object` on `entity`.

GAIA_NODISCARD bool	has (Entity entity) const
	Checks if entity is currently used by the world.

GAIA_NODISCARD bool	has (Pair pair) const
	Checks if pair is currently used by the world.

GAIA_NODISCARD bool	has (Entity entity, Entity object) const
	Checks if entity contains the entity object.

GAIA_NODISCARD bool	has_direct (Entity entity, Entity object) const
	Checks if entity directly contains the entity object, without semantic inheritance expansion.

GAIA_NODISCARD bool	has_direct (Entity entity, Pair pair) const
	Checks if `entity` directly contains `pair`, without semantic inheritance expansion.

GAIA_NODISCARD std::span< const Entity >	lookup_path () const
	Returns the ordered component lookup path used for unqualified component lookup. Each scope is searched like a temporary component scope: the scope first, then its parents.

void	lookup_path (std::span< const Entity > scopes)
	Replaces the ordered component lookup path used for unqualified component lookup. Each scope is searched in the order provided, and each scope walk includes its parents.

GAIA_NODISCARD Entity	scope () const
	Returns the current component scope used for component registration and relative component lookup.

Entity	scope (Entity scope)
	Sets the current component scope used for component registration and relative component lookup. The scope entity and its ChildOf ancestors are expected to have names so we can build a path from them.

template<typename Func >
void	scope (Entity scopeEntity, Func &&func)
	Executes func with a temporary component scope and restores the previous scope afterwards. Relative component lookup walks up the ChildOf hierarchy of the active scope. The scope entity and its ChildOf ancestors are expected to have names so we can build a path from them.

Entity	module (const char *path, uint32_t len=0)
	Finds or builds a named module hierarchy and returns the deepest scope entity. Each path segment is mapped to an entity name and connected with ChildOf relationships.

GAIA_NODISCARD bool	has (Entity entity, Pair pair) const
	Checks if entity contains pair.

template<typename T >
GAIA_NODISCARD bool	has (Entity entity) const
	Checks if entity contains the component T.

void	name (Entity entity, const char *name, uint32_t len=0)
	Assigns a name to entity. Ignored if used with pair. The string is copied and kept internally.

void	name_raw (Entity entity, const char *name, uint32_t len=0)
	Assigns a name to entity. Ignored if used with pair. The string is NOT copied. Your are responsible for its lifetime.

GAIA_NODISCARD util::str_view	name (Entity entity) const
	Returns the name assigned to entity.

GAIA_NODISCARD util::str_view	name (EntityId entityId) const
	Returns the entity name assigned to entityId.

GAIA_NODISCARD Entity	resolve (const char *name, uint32_t len=0) const
	Resolves name in the world naming system. Entity names and hierarchical entity paths are attempted first. If they do not match, component lookup uses the current scope, then the lookup path, then global component symbol, path and alias lookup.

void	resolve (cnt::darray< Entity > &out, const char *name, uint32_t len=0) const
	Collects every entity and component entity that matches name. This is useful for diagnostics when a short lookup could refer to multiple scoped components.

GAIA_NODISCARD Entity	get (const char *name, uint32_t len=0) const
	Returns the entity assigned a name name. This is a convenience alias for resolve(name).

GAIA_NODISCARD const cnt::set< EntityLookupKey > *	relations (Entity target) const
	Returns relations for `target`.

GAIA_NODISCARD Entity	relation (Entity entity, Entity target) const
	Returns the first relationship relation for the target entity on entity.

template<typename Func >
void	relations (Entity entity, Entity target, Func func) const
	Returns the relationship relations for the target entity on entity.

template<typename Func >
void	relations_if (Entity entity, Entity target, Func func) const
	Returns the relationship relations for the target entity on entity.

GAIA_NODISCARD const cnt::darray< Entity > &	as_relations_trav_cache (Entity target) const
	Returns the cached transitive `Is` descendants for a target entity. The cache is rebuilt lazily and cleared whenever an `Is` edge changes.

GAIA_NODISCARD const cnt::darray< Entity > &	as_targets_trav_cache (Entity relation) const
	Returns the cached transitive `Is` targets for a relation entity. The cache is rebuilt lazily and cleared whenever an `Is` edge changes.

GAIA_NODISCARD const cnt::darray< Entity > &	targets_trav_cache (Entity relation, Entity source) const
	Returns the cached unlimited upward traversal chain for `(relation, source)`. The cache excludes the source entity itself and is cleared whenever a pair edge changes.

GAIA_NODISCARD const cnt::darray< Entity > &	targets_all_cache (Entity source) const
	Returns the cached deduped direct targets for wildcard target traversal on `source`. The cache is keyed by `source` and cleared whenever a pair edge changes.

GAIA_NODISCARD const cnt::darray< Entity > &	sources_all_cache (Entity target) const
	Returns the cached deduped direct sources for wildcard source traversal on `target`. The cache is keyed by `target` and cleared whenever a pair edge changes.

template<typename Func >
void	targets_trav (Entity relation, Entity source, Func func) const
	Traverses relationship targets upwards starting from `source`. Disabled entities act as traversal barriers and are not yielded.

template<typename Func >
GAIA_NODISCARD bool	targets_trav_if (Entity relation, Entity source, Func func) const
	Traverses relationship targets upwards starting from `source`. Disabled entities act as traversal barriers and are not yielded.

GAIA_NODISCARD const cnt::darray< Entity > &	sources_bfs_trav_cache (Entity relation, Entity rootTarget) const
	Returns the cached unlimited breadth-first descendant traversal for `(relation, rootTarget)`. The cache excludes the root target itself and is cleared whenever a pair edge changes.

GAIA_NODISCARD uint32_t	depth_order_cache (Entity relation, Entity sourceTarget) const
	Returns the cached fragmenting relation depth used by depth-ordered iteration for `(relation, target)`. The returned value is `1` for direct dependents of a root/source with no further relation targets and grows by one per level. For multi-target relations, the deepest target chain determines the result.

template<typename Func >
void	as_relations_trav (Entity target, Func func) const
	Traverses transitive `Is` descendants of target. The traversal uses the cached closure built by as_relations_trav_cache().

template<typename Func >
GAIA_NODISCARD bool	as_relations_trav_if (Entity target, Func func) const
	Traverses transitive `Is` descendants of target until func returns true.

GAIA_NODISCARD const cnt::set< EntityLookupKey > *	targets (Entity relation) const
	Returns targets for `relation`.

GAIA_NODISCARD Entity	target (Entity entity, Entity relation) const
	Returns the first relationship target for the relation entity on entity.

template<typename Func >
void	targets (Entity entity, Entity relation, Func func) const
	Returns the relationship targets for the relation entity on entity.

template<typename Func >
void	targets_if (Entity entity, Entity relation, Func func) const
	Returns the relationship targets for the relation entity on entity.

GAIA_NODISCARD Entity	pair_target_if_alive (Entity pair) const
	Resolves the target of an archetype-stored exact pair id, skipping stale cleanup-time targets.

template<typename Func >
void	sources (Entity relation, Entity target, Func func) const
	Returns relationship sources for the relation and target.

template<typename Func >
void	sources_if (Entity relation, Entity target, Func func) const
	Returns relationship sources for the relation and target.

GAIA_NODISCARD uint32_t	count_direct_term_entities (Entity term) const
	Counts entities directly matching term, including semantic `Is` inheritance expansion.

GAIA_NODISCARD uint32_t	count_direct_term_entities_direct (Entity term) const
	Counts entities directly matching term without semantic `Is` expansion.

void	collect_direct_term_entities (Entity term, cnt::darray< Entity > &out) const
	Appends entities directly matching term to out, including semantic `Is` expansion.

void	collect_direct_term_entities_direct (Entity term, cnt::darray< Entity > &out) const
	Appends entities directly matching term to out without semantic `Is` expansion.

GAIA_NODISCARD bool	for_each_direct_term_entity (Entity term, void ctx, bool(func)(void *, Entity)) const
	Visits entities directly matching term, including semantic `Is` expansion.

GAIA_NODISCARD bool	for_each_direct_term_entity_direct (Entity term, void ctx, bool(func)(void *, Entity)) const
	Visits entities directly matching term without semantic `Is` expansion.

template<typename Func >
void	sources_bfs (Entity relation, Entity rootTarget, Func func) const
	Traverses relationship sources in breadth-first order. Starting at rootTarget, this visits all direct sources first and then deeper levels.

template<typename Func >
GAIA_NODISCARD bool	sources_bfs_if (Entity relation, Entity rootTarget, Func func) const
	Traverses relationship sources in breadth-first order. Starting at rootTarget, this visits all direct sources first and then deeper levels.

template<typename Func >
void	as_targets_trav (Entity relation, Func func) const
	Traverses transitive `Is` targets of relation. The traversal uses the cached closure built by as_targets_trav_cache().

template<typename Func >
bool	as_targets_trav_if (Entity relation, Func func) const
	Traverses transitive `Is` targets of relation until func returns true.

CommandBufferST &	cmd_buffer_st () const
	Returns the single-threaded deferred command buffer owned by the world.

CommandBufferMT &	cmd_buffer_mt () const
	Returns the multi-thread-safe deferred command buffer owned by the world.

void	defer_sort_inv_begin (uint32_t slotCount)
	Starts recording sorted-query invalidations instead of applying them right away. Called by the coordinator before a region whose writes may run on worker threads.

void	defer_sort_inv_end ()
	Stops recording sorted-query invalidations and applies everything recorded since the matching defer_sort_inv_begin(). Invalidation runs on the calling thread, which is the coordinator once the parallel region joins.

GAIA_NODISCARD bool	defer_sort_inv_active () const
	Returns whether sorted-query invalidations are currently being recorded.

void	defer_sort_inv_record (uint32_t slot, Entity entity)
	Records a sorted-query invalidation for later application.

void	enable (Entity entity, bool enable)
	Enables or disables an entire entity.

GAIA_NODISCARD bool	enabled (const EntityContainer &ec) const
	Checks if an entity is enabled.

GAIA_NODISCARD bool	enabled (Entity entity) const
	Checks if an entity is enabled.

GAIA_NODISCARD bool	enabled_hierarchy (Entity entity, Entity relation) const
	Checks whether an entity is enabled together with all of its ancestors reachable through `relation`. This keeps direct enabled state separate from hierarchy-aware gating.

GAIA_NODISCARD Chunk *	get_chunk (Entity entity) const
	Returns a chunk containing the entity.

GAIA_NODISCARD Chunk *	get_chunk (Entity entity, uint32_t &row) const
	Returns a chunk containing the entity. Index of the entity is stored in row.

GAIA_NODISCARD uint32_t	size () const
	Returns the number of active entities.

void	runtime_counters (uint32_t &outArchetypes, uint32_t &outChunks, uint32_t &outEntitiesTotal, uint32_t &outEntitiesActive) const
	Returns high-level runtime counters useful for diagnostics/telemetry.

GAIA_NODISCARD uint32_t &	world_version ()
	Returns the current version of the world.

GAIA_NODISCARD uint32_t	rel_version (Entity relation) const
	Returns structural version for a given relation. Increments whenever any Pair(relation, *) is added or removed on any entity.

GAIA_NODISCARD uint32_t	enabled_hierarchy_version () const
	Returns the version that changes when entity enabled state changes. Hierarchy-aware cached traversals use this to invalidate ancestor gating state.

GAIA_NODISCARD uint32_t	archetype_delete_version () const
	Returns the version that changes when archetype deletion visibility changes.

void	update_src_entity_version (Entity entity)
	Updates a tracked source-entity version after the entity changes archetype membership.

void	remove_src_entity_version (Entity entity)
	Removes sparse source-version state for an entity that is being destroyed.

void	set_max_lifespan (Entity entity, uint32_t lifespan=Archetype::MAX_ARCHETYPE_LIFESPAN)
	Sets maximal lifespan of an archetype entity belongs to.

void	frame_cleanup ()
	Performs deferred cleanup for the current frame.

void	frame_end ()
	Marks the end of the current frame.

void	update ()
	Runs systems and then finishes the current frame.

void	teardown ()
	Performs world shutdown maintenance without running systems or observers. Runtime callbacks are shut down in-place first, then deferred entity/chunk/archetype cleanup is drained until no more pending teardown work remains.

void	cleanup ()
	Clears the world so that all its entities and components are released.

void	defrag_entities_per_tick (uint32_t value)
	Sets the maximum number of entities defragmented per world tick.

void	diag_archetypes () const
	Performs diagnostics on archetypes. Prints basic info about them and the chunks they contain.

void	diag_components () const
	Performs diagnostics on registered components. Prints basic info about them and reports and detected issues.

void	diag_entities () const
	Performs diagnostics on entities of the world. Also performs validation of internal structures which hold the entities.

void	diag () const
	Performs all diagnostics.

GAIA_NODISCARD bool	locked () const
	Checks if the chunk is locked for structural changes.

GAIA_NODISCARD bool	tearing_down () const
	Returns true while the world is draining teardown work and normal runtime callbacks must not execute.

void	save ()
	Saves contents of the world to a buffer. The buffer is reset, not appended. NOTE: In order for custom version of save to be used for a given component, it needs to have either of the following functions defined: 1) member function: "void save(bin_stream& s)" 2) free function in gaia::ser namespace: "void tag_invoke(gaia::ser::save_v, bin_stream& s, const YourType& data)".

bool	load (ser::serializer inputSerializer={})
	Loads a world state from a buffer. The buffer is sought to 0 before any loading happens. NOTE: In order for custom version of load to be used for a given component, it needs to have either of the following functions defined: 1) member function: "void load(bin_stream& s)" 2) free function in gaia::ser namespace: "void tag_invoke(gaia::ser::load_v, bin_stream& s, YourType& data)".

template<typename TSerializer >
bool	load (TSerializer &inputSerializer)
	Loads a world state from a serializer-compatible stream wrapper.

QuerySerBuffer &	query_buffer (QueryId &serId)
	Returns the temporary serialization buffer used while building a query. A fresh query id is allocated lazily when serId is QueryIdBad.

void	query_buffer_reset (QueryId &serId)
	Releases the temporary serialization buffer associated with serId.

void	invalidate_queries_for_structural_entity (EntityLookupKey entityKey)
	Invalidates cached queries structurally affected by entityKey.

void	invalidate_queries_for_rel (Entity relation)
	Invalidates cached queries whose dynamic result depends on relation.

GAIA_NODISCARD bool	has_sorted_queries () const
	Checks whether any cached sorted query is registered in this world.

GAIA_NODISCARD bool	has_sorted_queries_for_entity (Entity entity) const
	Checks whether any cached sorted query depends on entity being written.

void	invalidate_sorted_queries_for_entity (Entity entity)
	Invalidates cached sorted queries whose row ordering depends on entity.

void	invalidate_sorted_queries ()
	Invalidates all cached sorted queries after row-order changes.

void	invalidate_queries_for_entity (Pair is_pair)
	Invalidates semantic `Is` queries affected by removing or changing is_pair.

Entity	name_to_entity (std::span< const char > exprRaw) const
	Resolves a textual id expression to an entity. Supports names, aliases, wildcard `*`, and pair expressions like `(Rel, Target)`.

Entity	expr_to_entity (va_list &args, std::span< const char > exprRaw) const
	Resolves a textual id expression with `e` placeholders to an entity. Supports the same pair and wildcard syntax as name_to_entity().

Static Public Member Functions
static GAIA_NODISCARD bool	is_req_del (const EntityContainer &ec)
	Returns whether the record is already in delete-requested state. Covers both explicit per-entity deletion and archetype-level forced teardown.

template<typename T >
static GAIA_NODISCARD constexpr bool	supports_sparse_component_storage ()
	Sparse storage currently supports only plain generic components. Pairs, unique components and SoA layouts stay on the normal archetype path.

template<typename T >
static GAIA_NODISCARD constexpr bool	uses_compile_time_sparse_storage ()
	Returns whether T has compile-time sparse payload storage.

Static Public Attributes
static bool	s_enableUniqueNameDuplicateAssert = true
	Allows asserts on duplicate name/alias assignment.

Friends
struct	ComponentGetter

struct	ComponentSetter

void	lock (World &)

void	unlock (World &)

QueryMatchScratch &	query_match_scratch_acquire (World &)
	Acquires temporary scratch storage used during query matching.

void	query_match_scratch_release (World &, bool)
	Releases previously acquired query-match scratch storage.

uint32_t	world_component_index_bucket_size (const World &, Entity)
	Returns the size of the component-to-archetype bucket for term.

uint32_t	world_component_index_comp_idx (const World &, const Archetype &, Entity)
	Returns the cached component index of term inside archetype.

uint32_t	world_component_index_match_count (const World &, const Archetype &, Entity)
	Returns the cached match count of term inside archetype.

template<typename T >
decltype(auto)	world_direct_entity_arg (World &world, Entity entity)
	Returns a direct query argument for entity using immediate-write access for mutable references.

template<typename T >
decltype(auto)	world_direct_entity_arg_raw (World &world, Entity entity)
	Returns a direct query argument for entity using raw mutable access.

template<typename T >
decltype(auto)	world_query_entity_arg_by_id (World &world, Entity entity, Entity id)
	Returns the query argument for entity using explicit term id id. Mutable references materialize an override when inherited data must become direct.

template<typename T >
decltype(auto)	world_query_entity_arg_by_id_raw (World &world, Entity entity, Entity id)
	Returns the query argument for entity using explicit term id id and raw mutable access. Mutable references materialize an override when inherited data must become direct.

void	world_finish_write (World &world, Entity term, Entity entity)
	Finishes a cursor write through the owning world.

uint32_t	world_rel_version (const World &world, Entity relation)
	Returns the current version of `relation-specific` traversal metadata.

uint32_t	world_version (const World &world)
	Returns the current world structural version.

uint32_t	world_archetype_delete_version (const World &world)
	Returns the version that changes when an archetype enters or leaves the deletion-request set.

uint32_t	world_entity_archetype_version (const World &world, Entity entity)
	Returns the per-entity archetype version used for targeted source-query freshness checks.

Detailed Description

Owns entities, components, archetypes, queries, observers, and systems.

Member Function Documentation

◆ acc()

ComponentGetter gaia::ecs::World::acc ( Entity entity ) const

inline

Starts a bulk get operation on an entity.

Parameters

entity Entity

Returns: Entity-scoped ComponentGetter bound to this world and entity's current storage

Warning: It is expected that entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentGetter is created.

◆ acc_mut()

GAIA_NODISCARD ComponentSetter gaia::ecs::World::acc_mut ( Entity entity )

inline

Starts a bulk set operation on entity.

Parameters

entity Entity

Returns: Entity-scoped ComponentSetter bound to this world and entity's current storage

Warning: It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ add() [1/9]

template<typename T >

GAIA_NODISCARD const ComponentCacheItem & gaia::ecs::World::add ( )

inline

Creates a new component if not found already.

Template Parameters

T Component

Returns: Component cache item of the component

◆ add() [2/9]

GAIA_NODISCARD ComponentCacheItem & gaia::ecs::World::add	(	const ComponentDesc &	desc,
		EntityKind	kind = `EntityKind::EK_Gen`
	)

inline

Creates a new runtime component from a plain component descriptor if not found already.

Parameters

desc	Component registration descriptor.
kind	Entity kind assigned to the new component entity.

Returns: Mutable component cache item of the component.

◆ add() [3/9]

template<typename T >

GAIA_NODISCARD const ComponentCacheItem & gaia::ecs::World::add ( const RuntimeTypeDesc & runtimeType )

inline

Registers a compile-time component with explicit runtime type metadata. Metadata is applied only during first registration. Existing component metadata remains immutable. Runtime metadata does not change typed storage, lifecycle callbacks, or the component symbol.

Template Parameters

T	Component type to register.

Parameters

runtimeType Reflection-only metadata attached during first registration.

Returns: Registered component cache item.

◆ add() [4/9]

template<typename T >

void gaia::ecs::World::add ( Entity entity )

inline

Attaches a new component T to entity.

Template Parameters

T Component

Parameters

entity Entity

Warning: It is expected the component is not present on entity yet. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.

◆ add() [5/9]

void gaia::ecs::World::add	(	Entity	entity,
		Entity	object
	)

inline

Attaches entity object to entity entity.

Parameters

entity	Source entity
object	Added entity

Warning: It is expected both entity and object are valid. Undefined behavior otherwise.

◆ add() [6/9]

template<typename T >

void gaia::ecs::World::add	(	Entity	entity,
		Entity	object,
		T &&	value
	)

inline

Attaches object to entity. Also sets its value.

Parameters

object	Object
entity	Entity
value	Value to set for the object

Warning: It is expected the component is not present on entity yet. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; It is expected object is valid. Undefined behavior otherwise.

◆ add() [7/9]

void gaia::ecs::World::add	(	Entity	entity,
		Pair	pair
	)

inline

Attaches a relationship pair to entity.

Parameters

entity	Source entity.
pair	Pair to attach.

Warning: It is expected both entity and the entities forming the relationship are valid. Undefined behavior otherwise.

◆ add() [8/9]

template<typename T , typename U = typename actual_type_t<T>::Type>

void gaia::ecs::World::add	(	Entity	entity,
		U &&	value
	)

inline

Attaches a new component T to entity. Also sets its value.

Template Parameters

T Component

Parameters

entity	Entity
value	Value to set for the component

Warning: It is expected the component is not present on entity yet. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.

◆ add() [9/9]

GAIA_NODISCARD Entity gaia::ecs::World::add ( EntityKind kind = EntityKind::EK_Gen )

inline

Creates a new empty entity.

Parameters

kind	Entity kind. Generic entity by default.

Returns: New entity.

◆ add_n() [1/2]

template<typename Func = TFunc_Void_With_Entity>

void gaia::ecs::World::add_n	(	Entity	entity,
		uint32_t	count,
		Func	func = `func_void_with_entity`
	)

inline

Creates count of entities of the same archetype as entity.

Parameters

entity	Source entity whose archetype is reused.
count	Number of entities to create.
func	Functor invoked for each new entity.

Note: Similar to copy_n(), but component payload is left uninitialized or default-initialized.

◆ add_n() [2/2]

template<typename Func = TFunc_Void_With_Entity>

void gaia::ecs::World::add_n	(	uint32_t	count,
		Func	func = `func_void_with_entity`
	)

inline

Creates count new empty entities.

Parameters

count	Number of entities to create.
func	Functor invoked for each new entity.

◆ add_raw()

bool gaia::ecs::World::add_raw	(	Entity	entity,
		Entity	component,
		const void *	data,
		uint32_t	size
	)

inline

Adds an AoS component and initializes its raw payload before OnAdd observers run.

Parameters

entity	Entity receiving the component.
component	Runtime component entity or exact relationship pair.
data	Payload bytes. Must be non-null when the component size is non-zero.
size	Payload byte count. Must match the registered component size.

Returns: True when the component was added and initialized.

◆ alias() [1/3]

GAIA_NODISCARD Entity gaia::ecs::World::alias	(	const char *	alias,
		uint32_t	len = `0`
	)		const

inline

Finds an entity by its exact alias.

Parameters

alias	Exact entity alias.
len	String length. If zero, the length is calculated.

Returns: Matching entity. EntityBad when no exact alias match exists.

◆ alias() [2/3]

GAIA_NODISCARD util::str_view gaia::ecs::World::alias ( Entity entity ) const

inline

Returns the alias assigned to an entity.

Parameters

entity Entity.

Returns: Alias. Empty view when no alias is assigned.

◆ alias() [3/3]

bool gaia::ecs::World::alias	(	Entity	entity,
		const char *	alias,
		uint32_t	len = `0`
	)

inline

Assigns an alias name to an entity.

Parameters

entity	Entity.
alias	Alias to assign. Pass nullptr to clear the current alias.
len	String length. If zero, the length is calculated.

Returns: True when the alias metadata changed, false otherwise.

◆ alias_raw()

bool gaia::ecs::World::alias_raw	(	Entity	entity,
		const char *	alias,
		uint32_t	len = `0`
	)

inline

Assigns an alias name to an entity without copying the string.

Parameters

entity	Entity.
alias	Alias to assign. Pass nullptr to clear the current alias.
len	String length. If zero, the length is calculated.

Returns: True when the alias metadata changed, false otherwise.

◆ archetype_delete_version()

GAIA_NODISCARD uint32_t gaia::ecs::World::archetype_delete_version ( ) const

inline

Returns the version that changes when archetype deletion visibility changes.

Returns: Archetype deletion-request version.

◆ as()

void gaia::ecs::World::as	(	Entity	entity,
		Entity	entityBase
	)

inline

Shortcut for add(entity, Pair(Is, entityBase)).

Parameters

entity	Entity receiving the inheritance pair.
entityBase	Base entity to inherit from.

◆ as_relations_trav()

template<typename Func >

void gaia::ecs::World::as_relations_trav	(	Entity	target,
		Func	func
	)		const

inline

Traverses transitive Is descendants of target. The traversal uses the cached closure built by as_relations_trav_cache().

Parameters

target	Target entity
func	void(Entity relation) functor executed for each descendant relation.

◆ as_relations_trav_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::as_relations_trav_cache ( Entity target ) const

inline

Returns the cached transitive Is descendants for a target entity. The cache is rebuilt lazily and cleared whenever an Is edge changes.

Parameters

target Base entity whose derived entities are requested.

Returns: Cached transitive descendants of target.

Small inline traversal stack for the common shallow inheritance case.

◆ as_relations_trav_if()

template<typename Func >

GAIA_NODISCARD bool gaia::ecs::World::as_relations_trav_if	(	Entity	target,
		Func	func
	)		const

inline

Traverses transitive Is descendants of target until func returns true.

Parameters

target	Target entity
func	bool(Entity relation) functor executed for each descendant relation. Stops if true is returned.

Returns: True when traversal stopped early. False otherwise.

◆ as_targets_trav()

template<typename Func >

void gaia::ecs::World::as_targets_trav	(	Entity	relation,
		Func	func
	)		const

inline

Traverses transitive Is targets of relation. The traversal uses the cached closure built by as_targets_trav_cache().

Parameters

relation	Relation entity
func	void(Entity target) functor executed for each inherited target.

◆ as_targets_trav_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::as_targets_trav_cache ( Entity relation ) const

inline

Returns the cached transitive Is targets for a relation entity. The cache is rebuilt lazily and cleared whenever an Is edge changes.

Parameters

relation Derived entity whose transitive bases are requested.

Returns: Cached transitive base targets of relation.

Small inline traversal stack for the common shallow inheritance case.

◆ as_targets_trav_if()

template<typename Func >

bool gaia::ecs::World::as_targets_trav_if	(	Entity	relation,
		Func	func
	)		const

inline

Traverses transitive Is targets of relation until func returns true.

Parameters

relation	Relation entity
func	bool(Entity target) functor executed for each inherited target. Stops if true is returned.

Returns: True when traversal stopped early. False otherwise.

◆ build()

EntityBuilder gaia::ecs::World::build ( Entity entity )

inline

Starts a bulk add/remove operation on entity.

Parameters

entity Entity

Returns: EntityBuilder

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ can_add_component_storage_trait()

GAIA_NODISCARD bool gaia::ecs::World::can_add_component_storage_trait ( Entity component ) const

inline

Returns whether a runtime storage trait can be attached to component. Compile-time component storage is authoritative. Runtime component descriptors remain mutable.

Parameters

component Component entity.

Returns: True for runtime components or typed sparse components.

◆ can_use_sparse_component_storage()

template<typename T >

GAIA_NODISCARD bool gaia::ecs::World::can_use_sparse_component_storage ( Entity object ) const

inline

Returns whether object is a usable sparse storage target for component type T.

Template Parameters

T	Component type to validate against.

Parameters

object Component entity to inspect.

Returns: True when object can back sparse storage for T.

◆ child() [1/2]

void gaia::ecs::World::child	(	Entity	entity,
		Entity	parent
	)

inline

Shortcut for add(entity, Pair(ChildOf, parent)).

Parameters

entity	Entity receiving the ChildOf pair.
parent	Parent target of the ChildOf pair.

◆ child() [2/2]

GAIA_NODISCARD bool gaia::ecs::World::child	(	Entity	entity,
		Entity	parent
	)		const

inline

Checks whether entity has a ChildOf relationship to parent.

Parameters

entity	Entity to inspect.
parent	Candidate parent entity.

Returns: True if entity is a child of parent. False otherwise.

◆ clear()

void gaia::ecs::World::clear ( Entity entity )

inline

Removes any component or entity attached to entity.

Parameters

entity Entity we want to remove any attached component or entity from

Warning: It is expected entity is not a pair. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.

◆ cmd_buffer_mt()

CommandBufferMT & gaia::ecs::World::cmd_buffer_mt ( ) const

inline

Returns the multi-thread-safe deferred command buffer owned by the world.

Returns: Multi-thread-safe command buffer reference.

◆ cmd_buffer_st()

CommandBufferST & gaia::ecs::World::cmd_buffer_st ( ) const

inline

Returns the single-threaded deferred command buffer owned by the world.

Returns: Single-threaded command buffer reference.

◆ collect_direct_term_entities()

void gaia::ecs::World::collect_direct_term_entities	(	Entity	term,
		cnt::darray< Entity > &	out
	)		const

inline

Appends entities directly matching term to out, including semantic Is expansion.

Parameters

term	Query term
out	Output array

◆ collect_direct_term_entities_direct()

void gaia::ecs::World::collect_direct_term_entities_direct	(	Entity	term,
		cnt::darray< Entity > &	out
	)		const

inline

Appends entities directly matching term to out without semantic Is expansion.

Parameters

term	Query term
out	Output array

◆ comp_cache()

GAIA_NODISCARD const ComponentCache & gaia::ecs::World::comp_cache ( ) const

inline

Returns read-only access to the world component cache.

Returns: Component cache owned by this world.

◆ comp_cache_mut()

GAIA_NODISCARD ComponentCache & gaia::ecs::World::comp_cache_mut ( )

inline

Returns mutable access to the world component cache.

Returns: Component cache owned by this world.

◆ compile_time_sparse_storage_mode()

GAIA_NODISCARD SparseStorageMode gaia::ecs::World::compile_time_sparse_storage_mode ( Entity component ) const

inline

Returns the fragmentation mode for a component known at compile time to use sparse storage.

Parameters

component Typed sparse component entity.

Returns: Fragmenting or non-fragmenting sparse mode.

◆ component_is_non_fragmenting()

GAIA_NODISCARD bool gaia::ecs::World::component_is_non_fragmenting ( Entity component ) const

inline

Returns whether component is non-fragmenting. Non-fragmenting components do not participate in archetype identity.

Parameters

component Component entity to inspect.

Returns: True when the component is non-fragmenting.

◆ component_uses_sparse_storage()

GAIA_NODISCARD bool gaia::ecs::World::component_uses_sparse_storage ( Entity component ) const

inline

Returns whether component stores instance data in sparse storage instead of archetype chunks. This is currently the storage path used for sparse plain generic AoS components.

Parameters

component Component entity to inspect.

Returns: True when the component uses sparse storage.

◆ copies_non_frag_sparse_payload_inter()

GAIA_NODISCARD bool gaia::ecs::World::copies_non_frag_sparse_payload_inter	(	Entity	comp,
		Entity	srcEntity,
		const SparseComponentStoreErased &	store
	)		const

inline

Checks whether an inter-world copy includes a non-fragmenting sparse payload.

Parameters

comp	Component entity being copied.
srcEntity	Source entity in `store`.
store	Type-erased sparse store containing the source payload.

Returns: True when the copied sparse payload does not participate in archetype identity.

◆ copies_sparse_payload_inter()

GAIA_NODISCARD bool gaia::ecs::World::copies_sparse_payload_inter	(	Entity	comp,
		Entity	srcEntity,
		const SparseComponentStoreErased &	store
	)		const

inline

Checks whether an inter-world copy includes a sparse component payload.

Parameters

comp	Component entity being copied.
srcEntity	Source entity in `store`.
store	Type-erased sparse store containing the source payload.

Returns: True when srcEntity owns the sparse payload and comp uses sparse storage.

◆ copy()

GAIA_NODISCARD Entity gaia::ecs::World::copy ( Entity srcEntity )

inline

Creates a new entity by cloning an already existing one. Does not trigger observers.

Parameters

srcEntity Entity to clone

Returns: New entity

Warning: It is expected srcEntity is valid. Undefined behavior otherwise.; If EntityDesc is present on srcEntity, it is not copied because names are expected to be unique. Instead, the copied entity will be a part of an archetype without EntityDesc and any calls to World::name(copiedEntity) will return an empty view.

◆ copy_n()

template<typename Func = TFunc_Void_With_Entity>

void gaia::ecs::World::copy_n	(	Entity	entity,
		uint32_t	count,
		Func	func = `func_void_with_entity`
	)

inline

Creates count new entities by cloning an already existing one.

Parameters

entity	Entity to clone
count	Number of clones to make
func	Functor executed every time a copy is created. It can be either void(ecs::Entity) or void(ecs::CopyIter&).

Warning: It is expected entity is valid generic entity. Undefined behavior otherwise.; If EntityDesc is present on entity, it is not copied because names are expected to be unique. Instead, the copied entity will be a part of an archetype without EntityDesc and any calls to World::name(copiedEntity) will return an empty view.

◆ count_direct_term_entities()

GAIA_NODISCARD uint32_t gaia::ecs::World::count_direct_term_entities ( Entity term ) const

inline

Counts entities directly matching term, including semantic Is inheritance expansion.

Parameters

term	Query term

Returns: Number of directly matching entities.

◆ count_direct_term_entities_direct()

GAIA_NODISCARD uint32_t gaia::ecs::World::count_direct_term_entities_direct ( Entity term ) const

inline

Counts entities directly matching term without semantic Is expansion.

Parameters

term	Query term

Returns: Number of directly matching entities.

◆ cursor()

ComponentCursor gaia::ecs::World::cursor	(	Entity	entity,
		Entity	component
	)		const

inline

Creates a read-only cursor over a runtime component on entity. Inherited ids resolve like get_raw(). SoA roots expose fields without pretending the root is contiguous.

Parameters

entity	Entity being read.
component	Component entity or exact relationship pair being read.

Returns: Cursor positioned at the root component payload, or invalid cursor when unavailable.

◆ cursor_mut()

ComponentCursor gaia::ecs::World::cursor_mut	(	Entity	entity,
		Entity	component
	)

inline

Creates a mutable cursor over a directly owned runtime component on entity. Direct writes through mut_ptr() are silent and must be paired with modify_raw(). Writes through ComponentCursor::set_raw() finishes the root component write automatically.

Parameters

entity	Entity being mutated.
component	Component entity or exact relationship pair being mutated.

Returns: Cursor positioned at the root component payload, or invalid cursor when unavailable.

◆ defer_sort_inv_active()

GAIA_NODISCARD bool gaia::ecs::World::defer_sort_inv_active ( ) const

inline

Returns whether sorted-query invalidations are currently being recorded.

Returns: True while deferred sorted-query invalidation is active.

◆ defer_sort_inv_begin()

void gaia::ecs::World::defer_sort_inv_begin ( uint32_t slotCount )

inline

Starts recording sorted-query invalidations instead of applying them right away. Called by the coordinator before a region whose writes may run on worker threads.

Parameters

slotCount Number of work items that can record concurrently.

◆ defer_sort_inv_record()

void gaia::ecs::World::defer_sort_inv_record	(	uint32_t	slot,
		Entity	entity
	)

inline

Records a sorted-query invalidation for later application.

Parameters

slot	Work-item slot owned exclusively by the calling thread.
entity	Component entity whose version was bumped by a write.

◆ defrag_entities_per_tick()

void gaia::ecs::World::defrag_entities_per_tick ( uint32_t value )

inline

Sets the maximum number of entities defragmented per world tick.

Parameters

value Number of entities to defragment

◆ del() [1/4]

void gaia::ecs::World::del ( Entity entity )

inline

Removes an entity along with all data associated with it.

Parameters

entity Entity to delete

◆ del() [2/4]

template<typename T >

void gaia::ecs::World::del ( Entity entity )

inline

Removes a component T from entity.

Template Parameters

T Component

Parameters

entity Entity

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.

◆ del() [3/4]

void gaia::ecs::World::del	(	Entity	entity,
		Entity	object
	)

inline

Removes an object from entity if possible.

Parameters

entity	Entity to delete from
object	Entity to delete

Warning: It is expected both entity and object are valid. Undefined behavior otherwise.

◆ del() [4/4]

void gaia::ecs::World::del	(	Entity	entity,
		Pair	pair
	)

inline

Removes an existing entity relationship pair.

Parameters

entity	Source entity
pair	Pair

Warning: It is expected both entity and the entities forming the relationship are valid. Undefined behavior otherwise.

◆ del_nonfragmenting_relation()

void gaia::ecs::World::del_nonfragmenting_relation ( Entity relation )

inline

Removes every stored source-target mapping for a non-fragmenting relation.

Parameters

relation Relation entity whose store is removed.

◆ del_nonfragmenting_relation_source()

void gaia::ecs::World::del_nonfragmenting_relation_source ( Entity source )

inline

Removes all outgoing non-fragmenting relations from a source entity.

Parameters

source Source entity whose stored relation targets are removed.

◆ del_sparse_component_store()

void gaia::ecs::World::del_sparse_component_store ( Entity component )

inline

Deletes the sparse component store associated with component.

Parameters

component Component entity identifying the store.

◆ del_sparse_components()

void gaia::ecs::World::del_sparse_components ( Entity entity )

inline

Removes all sparse component instances owned by entity.

Parameters

entity Entity

◆ depth_order_cache()

GAIA_NODISCARD uint32_t gaia::ecs::World::depth_order_cache	(	Entity	relation,
		Entity	sourceTarget
	)		const

inline

Returns the cached fragmenting relation depth used by depth-ordered iteration for (relation, target). The returned value is 1 for direct dependents of a root/source with no further relation targets and grows by one per level. For multi-target relations, the deepest target chain determines the result.

Parameters

relation	Fragmenting relation defining depth edges.
sourceTarget	Target entity whose depth is requested.

Returns: Cached one-based depth, or zero when either entity is invalid.

◆ display_name()

GAIA_NODISCARD util::str_view gaia::ecs::World::display_name ( Entity entity ) const

inline

Returns the preferred display name for a entity. This is intended for diagnostics and other pretty output, not as a stable identity key.

Parameters

entity Entity.

Returns: Display name used for user-facing output. Empty view when entity is not cached.

◆ enable()

void gaia::ecs::World::enable	(	Entity	entity,
		bool	enable
	)

inline

Enables or disables an entire entity.

Parameters

entity	Entity
enable	Enable or disable the entity

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ enabled() [1/2]

GAIA_NODISCARD bool gaia::ecs::World::enabled ( const EntityContainer & ec ) const

inline

Checks if an entity is enabled.

Parameters

ec	Entity container of the entity

Returns: True if the entity is enabled. False otherwise.

◆ enabled() [2/2]

GAIA_NODISCARD bool gaia::ecs::World::enabled ( Entity entity ) const

inline

Checks if an entity is enabled.

Parameters

entity Entity

Returns: True it the entity is enabled. False otherwise.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ enabled_hierarchy()

GAIA_NODISCARD bool gaia::ecs::World::enabled_hierarchy	(	Entity	entity,
		Entity	relation
	)		const

inline

Checks whether an entity is enabled together with all of its ancestors reachable through relation. This keeps direct enabled state separate from hierarchy-aware gating.

Parameters

entity	Entity whose effective enabled state is requested.
relation	Relation defining the ancestor chain.

Returns: True when entity and every reachable ancestor are enabled. False otherwise.

◆ enabled_hierarchy_version()

GAIA_NODISCARD uint32_t gaia::ecs::World::enabled_hierarchy_version ( ) const

inline

Returns the version that changes when entity enabled state changes. Hierarchy-aware cached traversals use this to invalidate ancestor gating state.

Returns: Enabled-hierarchy version.

◆ expr_to_entity()

Entity gaia::ecs::World::expr_to_entity	(	va_list &	args,
		std::span< const char >	exprRaw
	)		const

inline

Resolves a textual id expression with e placeholders to an entity. Supports the same pair and wildcard syntax as name_to_entity().

Parameters

args	Vararg list consumed by `e` placeholders
exprRaw	Expression text

Returns: Resolved entity or EntityBad on failure.

◆ fetch() [1/2]

GAIA_NODISCARD EntityContainer & gaia::ecs::World::fetch ( Entity entity )

inline

Returns the internal record for entity.

Parameters

entity Entity or exact pair record.

Returns: Mutable entity container record.

◆ fetch() [2/2]

GAIA_NODISCARD const EntityContainer & gaia::ecs::World::fetch ( Entity entity ) const

inline

Returns the internal record for entity.

Parameters

entity Entity or exact pair record.

Returns: Const entity container record.

◆ finalize_component_registration()

void gaia::ecs::World::finalize_component_registration	(	const ComponentCacheItem &	item,
		bool	addSparseTrait
	)

inline

Finalizes a newly registered component entity after the cache record has been created. This synchronizes the core Component value stored on the component entity, registers the default symbol through the normal naming path, and optionally latches the Sparse trait.

Parameters

item	Registered component cache item.
addSparseTrait	Whether runtime sparse registration should attach the `Sparse` trait.

◆ find_prefab_instance()

GAIA_NODISCARD Entity gaia::ecs::World::find_prefab_instance	(	Entity	instanceRoot,
		Entity	prefabEntity
	)		const

inline

Finds the entity inside instanceRoot that was instantiated from prefabEntity. The lookup checks instanceRoot first, then walks direct Parent and ChildOf descendants breadth-first. It matches the direct Pair(Is, prefabEntity) edge created by prefab instantiation and does not use names.

Parameters

instanceRoot	Root instance entity to search from.
prefabEntity	Prefab entity to map into the instance subtree.

Returns: Matching instance entity, or EntityBad when the prefab is not present in the instance subtree.

◆ finish_sparse_component_add_inter()

void gaia::ecs::World::finish_sparse_component_add_inter	(	Entity	entity,
		Entity	object,
		SparseStorageMode	mode
	)

inline

Finishes adding a sparse component after its payload has been created. Fragmenting components also add the id directly to the entity archetype.

Parameters

entity	Entity receiving the component.
object	Component entity being added.
mode	Sparse storage mode for the component.

◆ for_each_direct_term_entity()

GAIA_NODISCARD bool gaia::ecs::World::for_each_direct_term_entity	(	Entity	term,
		void *	ctx,
		bool()(void , Entity)	func
	)		const

inline

Visits entities directly matching term, including semantic Is expansion.

Parameters

term	Query term
ctx	User context passed to func
func	bool(void*, Entity) callback executed for each matching entity.

Returns: False when func requested early stop. True otherwise.

◆ for_each_direct_term_entity_direct()

GAIA_NODISCARD bool gaia::ecs::World::for_each_direct_term_entity_direct	(	Entity	term,
		void *	ctx,
		bool()(void , Entity)	func
	)		const

inline

Visits entities directly matching term without semantic Is expansion.

Parameters

term	Query term
ctx	User context passed to func
func	bool(void*, Entity) callback executed for each matching entity.

Returns: False when func requested early stop. True otherwise.

◆ frame_cleanup()

void gaia::ecs::World::frame_cleanup ( )

inline

Performs deferred cleanup for the current frame.

This finalizes deferred entity deletion and runs Gaia-ECS garbage collection. Use this after an external loop calls systems_run() itself, or when a frame has no system pass but still needs world cleanup.

Warning: This does not execute registered systems. Call systems_run() first when the frame should run systems.; Do not call this from an observer callback. Debug builds assert this contract.

See also: systems_run(); frame_end(); update()

◆ frame_end()

void gaia::ecs::World::frame_end ( )

inline

Marks the end of the current frame.

This flushes pending log output and emits the profiler frame marker. External loops that call systems_run() directly should usually call frame_cleanup() and then frame_end() once per frame.

Warning: This does not execute registered systems or finalize deferred deletion.

See also: systems_run(); frame_cleanup(); update()

◆ get() [1/5]

template<typename T >

GAIA_NODISCARD Entity gaia::ecs::World::get ( ) const

inline

Returns the entity registered for component type T.

Template Parameters

T	Component type.

Returns: Component entity.

◆ get() [2/5]

GAIA_NODISCARD Entity gaia::ecs::World::get	(	const char *	name,
		uint32_t	len = `0`
	)		const

inline

Returns the entity assigned a name name. This is a convenience alias for resolve(name).

Parameters

name	Pointer to a stable null-terminated string
len	String length. If zero, the length is calculated

Returns: Matching entity. EntityBad if there is nothing to return.

◆ get() [3/5]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::get ( Entity entity ) const

inline

Returns the value stored in the component T on entity.

Template Parameters

T Component

Parameters

entity Entity

Returns: Value stored in the component.

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentGetter is created.

◆ get() [4/5]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::get	(	Entity	entity,
		Entity	object
	)		const

inline

Returns the value stored in the component associated with object on entity.

Template Parameters

T	Component type represented by `object`.

Parameters

entity	Entity to read, resolving inherited ownership when necessary.
object	Component entity selecting the payload.

Returns: Read-only component value or proxy.

◆ get() [5/5]

GAIA_NODISCARD Entity gaia::ecs::World::get ( EntityId id ) const

inline

Returns the entity located at the index id.

Parameters

id Entity id

Returns: Entity

◆ get_chunk() [1/2]

GAIA_NODISCARD Chunk * gaia::ecs::World::get_chunk ( Entity entity ) const

inline

Returns a chunk containing the entity.

Parameters

entity Entity

Returns: Chunk or nullptr if not found.

◆ get_chunk() [2/2]

GAIA_NODISCARD Chunk * gaia::ecs::World::get_chunk	(	Entity	entity,
		uint32_t &	row
	)		const

inline

Returns a chunk containing the entity. Index of the entity is stored in row.

Parameters

	entity	Entity
[out]	row	Row of entity within chunk

Returns: Chunk or nullptr if not found

◆ get_raw()

GAIA_NODISCARD ComponentRawView gaia::ecs::World::get_raw	(	Entity	entity,
		Entity	component
	)		const

inline

Returns raw read-only bytes for an AoS component or exact pair payload on entity. Inherited ids resolve to the owning entity. SoA and unsupported components return an invalid view.

Parameters

entity	Entity being read.
component	Component entity or exact relationship pair being read.

Returns: Raw payload view, or invalid view when the component cannot be resolved.

◆ get_raw_field()

GAIA_NODISCARD ComponentRawView gaia::ecs::World::get_raw_field	(	Entity	entity,
		Entity	component,
		uint32_t	fieldIdx
	)		const

inline

Returns one read-only field value from a directly addressed SoA field array. The field index follows the registered SoA field order. Inherited ids resolve to the owning entity.

Parameters

entity	Entity being read.
component	Runtime component entity being read.
fieldIdx	SoA field array index.

Returns: Raw field value view, or an invalid view when unavailable.

◆ get_serializer()

ser::serializer gaia::ecs::World::get_serializer ( ) const

inline

Returns the currently bound runtime serializer handle.

Returns: Bound serializer handle.

◆ has() [1/5]

GAIA_NODISCARD bool gaia::ecs::World::has ( Entity entity ) const

inline

Checks if entity is currently used by the world.

Parameters

entity Entity.

Returns: True if the entity is used. False otherwise.

◆ has() [2/5]

template<typename T >

GAIA_NODISCARD bool gaia::ecs::World::has ( Entity entity ) const

inline

Checks if entity contains the component T.

Template Parameters

T Component

Parameters

entity Entity

Returns: True if the component is present on entity.

Warning: It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ has() [3/5]

GAIA_NODISCARD bool gaia::ecs::World::has	(	Entity	entity,
		Entity	object
	)		const

inline

Checks if entity contains the entity object.

Parameters

entity	Entity
object	Tested entity

Returns: True if object is present on entity. False otherwise or if any of the entities is not valid.

Warning: It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ has() [4/5]

GAIA_NODISCARD bool gaia::ecs::World::has	(	Entity	entity,
		Pair	pair
	)		const

inline

Checks if entity contains pair.

Parameters

entity	Entity
pair	Tested pair

Returns: True if object is present on entity. False otherwise or if any of the entities is not valid.

Warning: It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ has() [5/5]

GAIA_NODISCARD bool gaia::ecs::World::has ( Pair pair ) const

inline

Checks if pair is currently used by the world.

Parameters

pair Pair

Returns: True if the entity is used. False otherwise.

◆ has_direct() [1/2]

GAIA_NODISCARD bool gaia::ecs::World::has_direct	(	Entity	entity,
		Entity	object
	)		const

inline

Checks if entity directly contains the entity object, without semantic inheritance expansion.

Parameters

entity	Entity
object	Tested entity

Returns: True if object is directly present on entity. False otherwise or if any of the entities is not valid.

◆ has_direct() [2/2]

GAIA_NODISCARD bool gaia::ecs::World::has_direct	(	Entity	entity,
		Pair	pair
	)		const

inline

Checks if entity directly contains pair, without semantic inheritance expansion.

Parameters

entity	Entity to inspect.
pair	Exact or wildcard pair to test.

Returns: True when pair is directly present. False otherwise.

◆ has_nonfragmenting_relation_pair()

GAIA_NODISCARD bool gaia::ecs::World::has_nonfragmenting_relation_pair	(	Entity	source,
		Entity	object
	)		const

inline

Checks whether a source matches a possibly wildcarded non-fragmenting relation pair.

Parameters

source	Source entity to inspect.
object	Exact or wildcard relation pair to match.

Returns: True when a stored non-fragmenting relation matches object. False otherwise.

◆ has_nonfragmenting_relation_target_cond()

GAIA_NODISCARD bool gaia::ecs::World::has_nonfragmenting_relation_target_cond	(	Entity	target,
		Pair	cond
	)		const

inline

Checks whether any non-fragmenting exclusive relation targeting target uses an OnDeleteTarget rule.

Parameters

target	Target entity referenced by stored non-fragmenting relations.
cond	OnDeleteTarget condition pair to test on each matching relation.

Returns: True when a matching relation has cond. False otherwise.

◆ has_sorted_queries()

GAIA_NODISCARD bool gaia::ecs::World::has_sorted_queries ( ) const

inline

Checks whether any cached sorted query is registered in this world.

Returns: True when at least one sorted query is cached.

◆ has_sorted_queries_for_entity()

GAIA_NODISCARD bool gaia::ecs::World::has_sorted_queries_for_entity ( Entity entity ) const

inline

Checks whether any cached sorted query depends on entity being written.

Parameters

entity Entity.

Returns: True when at least one cached sorted query reads a component of entity.

◆ in()

GAIA_NODISCARD bool gaia::ecs::World::in	(	Entity	entity,
		Entity	entityBase
	)		const

inline

Checks if entity is located in entityBase. This is almost the same as "is" with the exception that false is returned if entity matches entityBase.

Parameters

entity	Entity
entityBase	Base entity

Returns: True if entity is located in entityBase. False otherwise.

◆ instantiate() [1/2]

GAIA_NODISCARD Entity gaia::ecs::World::instantiate ( Entity prefabEntity )

inline

Instantiates a prefab as a normal entity. The instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, and adds a direct Pair(Is, prefabEntity) edge instead. Prefab children linked through Parent or ChildOf are instantiated with the same hierarchy relation.

Parameters

prefabEntity Prefab entity to instantiate.

Returns: Spawned root instance, or a plain copy when prefabEntity is not marked Prefab.

◆ instantiate() [2/2]

GAIA_NODISCARD Entity gaia::ecs::World::instantiate	(	Entity	prefabEntity,
		Entity	parentInstance
	)

inline

Instantiates a prefab as a normal entity parented under parentInstance. The instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, adds a direct Pair(Is, prefabEntity) edge instead, and attaches Pair(Parent, parentInstance) to the new root instance. Prefab children linked through Parent or ChildOf are instantiated with the same hierarchy relation.

Parameters

prefabEntity	Prefab entity to instantiate.
parentInstance	Entity receiving the spawned root through Parent.

Returns: Spawned root instance, or a parented plain copy when prefabEntity is not marked Prefab.

◆ instantiate_n() [1/3]

void gaia::ecs::World::instantiate_n	(	Entity	prefabEntity,
		Entity	parentInstance,
		uint32_t	count
	)

inline

Instantiates count copies of a prefab as normal root entities parented under parentInstance. Each spawned root instance receives a direct Pair(Parent, parentInstance) relationship. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

Parameters

prefabEntity	Prefab entity to clone
parentInstance	Parent entity attached to each spawned root instance
count	Number of clones to make

◆ instantiate_n() [2/3]

template<typename Func >

void gaia::ecs::World::instantiate_n	(	Entity	prefabEntity,
		Entity	parentInstance,
		uint32_t	count,
		Func	func
	)

inline

Instantiates count copies of a prefab as normal root entities, assigning a direct Pair(Parent, parentInstance) relationship when parentInstance is not EntityBad. The callback is invoked for each spawned root instance after its subtree has been instantiated. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

Template Parameters

Func	Callback type. It can be either void(ecs::Entity) or void(ecs::CopyIter&).

Parameters

prefabEntity	Prefab entity to clone
parentInstance	Parent entity attached to each spawned root instance, or EntityBad for unparented roots
count	Number of clones to make
func	Functor executed for spawned root instances.

◆ instantiate_n() [3/3]

template<typename Func = TFunc_Void_With_Entity>

void gaia::ecs::World::instantiate_n	(	Entity	prefabEntity,
		uint32_t	count,
		Func	func = `func_void_with_entity`
	)

inline

Instantiates count copies of a prefab as normal root entities. Each instance copies the prefab's direct data, drops the Prefab tag, does not copy the name, removes the prefab's direct Is edges, and adds a direct Pair(Is, prefabEntity) edge instead. Recursively instantiated prefab children keep their Parent or ChildOf hierarchy relation.

Template Parameters

Func	Callback type. It can be either void(ecs::Entity) or void(ecs::CopyIter&).

Parameters

prefabEntity	Prefab entity to clone
count	Number of clones to make
func	Functor executed for spawned root instances. It can be either void(ecs::Entity) or void(ecs::CopyIter&).

Warning: It is expected prefabEntity is valid entity. Undefined behavior otherwise.; If EntityDesc is present on prefabEntity, it is not copied because names are expected to be unique. Instead, the copied entity will be a part of an archetype without EntityDesc and any calls to World::name(copiedEntity) will return an empty view.

◆ invalidate_queries_for_entity()

void gaia::ecs::World::invalidate_queries_for_entity ( Pair is_pair )

inline

Invalidates semantic Is queries affected by removing or changing is_pair.

Parameters

is_pair Is pair

◆ invalidate_queries_for_rel()

void gaia::ecs::World::invalidate_queries_for_rel ( Entity relation )

inline

Invalidates cached queries whose dynamic result depends on relation.

Parameters

relation Relation whose dependent query results are invalidated.

◆ invalidate_queries_for_structural_entity()

void gaia::ecs::World::invalidate_queries_for_structural_entity ( EntityLookupKey entityKey )

inline

Invalidates cached queries structurally affected by entityKey.

Parameters

entityKey Structural entity lookup key

◆ invalidate_sorted_queries_for_entity()

void gaia::ecs::World::invalidate_sorted_queries_for_entity ( Entity entity )

inline

Invalidates cached sorted queries whose row ordering depends on entity.

Parameters

entity Entity.

◆ is()

GAIA_NODISCARD bool gaia::ecs::World::is	(	Entity	entity,
		Entity	entityBase
	)		const

inline

Checks if entity inherits from entityBase.

Parameters

entity	Entity
entityBase	Base entity

Returns: True if entity is located in entityBase. False otherwise.

◆ is_base()

GAIA_NODISCARD bool gaia::ecs::World::is_base ( Entity target ) const

inline

Checks whether an entity is the target of at least one direct Is relation.

Parameters

target Candidate base entity.

Returns: True when target has a derived entity. False otherwise.

◆ is_dont_fragment()

GAIA_NODISCARD bool gaia::ecs::World::is_dont_fragment ( Entity entity ) const

inline

Returns whether entity is marked DontFragment.

Parameters

entity Entity

Returns: True if entity is marked DontFragment. False otherwise.

◆ is_req_del()

static GAIA_NODISCARD bool gaia::ecs::World::is_req_del ( const EntityContainer & ec )

inlinestatic

Returns whether the record is already in delete-requested state. Covers both explicit per-entity deletion and archetype-level forced teardown.

Parameters

ec	Entity container record

Returns: True if the record is marked for deletion. False otherwise.

◆ load() [1/2]

bool gaia::ecs::World::load ( ser::serializer inputSerializer = {} )

inline

Loads a world state from a buffer. The buffer is sought to 0 before any loading happens. NOTE: In order for custom version of load to be used for a given component, it needs to have either of the following functions defined: 1) member function: "void load(bin_stream& s)" 2) free function in gaia::ser namespace: "void tag_invoke(gaia::ser::load_v, bin_stream& s, YourType& data)".

Parameters

inputSerializer Serializer to read from, or an invalid handle to use the world's bound serializer.

Returns: True when the snapshot version is supported and all world data loads successfully. False otherwise.

◆ load() [2/2]

template<typename TSerializer >

bool gaia::ecs::World::load ( TSerializer & inputSerializer )

inline

Loads a world state from a serializer-compatible stream wrapper.

Parameters

inputSerializer Input serializer

Returns: True when loading succeeds. False otherwise.

◆ locked()

GAIA_NODISCARD bool gaia::ecs::World::locked ( ) const

inline

Checks if the chunk is locked for structural changes.

Returns: True while at least one structural-change lock is held. False otherwise.

◆ lookup_path() [1/2]

GAIA_NODISCARD std::span< const Entity > gaia::ecs::World::lookup_path ( ) const

inline

Returns the ordered component lookup path used for unqualified component lookup. Each scope is searched like a temporary component scope: the scope first, then its parents.

Returns: View of the configured lookup scopes.

◆ lookup_path() [2/2]

void gaia::ecs::World::lookup_path ( std::span< const Entity > scopes )

inline

Replaces the ordered component lookup path used for unqualified component lookup. Each scope is searched in the order provided, and each scope walk includes its parents.

Parameters

scopes Ordered lookup scopes. Pass an empty span to clear the lookup path.

◆ modify() [1/2]

template<typename T >

void gaia::ecs::World::modify ( Entity entity )

inline

Marks the component type T as modified. Best used with acc_mut().sset() or set() to manually trigger an update at user's whim. If TriggerSetEffects is true, also triggers the component's set side effects: set hooks and OnSet observers.

Template Parameters

T	Component type
TriggerSetEffects	Triggers set side effects if true

Parameters

entity Entity whose component version is updated.

◆ modify() [2/2]

template<typename T >

void gaia::ecs::World::modify	(	Entity	entity,
		Entity	object
	)

inline

Marks the component associated with object as modified on entity. Best used with mut<T>(entity, object) or sset<T>(entity, object) to manually trigger an update at user's whim. If TriggerSetEffects is true, also triggers the component's set side effects: set hooks and OnSet observers.

Template Parameters

T	Component type
TriggerSetEffects	Triggers set side effects if true

Parameters

entity	Entity whose component version is updated.
object	Component entity associated with `T`.

◆ modify_raw()

void gaia::ecs::World::modify_raw	(	Entity	entity,
		Entity	component
	)

inline

Marks a raw payload or SoA field returned by a mutable raw view as modified and emits normal set side effects.

Parameters

entity	Entity whose raw component payload was mutated.
component	Runtime component entity previously passed to mut_raw().

◆ module()

Entity gaia::ecs::World::module	(	const char *	path,
		uint32_t	len = `0`
	)

inline

Finds or builds a named module hierarchy and returns the deepest scope entity. Each path segment is mapped to an entity name and connected with ChildOf relationships.

Parameters

path	Dotted module path such as "gameplay.render".
len	String length. If zero, the length is calculated.

Returns: Deepest module entity, or EntityBad when the path is invalid.

Warning: This only builds the scope hierarchy. Use scope(...) to activate it.

◆ mut() [1/2]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::mut ( Entity entity )

inline

Returns a mutable reference or proxy to the component on entity without triggering a world version update. This is a silent raw write path. Call modify<T, true>(entity) when you need hooks or OnSet.

Template Parameters

T Component

Parameters

entity Entity

Returns: Mutable reference or proxy to the component payload.

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ mut() [2/2]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::mut	(	Entity	entity,
		Entity	object
	)

inline

Returns a mutable reference or proxy to the component associated with object on entity. This is a silent raw write path. Call modify<T, true>(entity, object) when you need hooks or OnSet.

Template Parameters

T	Component type represented by `object`.

Parameters

entity	Entity owning the component.
object	Component entity selecting the payload.

Returns: Mutable reference or proxy to the component payload.

◆ mut_raw()

GAIA_NODISCARD ComponentRawMutView gaia::ecs::World::mut_raw	(	Entity	entity,
		Entity	component
	)

inline

Returns raw mutable bytes for a directly owned AoS component or exact pair payload. This is a silent write path. Pair with modify_raw() to emit set hooks and OnSet observers.

Parameters

entity	Entity being mutated.
component	Component entity or exact relationship pair being mutated.

Returns: Raw mutable payload view, or invalid view when the component is absent or unsupported.

◆ mut_raw_field()

GAIA_NODISCARD ComponentRawMutView gaia::ecs::World::mut_raw_field	(	Entity	entity,
		Entity	component,
		uint32_t	fieldIdx
	)

inline

Returns one mutable field value from a directly owned SoA field array. This is a silent write path. Pair with modify_raw() to emit set hooks and OnSet observers.

Parameters

entity	Entity being mutated.
component	Runtime component entity being mutated.
fieldIdx	SoA field array index.

Returns: Mutable raw field value view, or an invalid view when unavailable.

◆ name() [1/3]

GAIA_NODISCARD util::str_view gaia::ecs::World::name ( Entity entity ) const

inline

Returns the name assigned to entity.

Parameters

entity Entity

Returns: Name assigned to entity. Empty view when there is no name.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ name() [2/3]

void gaia::ecs::World::name	(	Entity	entity,
		const char *	name,
		uint32_t	len = `0`
	)

inline

Assigns a name to entity. Ignored if used with pair. The string is copied and kept internally.

Parameters

entity	Entity
name	A null-terminated string
len	String length. If zero, the length is calculated

Warning: It is expected entity is valid. Undefined behavior otherwise.; Name is expected to be unique. If it is not this function does nothing.; The name can't contain the character '.'. This character is reserved for hierarchical lookups such as "parent.child.subchild".

◆ name() [3/3]

GAIA_NODISCARD util::str_view gaia::ecs::World::name ( EntityId entityId ) const

inline

Returns the entity name assigned to entityId.

Parameters

entityId EntityId

Returns: Name assigned through the entity naming API. Empty view when there is no entity name.

Warning: It is expected entityId is valid. Undefined behavior otherwise.

◆ name_raw()

void gaia::ecs::World::name_raw	(	Entity	entity,
		const char *	name,
		uint32_t	len = `0`
	)

inline

Assigns a name to entity. Ignored if used with pair. The string is NOT copied. Your are responsible for its lifetime.

Parameters

entity	Entity
name	Pointer to a stable null-terminated string
len	String length. If zero, the length is calculated

Warning: It is expected entity is valid. Undefined behavior otherwise.; The name is expected to be unique. If it is not this function does nothing.; The name can't contain the character '.'. This character is reserved for hierarchical lookups such as "parent.child.subchild".; In this case the string is NOT copied and NOT stored internally. You are responsible for its lifetime. The pointer, contents, and length need to stay stable. Otherwise, any time your storage tries to move or rewrite the string you have to unset the name before it happens and set it anew after the change is done.

◆ name_to_entity()

Entity gaia::ecs::World::name_to_entity ( std::span< const char > exprRaw ) const

inline

Resolves a textual id expression to an entity. Supports names, aliases, wildcard *, and pair expressions like (Rel, Target).

Parameters

exprRaw Expression text

Returns: Resolved entity or EntityBad on failure.

◆ nonfragmenting_relation_del()

bool gaia::ecs::World::nonfragmenting_relation_del	(	Entity	source,
		Entity	relation,
		Entity	target
	)

inline

Removes an exclusive non-fragmenting relation from a source entity.

Parameters

source	Source entity whose relation is removed.
relation	Non-fragmenting relation entity.
target	Expected target, or EntityBad to remove the current target unconditionally.

Returns: True when a stored relation was removed. False otherwise.

◆ nonfragmenting_relation_set() [1/2]

void gaia::ecs::World::nonfragmenting_relation_set	(	Entity	source,
		Entity	relation,
		Entity	target
	)

inline

Sets an exclusive non-fragmenting relation target, creating its store when necessary.

Parameters

source	Source entity whose target is replaced.
relation	Non-fragmenting relation entity.
target	New target entity.

◆ nonfragmenting_relation_set() [2/2]

void gaia::ecs::World::nonfragmenting_relation_set	(	NonFragmentingRelationStore &	store,
		Entity	source,
		Entity	relation,
		Entity	target
	)

inline

Sets an exclusive non-fragmenting relation target in an existing store.

Parameters

store	Relation store to update.
source	Source entity whose target is replaced.
relation	Non-fragmenting relation entity represented by `store`.
target	New target entity.

◆ nonfragmenting_relation_store()

GAIA_NODISCARD const NonFragmentingRelationStore * gaia::ecs::World::nonfragmenting_relation_store ( Entity relation ) const

inline

Returns the non-fragmenting relation store for relation, or nullptr when absent.

Parameters

relation Relation entity

Returns: Non-fragmenting relation store or nullptr if absent.

◆ nonfragmenting_relation_store_mut()

GAIA_NODISCARD NonFragmentingRelationStore & gaia::ecs::World::nonfragmenting_relation_store_mut ( Entity relation )

inline

Returns the non-fragmenting relation store for relation, creating it if needed.

Parameters

relation Relation entity

Returns: Mutable non-fragmenting relation store reference.

◆ override() [1/4]

template<typename T >

GAIA_NODISCARD bool gaia::ecs::World::override ( Entity entity )

inline

Materializes an inherited typed component as directly owned storage on entity.

Template Parameters

T	Component type to materialize.

Parameters

entity Entity receiving the local override.

Returns: True when a local override was created. False if nothing changed.

◆ override() [2/4]

GAIA_NODISCARD bool gaia::ecs::World::override	(	Entity	entity,
		Entity	object
	)

inline

Materializes an inherited id as directly owned storage on entity.

Parameters

entity	Entity receiving the local override.
object	Inherited component or pair id to materialize.

Returns: True when a local override was created. False if nothing changed.

◆ override() [3/4]

template<typename T >

GAIA_NODISCARD bool gaia::ecs::World::override	(	Entity	entity,
		Entity	object
	)

inline

Materializes an inherited typed component associated with object on entity.

Template Parameters

T	Component type represented by `object`.

Parameters

entity	Entity receiving the local override.
object	Inherited component entity to materialize.

Returns: True when a local override was created. False if nothing changed.

◆ override() [4/4]

GAIA_NODISCARD bool gaia::ecs::World::override	(	Entity	entity,
		Pair	pair
	)

inline

Materializes an inherited pair as directly owned storage on entity.

Parameters

entity	Entity receiving the local override.
pair	Inherited pair to materialize.

Returns: True when a local override was created. False if nothing changed.

◆ pair_target_if_alive()

GAIA_NODISCARD Entity gaia::ecs::World::pair_target_if_alive ( Entity pair ) const

inline

Resolves the target of an archetype-stored exact pair id, skipping stale cleanup-time targets.

Parameters

pair	Exact relationship pair whose target is resolved.

Returns: Live target entity, or EntityBad when its id is stale or absent.

◆ parent() [1/2]

void gaia::ecs::World::parent	(	Entity	entity,
		Entity	parentEntity
	)

inline

Adds a direct non-fragmenting Parent relationship to parentEntity. The relationship is non-fragmenting and does not participate in archetype identity.

Parameters

entity	Entity to inspect.
parentEntity	Candidate parent entity.

◆ parent() [2/2]

GAIA_NODISCARD bool gaia::ecs::World::parent	(	Entity	entity,
		Entity	parentEntity
	)		const

inline

Checks whether entity has a direct non-fragmenting Parent relationship to parentEntity.

Parameters

entity	Entity to inspect.
parentEntity	Candidate parent entity.

Returns: True if entity references parentEntity through Parent. False otherwise.

◆ path() [1/3]

GAIA_NODISCARD Entity gaia::ecs::World::path	(	const char *	path,
		uint32_t	len = `0`
	)		const

inline

Finds a component entity by its exact scoped path.

Parameters

path	Exact component path.
len	String length. If zero, the length is calculated.

Returns: Matching component entity. EntityBad when no exact path match exists.

◆ path() [2/3]

GAIA_NODISCARD util::str_view gaia::ecs::World::path ( Entity component ) const

inline

Returns the scoped path name for a component entity.

Parameters

component Component entity.

Returns: Scoped component path. Empty view when no path is assigned or component is not cached.

◆ path() [3/3]

bool gaia::ecs::World::path	(	Entity	component,
		const char *	path,
		uint32_t	len = `0`
	)

inline

Assigns a scoped path name to a component entity.

Parameters

component	Component entity.
path	Path to assign. Pass nullptr to clear the current path.
len	String length. If zero, the length is calculated.

Returns: True when the path metadata changed, false otherwise.

◆ prefab()

GAIA_NODISCARD Entity gaia::ecs::World::prefab ( EntityKind kind = EntityKind::EK_Gen )

inline

Creates a new prefab entity.

Parameters

kind	Entity kind. Generic entity by default.

Returns: New prefab entity.

◆ query()

Query gaia::ecs::World::query ( )

inline

Provides a cached query set up to work with the parent world. Cached queries use local scope by default.

Returns: Valid query object

◆ query_buffer()

QuerySerBuffer & gaia::ecs::World::query_buffer ( QueryId & serId )

inline

Returns the temporary serialization buffer used while building a query. A fresh query id is allocated lazily when serId is QueryIdBad.

Parameters

serId Query serialization id

Returns: Serialization buffer associated with serId.

◆ query_buffer_reset()

void gaia::ecs::World::query_buffer_reset ( QueryId & serId )

inline

Releases the temporary serialization buffer associated with serId.

Parameters

serId Query serialization id reset to QueryIdBad on return.

◆ reg_comp()

template<typename T >

GAIA_NODISCARD const ComponentCacheItem & gaia::ecs::World::reg_comp ( )

inline

Returns the registered component cache item for T, auto-registering it when enabled.

Template Parameters

T	Component type.

Returns: Component cache item for T.

◆ rel_version()

GAIA_NODISCARD uint32_t gaia::ecs::World::rel_version ( Entity relation ) const

inline

Returns structural version for a given relation. Increments whenever any Pair(relation, *) is added or removed on any entity.

Parameters

relation Relation whose structural version is requested.

Returns: Current relation version, or zero when the relation has not changed.

◆ relation()

GAIA_NODISCARD Entity gaia::ecs::World::relation	(	Entity	entity,
		Entity	target
	)		const

inline

Returns the first relationship relation for the target entity on entity.

Parameters

entity	Source entity
target	Target entity

Returns: Relationship target. EntityBad if there is nothing to return.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ relation_depth_order_prunes_disabled_subtrees()

GAIA_NODISCARD bool gaia::ecs::World::relation_depth_order_prunes_disabled_subtrees ( Entity relation ) const

inline

Returns true when depth-ordered iteration may safely prune disabled subtrees at archetype level. Only fragmenting hierarchy relations qualify because all rows in the archetype then share the same direct parent and therefore the same ancestor chain.

Parameters

relation Relation entity to inspect.

Returns: True when disabled subtrees can be pruned at archetype granularity. False otherwise.

◆ relation_is_fragmenting()

GAIA_NODISCARD bool gaia::ecs::World::relation_is_fragmenting ( Entity relation ) const

inline

Returns true when the relation still participates in archetype identity. Non-fragmenting relations such as Parent are excluded.

Parameters

relation Relation entity to inspect.

Returns: True when relation participates in archetype identity. False otherwise.

◆ relation_is_fragmenting_hierarchy()

GAIA_NODISCARD bool gaia::ecs::World::relation_is_fragmenting_hierarchy ( Entity relation ) const

inline

Returns true for hierarchy relations that still fragment archetypes. ChildOf satisfies this today, while Parent intentionally does not.

Parameters

relation Relation entity to inspect.

Returns: True when relation is both hierarchical and fragmenting. False otherwise.

◆ relation_is_hierarchy()

GAIA_NODISCARD bool gaia::ecs::World::relation_is_hierarchy ( Entity relation ) const

inline

Returns true for hierarchy-like relations whose targets form an exclusive traversable parent chain. ChildOf and Parent satisfy this today. DependsOn intentionally does not.

Parameters

relation Relation entity to inspect.

Returns: True when relation is exclusive and traversable. False otherwise.

◆ relation_is_non_fragmenting()

GAIA_NODISCARD bool gaia::ecs::World::relation_is_non_fragmenting ( Entity relation ) const

inline

Returns whether relation is non-fragmenting.

Parameters

relation Relation entity

Returns: True if relation is valid and non-fragmenting. False otherwise.

◆ relation_supports_depth_order()

GAIA_NODISCARD bool gaia::ecs::World::relation_supports_depth_order ( Entity relation ) const

inline

Returns true when the relation can drive cached depth-ordered iteration. This requires a fragmenting relation whose target participates in archetype identity, such as ChildOf, DependsOn, or a custom fragmenting relation. Cycles are still invalid and are diagnosed by the depth cache itself.

Parameters

relation Relation entity to inspect.

Returns: True when relation can provide archetype-level depth ordering. False otherwise.

◆ relation_uses_non_fragmenting_storage()

GAIA_NODISCARD bool gaia::ecs::World::relation_uses_non_fragmenting_storage ( Entity relation ) const

inline

Returns whether relation uses non-fragmenting relation storage. Only exclusive non-fragmenting relations use this storage path.

Parameters

relation Relation entity

Returns: True if relation uses non-fragmenting relation storage. False otherwise.

◆ relations() [1/2]

template<typename Func >

void gaia::ecs::World::relations	(	Entity	entity,
		Entity	target,
		Func	func
	)		const

inline

Returns the relationship relations for the target entity on entity.

Parameters

entity	Source entity
target	Target entity
func	void(Entity relation) functor executed for relationship relation found.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ relations() [2/2]

GAIA_NODISCARD const cnt::set< EntityLookupKey > * gaia::ecs::World::relations ( Entity target ) const

inline

Returns relations for target.

Parameters

target Target entity

Returns: Set of relations that reference target, or nullptr when none do.

Warning: It is expected target is valid. Undefined behavior otherwise.

◆ relations_if()

template<typename Func >

void gaia::ecs::World::relations_if	(	Entity	entity,
		Entity	target,
		Func	func
	)		const

inline

Returns the relationship relations for the target entity on entity.

Parameters

entity	Source entity
target	Target entity
func	bool(Entity relation) functor executed for relationship relation found. Stops if false is returned.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ remove_src_entity_version()

void gaia::ecs::World::remove_src_entity_version ( Entity entity )

inline

Removes sparse source-version state for an entity that is being destroyed.

Parameters

entity Source entity whose tracked version entry is removed.

◆ resolve() [1/2]

void gaia::ecs::World::resolve	(	cnt::darray< Entity > &	out,
		const char *	name,
		uint32_t	len = `0`
	)		const

inline

Collects every entity and component entity that matches name. This is useful for diagnostics when a short lookup could refer to multiple scoped components.

Parameters

[out]	out	Output array cleared and then filled with unique matching entities.
	name	Pointer to a stable null-terminated string.
	len	String length. If zero, the length is calculated.

◆ resolve() [2/2]

GAIA_NODISCARD Entity gaia::ecs::World::resolve	(	const char *	name,
		uint32_t	len = `0`
	)		const

inline

Resolves name in the world naming system. Entity names and hierarchical entity paths are attempted first. If they do not match, component lookup uses the current scope, then the lookup path, then global component symbol, path and alias lookup.

Parameters

name	Pointer to a stable null-terminated string
len	String length. If zero, the length is calculated

Returns: Matching entity. EntityBad when no entity or component matches.

◆ runtime_counters()

void gaia::ecs::World::runtime_counters	(	uint32_t &	outArchetypes,
		uint32_t &	outChunks,
		uint32_t &	outEntitiesTotal,
		uint32_t &	outEntitiesActive
	)		const

inline

Returns high-level runtime counters useful for diagnostics/telemetry.

Parameters

[out]	outArchetypes	Number of allocated archetypes, including deletion-pending archetypes.
[out]	outChunks	Number of chunks owned by those archetypes.
[out]	outEntitiesTotal	Total rows across those chunks.
[out]	outEntitiesActive	Enabled rows across those chunks.

◆ sched()

GAIA_NODISCARD const Sched & gaia::ecs::World::sched ( ) const

inline

Returns the resolved scheduler used by this world.

Returns: Bound scheduler or the default scheduler when none was installed.

◆ scope() [1/3]

GAIA_NODISCARD Entity gaia::ecs::World::scope ( ) const

inline

Returns the current component scope used for component registration and relative component lookup.

Returns: Scoped entity or EntityBad when component scope is disabled.

◆ scope() [2/3]

Entity gaia::ecs::World::scope ( Entity scope )

inline

Sets the current component scope used for component registration and relative component lookup. The scope entity and its ChildOf ancestors are expected to have names so we can build a path from them.

Parameters

scope Scope entity. Pass EntityBad to clear the current component scope.

Returns: Previous component scope.

◆ scope() [3/3]

template<typename Func >

void gaia::ecs::World::scope	(	Entity	scopeEntity,
		Func &&	func
	)

inline

Executes func with a temporary component scope and restores the previous scope afterwards. Relative component lookup walks up the ChildOf hierarchy of the active scope. The scope entity and its ChildOf ancestors are expected to have names so we can build a path from them.

Parameters

scopeEntity	Scope entity. Pass EntityBad to temporarily disable component scope.
func	Callable executed while the scope is active.

◆ set() [1/2]

template<typename T >

GAIA_NODISCARD auto gaia::ecs::World::set ( Entity entity )

inline

Returns a write-back proxy for the component T on entity. The proxy copies the current value, lets the caller mutate it, then writes it back at the end of the full expression or scope. OnSet observers and chunk-backed set hooks are triggered only after the write-back completes.

Template Parameters

T Component

Parameters

entity Entity

Returns: Write-back proxy

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype before the proxy writes the value back.

◆ set() [2/2]

template<typename T >

GAIA_NODISCARD auto gaia::ecs::World::set	(	Entity	entity,
		Entity	object
	)

inline

Returns a write-back proxy for the component associated with object on entity. The proxy copies the current value, lets the caller mutate it, then writes it back at the end of the full expression or scope. OnSet observers and chunk-backed set hooks are triggered only after the write-back completes.

Template Parameters

T Component

Parameters

entity	Entity
object	Component entity

Returns: Write-back proxy

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype before the proxy writes the value back.

◆ set_component_dont_fragment()

void gaia::ecs::World::set_component_dont_fragment	(	Entity	component,
		EntityContainer &	ec
	)

inline

Latches DontFragment on a component entity record. This first moves the payload out of chunks, then removes the id from archetype identity.

Parameters

component	Component entity.
ec	Component entity container.

◆ set_component_sparse_storage()

void gaia::ecs::World::set_component_sparse_storage ( Entity component )

inline

Latches Sparse storage on a component entity before any instances exist. This moves the payload out of chunks while keeping the id in archetype identity. Only plain generic AoS components are supported.

Parameters

component Component entity.

◆ set_max_lifespan()

void gaia::ecs::World::set_max_lifespan	(	Entity	entity,
		uint32_t	lifespan = `Archetype::MAX_ARCHETYPE_LIFESPAN`
	)

inline

Sets maximal lifespan of an archetype entity belongs to.

Parameters

entity	Entity
lifespan	How many world updates an empty archetype is kept. If zero, the archetype it kept indefinitely.

◆ set_raw()

bool gaia::ecs::World::set_raw	(	Entity	entity,
		Entity	component,
		const void *	data,
		uint32_t	size
	)

inline

Replaces raw bytes for a directly owned AoS component and finishes the write.

Parameters

entity	Entity whose component is being replaced.
component	Runtime component entity or exact relationship pair.
data	Payload bytes. Must be non-null when the component size is non-zero.
size	Payload byte count. Must match the registered component size.

Returns: True when the component was updated.

◆ set_sched()

void gaia::ecs::World::set_sched ( const Sched & sched )

inline

Installs a custom scheduler used by ECS parallel execution paths.

Parameters

sched Scheduler descriptor to bind to this world.

◆ set_serializer() [1/2]

void gaia::ecs::World::set_serializer ( ser::serializer serializer )

inline

Binds a pre-built runtime serializer handle.

Parameters

serializer Serializer handle to store.

◆ set_serializer() [2/2]

template<typename TSerializer >

void gaia::ecs::World::set_serializer ( TSerializer & serializer )

inline

Binds a concrete serializer object through ser::make_serializer().

Parameters

serializer Serializer instance to wrap.

◆ size()

GAIA_NODISCARD uint32_t gaia::ecs::World::size ( ) const

inline

Returns the number of active entities.

Returns: Entity

◆ sources()

template<typename Func >

void gaia::ecs::World::sources	(	Entity	relation,
		Entity	target,
		Func	func
	)		const

inline

Returns relationship sources for the relation and target.

Parameters

relation	Relation entity
target	Target entity
func	void(Entity source) functor executed for each source entity found.

Warning: It is expected relation and target are valid. Undefined behavior otherwise.

◆ sources_all_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::sources_all_cache ( Entity target ) const

inline

Returns the cached deduped direct sources for wildcard source traversal on target. The cache is keyed by target and cleared whenever a pair edge changes.

Parameters

target Entity whose direct pair sources are requested.

Returns: Cached unique direct sources referencing target.

◆ sources_bfs()

template<typename Func >

void gaia::ecs::World::sources_bfs	(	Entity	relation,
		Entity	rootTarget,
		Func	func
	)		const

inline

Traverses relationship sources in breadth-first order. Starting at rootTarget, this visits all direct sources first and then deeper levels.

Parameters

relation	Relation entity
rootTarget	Root target entity
func	void(Entity source) functor executed for each traversed source.

◆ sources_bfs_if()

template<typename Func >

GAIA_NODISCARD bool gaia::ecs::World::sources_bfs_if	(	Entity	relation,
		Entity	rootTarget,
		Func	func
	)		const

inline

Traverses relationship sources in breadth-first order. Starting at rootTarget, this visits all direct sources first and then deeper levels.

Parameters

relation	Relation entity
rootTarget	Root target entity
func	bool(Entity source) functor executed for each traversed source. Stops if true is returned.

Returns: True if traversal was stopped by func, false otherwise.

◆ sources_bfs_trav_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::sources_bfs_trav_cache	(	Entity	relation,
		Entity	rootTarget
	)		const

inline

Returns the cached unlimited breadth-first descendant traversal for (relation, rootTarget). The cache excludes the root target itself and is cleared whenever a pair edge changes.

Parameters

relation	Relation defining descendant edges.
rootTarget	Target entity where traversal starts.

Returns: Cached descendants in deterministic breadth-first order.

◆ sources_if()

template<typename Func >

void gaia::ecs::World::sources_if	(	Entity	relation,
		Entity	target,
		Func	func
	)		const

inline

Returns relationship sources for the relation and target.

Parameters

relation	Relation entity
target	Target entity
func	bool(Entity source) functor executed for each source entity found. Stops if false is returned.

Warning: It is expected relation and target are valid. Undefined behavior otherwise.

◆ sparse_component_add_value()

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::sparse_component_add_value	(	Entity	component,
		Entity	entity
	)

inline

Adds or returns a sparse value through the store's erased payload interface.

Template Parameters

T	Expected payload type.

Parameters

component	Sparse component entity.
entity	Entity owning the value.

Returns: Mutable typed payload reference.

◆ sparse_component_get_value()

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::sparse_component_get_value	(	Entity	component,
		Entity	entity
	)		const

inline

Returns a read-only sparse value through the store's erased payload interface.

Template Parameters

T	Expected payload type.

Parameters

component	Sparse component entity.
entity	Entity owning the value.

Returns: Read-only typed payload reference.

◆ sparse_component_mut_value()

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::sparse_component_mut_value	(	Entity	component,
		Entity	entity
	)

inline

Returns a mutable sparse value through the store's erased payload interface.

Template Parameters

T	Expected payload type.

Parameters

component	Sparse component entity.
entity	Entity owning the value.

Returns: Mutable typed payload reference.

◆ sparse_component_store() [1/2]

template<typename T >

GAIA_NODISCARD SparseComponentStore< T > * gaia::ecs::World::sparse_component_store ( Entity component )

inline

Returns the sparse component store for component, or nullptr if it does not exist.

Template Parameters

T	Component payload type stored in the sparse store.

Parameters

component Component entity identifying the store.

Returns: Pointer to the sparse store, or nullptr when absent.

◆ sparse_component_store() [2/2]

template<typename T >

GAIA_NODISCARD const SparseComponentStore< T > * gaia::ecs::World::sparse_component_store ( Entity component ) const

inline

Returns the sparse component store for component, or nullptr if it does not exist.

Template Parameters

T	Component payload type stored in the sparse store.

Parameters

component Component entity identifying the store.

Returns: Pointer to the sparse store, or nullptr when absent.

◆ sparse_component_store_erased()

GAIA_NODISCARD const SparseComponentStoreErased * gaia::ecs::World::sparse_component_store_erased ( Entity component ) const

inline

Returns the erased sparse store for component, or nullptr when absent.

Parameters

component Sparse component entity.

Returns: Erased sparse store, or nullptr when no values have been stored.

◆ sparse_component_store_erased_mut()

GAIA_NODISCARD SparseComponentStoreErased & gaia::ecs::World::sparse_component_store_erased_mut	(	Entity	component,
		const ComponentCacheItem &	item
	)

inline

Returns the erased sparse store for component, creating runtime-sized storage when absent.

Parameters

component	Sparse component entity.
item	Runtime component metadata controlling payload size, alignment, and lifecycle.

Returns: Mutable erased sparse store.

◆ sparse_component_store_mut()

template<typename T >

GAIA_NODISCARD SparseComponentStore< T > & gaia::ecs::World::sparse_component_store_mut ( Entity component )

inline

Returns the sparse component store for component, creating it if needed.

Template Parameters

T	Component payload type stored in the sparse store.

Parameters

component Component entity identifying the store.

Returns: Mutable sparse store reference.

◆ sparse_copy_adds_id_inter()

GAIA_NODISCARD bool gaia::ecs::World::sparse_copy_adds_id_inter ( Entity comp ) const

inline

Checks whether copying a sparse payload must also add its id to the destination entity.

Parameters

comp	Sparse component entity being copied.

Returns: True for non-fragmenting sparse components. False otherwise.

◆ sparse_storage_mode()

GAIA_NODISCARD SparseStorageMode gaia::ecs::World::sparse_storage_mode ( Entity component ) const

inline

Returns the sparse storage mode used by a component.

Parameters

component Component entity to inspect.

Returns: Sparse storage mode, or SparseStorageMode::None when the component is not sparse.

◆ sset() [1/2]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::sset ( Entity entity )

inline

Returns silent mutable access to component type T on entity. This is a silent write and does not trigger set hooks or OnSet observers.

Template Parameters

T Component

Parameters

entity Entity

Returns: Mutable reference or proxy to the component payload.

Warning: It is expected the component is present on entity. Undefined behavior otherwise.; It is expected entity is valid. Undefined behavior otherwise.; Undefined behavior if entity changes archetype after ComponentSetter is created.

◆ sset() [2/2]

template<typename T >

GAIA_NODISCARD decltype(auto) gaia::ecs::World::sset	(	Entity	entity,
		Entity	object
	)

inline

Sets the value of the component associated with object on entity without updating world version. This is a silent write and does not trigger set hooks or OnSet observers.

Template Parameters

T	Component type represented by `object`.

Parameters

entity	Entity owning the component.
object	Component entity selecting the payload.

Returns: Mutable reference or proxy to the component payload.

◆ supports_sparse_component_storage()

template<typename T >

static GAIA_NODISCARD constexpr bool gaia::ecs::World::supports_sparse_component_storage ( )

inlinestaticconstexpr

Sparse storage currently supports only plain generic components. Pairs, unique components and SoA layouts stay on the normal archetype path.

Template Parameters

T	Component type to inspect.

Returns: True when T can use the sparse storage path.

◆ symbol() [1/2]

GAIA_NODISCARD Entity gaia::ecs::World::symbol	(	const char *	symbol,
		uint32_t	len = `0`
	)		const

inline

Finds a component entity by its exact registered symbol.

Parameters

symbol	Registered component symbol.
len	String length. If zero, the length is calculated.

Returns: Matching component entity. EntityBad when no exact symbol match exists.

◆ symbol() [2/2]

GAIA_NODISCARD util::str_view gaia::ecs::World::symbol ( Entity component ) const

inline

Returns the registered symbol name for a component entity.

Parameters

component Component entity.

Returns: Registered component symbol. Empty view when component is not a cached component.

◆ sync()

GAIA_NODISCARD uint32_t gaia::ecs::World::sync ( Entity prefabEntity )

inline

Propagates additive prefab changes to existing non-prefab instances. Missing copied ids are added to existing instances and missing prefab children are spawned with their Parent or ChildOf hierarchy relation. Existing owned instance data is left intact.

Parameters

prefabEntity Prefab root whose instances are synchronized.

Returns: Number of copied ids and spawned child instances.

◆ sync_component_record()

void gaia::ecs::World::sync_component_record	(	Entity	component,
		Component	comp
	)

inline

Updates the cached component metadata in both the component cache and the core Component storage.

Parameters

component	Component entity.
comp	New component descriptor value.

◆ target()

GAIA_NODISCARD Entity gaia::ecs::World::target	(	Entity	entity,
		Entity	relation
	)		const

inline

Returns the first relationship target for the relation entity on entity.

Parameters

entity	Source entity
relation	Relation entity

Returns: Relationship target. EntityBad if there is nothing to return.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ targets() [1/2]

template<typename Func >

void gaia::ecs::World::targets	(	Entity	entity,
		Entity	relation,
		Func	func
	)		const

inline

Returns the relationship targets for the relation entity on entity.

Parameters

entity	Source entity
relation	Relation entity
func	void(Entity target) functor executed for relationship target found.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ targets() [2/2]

GAIA_NODISCARD const cnt::set< EntityLookupKey > * gaia::ecs::World::targets ( Entity relation ) const

inline

Returns targets for relation.

Parameters

relation Relation entity

Returns: Set of targets referenced by relation, or nullptr when none exist.

Warning: It is expected relation is valid. Undefined behavior otherwise.

◆ targets_all_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::targets_all_cache ( Entity source ) const

inline

Returns the cached deduped direct targets for wildcard target traversal on source. The cache is keyed by source and cleared whenever a pair edge changes.

Parameters

source Entity whose direct pair targets are requested.

Returns: Cached unique direct targets of source.

◆ targets_if()

template<typename Func >

void gaia::ecs::World::targets_if	(	Entity	entity,
		Entity	relation,
		Func	func
	)		const

inline

Returns the relationship targets for the relation entity on entity.

Parameters

entity	Source entity
relation	Relation entity
func	bool(Entity target) functor executed for relationship target found. Stops if false is returned.

Warning: It is expected entity is valid. Undefined behavior otherwise.

◆ targets_trav()

template<typename Func >

void gaia::ecs::World::targets_trav	(	Entity	relation,
		Entity	source,
		Func	func
	)		const

inline

Traverses relationship targets upwards starting from source. Disabled entities act as traversal barriers and are not yielded.

Template Parameters

Func	Callable type accepting each target entity.

Parameters

relation	Relation defining each upward edge.
source	Entity where traversal starts.
func	Callable invoked for each enabled target.

◆ targets_trav_cache()

GAIA_NODISCARD const cnt::darray< Entity > & gaia::ecs::World::targets_trav_cache	(	Entity	relation,
		Entity	source
	)		const

inline

Returns the cached unlimited upward traversal chain for (relation, source). The cache excludes the source entity itself and is cleared whenever a pair edge changes.

Parameters

relation	Relation defining each upward edge.
source	Entity where traversal starts.

Returns: Cached targets above source in traversal order.

◆ targets_trav_if()

template<typename Func >

GAIA_NODISCARD bool gaia::ecs::World::targets_trav_if	(	Entity	relation,
		Entity	source,
		Func	func
	)		const

inline

Traverses relationship targets upwards starting from source. Disabled entities act as traversal barriers and are not yielded.

Template Parameters

Func	Callable type returning whether traversal should continue.

Parameters

relation	Relation defining each upward edge.
source	Entity where traversal starts.
func	Callable invoked for each enabled target. Returning false stops traversal.

Returns: True if traversal was stopped by func, false otherwise.

◆ tearing_down()

GAIA_NODISCARD bool gaia::ecs::World::tearing_down ( ) const

inline

Returns true while the world is draining teardown work and normal runtime callbacks must not execute.

Returns: True during world teardown. False otherwise.

◆ try_get()

GAIA_NODISCARD Entity gaia::ecs::World::try_get ( EntityId id ) const

inline

Returns the entity for id when it is still live, or EntityBad for stale cleanup-time ids.

Parameters

id	Entity id to resolve.

Returns: Live entity for id, or EntityBad when the id is stale or absent.

◆ update()

void gaia::ecs::World::update ( )

inline

Runs systems and then finishes the current frame.

This is the normal frame step. When systems are enabled, it executes registered systems through systems_run(). It then calls frame_cleanup() and frame_end(). With systems disabled, only the frame maintenance steps run.

Warning: Do not call this from an observer callback. Debug builds assert this contract.

See also: systems_run(); frame_cleanup(); frame_end()

◆ update_src_entity_version()

void gaia::ecs::World::update_src_entity_version ( Entity entity )

inline

Updates a tracked source-entity version after the entity changes archetype membership.

Parameters

entity Source entity whose existing tracked version is incremented.

◆ uquery()

Query gaia::ecs::World::uquery ( )

inline

Provides an uncached query set up to work with the parent world. Uncached queries keep only a local immutable plan and rebuild transient matches on demand.

Returns: Valid query object

◆ uses_compile_time_sparse_storage()

template<typename T >

static GAIA_NODISCARD constexpr bool gaia::ecs::World::uses_compile_time_sparse_storage ( )

inlinestaticconstexpr

Returns whether T has compile-time sparse payload storage.

Template Parameters

T	Component type to inspect.

Returns: True when GAIA_STORAGE(Sparse) is authoritative for T.

◆ valid()

GAIA_NODISCARD bool gaia::ecs::World::valid ( Entity entity ) const

inline

Checks if entity is valid.

Parameters

entity Checked entity.

Returns: True if the entity is valid. False otherwise.

◆ validate_runtime_semantics()

void gaia::ecs::World::validate_runtime_semantics ( const RuntimeTypeDesc & runtimeType ) const

inline

Validates runtime-reflection state against the live scope graph in debug builds. Verifies that every semantic entity referenced by runtimeType resolves to a reachable scope path. All checks are compiled out when assertions are disabled.

Parameters

runtimeType Runtime descriptor whose semantic entities are validated.

◆ world_version()

GAIA_NODISCARD uint32_t & gaia::ecs::World::world_version ( )

inline

Returns the current version of the world.

Returns: World version number.

Friends And Related Symbol Documentation

◆ query_match_scratch_acquire

QueryMatchScratch & query_match_scratch_acquire ( World & world )

friend

Acquires temporary scratch storage used during query matching.

Parameters

world World providing the scratch stack.

Returns: Scratch storage reference.

◆ query_match_scratch_release

void query_match_scratch_release	(	World &	world,
		bool	keepStamps
	)

friend

Releases previously acquired query-match scratch storage.

Parameters

world	World providing the scratch stack.
keepStamps	Whether stamp buffers should be preserved.

◆ world_archetype_delete_version

uint32_t world_archetype_delete_version ( const World & world )

friend

Returns the version that changes when an archetype enters or leaves the deletion-request set.

Returns the version of the world's pending archetype-deletion set.

Parameters

world World whose archetype deletion state is inspected.

Returns: Current archetype deletion-set version.

◆ world_component_index_bucket_size

uint32_t world_component_index_bucket_size	(	const World &	world,
		Entity	term
	)

friend

Returns the size of the component-to-archetype bucket for term.

Parameters

world	World to query.
term	Term to inspect.

Returns: Number of indexed archetype entries.

◆ world_component_index_comp_idx

uint32_t world_component_index_comp_idx	(	const World &	world,
		const Archetype &	archetype,
		Entity	term
	)

friend

Returns the cached component index of term inside archetype.

Parameters

world	World to query.
archetype	Archetype to inspect.
term	Term to inspect.

Returns: Component index, or BadIndex if unavailable.

◆ world_component_index_match_count

uint32_t world_component_index_match_count	(	const World &	world,
		const Archetype &	archetype,
		Entity	term
	)

friend

Returns the cached match count of term inside archetype.

Parameters

world	World to query.
archetype	Archetype to inspect.
term	Term to inspect.

Returns: Match count, or 0 if unavailable.

◆ world_direct_entity_arg

template<typename T >

decltype(auto) world_direct_entity_arg	(	World &	world,
		Entity	entity
	)

friend

Returns a direct query argument for entity using immediate-write access for mutable references.

Template Parameters

T	Query argument type.

Parameters

world	World to query.
entity	Entity to read or mutate.

Returns: Query argument bound to entity.

◆ world_direct_entity_arg_raw

template<typename T >

decltype(auto) world_direct_entity_arg_raw	(	World &	world,
		Entity	entity
	)

friend

Returns a direct query argument for entity using raw mutable access.

Template Parameters

T	Query argument type.

Parameters

world	World to query.
entity	Entity to read or mutate.

Returns: Query argument bound to entity.

◆ world_entity_archetype_version

uint32_t world_entity_archetype_version	(	const World &	world,
		Entity	entity
	)

friend

Returns the per-entity archetype version used for targeted source-query freshness checks.

Returns the sparse archetype-membership version tracked for a source entity. Invalid source entities report version 0 so cached queries see deletions immediately. Valid entries are created on first use so non-source entities do not pay any extra storage.

Parameters

world	World containing the sparse source-version state.
entity	Source entity whose archetype-membership version is requested.

Returns: Tracked version, one for a newly tracked live entity, or zero for an invalid entity.

◆ world_finish_write

void world_finish_write	(	World &	world,
		Entity	term,
		Entity	entity
	)

friend

Finishes a cursor write through the owning world.

Finalizes one cursor-backed component write.

Parameters

world	World owning the component value.
term	Written component or relationship id.
entity	Entity owning the written value.

◆ world_query_entity_arg_by_id

template<typename T >

decltype(auto) world_query_entity_arg_by_id	(	World &	world,
		Entity	entity,
		Entity	id
	)

friend

Returns the query argument for entity using explicit term id id. Mutable references materialize an override when inherited data must become direct.

Template Parameters

T	Query argument type.

Parameters

world	World to query.
entity	Entity to read or mutate.
id	Explicit component or pair id, or EntityBad to derive it from T.

Returns: Query argument bound to entity.

◆ world_query_entity_arg_by_id_raw

template<typename T >

decltype(auto) world_query_entity_arg_by_id_raw	(	World &	world,
		Entity	entity,
		Entity	id
	)

friend

Returns the query argument for entity using explicit term id id and raw mutable access. Mutable references materialize an override when inherited data must become direct.

Template Parameters

T	Query argument type.

Parameters

world	World to query.
entity	Entity to read or mutate.
id	Explicit component or pair id, or EntityBad to derive it from T.

Returns: Query argument bound to entity.

◆ world_rel_version

uint32_t world_rel_version	(	const World &	world,
		Entity	relation
	)

friend

Returns the current version of relation-specific traversal metadata.

Returns the current traversal-metadata version for a relation.

Parameters

world	World that owns the traversal metadata.
relation	Relation whose metadata version is inspected.

Returns: Current relation traversal version.

◆ world_version

uint32_t world_version ( const World & world )

friend

Returns the current world structural version.

Returns the world's current structural version.

Parameters

world World whose version is inspected.

Returns: Current structural version.

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

/home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/world.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ acc()

◆ acc_mut()

◆ add() [1/9]

◆ add() [2/9]

◆ add() [3/9]

◆ add() [4/9]

◆ add() [5/9]

◆ add() [6/9]

◆ add() [7/9]

◆ add() [8/9]

◆ add() [9/9]

◆ add_n() [1/2]

◆ add_n() [2/2]

◆ add_raw()

◆ alias() [1/3]

◆ alias() [2/3]

◆ alias() [3/3]

◆ alias_raw()

◆ archetype_delete_version()

◆ as()

◆ as_relations_trav()

◆ as_relations_trav_cache()

◆ as_relations_trav_if()

◆ as_targets_trav()

◆ as_targets_trav_cache()

◆ as_targets_trav_if()

◆ build()

◆ can_add_component_storage_trait()

◆ can_use_sparse_component_storage()

◆ child() [1/2]

◆ child() [2/2]

◆ clear()

◆ cmd_buffer_mt()

◆ cmd_buffer_st()

◆ collect_direct_term_entities()

◆ collect_direct_term_entities_direct()

◆ comp_cache()

◆ comp_cache_mut()

◆ compile_time_sparse_storage_mode()

◆ component_is_non_fragmenting()

◆ component_uses_sparse_storage()

◆ copies_non_frag_sparse_payload_inter()

◆ copies_sparse_payload_inter()

◆ copy()

◆ copy_n()

◆ count_direct_term_entities()

◆ count_direct_term_entities_direct()

◆ cursor()

◆ cursor_mut()

◆ defer_sort_inv_active()

◆ defer_sort_inv_begin()

◆ defer_sort_inv_record()

◆ defrag_entities_per_tick()

◆ del() [1/4]

◆ del() [2/4]

◆ del() [3/4]

◆ del() [4/4]

◆ del_nonfragmenting_relation()

◆ del_nonfragmenting_relation_source()

◆ del_sparse_component_store()

◆ del_sparse_components()

◆ depth_order_cache()

◆ display_name()

◆ enable()

◆ enabled() [1/2]

◆ enabled() [2/2]

◆ enabled_hierarchy()

◆ enabled_hierarchy_version()

◆ expr_to_entity()

◆ fetch() [1/2]

◆ fetch() [2/2]

◆ finalize_component_registration()

◆ find_prefab_instance()