gaia::ecs::QueryCtx Struct Reference

Authored and compiled state defining query identity and execution behavior. More...

#include <query_common.h>

Classes
struct	Data
	Compact compiled query payload used by matching, identity, and cache maintenance. More...

Public Types
enum	QueryFlags : uint16_t {   Empty = 0x00 , SortEntities = 0x01 , SortGroups = 0x02 , Complex = 0x04 ,   Recompile = 0x08 , HasSourceTerms = 0x10 , HasVariableTerms = 0x20 , MatchPrefab = 0x40 ,   HasPrefabTerms = 0x80 , OrderGroups = 0x100 }
	Query maintenance and execution flags derived during compilation. More...
enum class	CachePolicy : uint8_t { Immediate , Lazy , Dynamic }
	Strategy used to maintain cached archetype matches. More...
enum class	CreateArchetypeMatchKind : uint8_t { Vm , DirectStructuralTerms }
	Matcher selected for newly created archetypes. More...
enum class	DynamicCacheKind : uint8_t {   None , RelationOnly , DirectSource , TraversedSource ,   Variable , Mixed }
	Dynamic-cache dependency shape derived from compiled query metadata. More...
enum class	DirectTargetEvalKind : uint8_t {   Generic , SingleAllDirect , SingleAllSemanticIs , SingleAllInIs ,   SingleAllInherited }
	Specialized evaluation shape for concrete target entities. More...
enum	DependencyFlags : uint16_t {   DependencyNone = 0x00 , DependencyHasSourceTerms = 0x01 , DependencyHasVariableTerms = 0x02 , DependencyHasPositiveTerms = 0x04 ,   DependencyHasNegativeTerms = 0x08 , DependencyHasAnyTerms = 0x10 , DependencyHasWildcardTerms = 0x20 , DependencyHasSort = 0x40 ,   DependencyHasGroup = 0x80 , DependencyHasTraversalTerms = 0x100 , DependencyHasEntityFilterTerms = 0x200 , DependencyHasInheritedDataTerms = 0x400 ,   DependencyHasPotentialInheritedIdTerms = 0x800 }
	Dependency facts derived from the compiled term set. More...

Public Member Functions
void	init (World *pWorld)
	Attaches the query context to a world and its component cache.
void	refresh ()
	Rebuilds derived masks, dependency metadata, and cache policy after authored terms change.
GAIA_NODISCARD bool	operator== (const QueryCtx &other) const noexcept
	Compares query contexts during initial shared-query lookup.
GAIA_NODISCARD bool	operator!= (const QueryCtx &other) const noexcept
	Compares query contexts for distinct shared query identity.

Static Public Member Functions
static GAIA_NODISCARD bool	equals_no_handle_assumption (const QueryCtx &leftCtx, const QueryCtx &rightCtx) noexcept
	Compares shared query identity without requiring invalid handles.

Public Attributes
const World *	w {}
	World against which the query is compiled and executed.
ComponentCache *	cc {}
	Component cache.
QueryLookupHash	hashLookup {}
	Lookup hash for this query.
QueryIdentity	q {}
	Query identity.
struct gaia::ecs::QueryCtx::Data	data
	Compiled query payload.

Detailed Description

Authored and compiled state defining query identity and execution behavior.

Member Enumeration Documentation

CachePolicy

enum class gaia::ecs::QueryCtx::CachePolicy : uint8_t

strong

Strategy used to maintain cached archetype matches.

Enumerator
Immediate	Updates a structural query immediately when an archetype is created.
Lazy	Refreshes a structural query lazily on the next read.
Dynamic	Repairs source- or variable-dependent cached state on demand.

CreateArchetypeMatchKind

enum class gaia::ecs::QueryCtx::CreateArchetypeMatchKind : uint8_t

strong

Matcher selected for newly created archetypes.

Enumerator
Vm	Uses the normal one-archetype VM path.
DirectStructuralTerms	Evaluates a small immediate ALL, OR, and NOT query directly on the archetype.

