Compiled query plan and its incrementally maintained result caches. More...

#include <query_info.h>

Classes
struct	CleanUpTmpArchetypeMatches
	Scope guard that releases the world-owned temporary VM matching frame. More...

Public Types
enum class	MatchArchetypeQueryRet : uint8_t { Fail , Ok , Skip }
	Result of evaluating one archetype for cache insertion. More...

enum class	InvalidationKind : uint8_t { Result , Seed , All }
	Cache layer invalidated after query inputs or world state change. More...

Public Member Functions
void	add_ref ()
	Adds one external reference to this query slot.

void	dec_ref ()
	Releases one external reference to this query slot.

uint32_t	refs () const
	Returns the current external reference count.

void	init (World *world)
	Binds this query info to a world after slot allocation.

void	reset ()
	Resets cached query state for slot reuse while keeping the compiled context object.

void	invalidate (InvalidationKind kind=InvalidationKind::All)
	Marks cached query results stale.

void	invalidate_seed ()
	Marks structural seed matches stale.

void	invalidate_result ()
	Marks final result matches stale while preserving structural seed matches.

void	invalidate_sort ()
	Marks the cached sorted slices dirty without invalidating query membership.

void	compile (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes)
	Compile the query terms into a form we can easily process.

void	recompile ()
	Recompile the query.

GAIA_NODISCARD QueryCtx::CachePolicy	cache_policy () const
	Returns the query cache policy selected during compilation.

GAIA_NODISCARD bool	has_grouped_payload () const
	Returns true when grouped-query payloads are active for this query.

template<typename Container >
void	group_ids (Container &out, bool sortGroups)
	Collects the query's active non-zero group ids.

GAIA_NODISCARD bool	has_sorted_payload () const
	Returns true when sorted-query payloads are active for this query.

GAIA_NODISCARD uint32_t	result_cache_rev () const
	Returns the result membership revision used by reverse-index cache users.

GAIA_NODISCARD bool	result_cache_may_need_prefab_filter () const
	Returns true when the result cache contains archetypes that need default prefab filtering.

GAIA_NODISCARD bool	can_update_with_new_archetype () const
	Returns true when a new archetype can be propagated into the current cache incrementally.

GAIA_NODISCARD bool	can_use_direct_create_archetype_match () const
	Returns whether create-time matching should bypass the temporary one-archetype VM path.

GAIA_NODISCARD bool	direct_create_archetype_match_uses_is () const
	Returns whether direct create-time matching needs Is-aware id checks.

GAIA_NODISCARD bool	operator== (const QueryCtx &other) const
	Compares this compiled plan with an authored query context.

GAIA_NODISCARD bool	operator!= (const QueryCtx &other) const
	Compares this compiled plan with an authored query context for inequality.

