gaia::ecs::World Class Reference

Classes
struct	EntityBuilder

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.
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	is_dont_fragment_relation (Entity relation) const
	Returns whether relation is a valid non-fragmenting relation entity.
GAIA_NODISCARD bool	is_exclusive_dont_fragment_relation (Entity relation) const
	Returns whether relation is both Exclusive and DontFragment. Such relations are stored in the adjunct side structure instead of archetype identity.
GAIA_NODISCARD bool	is_hierarchy_relation (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	is_fragmenting_relation (Entity relation) const
	Returns true when the relation still participates in archetype identity. Non-fragmenting relations such as Parent are excluded.
GAIA_NODISCARD bool	is_fragmenting_hierarchy_relation (Entity relation) const
	Returns true for hierarchy relations that still fragment archetypes. ChildOf satisfies this today, while Parent intentionally does not.
GAIA_NODISCARD bool	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	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	is_out_of_line_component (Entity component) const
	Returns whether component stores instance data out of line instead of in archetype chunks. This is currently the storage path used for sparse plain generic AoS components.
GAIA_NODISCARD bool	is_non_fragmenting_out_of_line_component (Entity component) const
	Returns whether component is both out-of-line and non-fragmenting. Non-fragmenting out-of-line components do not participate in archetype identity.
void	sync_component_record (Entity component, Component comp)
	Updates the cached component metadata in both the component cache and the core Component storage.
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.
template<typename T >
GAIA_NODISCARD bool	can_use_out_of_line_component (Entity object) const
	Returns whether object is a usable out-of-line storage target for component type T.
template<typename T >
GAIA_NODISCARD SparseComponentStore< T > *	sparse_component_store (Entity component)
	Returns the sparse out-of-line 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 out-of-line 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 out-of-line component store for component, creating it if needed.
void	del_sparse_components (Entity entity)
	Removes all sparse out-of-line component instances owned by entity.
void	del_sparse_component_store (Entity component)
	Deletes the sparse out-of-line component store associated with component.
GAIA_NODISCARD const ExclusiveAdjunctStore *	exclusive_adjunct_store (Entity relation) const
	Returns the exclusive adjunct store for relation, or nullptr when absent.
GAIA_NODISCARD ExclusiveAdjunctStore &	exclusive_adjunct_store_mut (Entity relation)
	Returns the exclusive adjunct store for relation, creating it if needed.
void	exclusive_adjunct_track_src_relation (Entity source, Entity relation)
void	exclusive_adjunct_untrack_src_relation (Entity source, Entity relation)
void	exclusive_adjunct_set (Entity source, Entity relation, Entity target)
bool	exclusive_adjunct_del (Entity source, Entity relation, Entity target)
GAIA_NODISCARD bool	has_exclusive_adjunct_pair (Entity source, Entity object) const
void	del_exclusive_adjunct_source (Entity source)
void	del_exclusive_adjunct_relation (Entity relation)
GAIA_NODISCARD bool	has_exclusive_adjunct_target_cond (Entity target, Pair cond) const
	Checks whether any non-fragmenting exclusive relation targeting target uses the given 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.
GAIA_NODISCARD const ComponentCacheItem &	add (const char *name, uint32_t size, DataStorageType storageType, uint32_t alig=1, uint32_t soa=0, const uint8_t *pSoaSizes=nullptr, ComponentLookupHash hashLookup={}, EntityKind kind=EntityKind::EK_Gen)
	Creates a new runtime component 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.
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.
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 entities. 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.
void	instantiate_n (Entity prefabEntity, Entity parentInstance, uint32_t count)
	Instantiates count copies of a prefab as normal entities parented under parentInstance.
template<typename Func >
void	instantiate_n (Entity prefabEntity, Entity parentInstance, uint32_t count, Func func)
	Instantiates count copies of a prefab as normal entities parented under parentInstance. The callback is invoked for each spawned root instance.
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. Existing owned instance data is left intact.
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
void	child (Entity entity, Entity parent)
	Shortcut for add(entity, Pair(ChildOf, parent)
GAIA_NODISCARD bool	child (Entity entity, Entity parent) const
	Checks if.
void	parent (Entity entity, Entity parentEntity)
	Shortcut for add(entity, Pair(Parent, parent))
GAIA_NODISCARD bool	parent (Entity entity, Entity parentEntity) const
	Checks if.
template<typename T >
void	modify (Entity entity)
	Marks the component 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)
	Sets the value of the component T on entity without triggering a world version update. 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.
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	children (Entity parent, Func func) const
	Visits direct children in the ChildOf hierarchy.
template<typename Func >
void	children_if (Entity parent, Func func) const
	Visits direct children in the ChildOf hierarchy until func returns false.
template<typename Func >
void	children_bfs (Entity root, Func func) const
	Traverses descendants in the ChildOf hierarchy in breadth-first order.
template<typename Func >
GAIA_NODISCARD bool	children_bfs_if (Entity root, Func func) const
	Traverses descendants in the ChildOf hierarchy in breadth-first order.
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	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.
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	update ()
	Performs various internal operations related to the end of the frame such as memory cleanup and other management operations which keep the system healthy.
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	save_json (ser::ser_json &writer, ser::JsonSaveFlags flags=ser::JsonSaveFlags::Default) const
	Serializes world state into a JSON document. Components with runtime schema are emitted as structured JSON objects. Components with no schema fallback to raw serialized bytes. Returns false when some schema field types are unsupported (those fields are emitted as null).
ser::json_str	save_json (bool &ok, ser::JsonSaveFlags flags=ser::JsonSaveFlags::Default) const
	Convenience overload returning JSON as a string.
bool	load_json (const char *json, uint32_t len, ser::JsonDiagnostics &diagnostics)
	Loads world state from JSON previously emitted by save_json(). Returns true when JSON shape is valid and parsing succeeds. Non-fatal semantic issues are reported through diagnostics.
bool	load_json (const char *json, uint32_t len)
	Loads world state from a raw JSON buffer and discards non-fatal diagnostics.
bool	load_json (ser::json_str_view json, ser::JsonDiagnostics &diagnostics)
	Loads world state from a JSON string view and reports non-fatal diagnostics.
bool	load_json (ser::json_str_view json)
	Loads world state from a JSON string view and discards non-fatal diagnostics.
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.
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_out_of_line_component ()
	Out-of-line non-fragmenting storage currently supports only plain generic components. Pairs, unique components and SoA layouts stay on the normal archetype path.
static void	ensure_exclusive_adjunct_src_capacity (ExclusiveAdjunctStore &store, Entity source)
static void	ensure_exclusive_adjunct_tgt_capacity (ExclusiveAdjunctStore &store, Entity target)
static GAIA_NODISCARD Entity	exclusive_adjunct_target (const ExclusiveAdjunctStore &store, Entity source)
static GAIA_NODISCARD const cnt::darray< Entity > *	exclusive_adjunct_sources (const ExclusiveAdjunctStore &store, Entity target)
static void	del_exclusive_adjunct_target_source (ExclusiveAdjunctStore &store, Entity target, Entity source)

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)
	Finalizes a write to term on entity.
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_entity_archetype_version (const World &world, Entity entity)
	Returns the per-entity archetype version used for targeted source-query freshness checks.

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/8]

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/8]

