Gaia-ECS v0.9.3
A simple and powerful entity component system
Loading...
Searching...
No Matches
gaia::ecs::detail::QueryImpl Class Reference

Classes

struct  DirectEntitySeedEvalPlan
 
struct  DirectEntitySeedInfo
 
struct  DirectEntitySeedPlan
 Describes which direct term should seed direct non-fragmenting evaluation. More...
 
class  OrderByWalkView
 

Public Types

enum class  ExecPayloadKind : uint8_t { Plain , Grouped , NonTrivial }
 

Public Member Functions

QueryInfofetch ()
 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.
 
QueryImplcache_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.
 
QueryImplkind (QueryCacheKind cacheKind)
 Sets the hard cache-kind requirement for the query.
 
QueryImplscope (QueryCacheScope cacheScope)
 Sets the cache scope used by cached queries.
 
QueryImplmatch_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
 
template<typename TIter >
GAIA_NODISCARD bool can_process_archetype_inter (const QueryInfo &queryInfo, const Archetype &archetype, int8_t barrierPasses=-1) const
 
template<bool HasFilters, typename TIter , 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 TIter , 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 TIter , 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 TIter , 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 TIter , typename Func >
void run_query (const QueryInfo &queryInfo, Func func)
 
template<QueryExecType ExecType, typename TIter , typename Func >
void run_query_on_archetypes (QueryInfo &queryInfo, Func func)
 
template<QueryExecType ExecType, typename TIter , typename Func >
void run_query_on_chunks (QueryInfo &queryInfo, Func func)
 
GAIA_NODISCARD bool can_use_direct_chunk_iteration_fastpath (const QueryInfo &queryInfo) const
 
template<typename Func , typename... T>
void run_query_on_chunks_direct (QueryInfo &queryInfo, Func func, core::func_type_list< T... >)
 
template<typename TIter , typename Func , typename... T>
GAIA_FORCEINLINE void run_query_on_chunk (TIter &it, Func func, core::func_type_list< T... > types)
 
template<typename TIter , typename Func , typename... T>
GAIA_FORCEINLINE void run_query_on_chunk (const QueryInfo &queryInfo, TIter &it, Func func, core::func_type_list< T... > types)
 
template<typename TIter , typename Func , typename... T>
GAIA_FORCEINLINE void run_query_on_chunk_direct (TIter &it, Func func, core::func_type_list< T... > types)
 
template<typename TIter , typename Func , typename... T>
GAIA_FORCEINLINE void run_query_on_direct_entity (TIter &it, Func func, core::func_type_list< T... > types)
 
template<typename TIter , typename Func , typename... T>
GAIA_FORCEINLINE void run_query_on_direct_entity_direct (TIter &it, Func func, core::func_type_list< T... > types)
 
template<QueryExecType ExecType, typename Func , typename... T>
void each_inter (QueryInfo &queryInfo, Func func, core::func_type_list< T... >)
 
template<QueryExecType ExecType, typename Func >
void each_inter (QueryInfo &queryInfo, Func func)
 
template<QueryExecType ExecType, typename Func >
void each_inter (Func func)
 
template<typename TIter >
GAIA_NODISCARD std::span< const detail::BfsChunkRuncached_direct_seed_runs (QueryInfo &queryInfo, const QueryTerm &seedTerm, const DirectEntitySeedInfo &seedInfo)
 
template<typename TIter >
GAIA_NODISCARD std::span< const Entitycached_direct_seed_entities (QueryInfo &queryInfo, const QueryTerm &seedTerm, const DirectEntitySeedInfo &seedInfo)
 
template<typename TIter >
GAIA_NODISCARD std::span< const Entitycached_direct_seed_chunk_entities (QueryInfo &queryInfo, const QueryTerm &seedTerm, const DirectEntitySeedInfo &seedInfo)
 
template<typename TIter , typename Func >
void for_each_direct_or_union (World &world, const QueryInfo &queryInfo, Func &&func)
 Visits the deduplicated OR union for direct-seeded queries without materializing an entity seed array first.
 
template<bool UseFilters, typename TIter >
GAIA_NODISCARD bool empty_inter (const QueryInfo &queryInfo) 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, typename TIter >
GAIA_NODISCARD uint32_t count_inter (const QueryInfo &queryInfo) const
 Fast count() path for direct non-fragmenting queries that can seed from entity-backed indices.
 
template<typename TIter , typename Func >
void each_chunk_runs_iter (QueryInfo &queryInfo, std::span< const detail::BfsChunkRun > runs, Func func)
 
