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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(query): composable filter predicates (And/Or/Not/With/Without)
esengine9e4df1cd380a
diff --git a/sdk/src/query.ts b/sdk/src/query.tsindex 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<AnyComtype 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<Quprivate 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<Qucomponent: 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<Quthis.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<Quthis.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<Qucount(): 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.tsindex 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.tsnew file mode 100644index 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());+ });+});