GAIA_NODISCARD const ComponentCacheItem & gaia::ecs::World::add ( const char *  name, uint32_t  size, DataStorageType  storageType, uint32_t  alig = 1, uint32_t  soa = 0, const uint8_t *  pSoaSizes = nullptr, ComponentLookupHash  hashLookup = {}, EntityKind  kind = EntityKind::EK_Gen  )

inline

Creates a new runtime component if not found already.

Parameters

name	Component name.
size	Component size in bytes.
storageType	Data storage type.
alig	Component alignment in bytes.
soa	Number of SoA items (0 for AoS).
pSoaSizes	SoA item sizes, must contain at least soa values when soa > 0.
hashLookup	Optional lookup hash. If zero, hash(name) is used.
kind	Entity kind (Gen by default, Uni supported).

Returns

Component cache item of the component.

add() [3/8]

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() [4/8]

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() [5/8]

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() [6/8]

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() [7/8]

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() [8/8]

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.

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.

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.

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.

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_use_out_of_line_component()

template<typename T >

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

inline

Returns whether object is a usable out-of-line 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 an out-of-line store for T.

child()

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

inline

Checks if.

Parameters

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

children()

template<typename Func >

void gaia::ecs::World::children ( Entity  parent, Func  func  ) const

inline

Visits direct children in the ChildOf hierarchy.

Parameters

parent	Parent entity
func	void(Entity child) functor executed for each child.

children_bfs()

template<typename Func >

void gaia::ecs::World::children_bfs ( Entity  root, Func  func  ) const

inline

Traverses descendants in the ChildOf hierarchy in breadth-first order.

Parameters

root	Root entity
func	void(Entity child) functor executed for each descendant.

children_bfs_if()

template<typename Func >

GAIA_NODISCARD bool gaia::ecs::World::children_bfs_if ( Entity  root, Func  func  ) const

inline

Traverses descendants in the ChildOf hierarchy in breadth-first order.

Parameters

root	Root entity
func	bool(Entity child) functor executed for each child found. Stops if true is returned.

Returns

True when traversal stopped early. False otherwise.

children_if()

template<typename Func >

