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.

perf(sdk): query iteration precomputes its dependency ids

esengine5bc9e77854c5
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 556d8ca98..d9dba3193 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -228,6 +228,7 @@ type: "animFrames"
## AnimationPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
@@ -6831,6 +6832,7 @@ static prototype: TrailAPI
## TrailPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): TrailPlugin
static prototype: TrailPlugin
@@ -7577,7 +7579,7 @@ get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<
getAllEntities: () => Entity[]
getComponentTypes: (entity: Entity) => string[]
getCppRegistry: () => CppRegistry | null
-getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 042902e24..9f0dd53e7 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -223,6 +223,7 @@ type: "animFrames"
## AnimationPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
@@ -6826,6 +6827,7 @@ static prototype: TrailAPI
## TrailPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): TrailPlugin
static prototype: TrailPlugin
@@ -7572,7 +7574,7 @@ get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<
getAllEntities: () => Entity[]
getComponentTypes: (entity: Entity) => string[]
getCppRegistry: () => CppRegistry | null
-getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8a7289f46..5748fe0e0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -223,6 +223,7 @@ type: "animFrames"
## AnimationPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
@@ -6833,6 +6834,7 @@ static prototype: TrailAPI
## TrailPlugin — class
```
build: (app: App) => void
+cleanup: () => void
name: string
static new (): TrailPlugin
static prototype: TrailPlugin
@@ -7596,7 +7598,7 @@ get: <C extends AnyComponentDef>(entity: Entity, component: C) => ComponentData<
getAllEntities: () => Entity[]
getComponentTypes: (entity: Entity) => string[]
getCppRegistry: () => CppRegistry | null
-getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/src/query.ts b/sdk/src/query.ts
index 441f6d8d0..192fac606 100644
--- a/sdk/src/query.ts
+++ b/sdk/src/query.ts
@@ -285,6 +285,9 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
private readonly result_: unknown[];
private readonly mutData_: Array<{ component: AnyComponentDef; data: Record<string, unknown> }>;
private readonly cacheKey_: string;
+ // Static cache-dependency ids (required + with + without + filter deps),
+ // precomputed like cacheKey_ so per-call query iteration allocates no array.
+ private readonly depIds_: symbol[];
private lastRunTick_: number;
private readonly getters_: Array<((entity: Entity) => unknown) | null>;
private readonly mutSetters_: Array<((entity: Entity, data: unknown) => void) | null>;
@@ -315,6 +318,15 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
descriptor._without,
descriptor._filter ? serializeFilter(descriptor._filter) : undefined,
);
+ // Same set the cache validity check reads; order is irrelevant (it maps
+ // each id to its version). Must match what getEntitiesWithComponents would
+ // otherwise build per call.
+ this.depIds_ = [
+ ...this.allRequired_.map(c => c._id),
+ ...descriptor._with.map(c => c._id),
+ ...descriptor._without.map(c => c._id),
+ ...(this.compiledFilter_?.deps.map(c => c._id) ?? []),
+ ];
this.getters_ = this.actualComponents_.map(comp => world.resolveGetter(comp));
this.mutSetters_ = descriptor._mutIndices.map(idx =>
world.resolveSetter(this.actualComponents_[idx])
@@ -357,6 +369,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
this.descriptor_._without,
this.cacheKey_,
this.compiledFilter_ ?? undefined,
+ this.depIds_,
);
const compCount = actualComponents.length;
const hasMut = _mutIndices.length > 0;
@@ -453,6 +466,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
this.descriptor_._without,
this.cacheKey_,
this.compiledFilter_ ?? undefined,
+ this.depIds_,
);
const compCount = this.actualComponents_.length;
const hasMut = _mutIndices.length > 0;
diff --git a/sdk/src/world.ts b/sdk/src/world.ts
index a0b072f16..330986f4f 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -679,6 +679,7 @@ export class World {
withoutFilters: AnyComponentDef[] = [],
precomputedKey?: string,
filter?: QueryFilter,
+ precomputedDepIds?: symbol[],
): Entity[] {
if (
components.length === 0 && withFilters.length === 0 &&
@@ -688,9 +689,16 @@ export class World {
}
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);
+ // The dep-id set is static per query; QueryInstance precomputes it (incl.
+ // filter deps) so cache-hit iteration allocates nothing here.
+ let depIds: symbol[];
+ if (precomputedDepIds) {
+ depIds = precomputedDepIds;
+ } else {
+ depIds = this.collectComponentIds_(components, withFilters, withoutFilters);
+ if (filter) {
+ for (const c of filter.deps) depIds.push(c._id);
+ }
}
return this.queries_.getOrCompute(cacheKey, depIds, () => {