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.

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.md
index 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: () => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: () => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: () => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: () => void
diff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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;