gaia::ecs::detail::QueryImpl Class Reference

Classes
struct	DirectChunkArgEvalDesc
struct	DirectEntitySeedEvalPlan
struct	DirectEntitySeedInfo
struct	DirectEntitySeedPlan
	Describes which direct term should seed direct non-fragmenting evaluation. More...
struct	IterJobCallback
	Callback adapter that sets iterator context before invoking an Iter& user callback. More...
struct	IterModeAcceptAll
	Tag selecting unconstrained row iteration for prepared query iteration. More...
struct	IterModeDisabledOnly
	Tag selecting disabled-only row constraints for prepared query iteration. More...
struct	IterModeEnabled
	Tag selecting enabled-only row constraints for prepared query iteration. More...
class	OrderByTravView
struct	QueryCacheRange
	Cache range selected by the query's optional group id filter. More...
struct	QueryJobCtx
struct	QueryPlan
	Prepared query execution metadata shared by typed callbacks and public Iter callbacks. More...
struct	QueryTaskJobCtx
struct	RuntimeIterCallback
struct	TypedDirectChunkCallback
struct	TypedIterErasedCallback
struct	TypedJobCallback
	Callback adapter that materializes typed callback arguments on top of a prepared iterator. More...
struct	TypedMappedChunkCallback

Public Types
enum class	ExecPayloadKind : uint8_t { Plain , Grouped , NonTrivial }
	Runtime payload layout required by generic chunk-batch execution. More...
enum class	QueryPlanMode : uint8_t {   Empty , General , EntitySeed , DirectDense ,   MappedDense , Sorted , Traversal }
	Prepared query runner mode shared by typed callbacks and public Iter callbacks. More...
enum	QueryPlanFlags : uint8_t {   QueryPlanFlag_None = 0 , QueryPlanFlag_Filtered = 1 << 0 , QueryPlanFlag_EntityFilter = 1 << 1 , QueryPlanFlag_InheritedPayload = 1 << 2 ,   QueryPlanFlag_Grouped = 1 << 3 , QueryPlanFlag_Sorted = 1 << 4 , QueryPlanFlag_BarrierCache = 1 << 5 }
	Orthogonal flags attached to a prepared query plan. More...

Public Member Functions
QueryInfo &	fetch ()
	Fetches the QueryInfo object. Creates or refreshes the backing QueryInfo if needed.
void	match_all (QueryInfo &queryInfo)
	Matches the query against all relevant archetypes.
GAIA_NODISCARD bool	match_one (QueryInfo &queryInfo, const Archetype &archetype, EntitySpan targetEntities)
	Matches the query against a single archetype.
GAIA_NODISCARD bool	matches_any (QueryInfo &queryInfo, const Archetype &archetype, EntitySpan targetEntities)
	Returns whether any supplied target entity matches the query on archetype.
GAIA_NODISCARD QueryCachePolicy	cache_policy ()
	Returns the effective cache policy chosen for the query.
QueryImpl &	cache_src_trav (uint16_t maxItems)
	Enables traversed-source snapshot reuse and caps the cached source closure size. This only matters for queries using traversed sources (for example src(...).trav()). For queries without source traversal the value is normalized away, so it does not affect shared cache identity. Use this only when traversed source closures stay small and stable enough for snapshot reuse to be cheaper than rebuilding them on demand.
GAIA_NODISCARD uint16_t	cache_src_trav () const
	Returns the traversed-source snapshot cap. 0 disables explicit traversed-source snapshot caching.
QueryImpl &	kind (QueryCacheKind cacheKind)
	Sets the hard cache-kind requirement for the query.
QueryImpl &	scope (QueryCacheScope cacheScope)
	Sets the cache scope used by cached queries.
QueryImpl &	match_prefab ()
	Makes the query include prefab entities in matches.
GAIA_NODISCARD QueryCacheScope	scope () const
	Returns the currently requested cache scope.
GAIA_NODISCARD QueryCacheKind	kind () const
	Returns the currently requested cache kind.
GAIA_NODISCARD QueryKindRes	kind_error ()
	Returns the validation result for the current query shape and requested kind.
GAIA_NODISCARD const char *	kind_error_str ()
	Returns a human-readable description of the current kind validation result.
GAIA_NODISCARD bool	valid ()
	Returns whether the current query shape satisfies the requested kind.
GAIA_NODISCARD bool	can_process_archetype (const QueryInfo &queryInfo, const Archetype &archetype) const
GAIA_NODISCARD bool	can_process_archetype_inter (const QueryInfo &queryInfo, const Archetype &archetype, Constraints constraints, int8_t barrierPasses=-1) const
	Checks whether a matched archetype can be processed for the current row constraints.