template<typename TIter , typename Func , typename... T>
void each_chunk_runs (QueryInfo &queryInfo, std::span< const detail::BfsChunkRun > runs, Func func, core::func_type_list< T... >)
 
template<typename TIter , typename Func >
void each_direct_entities_iter (QueryInfo &queryInfo, std::span< const Entity > entities, Func func)
 
template<typename TIter , typename Func , typename... T>
void each_direct_entities (QueryInfo &queryInfo, std::span< const Entity > entities, Func func, core::func_type_list< T... >)
 
template<typename TIter , typename Func >
void each_direct_iter_inter (QueryInfo &queryInfo, Func func)
 Runs an iterator-based each() callback over directly seeded entities using one-row chunk views.
 
template<typename TIter , typename Func , typename... T>
void each_direct_inter (QueryInfo &queryInfo, Func func, core::func_type_list< T... >)
 Runs a typed each() callback over directly seeded entities.
 
template<bool UseFilters, typename TIter , typename ContainerOut >
void arr_inter (QueryInfo &queryInfo, ContainerOut &outArray)
 
 QueryImpl (World &world, QueryCache &queryCache, ArchetypeId &nextArchetypeId, uint32_t &worldVersion, const EntityToArchetypeMap &entityToArchetypeMap, 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.
 
QueryImpladd (const char *str,...)
 Creates a query from a null-terminated expression string.
 
QueryImpladd (QueryInput item)
 Adds a prebuilt query input item.
 
QueryImplis (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
 Adds a semantic Is(entity) requirement.
 
QueryImplin (Entity entity, QueryTermOptions options=QueryTermOptions{})
 Adds an inherited in(entity) requirement.
 
QueryImplall (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
 Adds a required entity or pair term.
 
template<typename T >
QueryImplall (const QueryTermOptions &options)
 Adds a required typed term.
 
template<typename T >
QueryImplall ()
 Adds a required typed term.
 
QueryImplany (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
 Adds an optional entity or pair term.
 
template<typename T >
QueryImplany (const QueryTermOptions &options)
 Adds an optional typed term.
 
template<typename T >
QueryImplany ()
 Adds an optional typed term.
 
QueryImplor_ (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 >
QueryImplor_ (const QueryTermOptions &options)
 Adds an OR typed term.
 
template<typename T >
QueryImplor_ ()
 Adds an OR typed term.
 
QueryImplno (Entity entity, const QueryTermOptions &options=QueryTermOptions{})
 Adds an excluded entity or pair term.
 
template<typename T >
QueryImplno (const QueryTermOptions &options)
 Adds an excluded typed term.
 
template<typename T >
QueryImplno ()
 Adds an excluded typed term.
 
QueryImplvar_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).
 
QueryImplvar_name (Entity varEntity, const char *name)
 Assigns a human-readable name to a query variable entity (Var0..Var7).
 
QueryImplset_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.
 
QueryImplset_var (util::str_view name, Entity value)
 Binds a named query variable to a concrete entity value.
 
QueryImplset_var (const char *name, Entity value)
 Binds a named query variable to a concrete entity value.
 
QueryImplclear_var (Entity varEntity)
 Clears binding for a single query variable (Var0..Var7). The variable becomes unbound for the next query evaluation.
 
QueryImplclear_vars ()
 Clears all runtime variable bindings.
 
QueryImplchanged (Entity entity)
 Marks a runtime component or pair for changed() filtering.
 
template<typename T >
QueryImplchanged ()
 Marks a typed term for changed() filtering.
 
QueryImplsort_by (Entity entity, TSortByFunc func)
 Sorts the query by the specified entity and function.
 
template<typename T >
QueryImplsort_by (TSortByFunc func)
 Sorts the query by the specified component and function.
 
template<typename Rel , typename Tgt >
QueryImplsort_by (TSortByFunc func)
 Sorts the query by the specified pair and function.
 
GAIA_NODISCARD OrderByWalkView walk (Entity relation)
 Walks the relation graph in breadth-first levels for the given relation. Pair(relation, X) on entity E means E depends on X. This path evaluates traversal per entity, so it works for both fragmenting relations such as ChildOf and non-fragmenting relations such as Parent.
 
QueryImpldepth_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 walk(...), 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 walk(...) instead.
 
template<typename Rel >
QueryImpldepth_order ()
 Orders cached query entries by fragmenting relation depth so iteration runs breadth-first top-down.
 
QueryImplgroup_by (Entity entity, TGroupByFunc func=group_by_func_default)
 Organizes matching archetypes into groups according to the grouping function and entity.
 
template<typename T >
QueryImplgroup_by (TGroupByFunc func=group_by_func_default)
 Organizes matching archetypes into groups according to the grouping function.
 
template<typename Rel , typename Tgt >
QueryImplgroup_by (TGroupByFunc func=group_by_func_default)
 Organizes matching archetypes into groups according to the grouping function.
 
QueryImplgroup_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 >
QueryImplgroup_dep ()
 Declares an explicit relation dependency for grouped cache invalidation. Useful for custom group_by callbacks that depend on hierarchy or relation topology.
 
QueryImplgroup_id (GroupId groupId)
 Selects the group to iterate over.
 
QueryImplgroup_id (Entity entity)
 Selects the group to iterate over.
 
template<typename T >
QueryImplgroup_id ()
 Selects the group to iterate over.
 
template<typename Func >
void each (Func func)
 Iterates query matches using the default execution mode.
 
template<typename Func >
void each (Func func, QueryExecType execType)
 Iterates query matches using the selected execution mode.
 
template<typename Func >
void each_arch (Func func)
 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.
 
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 Entityordered_entities_walk (QueryInfo &queryInfo, Entity relation, Constraints constraints=Constraints::EnabledOnly)
 Builds and caches BFS walk order for the current query result.
 
template<typename Func >
void each_walk (Func func, Entity relation, Constraints constraints=Constraints::EnabledOnly)
 Iterates entities matching the query ordered in dependency BFS levels. For relation R this treats Pair(R, X) on entity E as "E depends on X". Systems depending on no other matched system are first, then their dependents level-by-level. Nodes on the same level are ordered by entity id.
 
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.
 

Static Public Member Functions

static GAIA_NODISCARD bool match_filters (const Chunk &chunk, const QueryInfo &queryInfo, uint32_t changedWorldVersion)
 
static GAIA_NODISCARD bool has_depth_order_hierarchy_enabled_barrier (const QueryInfo &queryInfo)
 
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 walk(...) path instead.
 
template<typename T >
static GAIA_NODISCARD constexpr bool is_write_query_arg ()
 
template<typename TIter >
static void finish_iter_writes (TIter &it)
 
template<typename... T>
static void finish_typed_chunk_writes (World &world, Chunk *pChunk, uint16_t from, uint16_t to)
 
template<typename T , typename TIter >
static void finish_typed_iter_write_arg (TIter &it, uint32_t fieldIdx)
 
template<typename TIter , typename... T, size_t... I>
static void finish_typed_iter_writes (TIter &it, std::index_sequence< I... >)
 
template<typename TIter >
static GAIA_NODISCARD ExecPayloadKind exec_payload_kind (const QueryInfo &queryInfo)
 
template<typename TIter >
static GAIA_NODISCARD bool needs_nontrivial_payload (const QueryInfo &queryInfo)
 
template<typename Func , typename TIter >
static void run_query_func (World *pWorld, Func func, ChunkBatch &batch)
 Execute the functor for a given chunk batch.
 
template<typename Func , typename TIter >
static void run_query_arch_func (World *pWorld, Func func, ChunkBatch &batch)
 Execute the functor for a given chunk batch.
 
template<typename Func , typename TIter >
static void run_query_func (World *pWorld, Func func, std::span< ChunkBatch > batches)
 Execute the functor in batches.
 
template<typename... T>
static GAIA_NODISCARD constexpr bool has_write_query_args ()
 
template<typename T >
static GAIA_FORCEINLINE decltype(auto) chunk_view_auto (Chunk *pChunk)
 
template<typename Func , typename... T>
static GAIA_FORCEINLINE void run_query_on_chunk_rows_direct (Chunk *pChunk, uint16_t from, uint16_t to, Func &func, core::func_type_list< T... >)
 
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_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.
 
template<typename TIter >
static GAIA_NODISCARD constexpr Constraints direct_seed_constraints ()
 
static void append_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 QueryTermfind_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 TIter , typename Func >
static GAIA_NODISCARD bool for_each_direct_all_seed (const World &world, const QueryInfo &queryInfo, const DirectEntitySeedPlan &plan, Func &&func)
 
template<typename TIter >
static GAIA_NODISCARD bool match_direct_entity_constraints (const World &world, const QueryInfo &queryInfo, Entity entity)
 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.
 
template<typename TIter >
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)
 Groups seeded entities by archetype and counts whole buckets when only structural ALL/NOT terms remain.
 
template<typename TIter >
static GAIA_NODISCARD uint32_t count_direct_or_union (const World &world, const QueryInfo &queryInfo)
 Counts the union of direct OR term entity sets while deduplicating entities across terms.
 
template<typename TIter >
static GAIA_NODISCARD bool is_empty_direct_or_union (const World &world, const QueryInfo &queryInfo)
 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.
 
template<typename TIter >
static void init_direct_entity_iter (const QueryInfo &queryInfo, const World &world, const EntityContainer &ec, TIter &it, uint8_t *pIndices, Entity *pTermIds, const Archetype *&pLastArchetype)
 
template<typename TIter >
static void init_direct_entity_iter (const QueryInfo &queryInfo, const World &world, Entity entity, TIter &it, uint8_t *pIndices, Entity *pTermIds)
 
template<typename TIter >
static void init_direct_entity_iter_basic (const EntityContainer &ec, TIter &it, const Archetype *&pLastArchetype)
 
template<typename T >
static GAIA_NODISCARD bool can_use_direct_bfs_chunk_term_eval (World &world, const QueryInfo &queryInfo)
 
template<typename... T>
static GAIA_NODISCARD bool can_use_direct_chunk_term_eval (World &world, const QueryInfo &queryInfo)
 
template<typename T >
static GAIA_NODISCARD constexpr bool can_use_raw_chunk_row_arg ()
 
template<typename T >
static Entity inherited_query_arg_id (World &world)
 
template<typename T >
static decltype(auto) inherited_query_entity_arg_by_id (World &world, Entity entity, Entity termId)
 
template<typename T >
static decltype(auto) inherited_query_entity_arg_by_id_cached (World &world, Entity entity, Entity termId, const Archetype *&pLastArchetype, Entity &cachedOwner, bool &cachedDirect)
 
template<typename... T, typename Func , size_t... I>
static void invoke_inherited_query_args_by_id (World &world, Entity entity, const Entity *pArgIds, Func &func, std::index_sequence< I... >)
 
template<typename... T, typename Func , size_t... I>
static void invoke_inherited_query_args_by_id_cached (World &world, Entity entity, const Entity *pArgIds, const Archetype **pLastArchetypes, Entity *pCachedOwners, bool *pCachedDirect, Func &func, std::index_sequence< I... >)
 
template<typename... T, typename Func , size_t... I>
static void invoke_query_args_by_id (World &world, Entity entity, const Entity *pArgIds, Func &func, std::index_sequence< I... >)
 
template<typename... T, size_t... I>
static void finish_query_args_by_id (World &world, Entity entity, const Entity *pArgIds, std::index_sequence< I... >)
 

Static Public Attributes

static bool SilenceInvalidCacheKindAssertions = false
 

Member Function Documentation

◆ 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
strNull-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
itemQuery 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
TComponent 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
TComponent or pair type.
Parameters
optionsTerm 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
entityRequired entity or pair id.
optionsTerm options.
Returns
Self reference.

◆ any() [1/3]

template<typename T >
QueryImpl & gaia::ecs::detail::QueryImpl::any ( )
inline

Adds an optional typed term.

Template Parameters
TComponent 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
TComponent or pair type.
Parameters
optionsTerm 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
entityOptional entity or pair id.
optionsTerm 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
ContainerContainer type
Parameters
[out]outArrayContainer storing entities or components
constraintsQueryImpl 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_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
worldWorld
queryInfoQuery info
seedTermSeed 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
TComponent 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
entityComponent or pair id to monitor.
Returns
Self reference.

◆ 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

◆ 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
RelFragmenting hierarchy relation, typically ChildOf.

◆ 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 walk(...), 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 walk(...) instead.

Parameters
relationFragmenting hierarchy relation

◆ each() [1/2]

template<typename Func >
void gaia::ecs::detail::QueryImpl::each ( Func  func)
inline

Iterates query matches using the default execution mode.

Parameters
funcCallable invoked for each match.

◆ each() [2/2]

template<typename Func >
void gaia::ecs::detail::QueryImpl::each ( Func  func,
QueryExecType  execType 
)
inline

Iterates query matches using the selected execution mode.

Parameters
funcCallable invoked for each match.
execTypeExecution mode.

◆ each_arch()

template<typename Func >
void gaia::ecs::detail::QueryImpl::each_arch ( Func  func)
inline

Iterates matching archetypes instead of individual entities.

Parameters
funcCallable invoked for each matching archetype iterator.

◆ each_walk()

template<typename Func >
void gaia::ecs::detail::QueryImpl::each_walk ( Func  func,
Entity  relation,
Constraints  constraints = Constraints::EnabledOnly 
)
inline

Iterates entities matching the query ordered in dependency BFS levels. For relation R this treats Pair(R, X) on entity E as "E depends on X". Systems depending on no other matched system are first, then their dependents level-by-level. Nodes on the same level are ordered by entity id.

Parameters
funcCallable invoked for each ordered entity.
relationDependency relation
constraintsQueryImpl 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.

◆ 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 TIter , typename Func >
void gaia::ecs::detail::QueryImpl::for_each_direct_or_union ( World world,
const QueryInfo queryInfo,
Func &&  func 
)
inline

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

Template Parameters
TIterIterator type
FuncCallback type
Parameters
worldWorld
queryInfoQuery info
funcCallback 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.

Parameters
entityThe entity to group by.
funcThe function to use for grouping. Returns a GroupId to group the entities by.

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

Template Parameters
TComponent to group by. It is registered if it hasn't been registered yet.
Parameters
funcThe function to use for grouping. Returns a GroupId to group the entities by.

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

Template Parameters
RelThe relation to group by. It is registered if it hasn't been registered yet.
TgtThe target to group by. It is registered if it hasn't been registered yet.
Parameters
funcThe function to use for grouping. Returns a GroupId to group the entities by.

◆ 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
RelRelation 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
relationRelation 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
TComponent 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
entityThe 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
groupIdThe group to iterate over.

◆ 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
queryInfoQuery 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
entityTarget entity matched through inherited Is traversal.
optionsTerm options.
Returns
Self reference.

◆ is()

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

Adds a semantic Is(entity) requirement.

Parameters
entityTarget entity matched through the Is relation.
optionsTerm 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
worldWorld
termQuery 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()

template<typename TIter >
static GAIA_NODISCARD bool gaia::ecs::detail::QueryImpl::is_empty_direct_or_union ( const World world,
const QueryInfo queryInfo 
)
inlinestatic

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

Template Parameters
TIterIterator type
Parameters
worldWorld
queryInfoQuery info
Returns
True if no surviving entity exists. False otherwise.

◆ 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
cacheKindRequested 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.

◆ match_all()

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

Matches the query against all relevant archetypes.

Parameters
queryInfoQuery info

◆ 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
queryInfoQuery info
archetypeArchetype
targetEntitiesOptional 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
queryInfoQuery info
archetypeArchetype
targetEntitiesCandidate 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
queryInfoQuery info
archetypeArchetype
targetEntitiesCandidate target entities
Returns
True if any target entity matches. False otherwise.

◆ no() [1/3]

template<typename T >
QueryImpl & gaia::ecs::detail::QueryImpl::no ( )
inline

Adds an excluded typed term.

Template Parameters
TComponent 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
TComponent or pair type.
Parameters
optionsTerm 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
entityEntity or pair id that must not match.
optionsTerm options.
Returns
Self reference.

◆ or_() [1/3]

template<typename T >
QueryImpl & gaia::ecs::detail::QueryImpl::or_ ( )
inline

Adds an OR typed term.

Template Parameters
TComponent 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
TComponent or pair type.
Parameters
optionsTerm 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
entityEntity or pair id.
optionsTerm options.
Returns
Self reference.

◆ ordered_entities_walk()

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

Builds and caches BFS walk order for the current query result.

Parameters
queryInfoQuery info
relationDependency relation used for the walk.
constraintsMatch constraints applied before ordering.
Returns
Ordered view of matched entities.

◆ 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
cacheScopeWhether cache-backed state stays local or can be shared across identical query shapes.
Returns
Self reference.

◆ 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
varEntityQuery variable entity (Var0..Var7)
valueEntity 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
nameVariable name previously assigned by var_name(...)
valueEntity 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
entityThe entity to sort by. Use ecs::EntityBad to sort by chunk entities,
funcThe 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
TThe component to sort by. It is registered if it hasn't been registered yet.
Parameters
funcThe 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
RelThe relation to sort by. It is registered if it hasn't been registered yet.
TgtThe target to sort by. It is registered if it hasn't been registered yet.
Parameters
funcThe 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.

◆ 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
termQuery 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
worldWorld
termQuery 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
termQuery term
Returns
True if any semantic Is matching is used. False otherwise.

◆ 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
termQuery 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
varEntityQuery variable entity (Var0..Var7)
nameVariable name (without '$')
Note
Empty names and reserved name "this" are rejected.

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