void gaia::ecs::World::children_if ( Entity  parent, Func  func  ) const

inline

Visits direct children in the ChildOf hierarchy until func returns false.

Parameters

parent	Parent entity
func	bool(Entity child) functor executed for each child found. Stops if false is returned.

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.

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.

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_sparse_component_store()

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

inline

Deletes the sparse out-of-line 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 out-of-line component instances owned by entity.

Parameters

entity

Entity

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_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.

exclusive_adjunct_store()

GAIA_NODISCARD const ExclusiveAdjunctStore * gaia::ecs::World::exclusive_adjunct_store ( Entity  relation ) const

inline

Returns the exclusive adjunct store for relation, or nullptr when absent.

Parameters

relation

Relation entity

Returns

Exclusive adjunct store or nullptr if absent.

exclusive_adjunct_store_mut()

GAIA_NODISCARD ExclusiveAdjunctStore & gaia::ecs::World::exclusive_adjunct_store_mut ( Entity  relation )

inline

Returns the exclusive adjunct store for relation, creating it if needed.

Parameters

relation

Relation entity

Returns

Mutable exclusive adjunct store reference.

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.

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.

get() [1/4]

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/4]

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/4]

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/4]

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_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()

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.

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_n()

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 entities. 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.

Parameters

prefabEntity	Prefab 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 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 entity

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_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_dont_fragment_relation()

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

inline

Returns whether relation is a valid non-fragmenting relation entity.

Parameters

relation

Relation entity

Returns

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

is_exclusive_dont_fragment_relation()

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

inline

Returns whether relation is both Exclusive and DontFragment. Such relations are stored in the adjunct side structure instead of archetype identity.

Parameters

relation

Relation entity

Returns

True if relation is an exclusive non-fragmenting relation. False otherwise.

is_non_fragmenting_out_of_line_component()

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

inline

Returns whether component is both out-of-line and non-fragmenting. Non-fragmenting out-of-line components do not participate in archetype identity.

Parameters

component

Component entity to inspect.

Returns

True when the component uses out-of-line non-fragmenting storage.

is_out_of_line_component()

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

inline

Returns whether component stores instance data out of line instead of in 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 out-of-line storage.

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()

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.

load_json() [1/4]

bool gaia::ecs::World::load_json ( const char *  json, uint32_t  len  )

inline

Loads world state from a raw JSON buffer and discards non-fatal diagnostics.

Parameters

json	JSON buffer
len	JSON buffer length

Returns

True when loading succeeds. False otherwise.

load_json() [2/4]

bool gaia::ecs::World::load_json ( const char *  json, uint32_t  len, ser::JsonDiagnostics &  diagnostics  )

inline

Loads world state from JSON previously emitted by save_json(). Returns true when JSON shape is valid and parsing succeeds. Non-fatal semantic issues are reported through diagnostics.

Loads world state from JSON previously emitted by save_json().

load_json() [3/4]

bool gaia::ecs::World::load_json ( ser::json_str_view  json )

inline

Loads world state from a JSON string view and discards non-fatal diagnostics.

Parameters

json

JSON view

Returns

True when loading succeeds. False otherwise.

load_json() [4/4]

bool gaia::ecs::World::load_json ( ser::json_str_view  json, ser::JsonDiagnostics &  diagnostics  )

inline

Loads world state from a JSON string view and reports non-fatal diagnostics.

Parameters

json	JSON view
diagnostics	Output diagnostics

Returns

True when loading succeeds. 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 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

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

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()

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

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.

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.

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.

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.

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.

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.

Returns

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

parent()

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

inline

Checks if.

Parameters

entity	has non-fragmenting Parent relationship to
parentEntity.

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.

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.

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

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.

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.

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

scope	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_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_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_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_store() [1/2]

template<typename T >

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

inline

Returns the sparse out-of-line 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 out-of-line 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_mut()

template<typename T >

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

inline

Returns the sparse out-of-line 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.

sset()

template<typename T >

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

inline

Sets the value of the component T on entity without triggering a world version update. This is a silent write and does not trigger set hooks or OnSet observers.

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.

Undefined behavior if entity changes archetype after ComponentSetter is created.

supports_out_of_line_component()

template<typename T >

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

inlinestaticconstexpr

Out-of-line non-fragmenting 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 out-of-line 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_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

Warning

It is expected entity is valid. Undefined behavior otherwise.

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_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.

Returns

True if traversal was stopped by func, false otherwise.

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

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.

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_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_finish_write

void world_finish_write ( World &  world, Entity  term, Entity  entity  )

friend

Finalizes a write to term on entity.

Parameters

world	World owning the entity.
term	Component or pair id that was written.
entity	Entity that was written.

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.

---

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

• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/world.h
• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/impl/world_json.h