template<typename Func , typename TMode , QueryExecType ExecType>
GAIA_NODISCARD SchedJob	add_parallel_query_job (Func func)
template<bool HasFilters>
void	collect_runtime_parallel_batches (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints)
template<typename Func >
GAIA_NODISCARD SchedJob	add_query_task_job (Func func, QueryExecType execType)
template<typename Func , QueryExecType ExecType>
GAIA_NODISCARD SchedJob	add_iter_parallel_job (Func func)
template<bool HasFilters, typename TMode , typename Func >
void	run_query_batch_no_group_id (const QueryInfo &queryInfo, const uint32_t idxFrom, const uint32_t idxTo, Func func)
template<bool HasFilters, typename TMode , typename Func , QueryExecType ExecType>
void	run_query_batch_no_group_id_par (const QueryInfo &queryInfo, const uint32_t idxFrom, const uint32_t idxTo, Func func)
template<bool HasFilters, typename TMode , typename Func >
void	run_query_batch_with_group_id (const QueryInfo &queryInfo, const uint32_t idxFrom, const uint32_t idxTo, Func func)
template<bool HasFilters, typename TMode , typename Func , QueryExecType ExecType>
void	run_query_batch_with_group_id_par (const QueryInfo &queryInfo, const uint32_t idxFrom, const uint32_t idxTo, Func func)
template<bool HasFilters, QueryExecType ExecType, typename TMode , typename Func >
void	run_query (const QueryInfo &queryInfo, Func func)
template<QueryExecType ExecType, typename Func >
void	run_query_on_archetypes (QueryInfo &queryInfo, Func func, Constraints constraints)
template<QueryExecType ExecType, typename TMode , typename Func >
void	run_query_on_chunks (QueryInfo &queryInfo, Func func)
template<bool HasFilters, typename Func >
void	run_query_batch_no_group_id_runtime (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
template<bool HasFilters, typename Func , QueryExecType ExecType>
void	run_query_batch_no_group_id_runtime_par (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
template<bool HasFilters, typename Func >
void	run_query_batch_with_group_id_runtime (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
template<bool HasFilters, typename Func , QueryExecType ExecType>
void	run_query_batch_with_group_id_runtime_par (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
template<bool HasFilters, QueryExecType ExecType, typename Func >
void	run_query_runtime_planned (const QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
template<QueryExecType ExecType, typename Func >
void	run_query_on_chunks_runtime_planned (QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func func)
	Runs public iterator chunk execution from an already prepared plan.
GAIA_NODISCARD bool	can_use_direct_chunk_iteration_fastpath (const QueryInfo &queryInfo) const
	Checks whether typed callbacks can use dense chunk iteration while preserving required cache ordering.
GAIA_NODISCARD QueryCacheRange	selected_query_cache_range (const QueryInfo &queryInfo) const
	Selects the cache range visible to this query, applying a selected group id when present.
GAIA_NODISCARD QueryPlan	prepare_query_plan (const QueryInfo &queryInfo, const TypedQueryExecState &state) const
	Selects the prepared execution plan for typed callbacks.
template<bool HasFilters, typename Func , typename... T>
void	run_query_on_chunks_direct_typed (QueryInfo &queryInfo, const QueryPlan &plan, const TypedQueryExecState &state, Func &func, core::func_type_list< T... >)
	Runs the prepared direct typed row path for simple cached queries.
void	run_query_on_chunks_direct (QueryInfo &queryInfo, const QueryPlan &plan, const TypedQueryExecState &state, void *pFunc, void(*runChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &))
void	run_query_on_chunks_direct_iter (QueryInfo &queryInfo, const QueryPlan &plan, const TypedQueryExecState &state, void *pFunc, void(*runChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &))
template<QueryExecType ExecType>
void	each_inter (QueryInfo &queryInfo, const QueryPlan &plan, void *pFunc, const TypedQueryExecState &state, void(*runDirectFastChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runDirectChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runMappedChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &), bool needsInheritedArgIds, void(*invokeInherited)(World &, Entity, const Entity *, void *))
void	each_typed_erased (QueryExecType execType, void *pFunc, const TypedQueryExecState &state, void(*runDirectFastChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runDirectChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runMappedChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &), bool needsInheritedArgIds, void(*invokeInherited)(World &, Entity, const Entity *, void *))
template<QueryExecType ExecType, typename Func >
void	each_typed_inter (QueryInfo &queryInfo, Func func)
template<QueryExecType ExecType>
void	each_iter_inter_erased (QueryInfo &queryInfo, const QueryPlan &plan, void *pFunc, const TypedQueryExecState &state, void(*runDirectFastChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runMappedChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &))
void	each_walk_inter (QueryInfo &queryInfo, std::span< const Entity > entities, Constraints constraints, void *pFunc, const TypedQueryExecState &state, void(*runChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &))
GAIA_NODISCARD QueryPlan	prepare_query_plan (const QueryInfo &queryInfo, Constraints constraints) const
	Selects the prepared execution plan for public iterator callbacks.
template<bool HasFilters, bool HasGroups, typename Func >
void	run_query_on_chunks_runtime_direct_plain_impl (QueryInfo &queryInfo, const QueryPlan &plan, Constraints constraints, Func &func)
	Runs a public Iter callback over cached chunks without creating chunk batches.
template<QueryExecType ExecType, typename Func >
void	each_runtime_inter (Func func, Constraints constraints=Constraints::EnabledOnly)
	Runs a public iterator callback through the fastest supported runtime path.
void	each_runtime_erased (QueryExecType execType, void *pFunc, void(*invoke)(void *, Iter &), Constraints constraints)
	Runs a type-erased public iterator callback through generic query execution.
void	each_runtime_erased (QueryInfo &queryInfo, const QueryPlan &plan, QueryExecType execType, void *pFunc, void(*invoke)(void *, Iter &), Constraints constraints)
	Runs a type-erased public iterator callback using an already prepared query cache and plan.
GAIA_NODISCARD std::span< const detail::BfsChunkRun >	cached_direct_seed_runs (QueryInfo &queryInfo, const QueryTerm &seedTerm, const DirectEntitySeedInfo &seedInfo, Constraints constraints)
GAIA_NODISCARD std::span< const Entity >	cached_direct_seed_chunk_entities (QueryInfo &queryInfo, const QueryTerm &seedTerm, const DirectEntitySeedInfo &seedInfo, Constraints constraints)
template<typename Func >
void	for_each_direct_or_union (World &world, const QueryInfo &queryInfo, Constraints constraints, Func &&func)
	Visits the deduplicated OR union for direct-seeded queries without materializing an entity seed array first.
template<bool UseFilters>
GAIA_NODISCARD bool	empty_inter (const QueryInfo &queryInfo, Constraints constraints) const
	Fast empty() path for direct non-fragmenting queries that can seed from entity-backed indices.
GAIA_NODISCARD bool	matches_target_entities (QueryInfo &queryInfo, const Archetype &archetype, EntitySpan targetEntities)
	Returns whether any of the provided target entities matches the query semantics.
template<bool UseFilters>
GAIA_NODISCARD uint32_t	count_inter (const QueryInfo &queryInfo, Constraints constraints) const
	Fast count() path for direct non-fragmenting queries that can seed from entity-backed indices.
template<typename Func >
void	each_chunk_runs_iter (QueryInfo &queryInfo, std::span< const detail::BfsChunkRun > runs, Constraints constraints, Func func)
template<typename Func >
void	each_direct_entities_iter (QueryInfo &queryInfo, std::span< const Entity > entities, Constraints constraints, Func func)
template<typename Func >
void	each_direct_iter_inter (QueryInfo &queryInfo, Constraints constraints, Func func)
	Runs an iterator-based each() callback over directly seeded entities using one-row chunk views.
void	each_direct_inter (QueryInfo &queryInfo, Constraints constraints, void *pFunc, const TypedQueryExecState &state, void(*runDirectChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), bool needsInheritedArgIds, void(*invokeInherited)(World &, Entity, const Entity *, void *))
	Runs a typed each() callback over directly seeded entities.
template<bool UseFilters, typename ContainerOut >
void	arr_inter (QueryInfo &queryInfo, ContainerOut &outArray, Constraints constraints)
	QueryImpl (World &world, QueryCache &queryCache, ArchetypeId &nextArchetypeId, uint32_t &worldVersion, const EntityToArchetypeMap &entityToArchetypeMap, const EntityToArchetypeVersionMap &entityToArchetypeMapVersions, const ArchetypeDArray &allArchetypes)
GAIA_NODISCARD QueryId	id () const
	Returns the cache handle id of this query.
GAIA_NODISCARD uint32_t	gen () const
	Returns the cache handle generation of this query.
void	reset ()
	Release any data allocated by the query.
void	destroy ()
	Destroys the current cached query state and local scratch data.
GAIA_NODISCARD bool	is_cached () const
	Returns whether the query is stored in the query cache.
QueryImpl &	add (const char *str,...)
	Creates a query from a null-terminated expression string.
QueryImpl &	add (QueryInput item)
	Adds a prebuilt query input item.
QueryImpl &	is (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
	Adds a semantic Is(entity) requirement.
QueryImpl &	in (Entity entity, QueryTermOptions options=QueryTermOptions{})
	Adds an inherited in(entity) requirement.
QueryImpl &	all (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
	Adds a required entity or pair term.
template<typename T >
QueryImpl &	all (const QueryTermOptions &options)
	Adds a required typed term.
template<typename T >
QueryImpl &	all ()
	Adds a required typed term.
QueryImpl &	any (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
	Adds an optional entity or pair term.
template<typename T >
QueryImpl &	any (const QueryTermOptions &options)
	Adds an optional typed term.
template<typename T >
QueryImpl &	any ()
	Adds an optional typed term.
QueryImpl &	or_ (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
	OR terms (at least one has to match). A single OR term is canonicalized to ALL during query normalization.
template<typename T >
QueryImpl &	or_ (const QueryTermOptions &options)
	Adds an OR typed term.
template<typename T >
QueryImpl &	or_ ()
	Adds an OR typed term.
QueryImpl &	no (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
	Adds an excluded entity or pair term.
template<typename T >
QueryImpl &	no (const QueryTermOptions &options)
	Adds an excluded typed term.
template<typename T >
QueryImpl &	no ()
	Adds an excluded typed term.
QueryImpl &	var_name (Entity varEntity, util::str_view name)
	Assigns a human-readable name to a query variable entity (Var0..Var7). The name can be used later by set_var(name, value).
QueryImpl &	var_name (Entity varEntity, const char *name)
	Assigns a human-readable name to a query variable entity (Var0..Var7).
QueryImpl &	set_var (Entity varEntity, Entity value)
	Binds a query variable (Var0..Var7) to a concrete entity value. Bound values are applied at runtime before query evaluation.
QueryImpl &	set_var (util::str_view name, Entity value)
	Binds a named query variable to a concrete entity value.
QueryImpl &	set_var (const char *name, Entity value)
	Binds a named query variable to a concrete entity value.
QueryImpl &	clear_var (Entity varEntity)
	Clears binding for a single query variable (Var0..Var7). The variable becomes unbound for the next query evaluation.
QueryImpl &	clear_vars ()
	Clears all runtime variable bindings.
QueryImpl &	changed (Entity entity)
	Marks a runtime component or pair for changed() filtering.
template<typename T >
QueryImpl &	changed ()
	Marks a typed term for changed() filtering.
QueryImpl &	sort_by (Entity entity, TSortByFunc func)
	Sorts the query by the specified entity and function.
template<typename T >
QueryImpl &	sort_by (TSortByFunc func)
	Sorts the query by the specified component and function.
template<typename Rel , typename Tgt >
QueryImpl &	sort_by (TSortByFunc func)
	Sorts the query by the specified pair and function.
GAIA_NODISCARD OrderByTravView	order_by (Entity relation, TravOrder order)
	Iterates matching entities in an explicit relation traversal order.
template<typename Rel >
GAIA_NODISCARD OrderByTravView	order_by (TravOrder order)
	Iterates matching entities in an explicit typed relation traversal order.
QueryImpl &	depth_order (Entity relation=ChildOf)
	Orders cached query entries by fragmenting relation depth so iteration runs breadth-first top-down. Intended only for fragmenting relations such as ChildOf or DependsOn where the target participates in archetype identity. Unlike order_by(relation, TravOrder), this affects the cached query iteration order itself and can therefore prune fragmenting disabled subtrees at the archetype level. For non-fragmenting relations such as Parent, use order_by(...) instead.
template<typename Rel >
QueryImpl &	depth_order ()
	Orders cached query entries by fragmenting relation depth so iteration runs breadth-first top-down.
QueryImpl &	group_by (Entity entity, TGroupByFunc func=group_by_func_default)
	Organizes matching archetypes into groups according to the grouping function and entity. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.
template<typename T >
QueryImpl &	group_by (TGroupByFunc func=group_by_func_default)
	Organizes matching archetypes into groups according to the grouping function. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.
template<typename Rel , typename Tgt >
QueryImpl &	group_by (TGroupByFunc func=group_by_func_default)
	Organizes matching archetypes into groups according to the grouping function. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.
QueryImpl &	group_dep (Entity relation)
	Declares an explicit relation dependency for grouped cache invalidation. Useful for custom group_by callbacks that depend on hierarchy or relation topology.
template<typename Rel >
QueryImpl &	group_dep ()
	Declares an explicit relation dependency for grouped cache invalidation. Useful for custom group_by callbacks that depend on hierarchy or relation topology.
QueryImpl &	group_id (GroupId groupId)
	Selects the group to iterate over.
QueryImpl &	group_id (Entity entity)
	Selects the group to iterate over.
template<typename T >
QueryImpl &	group_id ()
	Selects the group to iterate over.
template<typename Func >
GAIA_NODISCARD SchedJob	job (Func func, QueryExecType execType)
	Adds a query execution job without submitting it.
template<typename Func , std::enable_if_t< detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func)
	Iterates query matches using the default execution mode.
template<typename Func , std::enable_if_t<!detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func)
template<typename Func , std::enable_if_t< detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func, QueryExecType execType)
	Iterates query matches using the selected execution mode.
template<typename Func , std::enable_if_t< detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func, Constraints constraints)
template<typename Func , std::enable_if_t< detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func, QueryExecType execType, Constraints constraints)
template<typename Func , std::enable_if_t<!detail::is_query_iter_callback_v< Func >, int > = 0>
void	each (Func func, QueryExecType execType)
template<typename Func >
void	each_iter (Iter &it, Func func)
	Runs a typed callback against an already prepared iterator. This is used by higher-level adapters that normalize execution to Iter& first and then materialize typed arguments on top of the iterator.
void	each_iter_erased (QueryExecType execType, void *pFunc, const TypedQueryExecState &state, void(*runDirectFastChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runMappedChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &))
void	each_iter_erased (Iter &it, void *pFunc, const TypedQueryExecState &state, void(*runDirectFastChunk)(QueryImpl &, Iter &, void *, const TypedQueryExecState &), void(*runMappedChunk)(QueryImpl &, const QueryInfo &, Iter &, void *, const TypedQueryExecState &))
template<typename Func >
void	each_arch (Func func, Constraints constraints=Constraints::EnabledOnly)
	Iterates matching archetypes instead of individual entities.
bool	empty (Constraints constraints=Constraints::EnabledOnly)
	Returns true or false depending on whether there are any entities matching the query.
uint32_t	count (Constraints constraints=Constraints::EnabledOnly)
	Calculates the number of entities matching the query.
void	each_entity_enabled (void *pCtx, void(*func)(void *, Entity))
	Iterates matching enabled entities through a non-template erased callback.
void	collect_entities_enabled (cnt::darray< Entity > &out)
template<typename Container >
void	arr (Container &outArray, Constraints constraints=Constraints::EnabledOnly)
	Appends all components or entities matching the query to the output array.
GAIA_NODISCARD std::span< const Entity >	ordered_entities_walk (QueryInfo &queryInfo, Entity relation, TravOrder order, Constraints constraints=Constraints::EnabledOnly)
	Builds and caches relation traversal order for the current query result.
template<typename Func , std::enable_if_t< detail::is_query_walk_core_callback_v< Func >, int > = 0>
void	each_walk (Func func, Entity relation, TravOrder order=TravOrder::Down, Constraints constraints=Constraints::EnabledOnly)
	Iterates entities matching the query in a requested relation traversal order. For relation R this treats Pair(R, X) on entity E as "E points at X". Traversal changes only visit order. Nodes with the same parent are ordered by entity id.
template<typename Func , std::enable_if_t<!detail::is_query_walk_core_callback_v< Func >, int > = 0>
void	each_walk (Func func, Entity relation, TravOrder order=TravOrder::Down, Constraints constraints=Constraints::EnabledOnly)
void	diag ()
	Run diagnostics.
GAIA_NODISCARD util::str	bytecode ()
	Returns a textual dump of the generated query VM bytecode.
void	diag_bytecode ()
	Prints a textual dump of the generated query VM bytecode.
template<typename Rel >
QueryImpl::OrderByTravView	order_by (TravOrder order)
Query context
Stores raw, user-owned data on this query and exposes it to iterator-style callbacks. See also Iter::ctx() const SystemBuilder::ctx(void*)
QueryImpl &	ctx (void *pCtx)
	Sets the user-owned context pointer visible through Iter::ctx() during iterator callbacks. Changing the pointer does not affect query identity, query matching, shared-cache lookup, or cached query storage. Identical shared-cache query shapes may therefore keep different context pointers.
GAIA_NODISCARD void *	ctx () const
	Returns the user-owned context pointer attached to this query.
Scheduling declarations
Marks whether this query must run on the main thread/serial path. Use this for callbacks with side effects that are not captured by component read/write declarations, such as external APIs that are main-thread-only. This flag is scheduling metadata only and does not affect query matching, hashing, shared-cache identity, or cache invalidation. Parameters required True when the query requires the main thread/serial path. Returns Self reference.
QueryImpl &	main_thread (bool required=true)
GAIA_NODISCARD bool	main_thread_required () const
	Returns whether this query must run on the main thread/serial path.
Query access declarations
Declares an additional id read by this query callback. Use this for data accessed inside the query kernel but not present as a positive query term. The declaration is scheduling metadata only; it does not change query matching or cache identity. Parameters entity Component/entity id read by user code. Returns Self reference. See also writes(Entity)
QueryImpl &	reads (Entity entity)
template<typename T >
QueryImpl &	reads ()
	Declares an additional component or pair type read by this query callback.
QueryImpl &	writes (Entity entity)
	Declares an additional id written by this query callback.
template<typename T >
QueryImpl &	writes ()
	Declares an additional component or pair type written by this query callback.
GAIA_NODISCARD std::span< const Entity >	custom_reads () const
	Returns explicitly declared read ids that are not query terms.
GAIA_NODISCARD std::span< const Entity >	custom_writes () const
	Returns explicitly declared write ids that are not query terms.
GAIA_NODISCARD QueryAccess	access (Entity entity)
	Returns the effective read/write access for an id.
GAIA_NODISCARD bool	conflicts_with (QueryImpl &other)
	Returns whether this query conflicts with another query's effective access declarations.
GAIA_NODISCARD bool	can_run_parallel (QueryImpl &other)
	Returns whether this query can run concurrently with another query based on declared scheduling metadata.

Static Public Member Functions
static GAIA_NODISCARD bool	match_filters (const Chunk &chunk, const QueryInfo &queryInfo, uint32_t changedWorldVersion, std::span< const uint8_t > compIndices)
	Returns whether a chunk passes the query's changed filters.
static GAIA_NODISCARD bool	match_filters (const Chunk &chunk, const QueryInfo &queryInfo, uint32_t changedWorldVersion)
	Returns whether a chunk passes the query's changed filters.
static GAIA_NODISCARD bool	has_depth_order_hierarchy_enabled_barrier (const QueryInfo &queryInfo)
	Checks whether depth-order grouping can prune disabled hierarchy subtrees.
static GAIA_NODISCARD bool	needs_depth_order_hierarchy_barrier_cache (const QueryInfo &queryInfo, Constraints constraints)
	Checks whether the current row constraints require the depth-order hierarchy barrier cache.
static void	chunk_effective_range (Chunk *pChunk, Constraints constraints, bool needsBarrierCache, bool barrierPasses, uint16_t &from, uint16_t &to) noexcept
	Calculates the row range of a chunk after applying row constraints and depth-order barrier state.
static GAIA_NODISCARD bool	depth_order_hierarchy_barrier_prunes (const QueryInfo &queryInfo)
	Checks whether cached depth-order barrier results can prune any matched archetype.
static GAIA_NODISCARD bool	survives_cascade_hierarchy_enabled_barrier (const QueryInfo &queryInfo, const Archetype &archetype)
	Fast enabled-subtree gate for cached depth_order(...) queries over fragmenting hierarchy relations. ChildOf is the native built-in example, but the rule is semantic: the relation must support depth_order(...) and also form a fragmenting hierarchy chain. For such relations, all rows in the archetype share the same direct parent target. That lets us prune the entire archetype when its parent chain crosses a disabled entity. Non-fragmenting hierarchy relations such as Parent cannot use this archetype-level check and must stay on the per-entity traversal path instead.
template<typename TIter >
static void	finish_iter_writes (TIter &it)
static void	finish_typed_chunk_writes_runtime (World &world, Chunk *pChunk, uint16_t from, uint16_t to, const Entity *pArgIds, const bool *pWriteFlags, uint32_t argCnt, uint32_t firstWriteArg)
template<typename... T>
static void	finish_typed_chunk_writes (World &world, Chunk *pChunk, uint16_t from, uint16_t to)
static void	finish_typed_iter_writes_runtime (Iter &it, const Entity *pArgIds, const bool *pWriteFlags, uint32_t argCnt, uint32_t firstWriteArg)
static GAIA_NODISCARD ExecPayloadKind	exec_payload_kind (const QueryInfo &queryInfo, Constraints constraints)
	Classifies the generic batch payload needed for a matched query under row constraints.
template<typename TMode >
static GAIA_NODISCARD constexpr Constraints	iter_mode_constraints ()
	Maps an iteration-mode tag to the runtime row constraints used by iterators.
template<typename Func , typename TMode >
static void	run_query_func (World *pWorld, Func func, ChunkBatch &batch)
	Executes an iterator callback for one prepared chunk batch.
template<typename Func >
static void	run_query_arch_func (World *pWorld, Func func, ChunkBatch &batch, Constraints constraints)
	Executes an archetype-level iterator callback for one prepared chunk batch. The iterator is initialized with archetype metadata but no chunk rows.
template<typename Func , typename TMode >
static void	run_query_func (World *pWorld, Func func, std::span< ChunkBatch > batches)
	Executes an iterator callback over a contiguous list of prepared chunk batches.
template<typename Func >
static void	invoke_query_task_job (void *pCtx)
template<typename Func >
static void	cleanup_query_task_job (void *pCtx)
template<typename Func , typename TMode >
static void	cleanup_query_job (void *pCtx)
template<typename Func >
static void	run_query_func_runtime (World *pWorld, Func func, std::span< ChunkBatch > batches, Constraints constraints)
template<typename Func , typename TIter >
static void	invoke_runtime_iter (void *pFunc, TIter &it)
	Invokes a type-erased public iterator callback.
static GAIA_NODISCARD bool	is_adjunct_direct_term (const World &world, const QueryTerm &term)
	Returns whether a direct term is backed by non-fragmenting storage and must be evaluated per entity.
static GAIA_NODISCARD bool	uses_semantic_is_matching (const QueryTerm &term)
	Returns whether a term uses semantic Is matching rather than direct storage matching.
static GAIA_NODISCARD bool	uses_in_is_matching (const QueryTerm &term)
	Returns whether a term uses strict semantic Is matching that excludes the base entity itself.
static GAIA_NODISCARD bool	uses_non_direct_is_matching (const QueryTerm &term)
	Returns whether a term uses any semantic Is matching rather than direct storage matching.
static GAIA_NODISCARD bool	uses_potential_inherited_id_matching (const QueryTerm &term)
	Returns whether a term could use inherited-id matching based on query shape alone. This intentionally ignores mutable world metadata such as current OnInstantiate policy.
static GAIA_NODISCARD bool	uses_inherited_id_matching (const World &world, const QueryTerm &term)
	Returns whether a term uses semantic inherited-id matching rather than direct storage matching.
static GAIA_NODISCARD bool	match_entity_term (const World &world, Entity entity, const QueryTerm &term)
	Evaluates term presence for a concrete entity using either direct or semantic semantics.
static GAIA_NODISCARD bool	match_single_direct_target_term (const World &world, Entity entity, Entity termId, QueryCtx::DirectTargetEvalKind kind)
	Evaluates a compiled single-term direct-target query without re-walking the generic term loop.
static GAIA_NODISCARD uint32_t	count_direct_term_entities (const World &world, const QueryTerm &term)
static void	collect_direct_term_entities (const World &world, const QueryTerm &term, cnt::darray< Entity > &out)
template<typename Func >
static GAIA_NODISCARD bool	for_each_direct_term_entity (const World &world, const QueryTerm &term, Func &&func)
static GAIA_NODISCARD bool	can_use_direct_entity_seed_eval (const QueryInfo &queryInfo)
	Detects queries that can skip archetype seeding and start directly from entity-backed term indices.
static GAIA_NODISCARD bool	can_use_direct_target_eval (const QueryInfo &queryInfo)
	Detects queries whose terms can be evaluated directly against concrete target entities.
static GAIA_NODISCARD bool	has_only_direct_or_terms (const QueryInfo &queryInfo)
	Detects the special direct OR/NOT shape that can be answered from a union of direct term entity sets.
static void	add_chunk_run (cnt::darray< detail::BfsChunkRun > &runs, const EntityContainer &ec, uint32_t entityOffset)
static GAIA_NODISCARD bool	should_prefer_direct_seed_term (const World &world, const QueryTerm &candidate, uint32_t candidateCount, const DirectEntitySeedPlan &plan)
	Chooses the narrowest available seed for direct non-fragmenting evaluation.
static GAIA_NODISCARD DirectEntitySeedPlan	direct_entity_seed_plan (const World &world, const QueryInfo &queryInfo)
static GAIA_NODISCARD bool	match_direct_entity_terms (const World &world, Entity entity, const QueryInfo &queryInfo, const DirectEntitySeedInfo &seedInfo)
	Evaluates the remaining direct terms for a single seeded entity after the seed term itself was consumed.
static GAIA_NODISCARD const QueryTerm *	find_direct_all_seed_term (const QueryInfo &queryInfo, const DirectEntitySeedPlan &plan)
static GAIA_NODISCARD DirectEntitySeedEvalPlan	direct_all_seed_eval_plan (const QueryInfo &queryInfo, const DirectEntitySeedInfo &seedInfo)
static GAIA_NODISCARD bool	can_use_direct_seed_run_cache (const World &world, const QueryInfo &queryInfo, const QueryTerm &seedTerm)
	Returns whether a repeated semantic or inherited seed can be cached as chunk runs.
template<typename Func >
static GAIA_NODISCARD bool	for_each_direct_all_seed (const World &world, const QueryInfo &queryInfo, const DirectEntitySeedPlan &plan, Constraints constraints, Func &&func)
static GAIA_NODISCARD bool	match_direct_entity_constraints (const World &world, const QueryInfo &queryInfo, Entity entity, Constraints constraints)
	Applies iterator-specific entity state constraints to the direct seeded path.
static GAIA_NODISCARD bool	can_use_archetype_bucket_count (const World &world, const QueryInfo &queryInfo, const DirectEntitySeedInfo &seedInfo)
	Detects when a direct seed can be counted by archetype buckets instead of per entity checks.
static GAIA_NODISCARD uint32_t	count_direct_entity_seed_by_archetype (const World &world, const QueryInfo &queryInfo, const cnt::darray< Entity > &seedEntities, const DirectEntitySeedInfo &seedInfo, Constraints constraints)
	Groups seeded entities by archetype and counts whole buckets when only structural ALL/NOT terms remain.
static GAIA_NODISCARD uint32_t	count_direct_or_union (const World &world, const QueryInfo &queryInfo, Constraints constraints)
	Counts the union of direct OR term entity sets while deduplicating entities across terms.
static GAIA_NODISCARD bool	is_empty_direct_or_union (const World &world, const QueryInfo &queryInfo, Constraints constraints)
	Returns whether the direct OR union becomes empty after applying NOT terms and iterator constraints.
static DirectEntitySeedInfo	build_direct_entity_seed (const World &world, const QueryInfo &queryInfo, cnt::darray< Entity > &out)
	Builds the best direct entity seed set from the smallest positive ALL term or the OR union fallback.
static GAIA_NODISCARD bool	has_direct_not_terms (const QueryInfo &queryInfo)
	Returns whether direct OR evaluation still has direct NOT terms that must be checked per entity.
static GAIA_NODISCARD bool	match_entity_filters (const World &world, Entity entity, const QueryInfo &queryInfo)
	Evaluates the entity-level terms that are not fully represented by archetype membership.
static void	init_direct_entity_iter (const QueryInfo &queryInfo, const World &world, const EntityContainer &ec, Iter &it, uint8_t *pIndices, Entity *pTermIds, const Archetype *&pLastArchetype)
static void	init_direct_entity_iter (const QueryInfo &queryInfo, const World &world, Entity entity, Iter &it, uint8_t *pIndices, Entity *pTermIds)
static GAIA_NODISCARD bool	can_use_direct_chunk_term_eval_arg (World &world, const QueryInfo &queryInfo, const DirectChunkArgEvalDesc &desc)
	Returns whether a runtime query argument descriptor can use direct chunk access.
static GAIA_NODISCARD bool	can_use_direct_chunk_term_eval_descs (World &world, const QueryInfo &queryInfo, const DirectChunkArgEvalDesc *pDescs, uint32_t descCnt)

Static Public Attributes
static bool	SilenceInvalidCacheKindAssertions = false

Friends
class	SystemBuilder

Member Enumeration Documentation

ExecPayloadKind

enum class gaia::ecs::detail::QueryImpl::ExecPayloadKind : uint8_t

strong

Runtime payload layout required by generic chunk-batch execution.

Enumerator
Plain	Plain batches without group ids, inherited data, sorted slices, or barrier metadata.
Grouped	Batches carry group ids but do not require sorted slices or inherited/barrier metadata.
NonTrivial	Batches require non-trivial side payload such as sorted slices, inherited data, or barriers.

QueryPlanFlags

enum gaia::ecs::detail::QueryImpl::QueryPlanFlags : uint8_t

Orthogonal flags attached to a prepared query plan.

Flags describe properties that can apply to multiple runner modes. Keep them separate from QueryPlanMode so filtered and unfiltered variants do not multiply execution-mode values.

Enumerator
QueryPlanFlag_None	No additional query-plan properties are present.
QueryPlanFlag_Filtered	The query has per-chunk filters such as changed terms.
QueryPlanFlag_EntityFilter	The query has entity-filter terms that require per-entity rechecks.
QueryPlanFlag_InheritedPayload	The query carries inherited component data into iterator payloads.
QueryPlanFlag_Grouped	The query uses grouped payload/ranges or grouped cache ordering.
QueryPlanFlag_Sorted	The plan may need sorted cache slices; runners use them only with non-trivial payload.
QueryPlanFlag_BarrierCache	The plan must use the depth-order hierarchy barrier cache when checking archetype/row ranges.

QueryPlanMode

enum class gaia::ecs::detail::QueryImpl::QueryPlanMode : uint8_t

strong

Prepared query runner mode shared by typed callbacks and public Iter callbacks.

The mode is selected after the query cache has been matched. It describes the runner family independently from orthogonal query properties such as filters. Public C++ templates are expected to remain thin adapters on top of this prepared execution metadata.

Enumerator
Empty	The selected group/range has no matching archetypes, so execution can return immediately.
General	Use the generic query execution path because no specialized runner is valid.
EntitySeed	Direct entity-seed evaluation over explicitly selected entities.
DirectDense	Direct cached archetype/chunk iteration with query-term indices matching storage layout.
MappedDense	Typed dense cached archetype/chunk iteration using mapped component access. Public Iter callbacks use DirectDense with iterator component-index mapping instead.
Sorted	Sorted payload execution that must preserve cache-provided chunk order.
Traversal	Traversal or inherited payload execution that requires the mapped generic path.

Member Function Documentation

access()

GAIA_NODISCARD QueryAccess gaia::ecs::detail::QueryImpl::access ( Entity  entity )

inline

Returns the effective read/write access for an id.

Effective access combines positive query terms and explicit reads()/writes() declarations. Pair query terms do not imply data access; use explicit reads(Entity) or writes(Entity) when a pair id is a custom scheduling key.

Parameters

entity

Component/entity id to inspect.

Returns

Effective access mode for the id.

add() [1/2]

QueryImpl & gaia::ecs::detail::QueryImpl::add ( const char *  str,   ...  )

inline

Creates a query from a null-terminated expression string.

Expression is a string between separators. Spaces are trimmed automatically.

Supported modifiers: "," - separates expressions "||" - query::or_(OR chain; at least two OR terms) "?" - query::any (optional) "!" - query::none "&" - read-write access "%e" - entity value "(rel,tgt)" - relationship pair, a wildcard character in either rel or tgt is translated into All "$name" - query variable ($this is reserved) "Id(src)" - source lookup (src can be a variable, e.g. Planet($planet), or $this for default source)

Example: struct Position {...}; struct Velocity {...}; struct RigidBody {...}; struct Fuel {...}; auto player = w.add(); w.query().add("&Position, !Velocity, ?RigidBody, (Fuel,*), %e", player.value()); Translates into: w.query() .all<Position&>() .no<Velocity>() .any<RigidBody>() .all(Pair(w.add<Fuel>().entity, All)>() .all(Player);

Adds one or more query terms described by a string expression. Component names are resolved immediately while the expression is parsed and the resulting component ids are baked into the query terms. Later scope, path or alias changes do not rewrite an already parsed query. Names in str are resolved while add(...) parses the expression and the resulting ids are baked into the query. Active component scope and lookup-path state affect parsing only at that moment and do not rewrite the query later.

Parameters

str	Null-terminated string with the query expression.
...	Optional varargs consumed by e substitutions inside str.

Returns

Reference to this query.

add() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::add ( QueryInput  item )

inline

Adds a prebuilt query input item.

Parameters

item	Query term or filter description.

Returns

Self reference.

all() [1/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::all ( )

inline

Adds a required typed term.

Template Parameters

T	Component or pair type.

Returns

Self reference.

all() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::all ( const QueryTermOptions &  options )

inline

Adds a required typed term.

Template Parameters

T	Component or pair type.

Parameters

options

Term options.

Returns

Self reference.

all() [3/3]

QueryImpl & gaia::ecs::detail::QueryImpl::all ( Entity  entity, const QueryTermOptions &  options = QueryTermOptions{}  )

inline

Adds a required entity or pair term.

Parameters

entity	Required entity or pair id.
options	Term options.

Returns

Self reference.

any() [1/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::any ( )

inline

Adds an optional typed term.

Template Parameters

T	Component or pair type.

Returns

Self reference.

any() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::any ( const QueryTermOptions &  options )

inline

Adds an optional typed term.

Template Parameters

T	Component or pair type.

Parameters

options

Term options.

Returns

Self reference.

any() [3/3]

QueryImpl & gaia::ecs::detail::QueryImpl::any ( Entity  entity, const QueryTermOptions &  options = QueryTermOptions{}  )

inline

Adds an optional entity or pair term.

Parameters

entity	Optional entity or pair id.
options	Term options.

Returns

Self reference.

arr()

template<typename Container >

void gaia::ecs::detail::QueryImpl::arr ( Container &  outArray, Constraints  constraints = Constraints::EnabledOnly  )

inline

Appends all components or entities matching the query to the output array.

Template Parameters

Container

Container type

Parameters

[out]	outArray	Container storing entities or components
	constraints	QueryImpl constraints

bytecode()

GAIA_NODISCARD util::str gaia::ecs::detail::QueryImpl::bytecode ( )

inline

Returns a textual dump of the generated query VM bytecode.

Returns

Bytecode dump.

cache_policy()

GAIA_NODISCARD QueryCachePolicy gaia::ecs::detail::QueryImpl::cache_policy ( )

inline

Returns the effective cache policy chosen for the query.

Returns

Effective cache policy.

cache_src_trav()

GAIA_NODISCARD uint16_t gaia::ecs::detail::QueryImpl::cache_src_trav ( ) const

inline

Returns the traversed-source snapshot cap. 0 disables explicit traversed-source snapshot caching.

Returns

Traversed-source snapshot cap.

can_process_archetype_inter()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::can_process_archetype_inter ( const QueryInfo &  queryInfo, const Archetype &  archetype, Constraints  constraints, int8_t  barrierPasses = -1  ) const

inline

Checks whether a matched archetype can be processed for the current row constraints.

Parameters

queryInfo	Prepared query cache and execution metadata.
archetype	Matched archetype to test.
constraints	Entity-row subset exposed to the callback.
barrierPasses	Cached barrier result, or -1 to compute the enabled hierarchy gate directly.

Returns

True when the archetype is eligible for callback execution.

can_run_parallel()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::can_run_parallel ( QueryImpl &  other )

inline

Returns whether this query can run concurrently with another query based on declared scheduling metadata.

Parameters

other

Query to compare against.

Returns

True when neither query requires the main thread and conflicts_with(other) is false.

can_use_direct_chunk_iteration_fastpath()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::can_use_direct_chunk_iteration_fastpath ( const QueryInfo &  queryInfo ) const

inline

Checks whether typed callbacks can use dense chunk iteration while preserving required cache ordering.

Parameters

queryInfo

Prepared query cache and execution metadata.

Returns

True when direct chunk iteration preserves required ordering and hierarchy-barrier pruning semantics.

can_use_direct_chunk_term_eval_arg()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::can_use_direct_chunk_term_eval_arg ( World &  world, const QueryInfo &  queryInfo, const DirectChunkArgEvalDesc &  desc  )

inlinestatic

Returns whether a runtime query argument descriptor can use direct chunk access.

Parameters

world	World
queryInfo	Query info
desc	Typed argument descriptor

Returns

True if the argument can use direct chunk access. False otherwise.

can_use_direct_seed_run_cache()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::can_use_direct_seed_run_cache ( const World &  world, const QueryInfo &  queryInfo, const QueryTerm &  seedTerm  )

inlinestatic

Returns whether a repeated semantic or inherited seed can be cached as chunk runs.

Parameters

world	World
queryInfo	Query info
seedTerm	Seed term

Returns

True if direct-seed runs can be cached. False otherwise.

changed() [1/2]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::changed ( )

inline

Marks a typed term for changed() filtering.

Template Parameters

T	Component or pair type.

Returns

Self reference.

changed() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::changed ( Entity  entity )

inline

Marks a runtime component or pair for changed() filtering.

Parameters

entity

Component or pair id to monitor.

Returns

Self reference.

chunk_effective_range()

static void gaia::ecs::detail::QueryImpl::chunk_effective_range ( Chunk *  pChunk, Constraints  constraints, bool  needsBarrierCache, bool  barrierPasses, uint16_t &  from, uint16_t &  to  )

inlinestaticnoexcept

Calculates the row range of a chunk after applying row constraints and depth-order barrier state.

Parameters

pChunk	Chunk to inspect.
constraints	Entity-row subset exposed to the callback.
needsBarrierCache	True when barrier state participates in row selection.
barrierPasses	Cached barrier result for the archetype containing the chunk.
from	Receives the first row to process.
to	Receives the one-past-the-end row to process.

conflicts_with()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::conflicts_with ( QueryImpl &  other )

inline

Returns whether this query conflicts with another query's effective access declarations.

Two queries conflict when both access the same id and at least one side writes it. This check uses component access declared by positive query terms plus custom reads()/writes() declarations. It does not account for world structural mutation or arbitrary side effects.

Parameters

other

Query to compare against.

Returns

True if the two queries should not run concurrently based on declared access.

count()

uint32_t gaia::ecs::detail::QueryImpl::count ( Constraints  constraints = Constraints::EnabledOnly )

inline

Calculates the number of entities matching the query.

Warning

Only use if you only care about the number of entities matching the query. The result is not cached and repeated calls to the function might be slow.If you already called arr(), use the size provided by the array.Use empty() instead of calling count() == 0.

Note

For changed() queries this is a non-consuming probe. It does not advance the query's changed-reporting state. Iteration APIs such as each()/arr() do consume it.

Returns

The number of matching entities

count_inter()

template<bool UseFilters>

GAIA_NODISCARD uint32_t gaia::ecs::detail::QueryImpl::count_inter ( const QueryInfo &  queryInfo, Constraints  constraints  ) const

inline

Fast count() path for direct non-fragmenting queries that can seed from entity-backed indices.

Template Parameters

UseFilters

True when changed/per-chunk filters must be evaluated.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row constraints to apply.

Returns

Number of entities matching the query under constraints.

See also

count(Constraints)

ctx() [1/2]

GAIA_NODISCARD void * gaia::ecs::detail::QueryImpl::ctx ( ) const

inline

Returns the user-owned context pointer attached to this query.

Returns

Context pointer, or null when none is attached.

ctx() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::ctx ( void *  pCtx )

inline

Sets the user-owned context pointer visible through Iter::ctx() during iterator callbacks. Changing the pointer does not affect query identity, query matching, shared-cache lookup, or cached query storage. Identical shared-cache query shapes may therefore keep different context pointers.

Note

Gaia-ECS stores only the pointer. The caller owns allocation, lifetime, destruction, and any synchronization needed when a parallel query callback reads or writes the pointed-to data.

Parameters

pCtx	Context pointer. May be null.

Returns

Self reference.

custom_reads()

GAIA_NODISCARD std::span< const Entity > gaia::ecs::detail::QueryImpl::custom_reads ( ) const

inline

Returns explicitly declared read ids that are not query terms.

Returns

Read-only span over custom read declarations.

custom_writes()

GAIA_NODISCARD std::span< const Entity > gaia::ecs::detail::QueryImpl::custom_writes ( ) const

inline

Returns explicitly declared write ids that are not query terms.

Returns

Read-only span over custom write declarations.

depth_order() [1/2]

template<typename Rel >

QueryImpl & gaia::ecs::detail::QueryImpl::depth_order ( )

inline

Orders cached query entries by fragmenting relation depth so iteration runs breadth-first top-down.

Template Parameters

Rel	Fragmenting hierarchy relation, typically ChildOf.

Returns

Reference to this query builder.

depth_order() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::depth_order ( Entity  relation = ChildOf )

inline

Orders cached query entries by fragmenting relation depth so iteration runs breadth-first top-down. Intended only for fragmenting relations such as ChildOf or DependsOn where the target participates in archetype identity. Unlike order_by(relation, TravOrder), this affects the cached query iteration order itself and can therefore prune fragmenting disabled subtrees at the archetype level. For non-fragmenting relations such as Parent, use order_by(...) instead.

Parameters

relation

Fragmenting hierarchy relation.

Returns

Reference to this query builder.

depth_order_hierarchy_barrier_prunes()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::depth_order_hierarchy_barrier_prunes ( const QueryInfo &  queryInfo )

inlinestatic

Checks whether cached depth-order barrier results can prune any matched archetype.

Parameters

queryInfo

Prepared query cache and execution metadata.

Returns

True when depth-order hierarchy barriers are active and the cache can prune rows.

each() [1/2]

template<typename Func , std::enable_if_t<!detail::is_query_iter_callback_v< Func >, int > >

void gaia::ecs::detail::QueryImpl::each ( Func  func )

inline

Iterates query matches using the default execution mode.

Template Parameters

Func	Iterator callback type invocable with Iter&.

Parameters

func	Callable invoked for each match.

See also

Iter::ctx() const

each() [2/2]

template<typename Func , std::enable_if_t<!detail::is_query_iter_callback_v< Func >, int > >

void gaia::ecs::detail::QueryImpl::each ( Func  func, QueryExecType  execType  )

inline

Iterates query matches using the selected execution mode.

Template Parameters

Func	Iterator callback type invocable with Iter&.

Parameters

func	Callable invoked for each match.
execType	Execution mode.

See also

Iter::ctx() const

each_arch()

template<typename Func >

void gaia::ecs::detail::QueryImpl::each_arch ( Func  func, Constraints  constraints = Constraints::EnabledOnly  )

inline

Iterates matching archetypes instead of individual entities.

Template Parameters

Func	Iterator callback type invocable with Iter&.

Parameters

func	Callable invoked for each matching archetype iterator.
constraints	Iteration constraints applied before invoking func.

See also

Iter::ctx() const

each_direct_iter_inter()

template<typename Func >

void gaia::ecs::detail::QueryImpl::each_direct_iter_inter ( QueryInfo &  queryInfo, Constraints  constraints, Func  func  )

inline

Runs an iterator-based each() callback over directly seeded entities using one-row chunk views.

Template Parameters

Func	Callback type invocable with Iter&.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row constraints to apply.
func	Callback invoked for each direct-entity iterator.

See also

each(Func)

each_entity_enabled()

void gaia::ecs::detail::QueryImpl::each_entity_enabled ( void *  pCtx, void(*)(void *, Entity)  func  )

inline

Iterates matching enabled entities through a non-template erased callback.

Parameters

pCtx	User callback context.
func	Callback invoked for each matching entity.

each_iter()

template<typename Func >

void gaia::ecs::detail::QueryImpl::each_iter ( Iter &  it, Func  func  )

inline

Runs a typed callback against an already prepared iterator. This is used by higher-level adapters that normalize execution to Iter& first and then materialize typed arguments on top of the iterator.

Template Parameters

Func	Callback type.

Parameters

it	Iterator positioned on the current chunk range.
func	Callback to invoke.

each_runtime_erased() [1/2]

void gaia::ecs::detail::QueryImpl::each_runtime_erased ( QueryExecType  execType, void *  pFunc, void(*)(void *, Iter &)  invoke, Constraints  constraints  )

inline

Runs a type-erased public iterator callback through generic query execution.

Parameters

execType	Query execution mode requested by the public API.
pFunc	Pointer to the stored callback object.
invoke	Type-erased callback invoker.
constraints	Entity-row subset exposed to the callback.

each_runtime_erased() [2/2]

void gaia::ecs::detail::QueryImpl::each_runtime_erased ( QueryInfo &  queryInfo, const QueryPlan &  plan, QueryExecType  execType, void *  pFunc, void(*)(void *, Iter &)  invoke, Constraints  constraints  )

inline

Runs a type-erased public iterator callback using an already prepared query cache and plan.

Parameters

queryInfo	Prepared query cache and execution metadata.
plan	Prepared query execution metadata.
execType	Query execution mode requested by the public API.
pFunc	Pointer to the stored callback object.
invoke	Type-erased callback invoker.
constraints	Entity-row subset exposed to the callback.

each_runtime_inter()

template<QueryExecType ExecType, typename Func >

void gaia::ecs::detail::QueryImpl::each_runtime_inter ( Func  func, Constraints  constraints = Constraints::EnabledOnly  )

inline

Runs a public iterator callback through the fastest supported runtime path.

Template Parameters

ExecType	Query execution mode requested by the public API.
Func	Public iterator callback type.

Parameters

func	Callback invoked for each iterator step.
constraints	Entity-row subset exposed to the callback.

each_walk()

template<typename Func , std::enable_if_t<!detail::is_query_walk_core_callback_v< Func >, int > >

void gaia::ecs::detail::QueryImpl::each_walk ( Func  func, Entity  relation, TravOrder  order = TravOrder::Down, Constraints  constraints = Constraints::EnabledOnly  )

inline

Iterates entities matching the query in a requested relation traversal order. For relation R this treats Pair(R, X) on entity E as "E points at X". Traversal changes only visit order. Nodes with the same parent are ordered by entity id.

Template Parameters

Func	Callback type. May accept Iter& or an entity value.

Parameters

func	Callable invoked for each ordered entity.
relation	Relation used to order matched entities.
order	Traversal order to apply.
constraints	QueryImpl constraints

See also

ordered_entities_walk(QueryInfo&, Entity, TravOrder, Constraints)

empty()

bool gaia::ecs::detail::QueryImpl::empty ( Constraints  constraints = Constraints::EnabledOnly )

inline

Returns true or false depending on whether there are any entities matching the query.

Warning

Only use if you only care if there are any entities matching the query. The result is not cached and repeated calls to the function might be slow. If you already called arr(), checking if it is empty is preferred. Use empty() instead of calling count()==0.

Note

For changed() queries this is a non-consuming probe. It does not advance the query's changed-reporting state. Iteration APIs such as each()/arr() do consume it.

Returns

True if there are any entities matching the query. False otherwise.

empty_inter()

template<bool UseFilters>

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::empty_inter ( const QueryInfo &  queryInfo, Constraints  constraints  ) const

inline

Fast empty() path for direct non-fragmenting queries that can seed from entity-backed indices.

Template Parameters

UseFilters

True when changed/per-chunk filters must be evaluated.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row constraints to apply.

Returns

True if no entity matches the query under constraints.

See also

empty(Constraints)

exec_payload_kind()

static GAIA_NODISCARD ExecPayloadKind gaia::ecs::detail::QueryImpl::exec_payload_kind ( const QueryInfo &  queryInfo, Constraints  constraints  )

inlinestatic

Classifies the generic batch payload needed for a matched query under row constraints.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row subset exposed to the callback.

Returns

Payload layout required by generic chunk-batch runners.

fetch()

QueryInfo & gaia::ecs::detail::QueryImpl::fetch ( )

inline

Fetches the QueryInfo object. Creates or refreshes the backing QueryInfo if needed.

Returns

QueryInfo object.

for_each_direct_or_union()

template<typename Func >

void gaia::ecs::detail::QueryImpl::for_each_direct_or_union ( World &  world, const QueryInfo &  queryInfo, Constraints  constraints, Func &&  func  )

inline

Visits the deduplicated OR union for direct-seeded queries without materializing an entity seed array first.

Template Parameters

Func	Callback type

Parameters

world	World
queryInfo	Query info
constraints	Iterator constraints applied to the candidate entities.
func	Callback executed for each surviving entity.

gen()

GAIA_NODISCARD uint32_t gaia::ecs::detail::QueryImpl::gen ( ) const

inline

Returns the cache handle generation of this query.

Returns

Query generation, or QueryIdBad for uncached queries.

group_by() [1/3]

QueryImpl & gaia::ecs::detail::QueryImpl::group_by ( Entity  entity, TGroupByFunc  func = group_by_func_default  )

inline

Organizes matching archetypes into groups according to the grouping function and entity. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.

Parameters

entity	The entity to group by.
func	The function to use for grouping. Returns a GroupId to group the entities by.

Returns

Reference to this query builder.

group_by() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::group_by ( TGroupByFunc  func = group_by_func_default )

inline

Organizes matching archetypes into groups according to the grouping function. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.

Template Parameters

T	Component to group by. It is registered if it hasn't been registered yet.

Parameters

func	The function to use for grouping. Returns a GroupId to group the entities by.

Returns

Reference to this query builder.

group_by() [3/3]

template<typename Rel , typename Tgt >

QueryImpl & gaia::ecs::detail::QueryImpl::group_by ( TGroupByFunc  func = group_by_func_default )

inline

Organizes matching archetypes into groups according to the grouping function. Does not order iteration by group id. Use group_id(...) to filter one group. Use depth_order(...) or sort_by(...) when iteration order matters.

Template Parameters

Rel	The relation to group by. It is registered if it hasn't been registered yet.
Tgt	The target to group by. It is registered if it hasn't been registered yet.

Parameters

func	The function to use for grouping. Returns a GroupId to group the entities by.

Returns

Reference to this query builder.

group_dep() [1/2]

template<typename Rel >

QueryImpl & gaia::ecs::detail::QueryImpl::group_dep ( )

inline

Declares an explicit relation dependency for grouped cache invalidation. Useful for custom group_by callbacks that depend on hierarchy or relation topology.

Template Parameters

Rel	Relation the group depends on.

group_dep() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::group_dep ( Entity  relation )

inline

Declares an explicit relation dependency for grouped cache invalidation. Useful for custom group_by callbacks that depend on hierarchy or relation topology.

Parameters

relation

Relation the group depends on.

group_id() [1/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::group_id ( )

inline

Selects the group to iterate over.

Template Parameters

T	Component to treat as a group to iterate over. It is registered if it hasn't been registered yet.

group_id() [2/3]

QueryImpl & gaia::ecs::detail::QueryImpl::group_id ( Entity  entity )

inline

Selects the group to iterate over.

Parameters

entity

The entity to treat as a group to iterate over.

group_id() [3/3]

QueryImpl & gaia::ecs::detail::QueryImpl::group_id ( GroupId  groupId )

inline

Selects the group to iterate over.

Parameters

groupId

The group to iterate over.

has_depth_order_hierarchy_enabled_barrier()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::has_depth_order_hierarchy_enabled_barrier ( const QueryInfo &  queryInfo )

inlinestatic

Checks whether depth-order grouping can prune disabled hierarchy subtrees.

Parameters

queryInfo

Prepared query cache and execution metadata.

Returns

True when the query groups by depth order on a relation whose hierarchy can prune disabled subtrees.

has_direct_not_terms()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::has_direct_not_terms ( const QueryInfo &  queryInfo )

inlinestatic

Returns whether direct OR evaluation still has direct NOT terms that must be checked per entity.

Parameters

queryInfo

Query info

Returns

True if direct NOT terms remain. False otherwise.

id()

GAIA_NODISCARD QueryId gaia::ecs::detail::QueryImpl::id ( ) const

inline

Returns the cache handle id of this query.

Returns

Query id, or QueryIdBad for uncached queries.

in()

QueryImpl & gaia::ecs::detail::QueryImpl::in ( Entity  entity, QueryTermOptions  options = QueryTermOptions{}  )

inline

Adds an inherited in(entity) requirement.

Parameters

entity	Target entity matched through inherited Is traversal.
options	Term options.

Returns

Self reference.

invoke_runtime_iter()

template<typename Func , typename TIter >

static void gaia::ecs::detail::QueryImpl::invoke_runtime_iter ( void *  pFunc, TIter &  it  )

inlinestatic

Invokes a type-erased public iterator callback.

Template Parameters

Func	Stored callback type.
TIter	Iterator type passed to the callback.

Parameters

pFunc	Pointer to the stored callback object.
it	Iterator passed to the callback.

is()

QueryImpl & gaia::ecs::detail::QueryImpl::is ( Entity  entity, const QueryTermOptions &  options = QueryTermOptions{}  )

inline

Adds a semantic Is(entity) requirement.

Parameters

entity	Target entity matched through the Is relation.
options	Term options.

Returns

Self reference.

is_adjunct_direct_term()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::is_adjunct_direct_term ( const World &  world, const QueryTerm &  term  )

inlinestatic

Returns whether a direct term is backed by non-fragmenting storage and must be evaluated per entity.

Parameters

world	World
term	Query term

Returns

True if the term is backed by adjunct storage. False otherwise.

is_cached()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::is_cached ( ) const

inline

Returns whether the query is stored in the query cache.

Returns

True if the query is stored in the query cache. False otherwise.

is_empty_direct_or_union()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::is_empty_direct_or_union ( const World &  world, const QueryInfo &  queryInfo, Constraints  constraints  )

inlinestatic

Returns whether the direct OR union becomes empty after applying NOT terms and iterator constraints.

Parameters

world	World
queryInfo	Query info
constraints	Iterator constraints applied to the candidate entities.

Returns

True if no surviving entity exists. False otherwise.

iter_mode_constraints()

template<typename TMode >

static GAIA_NODISCARD constexpr Constraints gaia::ecs::detail::QueryImpl::iter_mode_constraints ( )

inlinestaticconstexpr

Maps an iteration-mode tag to the runtime row constraints used by iterators.

Template Parameters

TMode

One of the IterMode* tag types.

Returns

Entity-row constraints represented by the tag.

job()

template<typename Func >

GAIA_NODISCARD SchedJob gaia::ecs::detail::QueryImpl::job ( Func  func, QueryExecType  execType  )

inline

Adds a query execution job without submitting it.

The returned SchedJob is backed by the world's ECS scheduler descriptor rather than a gaia::mt::JobHandle, so external schedulers can provide their own token, submission, dependency, wait, and cleanup behavior. The job owns only the callback copy and scheduler token; the query and world must outlive the job.

Template Parameters

Func	Query callback type accepted by each().

Parameters

func	Callback invoked when the added job runs.
execType	Query execution mode used inside the job.

Returns

Move-only scheduler job wrapper for the added query execution.

Warning

Structural mutations that invalidate this query while the job is pending are not safe.

See also

SchedJob

each(Func, QueryExecType)

kind() [1/2]

GAIA_NODISCARD QueryCacheKind gaia::ecs::detail::QueryImpl::kind ( ) const

inline

Returns the currently requested cache kind.

Returns

Cache-kind restriction used by this query.

kind() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::kind ( QueryCacheKind  cacheKind )

inline

Sets the hard cache-kind requirement for the query.

Parameters

cacheKind

Requested cache-kind restriction.

Returns

Self reference.

kind_error()

GAIA_NODISCARD QueryKindRes gaia::ecs::detail::QueryImpl::kind_error ( )

inline

Returns the validation result for the current query shape and requested kind.

Returns

Validation result for the query's kind requirement.

kind_error_str()

GAIA_NODISCARD const char * gaia::ecs::detail::QueryImpl::kind_error_str ( )

inline

Returns a human-readable description of the current kind validation result.

Returns

Validation message for the current kind requirement.

main_thread_required()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::main_thread_required ( ) const

inline

Returns whether this query must run on the main thread/serial path.

Returns

True when main_thread(true) was set.

match_all()

void gaia::ecs::detail::QueryImpl::match_all ( QueryInfo &  queryInfo )

inline

Matches the query against all relevant archetypes.

Parameters

queryInfo

Query info

match_filters() [1/2]

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::match_filters ( const Chunk &  chunk, const QueryInfo &  queryInfo, uint32_t  changedWorldVersion  )

inlinestatic

Returns whether a chunk passes the query's changed filters.

Parameters

chunk	Chunk being evaluated.
queryInfo	Query metadata containing changed-filter terms.
changedWorldVersion	World version captured by the previous query pass.

match_filters() [2/2]

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::match_filters ( const Chunk &  chunk, const QueryInfo &  queryInfo, uint32_t  changedWorldVersion, std::span< const uint8_t >  compIndices  )

inlinestatic

Returns whether a chunk passes the query's changed filters.

Parameters

chunk	Chunk being evaluated.
queryInfo	Query metadata containing changed-filter terms.
changedWorldVersion	World version captured by the previous query pass.
compIndices	Per-archetype mapping from query term index to chunk component column.

match_one()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::match_one ( QueryInfo &  queryInfo, const Archetype &  archetype, EntitySpan  targetEntities  )

inline

Matches the query against a single archetype.

Parameters

queryInfo	Query info
archetype	Archetype
targetEntities	Optional target-entity filter

Returns

True if the archetype matches. False otherwise.

match_prefab()

QueryImpl & gaia::ecs::detail::QueryImpl::match_prefab ( )

inline

Makes the query include prefab entities in matches.

Returns

Self reference.

matches_any()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::matches_any ( QueryInfo &  queryInfo, const Archetype &  archetype, EntitySpan  targetEntities  )

inline

Returns whether any supplied target entity matches the query on archetype.

Parameters

queryInfo	Query info
archetype	Archetype
targetEntities	Candidate target entities

Returns

True if any target entity matches. False otherwise.

matches_target_entities()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::matches_target_entities ( QueryInfo &  queryInfo, const Archetype &  archetype, EntitySpan  targetEntities  )

inline

Returns whether any of the provided target entities matches the query semantics.

Parameters

queryInfo	Query info
archetype	Archetype
targetEntities	Candidate target entities

Returns

True if any target entity matches. False otherwise.

needs_depth_order_hierarchy_barrier_cache()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::needs_depth_order_hierarchy_barrier_cache ( const QueryInfo &  queryInfo, Constraints  constraints  )

inlinestatic

Checks whether the current row constraints require the depth-order hierarchy barrier cache.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row subset exposed to the callback.

Returns

True when enabled/disabled row iteration needs cached barrier results.

no() [1/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::no ( )

inline

Adds an excluded typed term.

Template Parameters

T	Component or pair type.

Returns

Self reference.

no() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::no ( const QueryTermOptions &  options )

inline

Adds an excluded typed term.

Template Parameters

T	Component or pair type.

Parameters

options

Term options.

Returns

Self reference.

no() [3/3]

QueryImpl & gaia::ecs::detail::QueryImpl::no ( Entity  entity, const QueryTermOptions &  options = QueryTermOptions{}  )

inline

Adds an excluded entity or pair term.

Parameters

entity	Entity or pair id that must not match.
options	Term options.

Returns

Self reference.

or_() [1/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::or_ ( )

inline

Adds an OR typed term.

Template Parameters

T	Component or pair type.

Returns

Self reference.

or_() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::or_ ( const QueryTermOptions &  options )

inline

Adds an OR typed term.

Template Parameters

T	Component or pair type.

Parameters

options

Term options.

Returns

Self reference.

or_() [3/3]

QueryImpl & gaia::ecs::detail::QueryImpl::or_ ( Entity  entity, const QueryTermOptions &  options = QueryTermOptions{}  )

inline

OR terms (at least one has to match). A single OR term is canonicalized to ALL during query normalization.

Parameters

entity	Entity or pair id.
options	Term options.

Returns

Self reference.

order_by() [1/2]

GAIA_NODISCARD OrderByTravView gaia::ecs::detail::QueryImpl::order_by ( Entity  relation, TravOrder  order  )

inline

Iterates matching entities in an explicit relation traversal order.

Pair(relation, X) on entity E means E points at X. Down visits X before E. Up visits E before X. Reverse variants produce the exact reverse of their base order. Siblings are tie-broken by entity id, so the order is deterministic. The traversal changes only visit order; it does not change which entities match the query. This path resolves order per entity and works for fragmenting relations such as ChildOf and non-fragmenting relations such as Parent. It may be slower than normal chunk iteration.

Parameters

relation	Relation used to order the matched entities.
order	Traversal order to apply.

Returns

Lightweight view exposing each(...).

See also

depth_order(Entity)

group_by(Entity, TGroupByFunc)

sort_by(Entity, TSortByFunc)

order_by() [2/2]

template<typename Rel >

GAIA_NODISCARD OrderByTravView gaia::ecs::detail::QueryImpl::order_by

(

TravOrder

order

)

Iterates matching entities in an explicit typed relation traversal order.

Template Parameters

Rel	Relation type. It is registered if it hasn't been registered yet.

Parameters

order

Traversal order to apply.

Returns

Lightweight view exposing each(...).

See also

order_by(Entity, TravOrder)

ordered_entities_walk()

GAIA_NODISCARD std::span< const Entity > gaia::ecs::detail::QueryImpl::ordered_entities_walk ( QueryInfo &  queryInfo, Entity  relation, TravOrder  order, Constraints  constraints = Constraints::EnabledOnly  )

inline

Builds and caches relation traversal order for the current query result.

Parameters

queryInfo	Query info
relation	Dependency relation used for traversal.
order	Traversal order to apply.
constraints	Match constraints applied before ordering.

Returns

Ordered view of matched entities.

prepare_query_plan() [1/2]

QueryImpl::QueryPlan gaia::ecs::detail::QueryImpl::prepare_query_plan ( const QueryInfo &  queryInfo, const TypedQueryExecState &  state  ) const

inline

Selects the prepared execution plan for typed callbacks.

Parameters

queryInfo	Prepared query cache and execution metadata.
state	Typed callback execution metadata derived from callback arguments.

Returns

Query execution plan shared by typed and public iterator adapters.

prepare_query_plan() [2/2]

GAIA_NODISCARD QueryPlan gaia::ecs::detail::QueryImpl::prepare_query_plan ( const QueryInfo &  queryInfo, Constraints  constraints  ) const

inline

Selects the prepared execution plan for public iterator callbacks.

Parameters

queryInfo	Prepared query cache and execution metadata.
constraints	Entity-row subset exposed to the callback.

Returns

Query execution plan shared by typed and public iterator adapters.

reads()

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::reads ( )

inline

Declares an additional component or pair type read by this query callback.

Template Parameters

T	Component, entity type, or pair type to mark as read.

Returns

Self reference.

See also

reads(Entity)

run_query_arch_func()

template<typename Func >

static void gaia::ecs::detail::QueryImpl::run_query_arch_func ( World *  pWorld, Func  func, ChunkBatch &  batch, Constraints  constraints  )

inlinestatic

Executes an archetype-level iterator callback for one prepared chunk batch. The iterator is initialized with archetype metadata but no chunk rows.

Template Parameters

Func	Callback type invocable with Iter&.

Parameters

pWorld	World owning the archetype batch.
func	Callback invoked for the initialized iterator.
batch	Prepared batch carrying the archetype and inherited metadata.
constraints	Entity-row constraints associated with this execution.

See also

each_arch(Func, Constraints)

run_query_func() [1/2]

template<typename Func , typename TMode >

static void gaia::ecs::detail::QueryImpl::run_query_func ( World *  pWorld, Func  func, ChunkBatch &  batch  )

inlinestatic

Executes an iterator callback for one prepared chunk batch.

Template Parameters

Func	Callback type invocable with Iter&.
TMode	Iteration-mode tag controlling enabled/disabled row constraints.

Parameters

pWorld	World owning the chunk batch.
func	Callback invoked for the initialized iterator.
batch	Prepared chunk batch to expose through the iterator.

See also

run_query_func(World*, Func, std::span<ChunkBatch>)

run_query_func() [2/2]

template<typename Func , typename TMode >

static void gaia::ecs::detail::QueryImpl::run_query_func ( World *  pWorld, Func  func, std::span< ChunkBatch >  batches  )

inlinestatic

Executes an iterator callback over a contiguous list of prepared chunk batches.

Template Parameters

Func	Callback type invocable with Iter&.
TMode	Iteration-mode tag controlling enabled/disabled row constraints.

Parameters

pWorld	World owning the chunk batches.
func	Callback invoked once per initialized chunk iterator.
batches	Prepared chunk batches to iterate.

See also

run_query_func(World*, Func, ChunkBatch&)

run_query_on_chunks_direct_typed()

template<bool HasFilters, typename Func , typename... T>

void gaia::ecs::detail::QueryImpl::run_query_on_chunks_direct_typed ( QueryInfo &  queryInfo, const QueryPlan &  plan, const TypedQueryExecState &  state, Func &  func, core::func_type_list< T... >  types  )

inline

Runs the prepared direct typed row path for simple cached queries.

Template Parameters

HasFilters	True when changed/per-chunk filters must be evaluated.
Func	Callback type.
T	Typed query argument list.

Parameters

queryInfo	Prepared query cache and execution metadata.
plan	Prepared query execution plan.
state	Typed callback execution metadata.
func	Callback invoked for each matching row.
types	Type-list tag identifying callback arguments.

See also

prepare_query_plan(const QueryInfo&, const TypedQueryExecState&) const

run_query_on_chunks_runtime_direct_plain_impl()

template<bool HasFilters, bool HasGroups, typename Func >

void gaia::ecs::detail::QueryImpl::run_query_on_chunks_runtime_direct_plain_impl ( QueryInfo &  queryInfo, const QueryPlan &  plan, Constraints  constraints, Func &  func  )

inline

Runs a public Iter callback over cached chunks without creating chunk batches.

Template Parameters

HasFilters	When true, chunks must pass changed-filter checks before callback invocation.
HasGroups	When true, the prepared cache range carries per-archetype group ids.
Func	Public iterator callback type.

Parameters

queryInfo	Prepared query cache and execution metadata.
plan	Prepared query execution metadata.
constraints	Entity-row subset exposed to the callback.
func	Callback invoked once for each matching chunk.

run_query_on_chunks_runtime_planned()

template<QueryExecType ExecType, typename Func >

void gaia::ecs::detail::QueryImpl::run_query_on_chunks_runtime_planned ( QueryInfo &  queryInfo, const QueryPlan &  plan, Constraints  constraints, Func  func  )

inline

Runs public iterator chunk execution from an already prepared plan.

Template Parameters

ExecType	Query execution mode requested by the public API.
Func	Public iterator callback wrapper type.

Parameters

queryInfo	Prepared query cache and execution metadata.
plan	Prepared query execution metadata.
constraints	Entity-row subset exposed to the callback.
func	Callback wrapper invoked for each iterator step.

scope() [1/2]

GAIA_NODISCARD QueryCacheScope gaia::ecs::detail::QueryImpl::scope ( ) const

inline

Returns the currently requested cache scope.

Returns

Cache scope used by this query.

scope() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::scope ( QueryCacheScope  cacheScope )

inline

Sets the cache scope used by cached queries.

Parameters

cacheScope

Whether cache-backed state stays local or can be shared across identical query shapes.

Returns

Self reference.

selected_query_cache_range()

GAIA_NODISCARD QueryCacheRange gaia::ecs::detail::QueryImpl::selected_query_cache_range ( const QueryInfo &  queryInfo ) const

inline

Selects the cache range visible to this query, applying a selected group id when present.

Parameters

queryInfo

Prepared query cache and execution metadata.

Returns

Cache range metadata; valid == false means the selected group is absent.

set_var() [1/2]

QueryImpl & gaia::ecs::detail::QueryImpl::set_var ( Entity  varEntity, Entity  value  )

inline

Binds a query variable (Var0..Var7) to a concrete entity value. Bound values are applied at runtime before query evaluation.

Parameters

varEntity	Query variable entity (Var0..Var7)
value	Entity value to bind

set_var() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::set_var ( util::str_view  name, Entity  value  )

inline

Binds a named query variable to a concrete entity value.

Parameters

name	Variable name previously assigned by var_name(...)
value	Entity value to bind

sort_by() [1/3]

QueryImpl & gaia::ecs::detail::QueryImpl::sort_by ( Entity  entity, TSortByFunc  func  )

inline

Sorts the query by the specified entity and function.

Parameters

entity	The entity to sort by. Use ecs::EntityBad to sort by chunk entities, or anything else to sort by components.
func	The function to use for sorting. Return -1 to put the first entity before the second, 0 to keep the order, and 1 to put the first entity after the second.

sort_by() [2/3]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::sort_by ( TSortByFunc  func )

inline

Sorts the query by the specified component and function.

Template Parameters

T	The component to sort by. It is registered if it hasn't been registered yet.

Parameters

func	The function to use for sorting. Return -1 to put the first entity before the second, 0 to keep the order, and 1 to put the first entity after the second.

sort_by() [3/3]

template<typename Rel , typename Tgt >

QueryImpl & gaia::ecs::detail::QueryImpl::sort_by ( TSortByFunc  func )

inline

Sorts the query by the specified pair and function.

Template Parameters

Rel	The relation to sort by. It is registered if it hasn't been registered yet.
Tgt	The target to sort by. It is registered if it hasn't been registered yet.

Parameters

func	The function to use for sorting. Return -1 to put the first entity before the second, 0 to keep the order, and 1 to put the first entity after the second.

survives_cascade_hierarchy_enabled_barrier()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::survives_cascade_hierarchy_enabled_barrier ( const QueryInfo &  queryInfo, const Archetype &  archetype  )

inlinestatic

Fast enabled-subtree gate for cached depth_order(...) queries over fragmenting hierarchy relations. ChildOf is the native built-in example, but the rule is semantic: the relation must support depth_order(...) and also form a fragmenting hierarchy chain. For such relations, all rows in the archetype share the same direct parent target. That lets us prune the entire archetype when its parent chain crosses a disabled entity. Non-fragmenting hierarchy relations such as Parent cannot use this archetype-level check and must stay on the per-entity traversal path instead.

Parameters

queryInfo	Prepared query cache and execution metadata.
archetype	Matched archetype to test.

Returns

True when the archetype can be processed under the enabled hierarchy barrier.

uses_in_is_matching()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::uses_in_is_matching ( const QueryTerm &  term )

inlinestatic

Returns whether a term uses strict semantic Is matching that excludes the base entity itself.

Parameters

term	Query term

Returns

True if strict semantic Is matching is used. False otherwise.

uses_inherited_id_matching()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::uses_inherited_id_matching ( const World &  world, const QueryTerm &  term  )

inlinestatic

Returns whether a term uses semantic inherited-id matching rather than direct storage matching.

Parameters

world	World
term	Query term

Returns

True if inherited-id matching is used. False otherwise.

uses_non_direct_is_matching()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::uses_non_direct_is_matching ( const QueryTerm &  term )

inlinestatic

Returns whether a term uses any semantic Is matching rather than direct storage matching.

Parameters

term	Query term

Returns

True if any semantic Is matching is used. False otherwise.

uses_potential_inherited_id_matching()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::uses_potential_inherited_id_matching ( const QueryTerm &  term )

inlinestatic

Returns whether a term could use inherited-id matching based on query shape alone. This intentionally ignores mutable world metadata such as current OnInstantiate policy.

Parameters

term	Query term

Returns

True if the term shape can resolve through inherited-id matching.

uses_semantic_is_matching()

static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::uses_semantic_is_matching ( const QueryTerm &  term )

inlinestatic

Returns whether a term uses semantic Is matching rather than direct storage matching.

Parameters

term	Query term

Returns

True if semantic Is matching is used. False otherwise.

valid()

GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::valid ( )

inline

Returns whether the current query shape satisfies the requested kind.

Returns

True when the current kind requirement is satisfied.

var_name()

QueryImpl & gaia::ecs::detail::QueryImpl::var_name ( Entity  varEntity, util::str_view  name  )

inline

Assigns a human-readable name to a query variable entity (Var0..Var7). The name can be used later by set_var(name, value).

Parameters

varEntity	Query variable entity (Var0..Var7)
name	Variable name (without '$')

Note

Empty names and reserved name "this" are rejected.

writes() [1/2]

template<typename T >

QueryImpl & gaia::ecs::detail::QueryImpl::writes ( )

inline

Declares an additional component or pair type written by this query callback.

Template Parameters

T	Component, entity type, or pair type to mark as written.

Returns

Self reference.

See also

writes(Entity)

writes() [2/2]

QueryImpl & gaia::ecs::detail::QueryImpl::writes ( Entity  entity )

inline

Declares an additional id written by this query callback.

A write conflicts with any read or write of the same id when comparing two queries with conflicts_with(). The declaration is scheduling metadata only; it does not change query matching or cache identity.

Parameters

entity

Component/entity id written by user code.

Returns

Self reference.

See also

reads(Entity)

---

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

• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/query.h
• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/query_builder_typed.inl
• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/query_typed.inl