Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(query): composable filter predicates (And/Or/Not/With/Without)

esengine9e4df1cd380a
diff --git a/sdk/src/query.ts b/sdk/src/query.ts
index 6913cd254..29b569ac1 100644
--- a/sdk/src/query.ts
+++ b/sdk/src/query.ts
@@ -5,7 +5,7 @@
import { Entity } from './types';
import { AnyComponentDef, ComponentData, isBuiltinComponent } from './component';
-import type { World } from './world';
+import type { World, QueryFilter } from './world';
import { computeQueryCacheKey } from './world';
// =============================================================================
@@ -59,6 +59,109 @@ export function isChangedWrapper(value: unknown): value is ChangedWrapper<AnyCom
type QueryArg = AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>;
+// =============================================================================
+// Filter Expression Tree
+// =============================================================================
+// Composable filter predicates. `With`/`Without` remain as flat shortcuts on
+// the QueryBuilder for the common case (AND of positive/negative predicates);
+// `filter(expr)` accepts arbitrary combinations of And/Or/Not for cases the
+// flat API can't express, e.g. `Or(With(A), Without(B))`.
+
+export type FilterExpr =
+ | { readonly kind: 'with'; readonly component: AnyComponentDef }
+ | { readonly kind: 'without'; readonly component: AnyComponentDef }
+ | { readonly kind: 'and'; readonly filters: readonly FilterExpr[] }
+ | { readonly kind: 'or'; readonly filters: readonly FilterExpr[] }
+ | { readonly kind: 'not'; readonly filter: FilterExpr };
+
+export function With(component: AnyComponentDef): FilterExpr {
+ return { kind: 'with', component };
+}
+export function Without(component: AnyComponentDef): FilterExpr {
+ return { kind: 'without', component };
+}
+export function And(...filters: FilterExpr[]): FilterExpr {
+ return { kind: 'and', filters };
+}
+export function Or(...filters: FilterExpr[]): FilterExpr {
+ return { kind: 'or', filters };
+}
+export function Not(filter: FilterExpr): FilterExpr {
+ return { kind: 'not', filter };
+}
+
+/** Collect every component referenced by a filter expression (for cache-dep tracking). */
+function collectFilterComponents(expr: FilterExpr, out: AnyComponentDef[]): void {
+ switch (expr.kind) {
+ case 'with':
+ case 'without':
+ out.push(expr.component);
+ return;
+ case 'and':
+ case 'or':
+ for (const f of expr.filters) collectFilterComponents(f, out);
+ return;
+ case 'not':
+ collectFilterComponents(expr.filter, out);
+ return;
+ }
+}
+
+/**
+ * Serialize a filter expression deterministically for cache keys. Uses
+ * component `_name` (unique within a registry) so no cross-module numeric
+ * ID table is required.
+ */
+function serializeFilter(expr: FilterExpr): string {
+ switch (expr.kind) {
+ case 'with': return `+${expr.component._name}`;
+ case 'without': return `-${expr.component._name}`;
+ case 'not': return `!(${serializeFilter(expr.filter)})`;
+ case 'and': {
+ const parts = expr.filters.map(serializeFilter);
+ parts.sort();
+ return `&(${parts.join(',')})`;
+ }
+ case 'or': {
+ const parts = expr.filters.map(serializeFilter);
+ parts.sort();
+ return `|(${parts.join(',')})`;
+ }
+ }
+}
+
+/** Compile a filter expression into a reusable entity-predicate closure. */
+function compileFilter(expr: FilterExpr, world: World): (entity: Entity) => boolean {
+ switch (expr.kind) {
+ case 'with': {
+ const comp = expr.component;
+ return (e) => world.has(e, comp);
+ }
+ case 'without': {
+ const comp = expr.component;
+ return (e) => !world.has(e, comp);
+ }
+ case 'not': {
+ const inner = compileFilter(expr.filter, world);
+ return (e) => !inner(e);
+ }
+ case 'and': {
+ const subs = expr.filters.map(f => compileFilter(f, world));
+ return (e) => {
+ for (const s of subs) if (!s(e)) return false;
+ return true;
+ };
+ }
+ case 'or': {
+ const subs = expr.filters.map(f => compileFilter(f, world));
+ return (e) => {
+ for (const s of subs) if (s(e)) return true;
+ return false;
+ };
+ }
+ }
+}
+
// =============================================================================
// Query Descriptor
// =============================================================================
@@ -71,11 +174,14 @@ export interface QueryDescriptor<C extends readonly QueryArg[]> {
readonly _without: AnyComponentDef[];
readonly _addedFilters: Array<{ index: number; component: AnyComponentDef }>;
readonly _changedFilters: Array<{ index: number; component: AnyComponentDef }>;
+ readonly _filter: FilterExpr | null;
}
export interface QueryBuilder<C extends readonly QueryArg[]> extends QueryDescriptor<C> {
with(...components: AnyComponentDef[]): QueryBuilder<C>;
without(...components: AnyComponentDef[]): QueryBuilder<C>;
+ /** Attach a composable filter expression. Replaces any prior call. */
+ filter(expr: FilterExpr): QueryBuilder<C>;
}
function unwrapComponent(comp: QueryArg): AnyComponentDef {
@@ -88,7 +194,8 @@ function unwrapComponent(comp: QueryArg): AnyComponentDef {
function createQueryDescriptor<C extends readonly QueryArg[]>(
components: C,
withFilters: AnyComponentDef[] = [],
- withoutFilters: AnyComponentDef[] = []
+ withoutFilters: AnyComponentDef[] = [],
+ filter: FilterExpr | null = null,
): QueryBuilder<C> {
const mutIndices: number[] = [];
const addedFilters: Array<{ index: number; component: AnyComponentDef }> = [];
@@ -113,11 +220,15 @@ function createQueryDescriptor<C extends readonly QueryArg[]>(
_without: withoutFilters,
_addedFilters: addedFilters,
_changedFilters: changedFilters,
+ _filter: filter,
with(...extraWith: AnyComponentDef[]) {
- return createQueryDescriptor(components, [...withFilters, ...extraWith], withoutFilters);
+ return createQueryDescriptor(components, [...withFilters, ...extraWith], withoutFilters, filter);
},
without(...extraWithout: AnyComponentDef[]) {
- return createQueryDescriptor(components, withFilters, [...withoutFilters, ...extraWithout]);
+ return createQueryDescriptor(components, withFilters, [...withoutFilters, ...extraWithout], filter);
+ },
+ filter(expr: FilterExpr) {
+ return createQueryDescriptor(components, withFilters, withoutFilters, expr);
},
};
}
@@ -171,6 +282,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
private readonly getters_: Array<((entity: Entity) => unknown) | null>;
private readonly mutSetters_: Array<((entity: Entity, data: unknown) => void) | null>;
private readonly mutIsBuiltin_: boolean[];
+ private readonly compiledFilter_: QueryFilter | null;
constructor(world: World, descriptor: QueryDescriptor<C>, lastRunTick = -1) {
this.world_ = world;
@@ -183,10 +295,18 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
component: this.actualComponents_[idx],
data: null as unknown as Record<string, unknown>
}));
+ if (descriptor._filter) {
+ const deps: AnyComponentDef[] = [];
+ collectFilterComponents(descriptor._filter, deps);
+ this.compiledFilter_ = { match: compileFilter(descriptor._filter, world), deps };
+ } else {
+ this.compiledFilter_ = null;
+ }
this.cacheKey_ = computeQueryCacheKey(
this.allRequired_,
descriptor._with,
descriptor._without,
+ descriptor._filter ? serializeFilter(descriptor._filter) : undefined,
);
this.getters_ = this.actualComponents_.map(comp => world.resolveGetter(comp));
this.mutSetters_ = descriptor._mutIndices.map(idx =>
@@ -228,7 +348,8 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
this.allRequired_,
this.descriptor_._with,
this.descriptor_._without,
- this.cacheKey_
+ this.cacheKey_,
+ this.compiledFilter_ ?? undefined,
);
const compCount = actualComponents.length;
const hasMut = _mutIndices.length > 0;
@@ -323,7 +444,8 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
this.allRequired_,
this.descriptor_._with,
this.descriptor_._without,
- this.cacheKey_
+ this.cacheKey_,
+ this.compiledFilter_ ?? undefined,
);
const compCount = this.actualComponents_.length;
const hasMut = _mutIndices.length > 0;
@@ -408,7 +530,11 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
count(): number {
return this.world_.getEntitiesWithComponents(
- this.allRequired_, this.descriptor_._with, this.descriptor_._without
+ this.allRequired_,
+ this.descriptor_._with,
+ this.descriptor_._without,
+ this.cacheKey_,
+ this.compiledFilter_ ?? undefined,
).length;
}
diff --git a/sdk/src/world.ts b/sdk/src/world.ts
index 7764c6745..e6cb4cdea 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -40,6 +40,7 @@ export function computeQueryCacheKey(
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
withoutFilters: AnyComponentDef[] = [],
+ filterKey?: string,
): string {
_keyIds.length = 0;
for (const c of components) _keyIds.push(getCompNumId(c));
@@ -57,9 +58,23 @@ export function computeQueryCacheKey(
_keyIds.sort((a, b) => a - b);
key += '|-' + _keyIds.join(',');
}
+ if (filterKey) {
+ key += '|F=' + filterKey;
+ }
return key;
}
+/**
+ * Predicate-based filter applied after the positive/negative component
+ * checks. Callers (typically `QueryInstance`) compile an expression tree
+ * into a `match` closure plus a list of components the tree reads so the
+ * query cache can invalidate on structural changes to any of them.
+ */
+export interface QueryFilter {
+ readonly match: (entity: Entity) => boolean;
+ readonly deps: readonly AnyComponentDef[];
+}
+
// =============================================================================
// World
// =============================================================================
@@ -564,14 +579,21 @@ export class World {
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
withoutFilters: AnyComponentDef[] = [],
- precomputedKey?: string
+ precomputedKey?: string,
+ filter?: QueryFilter,
): Entity[] {
- if (components.length === 0 && withFilters.length === 0 && withoutFilters.length === 0) {
+ if (
+ components.length === 0 && withFilters.length === 0 &&
+ withoutFilters.length === 0 && !filter
+ ) {
return this.getAllEntities();
}
const cacheKey = precomputedKey ?? computeQueryCacheKey(components, withFilters, withoutFilters);
const depIds = this.collectComponentIds_(components, withFilters, withoutFilters);
+ if (filter) {
+ for (const c of filter.deps) depIds.push(c._id);
+ }
return this.queries_.getOrCompute(cacheKey, depIds, () => {
const entities: Entity[] = [];
@@ -653,6 +675,9 @@ export class World {
}
}
}
+ if (match && filter && !filter.match(entity)) {
+ match = false;
+ }
if (match) {
entities.push(entity);
}
diff --git a/sdk/tests/query-filter.test.ts b/sdk/tests/query-filter.test.ts
new file mode 100644
index 000000000..6af15c7d2
--- /dev/null
+++ b/sdk/tests/query-filter.test.ts
@@ -0,0 +1,123 @@
+/**
+ * @file query-filter.test.ts
+ * @brief Composable filter predicates (With/Without/And/Or/Not) on Query.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import { World } from '../src/world';
+import { defineComponent, defineTag } from '../src/component';
+import { Query, QueryInstance, With, Without, And, Or, Not } from '../src/query';
+
+const Position = defineComponent('F_Position', { x: 0, y: 0 });
+const Health = defineComponent('F_Health', { hp: 100 });
+const Player = defineTag('F_Player');
+const Enemy = defineTag('F_Enemy');
+const Shielded = defineTag('F_Shielded');
+
+function runQuery<T>(world: World, query: { [Symbol.iterator]?: unknown; toArray(): T[] }): T[] {
+ return query.toArray();
+}
+
+describe('Query filter composition', () => {
+ let world: World;
+ let p: number, e1: number, e2: number, shieldedEnemy: number, loose: number;
+
+ beforeEach(() => {
+ world = new World();
+ p = world.spawn();
+ world.insert(p, Position, { x: 1, y: 0 });
+ world.insert(p, Health, { hp: 100 });
+ world.insert(p, Player, {});
+
+ e1 = world.spawn();
+ world.insert(e1, Position, { x: 2, y: 0 });
+ world.insert(e1, Health, { hp: 50 });
+ world.insert(e1, Enemy, {});
+
+ e2 = world.spawn();
+ world.insert(e2, Position, { x: 3, y: 0 });
+ world.insert(e2, Health, { hp: 30 });
+ world.insert(e2, Enemy, {});
+
+ shieldedEnemy = world.spawn();
+ world.insert(shieldedEnemy, Position, { x: 4, y: 0 });
+ world.insert(shieldedEnemy, Health, { hp: 80 });
+ world.insert(shieldedEnemy, Enemy, {});
+ world.insert(shieldedEnemy, Shielded, {});
+
+ loose = world.spawn();
+ world.insert(loose, Position, { x: 5, y: 0 });
+ });
+
+ it('Or(With(A), With(B)) matches entities that have at least one', () => {
+ const q = new QueryInstance(
+ world,
+ Query(Position).filter(Or(With(Player), With(Enemy))),
+ );
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([p, e1, e2, shieldedEnemy].sort());
+ });
+
+ it('Not(With(X)) excludes entities that have X', () => {
+ const q = new QueryInstance(
+ world,
+ Query(Position).filter(Not(With(Shielded))),
+ );
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([p, e1, e2, loose].sort());
+ });
+
+ it('And(With(A), Not(With(B))) composes', () => {
+ const q = new QueryInstance(
+ world,
+ Query(Position).filter(And(With(Enemy), Not(With(Shielded)))),
+ );
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([e1, e2].sort());
+ });
+
+ it('Or(With(Player), And(With(Enemy), Not(With(Shielded))))', () => {
+ const q = new QueryInstance(
+ world,
+ Query(Position).filter(
+ Or(With(Player), And(With(Enemy), Not(With(Shielded)))),
+ ),
+ );
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([p, e1, e2].sort());
+ });
+
+ it('Without(X) via filter tree is equivalent to .without(X)', () => {
+ const tree = new QueryInstance(world, Query(Position).filter(Without(Shielded)));
+ const viaTree = tree.toArray().map((r: unknown[]) => r[0]).sort();
+
+ const flat = new QueryInstance(world, Query(Position).without(Shielded));
+ const viaBuilder = flat.toArray().map((r: unknown[]) => r[0]).sort();
+
+ expect(viaTree).toEqual(viaBuilder);
+ });
+
+ it('filter tree composes with .with() / .without() shortcuts (AND)', () => {
+ // Must have Health AND (Player OR Enemy), and must NOT have Shielded.
+ const q = new QueryInstance(
+ world,
+ Query(Position).with(Health).without(Shielded).filter(Or(With(Player), With(Enemy))),
+ );
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([p, e1, e2].sort());
+ });
+
+ it('count() honours the filter tree', () => {
+ const q = new QueryInstance(
+ world,
+ Query(Position).filter(Or(With(Player), With(Enemy))),
+ );
+ expect(q.count()).toBe(4);
+ });
+
+ it('replacing .filter() uses the new tree (last-write-wins)', () => {
+ const builder = Query(Position).filter(With(Player)).filter(With(Enemy));
+ const q = new QueryInstance(world, builder);
+ const ids = q.toArray().map((r: unknown[]) => r[0]).sort();
+ expect(ids).toEqual([e1, e2, shieldedEnemy].sort());
+ });
+});