Struct EcsQuery<TArchetype>

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

ECS query builder with three-tier evaluation: T1 (ArchetypeMask), T2 (EnabledBits), T3 (WHERE — future). Supports polymorphic queries (archetype + descendants) and exact queries (single archetype).

public struct EcsQuery<TArchetype> where TArchetype : class

Type Parameters

TArchetype

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Properties

EcsQueryId

Monotonic, globally-unique handle for this query struct instance, assigned at construction (mirrors ViewId). Each tx.Query<T>() / tx.QueryExact<T>() call produces a fresh ID; fluent mutation methods preserve it because the struct value carries the field. The profiler consumer thread dedupes multiple instance IDs into "definitions" using (constructionSite, structuralShape) — see issue #335 / #336.

public readonly int EcsQueryId { get; }

Property Value

int

SourceFile

User source file where this query was constructed (or zeroed when constructed without attribution). See SourceFile.

public readonly string SourceFile { get; }

Property Value

string

SourceLine

User source line where this query was constructed. Zero if unattributed.

public readonly int SourceLine { get; }

Property Value

int

SourceMethod

User source method name where this query was constructed. Null if unattributed.

public readonly string SourceMethod { get; }

Property Value

string

Methods

Any(string, int, string)

Test if any entity matches. Short-circuits on first match.

public bool Any(string callerFile = null, int callerLine = 0, string callerMethod = null)

Parameters

callerFile string

callerLine int

callerMethod string

Returns

bool

Count(string, int, string)

Count matching entities.

public int Count(string callerFile = null, int callerLine = 0, string callerMethod = null)

Parameters

callerFile string

callerLine int

callerMethod string

Returns

int

Disabled<T>()

Include only entities where T is disabled.

public EcsQuery<TArchetype> Disabled<T>() where T : unmanaged

Returns

EcsQuery<TArchetype>

Type Parameters

T

Enabled<T>()

Include only entities where T is enabled.

public EcsQuery<TArchetype> Enabled<T>() where T : unmanaged

Returns

EcsQuery<TArchetype>

Type Parameters

T

Exclude<TExcluded>()

Remove an archetype subtree. Mask AND NOT subtree.

public EcsQuery<TArchetype> Exclude<TExcluded>() where TExcluded : class

Returns

EcsQuery<TArchetype>

Type Parameters

TExcluded

Execute(string, int, string)

Execute the query and collect matching entity IDs into a HashSet.

public HashSet<EntityId> Execute(string callerFile = null, int callerLine = 0, string callerMethod = null)

Parameters

callerFile string

callerLine int

callerMethod string

Returns

HashSet<EntityId>

ExecuteOrdered(string, int, string)

Execute the query with ordering support. Requires OrderByField<T, TKey>(Expression<Func<T, TKey>>).

public List<EntityId> ExecuteOrdered(string callerFile = null, int callerLine = 0, string callerMethod = null)

Parameters

callerFile string

callerLine int

callerMethod string

Returns

List<EntityId>

GetEnumerator()

Get an enumerator for foreach support. Pre-collects matching entities then iterates.

Caller-attribute capture is NOT available here — the C# foreach pattern requires GetEnumerator to have zero parameters (optional parameters don't satisfy the pattern). Execution-site attribution for foreach loops falls back to the query's construction site (captured at tx.Query<T>()). For explicit execution-site capture, call Execute(string, int, string), Count(string, int, string), etc., instead.

public EcsQuery<TArchetype>.EcsQueryEnumerator GetEnumerator()

Returns

EcsQuery<TArchetype>.EcsQueryEnumerator

NavigateField<TSource, TTarget>(Expression<Func<TSource, long>>)

Start a navigation (FK join) query from the source archetype to a target component type. The FK field selector identifies the long FK field on the source component.

public readonly EcsNavigationQueryBuilder<TArchetype, TSource, TTarget> NavigateField<TSource, TTarget>(Expression<Func<TSource, long>> fkSelector) where TSource : unmanaged where TTarget : unmanaged

Parameters

fkSelector Expression<Func<TSource, long>>

Returns

EcsNavigationQueryBuilder<TArchetype, TSource, TTarget>

Type Parameters

TSource

TTarget

OrderByFieldDescending<T, TKey>(Expression<Func<T, TKey>>)

Order results descending by an indexed field.

public EcsQuery<TArchetype> OrderByFieldDescending<T, TKey>(Expression<Func<T, TKey>> keySelector) where T : unmanaged

