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
refactor(ecs): the query cache handed out the array it was keeping
esenginee391f72db1ca
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thecomponent 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 adiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]getWasmModule: () => ESEngineModule | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]getWasmModule: () => ESEngineModule | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]getWasmModule: () => ESEngineModule | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]getWasmModule: () => ESEngineModule | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]getWasmModule: () => ESEngineModule | nulldiff --git a/sdk/src/ai/bt/BtPlugin.ts b/sdk/src/ai/bt/BtPlugin.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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