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
test(net): the two contracts PR7's collector will stand on
esengine746d66e28c40
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex b1b6cfd67..c7f5810e4 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -9522,6 +9522,7 @@ tabIndex: number | undefined@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]@internal registerRemovedReader: (component: AnyComponentDef) => number+@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 85cd92d02..dfbc21446 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -9715,6 +9715,7 @@ tabIndex: number | undefined@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]@internal registerRemovedReader: (component: AnyComponentDef) => number+@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 65e451031..5246ac36e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -9517,6 +9517,7 @@ tabIndex: number | undefined@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]@internal registerRemovedReader: (component: AnyComponentDef) => number+@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 64a53fa74..6b1cf3c7e 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9769,6 +9769,7 @@ tabIndex: number | undefined@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]@internal registerRemovedReader: (component: AnyComponentDef) => number+@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d450f2648..3547923ca 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -9545,6 +9545,7 @@ tabIndex: number | undefined@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]@internal registerRemovedReader: (component: AnyComponentDef) => number+@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => voiddiff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex eb7659662..afd41ae3a 100644--- a/sdk/src/ecs/ChangeTracker.ts+++ b/sdk/src/ecs/ChangeTracker.ts@@ -73,13 +73,23 @@ export class ChangeTracker {* ownership is never ambiguous.*/registerRemovedReader(component: AnyComponentDef): number {+ return this.registerRemovedReaderFrom(component, this.worldTick_ + 1);+ }++ /**+ * A claim starting at an explicit tick, for a reader whose window is not+ * "since I last ran". A sampler that reads with a one-tick overlap must+ * claim from that same floor, or another reader's prune can take a row it+ * was always going to ask for.+ */+ registerRemovedReaderFrom(component: AnyComponentDef, retainFromTick: number): number {let readers = this.removedReaders_.get(component._id);if (!readers) {readers = new Map();this.removedReaders_.set(component._id, readers);}const id = this.nextReaderId_++;- readers.set(id, this.worldTick_ + 1);+ readers.set(id, retainFromTick);return id;}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 666f05d3c..6f3de4dff 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1202,6 +1202,12 @@ export class World {return this.changes_.registerRemovedReader(component);}+ /** @internal A claim from an explicit tick, for a reader that reads with an+ * overlap rather than "since I last ran". */+ registerRemovedReaderFrom(component: AnyComponentDef, retainFromTick: number): number {+ return this.changes_.registerRemovedReaderFrom(component, retainFromTick);+ }+/** @internal That reader is done with everything up to `lastRunTick`. */advanceRemovedReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {this.changes_.advanceRemovedReader(component, readerId, lastRunTick);diff --git a/sdk/tests/change-candidate-contract.test.ts b/sdk/tests/change-candidate-contract.test.tsnew file mode 100644index 000000000..037f2ed69--- /dev/null+++ b/sdk/tests/change-candidate-contract.test.ts@@ -0,0 +1,81 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file What `Changed` promises a candidate consumer, beyond what a query needs.+ *+ * Replication discovers dirty state by asking the tracker which entity/component+ * pairs are worth re-inspecting. That only covers a component ARRIVING because+ * every add path records a change as well as an add — `Changed` is not merely+ * the `Changed()` filter's input, it is the candidate contract. Anyone tempted+ * to drop the `recordChanged` on the add path ("it already recorded an add")+ * should fail here.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import { App } from '../src/app/app';+import { World } from '../src/ecs/world';+import { defineComponent, Transform } from '../src/ecs/component';+import type { CppRegistry, ESEngineModule } from '../src/wasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';++const Scr = defineComponent('CandScript', { v: 0, w: 0 });++/** A tracked world one tick past its seed, and the floor a sampler would use. */+function tracked(component: Parameters<World['insert']>[1]) {+ const world = new World();+ world.enableChangeTracking(component);+ world.advanceTick();+ return { world, floor: world.getWorldTick() - 1 };+}++describe('a component ARRIVING is a Changed candidate', () => {+ it('through insert', () => {+ const { world, floor } = tracked(Scr);+ const e = world.spawn();+ expect(world.has(e, Scr)).toBe(false);++ world.insert(e, Scr, { v: 1, w: 1 });++ expect(world.anyChangedSince(Scr, floor)).toBe(true);+ expect(world.isChangedSince(e, Scr, floor)).toBe(true);+ });++ it('through set on an entity that lacks it', () => {+ const { world, floor } = tracked(Scr);+ const e = world.spawn();++ world.set(e, Scr, { v: 2, w: 2 });++ expect(world.anyChangedSince(Scr, floor)).toBe(true);+ expect(world.isChangedSince(e, Scr, floor)).toBe(true);+ });++ it('and an entity that did NOT gain it is not a candidate', () => {+ const { world, floor } = tracked(Scr);+ const gained = world.spawn();+ const bystander = world.spawn();+ world.insert(gained, Scr, { v: 1, w: 1 });++ expect(world.isChangedSince(bystander, Scr, floor)).toBe(false);+ });+});++describe.skipIf(!HAS_WASM)('a builtin component arriving is a Changed candidate', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ it('through insert', () => {+ const app = App.new();+ app.connectCpp(new module.Registry() as unknown as CppRegistry, module);+ const world = app.world;+ world.enableChangeTracking(Transform);+ world.advanceTick();+ const floor = world.getWorldTick() - 1;++ const e = world.spawn();+ world.insert(e, Transform, { position: { x: 5, y: 0, z: 0 } });++ expect(world.anyChangedSince(Transform, floor)).toBe(true);+ expect(world.isChangedSince(e, Transform, floor)).toBe(true);+ world.disconnectCpp();+ });+});diff --git a/sdk/tests/removed-retention.test.ts b/sdk/tests/removed-retention.test.tsindex 8bc1dc670..8622f765c 100644--- a/sdk/tests/removed-retention.test.ts+++ b/sdk/tests/removed-retention.test.ts@@ -230,6 +230,33 @@ describe('removal history retention', () => {expect(world.removedReaderCount(Bullet)).toBe(0);});+ /**+ * A sampler reading with a one-tick overlap claims from THAT floor, not from+ * the tick after it. With a second reader on the same component, the default+ * claim would sit one tick above the row the sampler is about to ask for,+ * and that reader's prune takes it.+ */+ it('an overlapping claim survives another reader pruning the same tick', () => {+ const world = new World();+ world.advanceTick();+ const T = world.getWorldTick();++ // A `Removed()` system reader, and a sampler that reads `tick > T - 1`.+ const perSystem = world.registerRemovedReader(Bullet);+ world.registerRemovedReaderFrom(Bullet, T);++ const e = world.spawn();+ world.insert(e, Bullet, { n: 1 });+ world.remove(e, Bullet);+ expect(world.getRemovedEntitiesSince(Bullet, T - 1)).toEqual([e]);++ // The system reader finishes its run at T and gives up everything through+ // it. The sampler has not read yet, so the row must survive.+ world.advanceRemovedReader(Bullet, perSystem, T);++ expect(world.getRemovedEntitiesSince(Bullet, T - 1)).toEqual([e]);+ });+it('change tracking alone does not accumulate removal rows', async () => {const app = App.new();const world = app.world;