Parameters

keySelector Expression<Func<T, TKey>>

Returns

EcsQuery<TArchetype>

Type Parameters

T

TKey

OrderByField<T, TKey>(Expression<Func<T, TKey>>)

Order results by an indexed field. Requires WhereField<T>(Expression<Func<T, bool>>) to identify the component.

public EcsQuery<TArchetype> OrderByField<T, TKey>(Expression<Func<T, TKey>> keySelector) where T : unmanaged

Parameters

keySelector Expression<Func<T, TKey>>

Returns

EcsQuery<TArchetype>

Type Parameters

T

TKey

Skip(int)

Skip the first count results. Requires OrderBy.

public EcsQuery<TArchetype> Skip(int count)

Parameters

count int

Returns

EcsQuery<TArchetype>

Take(int)

Take at most count results. Requires OrderBy.

public EcsQuery<TArchetype> Take(int count)

Parameters

count int

Returns

EcsQuery<TArchetype>

ToView(int, string, int, string)

Create a persistent, refreshable View from this query. If Expression-based WHERE (WhereField) was used, creates an incremental view with ring buffer delta notifications. Otherwise, creates a pull-model view (full re-query on each Refresh).

public EcsView<TArchetype> ToView(int bufferCapacity = 4096, string callerFile = null, int callerLine = 0, string callerMethod = null)

Parameters

bufferCapacity int

callerFile string

callerLine int

callerMethod string

Returns

EcsView<TArchetype>

Remarks

The three trailing caller… parameters are populated by [CallerFilePath] / [CallerLineNumber] / [CallerMemberName] at the user's .ToView() call site and become the View's definition-site source location (see SourceFile).

WhereField<T>(Expression<Func<T, bool>>)

Filter entities by an indexed-field predicate, enabling incremental view refresh via Typhon.Engine.Internals.ViewDeltaRingBuffer. The expression is parsed into FieldEvaluator for boundary crossing detection. Requires indexed fields.

public EcsQuery<TArchetype> WhereField<T>(Expression<Func<T, bool>> predicate) where T : unmanaged

Parameters

predicate Expression<Func<T, bool>>

Returns

EcsQuery<TArchetype>

Type Parameters

T

WhereInAABB<T>(double, double, double, double, double, double)

Filter by AABB overlap. Component T must have [SpatialIndex].

public EcsQuery<TArchetype> WhereInAABB<T>(double minX, double minY, double minZ, double maxX, double maxY, double maxZ) where T : unmanaged

Parameters

minX double

minY double

minZ double

maxX double

maxY double

maxZ double

Returns

EcsQuery<TArchetype>

Type Parameters

T

WhereNearby<T>(double, double, double, double)

Filter by radius (sphere) around a center point. Component T must have [SpatialIndex].

public EcsQuery<TArchetype> WhereNearby<T>(double centerX, double centerY, double centerZ, double radius) where T : unmanaged

Parameters

centerX double

centerY double

centerZ double

radius double

Returns

EcsQuery<TArchetype>

Type Parameters

T

WhereRay<T>(double, double, double, double, double, double, double)

Filter by ray intersection. Component T must have [SpatialIndex].

public EcsQuery<TArchetype> WhereRay<T>(double originX, double originY, double originZ, double dirX, double dirY, double dirZ, double maxDist) where T : unmanaged

Parameters

originX double

originY double

originZ double

dirX double

dirY double

dirZ double

maxDist double

Returns

EcsQuery<TArchetype>

Type Parameters

T

Where<T>(Func<T, bool>)

Filter entities by a component field predicate. Evaluated per-entity during broad scan via Open(EntityId) + TryRead<T>(out T). Multiple Where calls chain as AND (each must pass).

public EcsQuery<TArchetype> Where<T>(Func<T, bool> predicate) where T : unmanaged

Parameters

predicate Func<T, bool>

Returns

EcsQuery<TArchetype>

Type Parameters

T

Remarks

Targeted scan (index-first) is not yet available — always uses broad scan.

With<T>()

Include only archetypes that declare T. Mask AND.

public EcsQuery<TArchetype> With<T>() where T : unmanaged

Returns

EcsQuery<TArchetype>

Type Parameters

T

Without<T>()

Exclude archetypes that declare T. Mask AND NOT.

public EcsQuery<TArchetype> Without<T>() where T : unmanaged

Returns

EcsQuery<TArchetype>

Type Parameters

T