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.

refactor(ecs): the query cache handed out the array it was keeping

esenginee391f72db1ca
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e5cb1ee1b..ee8cf033d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,14 @@ published separately; it ships inside the editor.
component and restore it afterwards. A name that matches no bool field on the
component fails the build rather than reading as "draws nothing".
+### Changed
+
+- **`world.getEntitiesWithComponents()` returns a `readonly Entity[]`.** The array
+ it hands back is the query cache's own entry, not a copy — sorting or pushing to
+ it reorders or corrupts what every later reader of that query sees. Nothing in
+ the engine did (all sixty-odd call sites read it), and now nothing can: the type
+ says so. Reading, `for..of`, `.map`, `.filter` and indexing are unaffected.
+
### Fixed
- **`Removed()` reported despawns from before anything was watching.** Losing a
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f571670c2..482621b98 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8500,7 +8500,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, precomputedDepIds?: symbol[]) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 606567b4d..b424b06e6 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8670,7 +8670,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, precomputedDepIds?: symbol[]) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly 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 bda4561be..2cddf679a 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8495,7 +8495,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, precomputedDepIds?: symbol[]) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2a0f2f9a6..2ca1648a8 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8740,7 +8740,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, precomputedDepIds?: symbol[]) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly 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 134a0b0b1..f199d4474 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8522,7 +8522,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, precomputedDepIds?: symbol[]) => Entity[]
+getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
getWasmModule: () => ESEngineModule | null
diff --git a/sdk/src/ai/bt/BtPlugin.ts b/sdk/src/ai/bt/BtPlugin.ts
index 118f64ae7..2df170bcf 100644
--- a/sdk/src/ai/bt/BtPlugin.ts
+++ b/sdk/src/ai/bt/BtPlugin.ts
@@ -37,7 +37,7 @@ interface BtAgentState {
/** The slice of `World` the BT step needs — lets tests inject a fake. */
export interface AiWorldView {
- getEntitiesWithComponents(components: readonly AnyComponentDef[]): Entity[];
+ getEntitiesWithComponents(components: readonly AnyComponentDef[]): readonly Entity[];
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C>;
set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void;
has(entity: Entity, component: AnyComponentDef): boolean;
diff --git a/sdk/src/ai/fsm/FsmPlugin.ts b/sdk/src/ai/fsm/FsmPlugin.ts
index 934dde272..fe9e63887 100644
--- a/sdk/src/ai/fsm/FsmPlugin.ts
+++ b/sdk/src/ai/fsm/FsmPlugin.ts
@@ -37,7 +37,7 @@ interface AgentState {
/** The slice of `World` the FSM step needs — lets tests inject a fake. */
export interface FsmWorldView {
- getEntitiesWithComponents(components: readonly AnyComponentDef[]): Entity[];
+ getEntitiesWithComponents(components: readonly AnyComponentDef[]): readonly Entity[];
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C>;
set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void;
has(entity: Entity, component: AnyComponentDef): boolean;
diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.ts
index 2c57b6c43..f2bf866a9 100644
--- a/sdk/src/ai/nav/NavPlugin.ts
+++ b/sdk/src/ai/nav/NavPlugin.ts
@@ -38,7 +38,7 @@ export interface AgentRuntime {
/** The slice of `World` the nav step needs — lets tests inject a fake. */
export interface NavWorldView {
- getEntitiesWithComponents(components: readonly AnyComponentDef[]): Entity[];
+ getEntitiesWithComponents(components: readonly AnyComponentDef[]): readonly Entity[];
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C>;
set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void;
}
diff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.ts
index ce6640293..7235e353f 100644
--- a/sdk/src/ai/perception/PerceptionPlugin.ts
+++ b/sdk/src/ai/perception/PerceptionPlugin.ts
@@ -23,7 +23,7 @@ import { Perceiver, Perception, PerceptionTarget, type PerceptionData } from './
/** The slice of `World` the perception step needs — lets tests inject a fake. */
export interface PerceptionWorldView {
- getEntitiesWithComponents(components: readonly AnyComponentDef[]): Entity[];
+ getEntitiesWithComponents(components: readonly AnyComponentDef[]): readonly Entity[];
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C>;
set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void;
has(entity: Entity, component: AnyComponentDef): boolean;
diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.ts
index c36d8ee2e..a2f4049d6 100644
--- a/sdk/src/ecs/query.ts
+++ b/sdk/src/ecs/query.ts
@@ -346,7 +346,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
* its own. Every caller that asks "which entities match" goes through here,
* so none of them can disagree about the cache key or the dep set.
*/
- private candidates_(): Entity[] {
+ private candidates_(): readonly Entity[] {
return this.world_.getEntitiesWithComponents(
this.allRequired_,
this.descriptor_._with,
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 6e83042f8..429b9be2a 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -750,7 +750,7 @@ export class World {
precomputedKey?: string,
filter?: QueryFilter,
precomputedDepIds?: symbol[],
- ): Entity[] {
+ ): readonly Entity[] {
if (
components.length === 0 && withFilters.length === 0 &&
withoutFilters.length === 0 && !filter