template<typename ArchetypeLookup >
void	match (const ArchetypeLookup &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap *pEntityToArchetypeMapVersions, ArchetypeId archetypeLastId, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Tries to match the query against archetypes in entityToArchetypeMap. This is necessary so we do not iterate all chunks over and over again when running queries.

bool	match_one (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Tries to match the query against the provided archetype. This is necessary so we do not iterate all chunks over and over again when running queries.

void	ensure_matches (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap &entityToArchetypeMapVersions, ArchetypeId archetypeLastId, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Refreshes persistent query matches when cache state or world archetypes changed.

void	ensure_matches_transient (const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes, const EntityToArchetypeVersionMap &entityToArchetypeMapVersions, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Rebuilds transient result membership without retaining persistent seed-cache state.

bool	ensure_matches_one (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Ensures persistent result membership for one target archetype.

bool	ensure_matches_one_transient (const Archetype &archetype, EntitySpan targetEntities, const cnt::sarray< Entity, MaxVarCnt > &runtimeVarBindings, uint8_t runtimeVarBindingMask)
	Rebuilds transient result membership by evaluating one target archetype.

bool	register_archetype (const Archetype &archetype, Entity matchedSelector=EntityBad, bool assumeNew=false)
	Registers a new or updated archetype with query caches when it matches this query.

void	calculate_sort_data ()
	Calculates the sort data for the archetypes in the cache. This allows us to iterate entites in the order they are sorted across all archetypes.

void	sort_entities ()
	Applies query entity sorting and rebuilds sorted chunk slices when needed.

void	sort_cache_groups ()
	Sorts cached archetypes by group id when grouped iteration requested ordering.

void	swap_archetype_cache_entry (uint32_t left, uint32_t right)
	Swaps two result-cache entries and every parallel payload array that mirrors cache order.

void	ensure_comp_indices ()
	Rebuilds cached component-index payloads for matched archetypes when marked pending.

void	ensure_direct_chunks (uint32_t idxFrom, uint32_t idxTo, const uint32_t *pDataFields, uint32_t dataFieldCount)
	Rebuilds flattened direct chunk cache when result membership, world structure, selected rows, component-index mapping storage, or cached callback fields changed.

GAIA_NODISCARD bool	has_inherited_data_payload () const
	Returns true when query iteration needs cached inherited data payloads.

void	ensure_inherited_data ()
	Rebuilds inherited-data payloads for matched archetypes when query terms require them.

void	ensure_group_data (bool orderGroups)
	Rebuilds grouped archetype ranges when a caller needs ordered group data.

void	ensure_depth_order_hierarchy_barrier_cache_inter ()
	Rebuilds cached depth-order hierarchy barrier results when relation or enabled-state versions changed.

ArchetypeCompIndices	create_comp_indices (const Archetype *pArchetype)
	Builds field-to-archetype component indices for one matched archetype.

void	create_inherited_data (const Archetype *pArchetype)
	Builds inherited component data pointers for semantic self-source terms on one archetype.

void	update_result_cache_prefab_filter_state (const Archetype *pArchetype)
	Records whether pArchetype requires the default prefab filter during result-cache iteration.

void	add_archetype_to_cache_no_grouping (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent=false)
	Adds an archetype to the final result cache for ungrouped queries.

void	add_archetype_to_seed_cache (const Archetype *pArchetype, bool assumeAbsent=false)
	Adds an archetype to the structural seed cache.

void	add_new_archetype_to_immediate_caches (const Archetype *pArchetype, bool trackMembershipChange)
	Adds a newly matched archetype to both immediate caches while reusing one computed index mapping.

void	add_archetype_to_cache_w_grouping (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent=false)
	Adds an archetype to the final result cache and records its group id.

void	add_archetype_to_cache (const Archetype *pArchetype, bool trackMembershipChange, bool assumeAbsent)
	Adds an archetype to the final result cache and updates derived-payload dirty flags.

void	add_archetype_to_transient_cache (const Archetype *pArchetype)
	Adds an archetype to the transient result cache used by non-persistent matching paths.

GAIA_NODISCARD const GroupData *	selected_group_data (GroupId runtimeGroupId) const
	Returns cached group bounds for the currently selected group filter. The cached range is invalidated whenever group layout changes or the selected group id changes.

GAIA_NODISCARD bool	has_same_result_membership_as_seed_cache () const
	Compares final result-cache membership with the structural seed cache.

GAIA_NODISCARD bool	has_same_result_membership_as (const CArchetypeDArray &archetypeCache) const
	Compares final result-cache membership with another archetype array.

void	sync_result_cache_from_seed_cache ()
	Rebuilds the final result cache from structural seed matches. Bumps result membership revision only when the final membership actually changes.

bool	del_archetype_from_cache (const Archetype *pArchetype)
	Removes an archetype from the final result cache and mirrored payload arrays.

bool	del_archetype_from_seed_cache (const Archetype *pArchetype)
	Removes an archetype from the structural seed cache.

GAIA_NODISCARD World *	world ()
	Returns the mutable world owning this query.

GAIA_NODISCARD const World *	world () const
	Returns the world owning this query.

GAIA_NODISCARD QuerySerBuffer &	ser_buffer ()
	Returns the query serialization buffer associated with the owning world.

void	ser_buffer_reset ()
	Resets the query serialization buffer associated with the owning world.

GAIA_NODISCARD QueryCtx &	ctx ()
	Returns the mutable compiled query context.

GAIA_NODISCARD const QueryCtx &	ctx () const
	Returns the compiled query context.

GAIA_NODISCARD util::str	bytecode () const
	Returns a textual dump of the compiled VM bytecode.

GAIA_NODISCARD uint32_t	op_count () const
	Returns the number of VM operations in the compiled query.

GAIA_NODISCARD uint64_t	op_signature () const
	Returns a stable signature for the compiled VM operation stream.

GAIA_NODISCARD bool	has_filters () const
	Returns true when the query has per-entity changed/filter terms.

GAIA_NODISCARD bool	has_entity_filter_terms () const
	Returns true when direct non-fragmenting terms must be rechecked per entity.

GAIA_NODISCARD bool	has_potential_inherited_id_terms () const
	Returns true when the query shape can resolve through inherited-id matching.

GAIA_NODISCARD QueryCtx::DirectTargetEvalKind	direct_target_eval_kind () const
	Returns the direct target evaluation mode selected during compilation.

GAIA_NODISCARD Entity	direct_target_eval_id () const
	Returns the concrete direct target id used by direct target evaluation.

GAIA_NODISCARD bool	can_direct_target_eval () const
	Returns true when the query can evaluate concrete target entities directly.

GAIA_NODISCARD bool	can_direct_entity_seed_eval_shape () const
	Returns true when the query shape is eligible for direct entity seed evaluation.

GAIA_NODISCARD bool	has_only_direct_or_terms () const
	Returns true when the query contains only direct OR/NOT terms and at least one OR term.

GAIA_NODISCARD bool	matches_prefab_entities () const
	Returns true when prefab-tagged entities should participate in query results.

template<typename... T>
GAIA_NODISCARD bool	has_any () const
	Returns true when any of the requested types is present as an Any term.

template<typename... T>
GAIA_NODISCARD bool	has_or () const
	Returns true when any of the requested types is present as an Or term.

template<typename... T>
GAIA_NODISCARD bool	has_all () const
	Returns true when all requested types are present as All terms.

template<typename... T>
GAIA_NODISCARD bool	has_no () const
	Returns true when none of the requested types is present as a Not term.

void	remove (Archetype *pArchetype)
	Removes an archetype from cache.

std::span< const uint8_t >	indices_mapping_view (uint32_t archetypeIdx) const
	Returns a view of indices mapping for component entities in a given archetype.

std::span< const DirectChunkEntry >	direct_chunk_view (uint32_t idxFrom, uint32_t idxTo, const uint32_t *pDataFields, uint32_t dataFieldCount) const
	Returns a flattened chunk view for a direct-dense result-cache range.

std::span< const void *const >	direct_chunk_data_view () const
	Returns cached flattened direct chunk data pointers.

InheritedTermDataView	inherited_data_view (uint32_t archetypeIdx) const
	Returns cached inherited-term data for a matched archetype index.

InheritedTermDataView	inherited_data_view (const Archetype *pArchetype) const
	Returns cached inherited-term data for a matched archetype pointer.

void	ensure_depth_order_hierarchy_barrier_cache ()
	Ensures depth-order hierarchy barrier results are current before public reads.

std::span< const uint8_t >	try_indices_mapping_view (const Archetype *pArchetype) const
	Returns a cached indices mapping view for an exact archetype match, or an empty span when absent.

InheritedTermDataView	try_inherited_data_view (const Archetype *pArchetype) const
	Returns cached inherited-term data if it is already available for a matched archetype.

GAIA_NODISCARD GroupId	group_id (uint32_t archetypeIdx) const
	Returns the cached group id for a matched archetype index.

GAIA_NODISCARD bool	barrier_passes (uint32_t archetypeIdx) const
	Returns true when the matched archetype passes the depth-order hierarchy barrier.

GAIA_NODISCARD bool	barrier_may_prune () const
	Returns true when any cached archetype can be pruned by the hierarchy barrier.

GAIA_NODISCARD CArchetypeDArray::iterator	begin ()
	Returns a mutable iterator to the first cached result archetype.

GAIA_NODISCARD CArchetypeDArray::const_iterator	begin () const
	Returns an iterator to the first cached result archetype.

GAIA_NODISCARD CArchetypeDArray::const_iterator	cbegin () const
	Returns a const iterator to the first cached result archetype.

GAIA_NODISCARD CArchetypeDArray::iterator	end ()
	Returns a mutable iterator past the last cached result archetype.

GAIA_NODISCARD CArchetypeDArray::const_iterator	end () const
	Returns an iterator past the last cached result archetype.

GAIA_NODISCARD CArchetypeDArray::const_iterator	cend () const
	Returns a const iterator past the last cached result archetype.

GAIA_NODISCARD std::span< const Archetype * >	cache_archetype_view () const
	Returns the cached result archetypes as a span.

GAIA_NODISCARD std::span< const SortData >	cache_sort_view () const
	Returns cached sorted chunk slices.

GAIA_NODISCARD std::span< const GroupData >	group_data_view () const
	Returns cached group ranges, rebuilding grouped data when needed.

Static Public Member Functions
static GAIA_NODISCARD QueryInfo	create (QueryId id, QueryCtx &&ctx, const EntityToArchetypeMap &entityToArchetypeMap, std::span< const Archetype * > allArchetypes)
	Creates and compiles a query info object from a moved query context.

static GAIA_NODISCARD QueryInfo	create (uint32_t idx, uint32_t gen, void *pCtx)
	Creates and compiles a query info object from slot creation context.

static GAIA_NODISCARD QueryHandle	handle (const QueryInfo &info)
	Builds a stable query handle from query slot metadata.

Public Attributes
uint32_t	idx = 0
	Allocated items: index in the query slot list. Deleted items: index of the next deleted item in the slot list.

uint32_t	gen = 0
	Generation ID of the query slot.

Detailed Description

Compiled query plan and its incrementally maintained result caches.

Member Enumeration Documentation

◆ InvalidationKind

enum class gaia::ecs::QueryInfo::InvalidationKind : uint8_t

strong

Cache layer invalidated after query inputs or world state change.

Enumerator
Result	Only the final result cache is stale. Structural seed matches remain valid and can be reused.
Seed	Structural seed matches are stale. This also implies the final result cache must be rebuilt.
All	Full invalidation of all query cache state.

◆ MatchArchetypeQueryRet

enum class gaia::ecs::QueryInfo::MatchArchetypeQueryRet : uint8_t

strong

Result of evaluating one archetype for cache insertion.

Enumerator
Fail	Archetype does not satisfy the query.
Ok	Archetype satisfies the query and should be cached.
Skip	Archetype requires no cache action for this evaluation path.

Member Function Documentation

◆ add_archetype_to_cache()

void gaia::ecs::QueryInfo::add_archetype_to_cache	(	const Archetype *	pArchetype,
		bool	trackMembershipChange,
		bool	assumeAbsent
	)

inline

Adds an archetype to the final result cache and updates derived-payload dirty flags.

Parameters

pArchetype	Matched archetype to cache.
trackMembershipChange	True to bump result membership revision after insertion.
assumeAbsent	True when the caller already proved the archetype is not cached.

◆ add_archetype_to_cache_no_grouping()

void gaia::ecs::QueryInfo::add_archetype_to_cache_no_grouping	(	const Archetype *	pArchetype,
		bool	trackMembershipChange,
		bool	assumeAbsent = `false`
	)

inline

Adds an archetype to the final result cache for ungrouped queries.

Parameters

pArchetype	Matched archetype to cache.
trackMembershipChange	True to bump result membership revision after insertion.
assumeAbsent	True when the caller already proved the archetype is not cached.

◆ add_archetype_to_cache_w_grouping()

void gaia::ecs::QueryInfo::add_archetype_to_cache_w_grouping	(	const Archetype *	pArchetype,
		bool	trackMembershipChange,
		bool	assumeAbsent = `false`
	)

inline

Adds an archetype to the final result cache and records its group id.

Parameters

pArchetype	Matched archetype to cache.
trackMembershipChange	True to bump result membership revision after insertion.
assumeAbsent	True when the caller already proved the archetype is not cached.

◆ add_archetype_to_seed_cache()

void gaia::ecs::QueryInfo::add_archetype_to_seed_cache	(	const Archetype *	pArchetype,
		bool	assumeAbsent = `false`
	)

inline

Adds an archetype to the structural seed cache.

Parameters

pArchetype	Structurally matched archetype to cache.
assumeAbsent	True when the caller already proved the archetype is not cached.

◆ add_archetype_to_transient_cache()

void gaia::ecs::QueryInfo::add_archetype_to_transient_cache ( const Archetype * pArchetype )

inline

Adds an archetype to the transient result cache used by non-persistent matching paths.

Parameters

pArchetype Matched archetype to cache for this transient result.

◆ add_new_archetype_to_immediate_caches()

void gaia::ecs::QueryInfo::add_new_archetype_to_immediate_caches	(	const Archetype *	pArchetype,
		bool	trackMembershipChange
	)

inline

Adds a newly matched archetype to both immediate caches while reusing one computed index mapping.

Parameters

pArchetype	Newly matched archetype to cache.
trackMembershipChange	True to bump result membership revision after insertion.

◆ barrier_may_prune()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::barrier_may_prune ( ) const

inline

Returns true when any cached archetype can be pruned by the hierarchy barrier.

Returns: True when any cached archetype can be pruned by the hierarchy barrier.

◆ barrier_passes()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::barrier_passes ( uint32_t archetypeIdx ) const

inline

Returns true when the matched archetype passes the depth-order hierarchy barrier.

Returns: True when the matched archetype passes the depth-order hierarchy barrier.

Parameters

archetypeIdx Result-cache archetype index.

◆ begin() [1/2]

GAIA_NODISCARD CArchetypeDArray::iterator gaia::ecs::QueryInfo::begin ( )

inline

Returns a mutable iterator to the first cached result archetype.

Returns: Mutable iterator to the first cached result archetype.

◆ begin() [2/2]

GAIA_NODISCARD CArchetypeDArray::const_iterator gaia::ecs::QueryInfo::begin ( ) const

inline

Returns an iterator to the first cached result archetype.

Returns: Iterator to the first cached result archetype.

◆ bytecode()

GAIA_NODISCARD util::str gaia::ecs::QueryInfo::bytecode ( ) const

inline

Returns a textual dump of the compiled VM bytecode.

Returns: Textual VM bytecode dump.

◆ cache_archetype_view()

GAIA_NODISCARD std::span< const Archetype * > gaia::ecs::QueryInfo::cache_archetype_view ( ) const

inline

Returns the cached result archetypes as a span.

Returns: Cached result archetypes as a span.

◆ cache_policy()

GAIA_NODISCARD QueryCtx::CachePolicy gaia::ecs::QueryInfo::cache_policy ( ) const

inline

Returns the query cache policy selected during compilation.

Returns: Immediate, lazy, or dynamic maintenance policy.

◆ cache_sort_view()

GAIA_NODISCARD std::span< const SortData > gaia::ecs::QueryInfo::cache_sort_view ( ) const

inline

Returns cached sorted chunk slices.

Returns: Cached sorted chunk slices.

◆ can_direct_entity_seed_eval_shape()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::can_direct_entity_seed_eval_shape ( ) const

inline

Returns true when the query shape is eligible for direct entity seed evaluation.

Returns: True when the query shape is eligible for direct entity seed evaluation.

◆ can_direct_target_eval()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::can_direct_target_eval ( ) const

inline

Returns true when the query can evaluate concrete target entities directly.

Returns: True when the query can evaluate concrete target entities directly.

◆ can_update_with_new_archetype()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::can_update_with_new_archetype ( ) const

inline

Returns true when a new archetype can be propagated into the current cache incrementally.

Returns: True for a compiled, clean, immediate structural query.

◆ can_use_direct_create_archetype_match()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::can_use_direct_create_archetype_match ( ) const

inline

Returns whether create-time matching should bypass the temporary one-archetype VM path.

Returns: True when direct structural matching was selected during compilation.

◆ cbegin()

GAIA_NODISCARD CArchetypeDArray::const_iterator gaia::ecs::QueryInfo::cbegin ( ) const

inline

Returns a const iterator to the first cached result archetype.

Returns: Const iterator to the first cached result archetype.

◆ cend()

GAIA_NODISCARD CArchetypeDArray::const_iterator gaia::ecs::QueryInfo::cend ( ) const

inline

Returns a const iterator past the last cached result archetype.

Returns: Const iterator past the last cached result archetype.

◆ compile()

void gaia::ecs::QueryInfo::compile	(	const EntityToArchetypeMap &	entityToArchetypeMap,
		std::span< const Archetype * >	allArchetypes
	)

inline

Compile the query terms into a form we can easily process.

Parameters

entityToArchetypeMap	World reverse index used by VM compilation.
allArchetypes	Archetypes present while the plan is compiled.

◆ create() [1/2]

static GAIA_NODISCARD QueryInfo gaia::ecs::QueryInfo::create	(	QueryId	id,
		QueryCtx &&	ctx,
		const EntityToArchetypeMap &	entityToArchetypeMap,
		std::span< const Archetype * >	allArchetypes
	)

inlinestatic

Creates and compiles a query info object from a moved query context.

Parameters

id	Query slot id.
ctx	Query context to take ownership of.
entityToArchetypeMap	World archetype lookup used during compilation.
allArchetypes	Current world archetype list.

Returns: Compiled query info owning ctx in slot id.

◆ create() [2/2]

static GAIA_NODISCARD QueryInfo gaia::ecs::QueryInfo::create	(	uint32_t	idx,
		uint32_t	gen,
		void *	pCtx
	)

inlinestatic

Creates and compiles a query info object from slot creation context.

Parameters

idx	Query slot index.
gen	Query slot generation.
pCtx	Pointer to QueryInfoCreationCtx.

Returns: Compiled query info initialized for the allocated slot.

◆ create_comp_indices()

ArchetypeCompIndices gaia::ecs::QueryInfo::create_comp_indices ( const Archetype * pArchetype )

inline

Builds field-to-archetype component indices for one matched archetype.

Parameters

pArchetype Matched archetype whose layout is mapped to query fields.

Returns: Component-index mapping consumed by query iteration.

Component-index mappings describe columns owned by the currently iterated rows. Terms resolved from another source must use entity-resolved accessors even when the current archetype happens to contain the same component id.

◆ create_inherited_data()

void gaia::ecs::QueryInfo::create_inherited_data ( const Archetype * pArchetype )

inline

Builds inherited component data pointers for semantic self-source terms on one archetype.

Parameters

pArchetype Matched archetype whose inherited term data is cached.

◆ ctx() [1/2]

GAIA_NODISCARD QueryCtx & gaia::ecs::QueryInfo::ctx ( )

inline

Returns the mutable compiled query context.

Returns: Mutable compiled query context.

◆ ctx() [2/2]

GAIA_NODISCARD const QueryCtx & gaia::ecs::QueryInfo::ctx ( ) const

inline

Returns the compiled query context.

Returns: Compiled query context.

◆ del_archetype_from_cache()

bool gaia::ecs::QueryInfo::del_archetype_from_cache ( const Archetype * pArchetype )

inline

Removes an archetype from the final result cache and mirrored payload arrays.

Parameters

pArchetype Archetype to remove.

Returns: True if the archetype was present or its set entry was removed.

◆ del_archetype_from_seed_cache()

bool gaia::ecs::QueryInfo::del_archetype_from_seed_cache ( const Archetype * pArchetype )

inline

Removes an archetype from the structural seed cache.

Parameters

pArchetype Archetype to remove.

Returns: True if the archetype was present or its set entry was removed.

◆ direct_chunk_data_view()

std::span< const void *const > gaia::ecs::QueryInfo::direct_chunk_data_view ( ) const

inline

Returns cached flattened direct chunk data pointers.

Returns: Cached flattened direct chunk data pointers.

◆ direct_chunk_view()

std::span< const DirectChunkEntry > gaia::ecs::QueryInfo::direct_chunk_view	(	uint32_t	idxFrom,
		uint32_t	idxTo,
		const uint32_t *	pDataFields,
		uint32_t	dataFieldCount
	)		const

inline

Returns a flattened chunk view for a direct-dense result-cache range.

Parameters

idxFrom	First result-cache archetype index to include.
idxTo	One-past-the-end result-cache archetype index to include.
pDataFields	Query term indices to cache component data pointers for, in callback-argument order.
dataFieldCount	Number of valid entries in pDataFields. Pass zero to cache only chunks/ranges.

Returns: Flattened chunk entries for the requested result-cache archetype range.

◆ direct_create_archetype_match_uses_is()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::direct_create_archetype_match_uses_is ( ) const

inline

Returns whether direct create-time matching needs Is-aware id checks.

Returns: True when at least one compiled term has semantic Is matching bits.

◆ direct_target_eval_id()

GAIA_NODISCARD Entity gaia::ecs::QueryInfo::direct_target_eval_id ( ) const

inline

Returns the concrete direct target id used by direct target evaluation.

Returns: Concrete direct target id.

◆ direct_target_eval_kind()

GAIA_NODISCARD QueryCtx::DirectTargetEvalKind gaia::ecs::QueryInfo::direct_target_eval_kind ( ) const

inline

Returns the direct target evaluation mode selected during compilation.

Returns: Direct target evaluation mode.

◆ end() [1/2]

GAIA_NODISCARD CArchetypeDArray::iterator gaia::ecs::QueryInfo::end ( )

inline

Returns a mutable iterator past the last cached result archetype.

Returns: Mutable iterator past the last cached result archetype.

◆ end() [2/2]

GAIA_NODISCARD CArchetypeDArray::const_iterator gaia::ecs::QueryInfo::end ( ) const

inline

Returns an iterator past the last cached result archetype.

Returns: Iterator past the last cached result archetype.

◆ ensure_direct_chunks()

void gaia::ecs::QueryInfo::ensure_direct_chunks	(	uint32_t	idxFrom,
		uint32_t	idxTo,
		const uint32_t *	pDataFields,
		uint32_t	dataFieldCount
	)

inline

Rebuilds flattened direct chunk cache when result membership, world structure, selected rows, component-index mapping storage, or cached callback fields changed.

The flattened cache is used by read-only direct typed execution over highly fragmented result caches. It stores the chunks and enabled row ranges once, then lets iteration skip per-archetype/per-chunk traversal setup on repeated runs.

When callback component fields are supplied, the cache also captures component data pointers in callback-argument order. A single selected field is stored directly in DirectChunkEntry::pData because that is the hot hierarchy-query path. Multiple selected fields are stored as a stable pointer block in ExecPayload::directChunkData and referenced by DirectChunkEntry::dataOffset.

The cache key includes the selected field list because the same query may be iterated later with a different typed callback argument order. In that case, the pointer block must be rebuilt even if the result archetype range itself is unchanged.

Parameters

idxFrom	First result-cache archetype index to include.
idxTo	One-past-the-end result-cache archetype index to include.
pDataFields	Query term indices to cache component data pointers for, in callback-argument order.
dataFieldCount	Number of valid entries in pDataFields. Pass zero to cache only chunks/ranges.

Single-argument callbacks are the hot hierarchy path. Store their pointer directly in DirectChunkEntry so iteration avoids the sidecar pointer block and its extra lookup. Multi-argument callbacks use directChunkData below because they need a stable per-entry block of pointers in callback-argument order.

◆ ensure_group_data()

void gaia::ecs::QueryInfo::ensure_group_data ( bool orderGroups )

inline

Rebuilds grouped archetype ranges when a caller needs ordered group data.

Parameters

orderGroups True to order archetypes by group id even when the query was not explicitly ordered.

Note: Plain grouped iteration passes false so group_by(...) does not sort the cache by itself.

◆ ensure_matches()

void gaia::ecs::QueryInfo::ensure_matches	(	const EntityToArchetypeMap &	entityToArchetypeMap,
		std::span< const Archetype * >	allArchetypes,
		const EntityToArchetypeVersionMap &	entityToArchetypeMapVersions,
		ArchetypeId	archetypeLastId,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Refreshes persistent query matches when cache state or world archetypes changed.

Parameters

entityToArchetypeMap	World reverse index used to seed matching.
allArchetypes	Current world archetypes.
entityToArchetypeMapVersions	Revisions for reverse-index buckets.
archetypeLastId	Greatest world-local archetype id currently allocated.
runtimeVarBindings	Runtime values for query variable slots.
runtimeVarBindingMask	Bitmask selecting bound slots in runtimeVarBindings.

◆ ensure_matches_one()

bool gaia::ecs::QueryInfo::ensure_matches_one	(	const Archetype &	archetype,
		EntitySpan	targetEntities,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Ensures persistent result membership for one target archetype.

Parameters

archetype	Archetype to evaluate.
targetEntities	Entities supplying target bindings for the evaluation.
runtimeVarBindings	Runtime values for query variable slots.
runtimeVarBindingMask	Bitmask selecting bound slots in runtimeVarBindings.

Returns: True when archetype satisfies the query.

◆ ensure_matches_one_transient()

bool gaia::ecs::QueryInfo::ensure_matches_one_transient	(	const Archetype &	archetype,
		EntitySpan	targetEntities,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Rebuilds transient result membership by evaluating one target archetype.

Parameters

archetype	Archetype to evaluate.
targetEntities	Entities supplying target bindings for the evaluation.
runtimeVarBindings	Runtime values for query variable slots.
runtimeVarBindingMask	Bitmask selecting bound slots in runtimeVarBindings.

Returns: True when archetype satisfies the query.

◆ ensure_matches_transient()

void gaia::ecs::QueryInfo::ensure_matches_transient	(	const EntityToArchetypeMap &	entityToArchetypeMap,
		std::span< const Archetype * >	allArchetypes,
		const EntityToArchetypeVersionMap &	entityToArchetypeMapVersions,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Rebuilds transient result membership without retaining persistent seed-cache state.

Parameters

entityToArchetypeMap	World reverse index used to seed matching.
allArchetypes	Current world archetypes.
entityToArchetypeMapVersions	Revisions for reverse-index buckets.
runtimeVarBindings	Runtime values for query variable slots.
runtimeVarBindingMask	Bitmask selecting bound slots in runtimeVarBindings.

◆ group_data_view()

GAIA_NODISCARD std::span< const GroupData > gaia::ecs::QueryInfo::group_data_view ( ) const

inline

Returns cached group ranges, rebuilding grouped data when needed.

Returns: Cached group ranges.

◆ group_id()

GAIA_NODISCARD GroupId gaia::ecs::QueryInfo::group_id ( uint32_t archetypeIdx ) const

inline

Returns the cached group id for a matched archetype index.

Returns: Cached group id for the archetype index.

Parameters

archetypeIdx Result-cache archetype index.

◆ group_ids()

template<typename Container >

void gaia::ecs::QueryInfo::group_ids	(	Container &	out,
		bool	sortGroups
	)

inline

Collects the query's active non-zero group ids.

Template Parameters

Container Container with GroupId elements.

Parameters

out	Output array overwritten with unique group ids.
sortGroups	True to sort grouped cache ranges by group id before collecting ids.

◆ handle()

static GAIA_NODISCARD QueryHandle gaia::ecs::QueryInfo::handle ( const QueryInfo & info )

inlinestatic

Builds a stable query handle from query slot metadata.

Parameters

info	Query info providing slot index and generation.

Returns: Handle identifying info's current slot generation.

◆ has_all()

template<typename... T>

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_all ( ) const

inline

Returns true when all requested types are present as All terms.

Template Parameters

T	Query term types to test.

Returns: True when all requested types are present as All terms.

◆ has_any()

template<typename... T>

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_any ( ) const

inline

Returns true when any of the requested types is present as an Any term.

Template Parameters

T	Query term types to test.

Returns: True when any of the requested types is present as an Any term.

◆ has_entity_filter_terms()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_entity_filter_terms ( ) const

inline

Returns true when direct non-fragmenting terms must be rechecked per entity.

Returns: True when direct non-fragmenting terms must be rechecked per entity.

◆ has_filters()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_filters ( ) const

inline

Returns true when the query has per-entity changed/filter terms.

Returns: True when the query has per-entity changed/filter terms.

◆ has_grouped_payload()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_grouped_payload ( ) const

inline

Returns true when grouped-query payloads are active for this query.

Returns: True when a group-by entity is configured.

◆ has_inherited_data_payload()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_inherited_data_payload ( ) const

inline

Returns true when query iteration needs cached inherited data payloads.

Returns: True when compiled terms require inherited component pointers.

◆ has_no()

template<typename... T>

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_no ( ) const

inline

Returns true when none of the requested types is present as a Not term.

Template Parameters

T	Query term types to test.

Returns: True when none of the requested types is present as a Not term.

◆ has_only_direct_or_terms()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_only_direct_or_terms ( ) const

inline

Returns true when the query contains only direct OR/NOT terms and at least one OR term.

Returns: True when the query contains only direct OR/NOT terms and at least one OR term.

◆ has_or()

template<typename... T>

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_or ( ) const

inline

Returns true when any of the requested types is present as an Or term.

Template Parameters

T	Query term types to test.

Returns: True when any of the requested types is present as an Or term.

◆ has_potential_inherited_id_terms()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_potential_inherited_id_terms ( ) const

inline

Returns true when the query shape can resolve through inherited-id matching.

Returns: True when the query shape can resolve through inherited-id matching.

◆ has_same_result_membership_as()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_same_result_membership_as ( const CArchetypeDArray & archetypeCache ) const

inline

Compares final result-cache membership with another archetype array.

Parameters

archetypeCache Archetype membership to compare against the final result cache.

Returns: True when both collections contain the same archetypes.

◆ has_same_result_membership_as_seed_cache()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_same_result_membership_as_seed_cache ( ) const

inline

Compares final result-cache membership with the structural seed cache.

Returns: True when both caches contain the same archetypes.

◆ has_sorted_payload()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::has_sorted_payload ( ) const

inline

Returns true when sorted-query payloads are active for this query.

Returns: True when an entity sorting callback is configured.

◆ indices_mapping_view()

std::span< const uint8_t > gaia::ecs::QueryInfo::indices_mapping_view ( uint32_t archetypeIdx ) const

inline

Returns a view of indices mapping for component entities in a given archetype.

Returns: View of indices mapping for component entities in the archetype.

◆ inherited_data_view() [1/2]

InheritedTermDataView gaia::ecs::QueryInfo::inherited_data_view ( const Archetype * pArchetype ) const

inline

Returns cached inherited-term data for a matched archetype pointer.

Returns: Cached inherited-term data for the matched archetype.

Parameters

pArchetype Matched archetype to look up.

◆ inherited_data_view() [2/2]

InheritedTermDataView gaia::ecs::QueryInfo::inherited_data_view ( uint32_t archetypeIdx ) const

inline

Returns cached inherited-term data for a matched archetype index.

Returns: Cached inherited-term data for the archetype index.

Parameters

archetypeIdx Result-cache archetype index.

◆ init()

void gaia::ecs::QueryInfo::init ( World * world )

inline

Binds this query info to a world after slot allocation.

Parameters

world World owning the query.

◆ invalidate()

void gaia::ecs::QueryInfo::invalidate ( InvalidationKind kind = InvalidationKind::All )

inline

Marks cached query results stale.

Parameters

kind	Cache layer to invalidate.

◆ match()

template<typename ArchetypeLookup >

void gaia::ecs::QueryInfo::match	(	const ArchetypeLookup &	entityToArchetypeMap,
		std::span< const Archetype * >	allArchetypes,
		const EntityToArchetypeVersionMap *	pEntityToArchetypeMapVersions,
		ArchetypeId	archetypeLastId,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Tries to match the query against archetypes in entityToArchetypeMap. This is necessary so we do not iterate all chunks over and over again when running queries.

Parameters

entityToArchetypeMap	Lookup of archetypes by entity
allArchetypes	List of all archetypes
pEntityToArchetypeMapVersions	Optional version map for archetype lookup validation
archetypeLastId	Last recorded archetype id
runtimeVarBindings	Runtime variable bindings for dynamic queries
runtimeVarBindingMask	Mask indicating which runtime variables are bound

Template Parameters

ArchetypeLookup Archetype lookup container/view type used by the query cache.

Warning: Not thread safe. No two threads can call this at the same time.

◆ match_one()

bool gaia::ecs::QueryInfo::match_one	(	const Archetype &	archetype,
		EntitySpan	targetEntities,
		const cnt::sarray< Entity, MaxVarCnt > &	runtimeVarBindings,
		uint8_t	runtimeVarBindingMask
	)

inline

Tries to match the query against the provided archetype. This is necessary so we do not iterate all chunks over and over again when running queries.

Parameters

archetype	Archtype to match
targetEntities	Entities related to the matched archetype
runtimeVarBindings	Runtime bindings for query variables.
runtimeVarBindingMask	Bitmask of variables already bound in runtimeVarBindings.

Returns: True when the archetype satisfies the query.

Warning: Not thread safe. No two threads can call this at the same time.

◆ matches_prefab_entities()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::matches_prefab_entities ( ) const

inline

Returns true when prefab-tagged entities should participate in query results.

Returns: True when prefab-tagged entities should participate in query results.

◆ op_count()

GAIA_NODISCARD uint32_t gaia::ecs::QueryInfo::op_count ( ) const

inline

Returns the number of VM operations in the compiled query.

Returns: Number of VM operations.

◆ op_signature()

GAIA_NODISCARD uint64_t gaia::ecs::QueryInfo::op_signature ( ) const

inline

Returns a stable signature for the compiled VM operation stream.

Returns: Stable opcode-stream signature.

◆ operator!=()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::operator!= ( const QueryCtx & other ) const

inline

Compares this compiled plan with an authored query context for inequality.

Parameters

other Query context to compare.

Returns: True when shared query identity differs.

◆ operator==()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::operator== ( const QueryCtx & other ) const

inline

Compares this compiled plan with an authored query context.

Parameters

other Query context to compare.

Returns: True when shared query identity matches.

◆ refs()

uint32_t gaia::ecs::QueryInfo::refs ( ) const

inline

Returns the current external reference count.

Returns: Number of live query objects referencing this slot.

◆ register_archetype()

bool gaia::ecs::QueryInfo::register_archetype	(	const Archetype &	archetype,
		Entity	matchedSelector = `EntityBad`,
		bool	assumeNew = `false`
	)

inline

Registers a new or updated archetype with query caches when it matches this query.

Parameters

archetype	Archetype to evaluate.
matchedSelector	Optional selector that already matched the archetype.
assumeNew	True when the caller knows the archetype is not present in the caches.

Returns: True when the archetype was added to a cache.

◆ remove()

void gaia::ecs::QueryInfo::remove ( Archetype * pArchetype )

inline

Removes an archetype from cache.

Parameters

pArchetype Archetype to remove

◆ result_cache_may_need_prefab_filter()

GAIA_NODISCARD bool gaia::ecs::QueryInfo::result_cache_may_need_prefab_filter ( ) const

inline

Returns true when the result cache contains archetypes that need default prefab filtering.

Returns: True when cached membership may include prefab-tagged archetypes to reject during iteration.

◆ result_cache_rev()

GAIA_NODISCARD uint32_t gaia::ecs::QueryInfo::result_cache_rev ( ) const

inline

Returns the result membership revision used by reverse-index cache users.

Returns: Revision incremented whenever result archetype membership changes.

◆ selected_group_data()

GAIA_NODISCARD const GroupData * gaia::ecs::QueryInfo::selected_group_data ( GroupId runtimeGroupId ) const

inline

Returns cached group bounds for the currently selected group filter. The cached range is invalidated whenever group layout changes or the selected group id changes.

Parameters

runtimeGroupId Group id to look up.

Returns: Group range for the requested group, or nullptr if the group does not exist.

◆ ser_buffer()

GAIA_NODISCARD QuerySerBuffer & gaia::ecs::QueryInfo::ser_buffer ( )

inline

Returns the query serialization buffer associated with the owning world.

Returns: Query serialization buffer.

◆ swap_archetype_cache_entry()

void gaia::ecs::QueryInfo::swap_archetype_cache_entry	(	uint32_t	left,
		uint32_t	right
	)

inline

Swaps two result-cache entries and every parallel payload array that mirrors cache order.

Parameters

left	Index of the first cache entry.
right	Index of the second cache entry.

◆ try_indices_mapping_view()

std::span< const uint8_t > gaia::ecs::QueryInfo::try_indices_mapping_view ( const Archetype * pArchetype ) const

inline

Returns a cached indices mapping view for an exact archetype match, or an empty span when absent.

Returns: Cached indices mapping view, or an empty span when absent.

◆ try_inherited_data_view()

InheritedTermDataView gaia::ecs::QueryInfo::try_inherited_data_view ( const Archetype * pArchetype ) const

inline

Returns cached inherited-term data if it is already available for a matched archetype.

Returns: Cached inherited-term data, or an empty view when unavailable.

Parameters

pArchetype Matched archetype to look up.

◆ update_result_cache_prefab_filter_state()

void gaia::ecs::QueryInfo::update_result_cache_prefab_filter_state ( const Archetype * pArchetype )

inline

Records whether pArchetype requires the default prefab filter during result-cache iteration.

Parameters

pArchetype Matched archetype added to the result cache.

◆ world() [1/2]

GAIA_NODISCARD World * gaia::ecs::QueryInfo::world ( )

inline

Returns the mutable world owning this query.

Returns: Owning world.

◆ world() [2/2]

GAIA_NODISCARD const World * gaia::ecs::QueryInfo::world ( ) const

inline

Returns the world owning this query.

Returns: Owning world.

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

/home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/query_info.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ InvalidationKind

◆ MatchArchetypeQueryRet

Member Function Documentation

◆ add_archetype_to_cache()

◆ add_archetype_to_cache_no_grouping()

◆ add_archetype_to_cache_w_grouping()

◆ add_archetype_to_seed_cache()

◆ add_archetype_to_transient_cache()

◆ add_new_archetype_to_immediate_caches()

◆ barrier_may_prune()

◆ barrier_passes()

◆ begin() [1/2]

◆ begin() [2/2]

◆ bytecode()

◆ cache_archetype_view()

◆ cache_policy()

◆ cache_sort_view()

◆ can_direct_entity_seed_eval_shape()

◆ can_direct_target_eval()

◆ can_update_with_new_archetype()

◆ can_use_direct_create_archetype_match()

◆ cbegin()

◆ cend()

◆ compile()

◆ create() [1/2]

◆ create() [2/2]

◆ create_comp_indices()

◆ create_inherited_data()

◆ ctx() [1/2]

◆ ctx() [2/2]

◆ del_archetype_from_cache()

◆ del_archetype_from_seed_cache()

◆ direct_chunk_data_view()

◆ direct_chunk_view()

◆ direct_create_archetype_match_uses_is()

◆ direct_target_eval_id()

◆ direct_target_eval_kind()

◆ end() [1/2]

◆ end() [2/2]

◆ ensure_direct_chunks()

◆ ensure_group_data()

◆ ensure_matches()

◆ ensure_matches_one()

◆ ensure_matches_one_transient()

◆ ensure_matches_transient()

◆ group_data_view()

◆ group_id()

◆ group_ids()

◆ handle()

◆ has_all()

◆ has_any()

◆ has_entity_filter_terms()

◆ has_filters()

◆ has_grouped_payload()

◆ has_inherited_data_payload()

◆ has_no()

◆ has_only_direct_or_terms()

◆ has_or()

◆ has_potential_inherited_id_terms()

◆ has_same_result_membership_as()

◆ has_same_result_membership_as_seed_cache()

◆ has_sorted_payload()

◆ indices_mapping_view()

◆ inherited_data_view() [1/2]

◆ inherited_data_view() [2/2]

◆ init()

◆ invalidate()

◆ match()

◆ match_one()

◆ matches_prefab_entities()

◆ op_count()

◆ op_signature()

◆ operator!=()