DependencyFlags

enum gaia::ecs::QueryCtx::DependencyFlags : uint16_t

Dependency facts derived from the compiled term set.

Enumerator
DependencyNone	No dependency facts are present.
DependencyHasSourceTerms	At least one term uses a fixed source entity.
DependencyHasVariableTerms	At least one term contains a runtime variable.
DependencyHasPositiveTerms	At least one positive ALL or OR term is present.
DependencyHasNegativeTerms	At least one negative NOT term is present.
DependencyHasAnyTerms	At least one optional ANY term is present.
DependencyHasWildcardTerms	At least one wildcard id or pair term is present.
DependencyHasSort	Query has an entity sorting callback.
DependencyHasGroup	Query has an archetype grouping callback.
DependencyHasTraversalTerms	At least one source term traverses a relation.
DependencyHasEntityFilterTerms	At least one term requires per-entity filtering.
DependencyHasInheritedDataTerms	Iteration requires cached inherited component pointers.
DependencyHasPotentialInheritedIdTerms	A term shape may resolve through inherited-id matching.

DirectTargetEvalKind

enum class gaia::ecs::QueryCtx::DirectTargetEvalKind : uint8_t

strong

Specialized evaluation shape for concrete target entities.

Enumerator
Generic	Uses the general compiled query evaluator.
SingleAllDirect	Evaluates one required direct-storage term.
SingleAllSemanticIs	Evaluates one required semantic Is term.
SingleAllInIs	Evaluates one required inherited-inclusive Is term.
SingleAllInherited	Evaluates one required term through inherited component data.

DynamicCacheKind

enum class gaia::ecs::QueryCtx::DynamicCacheKind : uint8_t

strong

Dynamic-cache dependency shape derived from compiled query metadata.

Enumerator
None	Query does not use dynamic-cache validation.
RelationOnly	Dynamic cache is invalidated by relation version dependencies only.
DirectSource	Dynamic cache tracks concrete source entity archetype versions.
TraversedSource	Dynamic cache tracks a traversed source closure.
Variable	Dynamic cache tracks runtime variable bindings only.
Mixed	Dynamic cache tracks more than one dependency family.

QueryFlags

enum gaia::ecs::QueryCtx::QueryFlags : uint16_t

Query maintenance and execution flags derived during compilation.

Enumerator
Empty	No query flags are set.
SortEntities	Cached entity slices require sorting.
SortGroups	Cached group ranges require sorting.
Complex	Query requires the general matching path.
Recompile	VM opcode recompilation is pending.
HasSourceTerms	Query contains fixed-source lookup terms.
HasVariableTerms	Query contains variable-based lookup terms.
MatchPrefab	Includes prefab entities without requiring an explicit Prefab term.
HasPrefabTerms	Query explicitly mentions Prefab and therefore bypasses automatic exclusion.
OrderGroups	Grouped archetypes are ordered by group identifier during cache refresh.

Member Function Documentation

equals_no_handle_assumption()

static GAIA_NODISCARD bool gaia::ecs::QueryCtx::equals_no_handle_assumption ( const QueryCtx &  leftCtx, const QueryCtx &  rightCtx  )

inlinestaticnoexcept

Compares shared query identity without requiring invalid handles.

Parameters

leftCtx	First query context.
rightCtx	Second query context.

Returns

True when lookup hashes and complete identity payloads match.

init()

void gaia::ecs::QueryCtx::init ( World *  pWorld )

inline

Attaches the query context to a world and its component cache.

Parameters

pWorld

World that will compile and execute the query.

operator!=()

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

inlinenoexcept

Compares query contexts for distinct shared query identity.

Parameters

other

Query context to compare.

Returns

True when the contexts do not have the same identity.

operator==()

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

inlinenoexcept

Compares query contexts during initial shared-query lookup.

Parameters

other

Query context to compare.

Returns

True when both contexts have the same shared query identity.

---

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

• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/query_common.h