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
fix(ecs): retain same-frame removals with sequence cursors
yhh8fa10bd5aeff
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f8c13ec6a..764fc2a46 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Removal queries retain events across system runs in the same frame.** Removed component events use reader-owned sequence cursors, so removals after a system runs or after its last read remain available on its next run. Fresh readers start from registration, paused and async readers keep their claims, and fast readers skip retained history rather than repeatedly scanning a paused reader's backlog; explicit tick-based samplers keep their existing windows.+- **Recreated UI components start a fresh visibility baseline.** Removing and reinserting a UINode no longer inherits its predecessor's shown/hidden state, including edits between frames or within one frame. Removed nodes leave the visibility cache; opted-in live component identities distinguish replacements without retaining removal history or adding resolved visibility reads on steady frames.## [0.87.0] - 2026-10-15diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 3815c4810..ac4b2139d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6876,7 +6876,7 @@ send: (data: string | ArrayBuffer) => void```@internal activateRetention: () => void@internal dispose: () => void-@internal releaseThrough: (lastRunTick: number) => void+@internal releaseThrough: (_lastRunTick: number) => void@internal resetTick: (tick: number) => void[Symbol.iterator]: () => Iterator<Entity>isEmpty: () => boolean@@ -9998,6 +9998,7 @@ tabIndex: number | undefined```@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined+@internal advanceRemovedCursorReader: (component: AnyComponentDef, readerId: number, through: number) => void@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@@ -10023,6 +10024,8 @@ tabIndex: number | undefined@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats+@internal getRemovalSequence: () => number+@internal getRemovedEntitiesForReader: (component: AnyComponentDef, readerId: number) => Entity[]@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@internal getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }@internal getTopologyChangedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@@ -10044,6 +10047,7 @@ tabIndex: number | undefined@internal queries_: QueryCache@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]+@internal registerRemovedCursorReader: (component: AnyComponentDef) => number@internal registerRemovedReader: (component: AnyComponentDef) => number@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c131c1cf5..62536ee21 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -7089,7 +7089,7 @@ send: (data: string | ArrayBuffer) => void```@internal activateRetention: () => void@internal dispose: () => void-@internal releaseThrough: (lastRunTick: number) => void+@internal releaseThrough: (_lastRunTick: number) => void@internal resetTick: (tick: number) => void[Symbol.iterator]: () => Iterator<Entity>isEmpty: () => boolean@@ -10211,6 +10211,7 @@ tabIndex: number | undefined```@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined+@internal advanceRemovedCursorReader: (component: AnyComponentDef, readerId: number, through: number) => void@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@@ -10236,6 +10237,8 @@ tabIndex: number | undefined@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats+@internal getRemovalSequence: () => number+@internal getRemovedEntitiesForReader: (component: AnyComponentDef, readerId: number) => Entity[]@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@internal getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }@internal getTopologyChangedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@@ -10257,6 +10260,7 @@ tabIndex: number | undefined@internal queries_: QueryCache@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]+@internal registerRemovedCursorReader: (component: AnyComponentDef) => number@internal registerRemovedReader: (component: AnyComponentDef) => number@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex eaef8556e..64599ac5d 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6871,7 +6871,7 @@ send: (data: string | ArrayBuffer) => void```@internal activateRetention: () => void@internal dispose: () => void-@internal releaseThrough: (lastRunTick: number) => void+@internal releaseThrough: (_lastRunTick: number) => void@internal resetTick: (tick: number) => void[Symbol.iterator]: () => Iterator<Entity>isEmpty: () => boolean@@ -9993,6 +9993,7 @@ tabIndex: number | undefined```@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined+@internal advanceRemovedCursorReader: (component: AnyComponentDef, readerId: number, through: number) => void@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@@ -10018,6 +10019,8 @@ tabIndex: number | undefined@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats+@internal getRemovalSequence: () => number+@internal getRemovedEntitiesForReader: (component: AnyComponentDef, readerId: number) => Entity[]@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@internal getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }@internal getTopologyChangedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@@ -10039,6 +10042,7 @@ tabIndex: number | undefined@internal queries_: QueryCache@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]+@internal registerRemovedCursorReader: (component: AnyComponentDef) => number@internal registerRemovedReader: (component: AnyComponentDef) => number@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex fb65afefb..a9c4ad571 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -7164,7 +7164,7 @@ send: (data: string | ArrayBuffer) => void```@internal activateRetention: () => void@internal dispose: () => void-@internal releaseThrough: (lastRunTick: number) => void+@internal releaseThrough: (_lastRunTick: number) => void@internal resetTick: (tick: number) => void[Symbol.iterator]: () => Iterator<Entity>isEmpty: () => boolean@@ -10292,6 +10292,7 @@ tabIndex: number | undefined```@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined+@internal advanceRemovedCursorReader: (component: AnyComponentDef, readerId: number, through: number) => void@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@@ -10317,6 +10318,8 @@ tabIndex: number | undefined@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats+@internal getRemovalSequence: () => number+@internal getRemovedEntitiesForReader: (component: AnyComponentDef, readerId: number) => Entity[]@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@internal getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }@internal getTopologyChangedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@@ -10338,6 +10341,7 @@ tabIndex: number | undefined@internal queries_: QueryCache@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]+@internal registerRemovedCursorReader: (component: AnyComponentDef) => number@internal registerRemovedReader: (component: AnyComponentDef) => number@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1fc1a1925..12802e5ff 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6878,7 +6878,7 @@ send: (data: string | ArrayBuffer) => void```@internal activateRetention: () => void@internal dispose: () => void-@internal releaseThrough: (lastRunTick: number) => void+@internal releaseThrough: (_lastRunTick: number) => void@internal resetTick: (tick: number) => void[Symbol.iterator]: () => Iterator<Entity>isEmpty: () => boolean@@ -10024,6 +10024,7 @@ tabIndex: number | undefined```@internal addressOfComponent: (component: AnyComponentDef, entity: Entity) => number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined+@internal advanceRemovedCursorReader: (component: AnyComponentDef, readerId: number, through: number) => void@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@@ -10049,6 +10050,8 @@ tabIndex: number | undefined@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats+@internal getRemovalSequence: () => number+@internal getRemovedEntitiesForReader: (component: AnyComponentDef, readerId: number) => Entity[]@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@internal getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }@internal getTopologyChangedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]@@ -10070,6 +10073,7 @@ tabIndex: number | undefined@internal queries_: QueryCache@internal queryCostEnabled: boolean@internal queryEntities: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]+@internal registerRemovedCursorReader: (component: AnyComponentDef) => number@internal registerRemovedReader: (component: AnyComponentDef) => number@internal registerRemovedReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => numberdiff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex 0aafaace3..21d280d5b 100644--- a/sdk/src/ecs/ChangeTracker.ts+++ b/sdk/src/ecs/ChangeTracker.ts@@ -19,11 +19,15 @@ import { AnyComponentDef } from './component';* — so a holder that can go idle advances anyway.*/class ReaderOwnedJournal {- private rows_ = new Map<symbol, Array<{ entity: Entity; tick: number }>>();+ private rows_ = new Map<symbol, Array<{ entity: Entity; tick: number; sequence?: number }>>();private readers_ = new Map<symbol, Map<number, number>>();+ private cursorReaders_ = new Map<symbol, Map<number, number>>();+ private sequence_ = 0;++ constructor(private readonly sequenced_ = false) {}hasReaders(componentId: symbol): boolean {- return this.readers_.has(componentId);+ return this.readers_.has(componentId) || this.cursorReaders_.has(componentId);}record(componentId: symbol, entity: Entity, tick: number): void {@@ -32,7 +36,43 @@ class ReaderOwnedJournal {buffer = [];this.rows_.set(componentId, buffer);}- buffer.push({ entity, tick });+ buffer.push(this.sequenced_ ? { entity, tick, sequence: ++this.sequence_ } : { entity, tick });+ }++ sequence(): number { return this.sequence_; }++ registerCursor(componentId: symbol, readerId: number): void {+ let readers = this.cursorReaders_.get(componentId);+ if (!readers) {+ readers = new Map();+ this.cursorReaders_.set(componentId, readers);+ }+ readers.set(readerId, this.sequence_);+ }++ sinceCursor(componentId: symbol, readerId: number): Entity[] {+ const after = this.cursorReaders_.get(componentId)?.get(readerId);+ if (after === undefined) return [];+ const rows = this.rows_.get(componentId);+ if (!rows) return [];+ // A parked reader may retain a large prefix. An up-to-date reader+ // should search past it rather than revisit every retained event.+ let lo = 0, hi = rows.length;+ while (lo < hi) {+ const mid = (lo + hi) >>> 1;+ if (rows[mid].sequence! <= after) lo = mid + 1;+ else hi = mid;+ }+ const out: Entity[] = [];+ for (let i = lo; i < rows.length; i++) out.push(rows[i].entity);+ return out;+ }++ advanceCursor(componentId: symbol, readerId: number, through: number): void {+ const readers = this.cursorReaders_.get(componentId);+ if (!readers?.has(readerId)) return;+ readers.set(readerId, through);+ this.prune_(componentId);}/** How many rows are buffered, at any tick. An UPPER bound on what `since`@@ -69,13 +109,14 @@ class ReaderOwnedJournal {dispose(componentId: symbol, readerId: number): void {const readers = this.readers_.get(componentId);- if (!readers) return;- readers.delete(readerId);+ readers?.delete(readerId);+ this.cursorReaders_.get(componentId)?.delete(readerId);this.prune_(componentId);}readerCount(componentId: symbol): number {- return this.readers_.get(componentId)?.size ?? 0;+ return (this.readers_.get(componentId)?.size ?? 0)+ + (this.cursorReaders_.get(componentId)?.size ?? 0);}totalRows(): number {@@ -86,21 +127,28 @@ class ReaderOwnedJournal {private prune_(componentId: symbol): void {const readers = this.readers_.get(componentId);- if (!readers || readers.size === 0) {- this.readers_.delete(componentId);+ const cursors = this.cursorReaders_.get(componentId);+ if (!readers?.size) this.readers_.delete(componentId);+ if (!cursors?.size) this.cursorReaders_.delete(componentId);+ if (!readers?.size && !cursors?.size) {this.rows_.delete(componentId);return;}const buffer = this.rows_.get(componentId);if (!buffer) return;let safe = Infinity;- for (const from of readers.values()) if (from < safe) safe = from;- let writeIdx = 0;- for (let i = 0; i < buffer.length; i++) {- if (buffer[i].tick >= safe) buffer[writeIdx++] = buffer[i];+ for (const from of readers?.values() ?? []) if (from < safe) safe = from;+ let safeSequence = Infinity;+ for (const through of cursors?.values() ?? []) {+ if (through < safeSequence) safeSequence = through;}- buffer.length = writeIdx;- if (writeIdx === 0) this.rows_.delete(componentId);+ // Both ticks and sequences are monotonic. A held prefix cannot expire+ // behind its first live row; do not copy it on every fast-reader run.+ let expired = 0;+ while (expired < buffer.length && buffer[expired].tick < safe+ && (buffer[expired].sequence ?? -Infinity) <= safeSequence) expired++;+ if (expired === buffer.length) this.rows_.delete(componentId);+ else if (expired > 0) buffer.splice(0, expired);}}@@ -110,7 +158,7 @@ export class ChangeTracker {private componentIncarnations_ = new Map<symbol, Map<Entity, number>>();private nextIncarnation_ = 1;private componentChangedTicks_ = new Map<symbol, Map<Entity, number>>();- private readonly removals_ = new ReaderOwnedJournal();+ private readonly removals_ = new ReaderOwnedJournal(true);/** Membership moves, independent of ordinary change tracking. */private readonly topology_ = new ReaderOwnedJournal();/**@@ -230,14 +278,29 @@ export class ChangeTracker {}/**- * Take out a claim on `component`'s removal history. History begins HERE:- * a new reader does not inherit rows another reader happened to leave, so- * ownership is never ambiguous.+ * A tick-based claim for windows after the current tick. System queries+ * use a cursor instead, distinguishing events within the same tick.*/registerRemovedReader(component: AnyComponentDef): number {return this.registerRemovedReaderFrom(component, this.worldTick_ + 1);}+ registerRemovedCursorReader(component: AnyComponentDef): number {+ const id = this.nextReaderId_++;+ this.removals_.registerCursor(component._id, id);+ return id;+ }++ getRemovalSequence(): number { return this.removals_.sequence(); }++ getRemovedEntitiesForReader(component: AnyComponentDef, readerId: number): Entity[] {+ return this.removals_.sinceCursor(component._id, readerId);+ }++ advanceRemovedCursorReader(component: AnyComponentDef, readerId: number, through: number): void {+ this.removals_.advanceCursor(component._id, readerId, through);+ }+/*** 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@@ -252,7 +315,7 @@ export class ChangeTracker {/*** This reader has finished a run whose window ended at `lastRunTick`, so it- * will never ask for a row at or before it again. `Removed` reads+ * will never ask for a row at or before it again. Tick-based samplers read* `tick > lastRunTick`, which is why the claim is the tick after.*/advanceRemovedReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.tsindex 16f0f70a7..5224e587d 100644--- a/sdk/src/ecs/query.ts+++ b/sdk/src/ecs/query.ts@@ -815,6 +815,7 @@ export class RemovedQueryInstance<T extends AnyComponentDef> implements Iterableprivate readonly component_: T;private lastRunTick_: number;private readerId_: number | null = null;+ private readThrough_ = 0;/** Constructing one has NO side effect on the world: a runner that builds* several params and throws on a later one would otherwise leave a claim@@ -829,18 +830,19 @@ export class RemovedQueryInstance<T extends AnyComponentDef> implements IterableactivateRetention(): void {if (this.readerId_ !== null) return;this.world_.enableChangeTracking(this.component_);- this.readerId_ = this.world_.registerRemovedReader(this.component_);+ this.readerId_ = this.world_.registerRemovedCursorReader(this.component_);+ this.readThrough_ = this.world_.getRemovalSequence();}/**- * @internal This run is over, so rows up to `lastRunTick` will never be- * asked for again. NOT `resetTick`: a system may await mid-body, and a claim- * released before the body read would let another reader's prune take rows- * this one is still owed.+ * @internal This run is over, so release the sequence it observed. A later+ * removal in the same frame is still owed. NOT `resetTick`: a system may+ * await mid-body, and an early release would let another reader's prune+ * take rows this one is still owed.*/- releaseThrough(lastRunTick: number): void {+ releaseThrough(_lastRunTick: number): void {if (this.readerId_ === null) return;- this.world_.advanceRemovedReader(this.component_, this.readerId_, lastRunTick);+ this.world_.advanceRemovedCursorReader(this.component_, this.readerId_, this.readThrough_);}/** @internal Give up the claim — the runner evicted or reset this system. */@@ -853,17 +855,24 @@ export class RemovedQueryInstance<T extends AnyComponentDef> implements Iterable/** @internal Update lastRunTick for reuse across system runs */resetTick(tick: number): void {this.lastRunTick_ = tick;+ this.readThrough_ = this.world_.getRemovalSequence();+ }++ private read_(): Entity[] {+ if (this.readerId_ === null) return this.world_.getRemovedEntitiesSince(this.component_, this.lastRunTick_);+ this.readThrough_ = this.world_.getRemovalSequence();+ return this.world_.getRemovedEntitiesForReader(this.component_, this.readerId_);}*[Symbol.iterator](): Iterator<Entity> {- yield* this.world_.getRemovedEntitiesSince(this.component_, this.lastRunTick_);+ yield* this.read_();}isEmpty(): boolean {- return this.world_.getRemovedEntitiesSince(this.component_, this.lastRunTick_).length === 0;+ return this.read_().length === 0;}toArray(): Entity[] {- return this.world_.getRemovedEntitiesSince(this.component_, this.lastRunTick_);+ return this.read_();}}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex ec4fdda3c..2c8d6cbdb 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1393,11 +1393,29 @@ export class World {return this.changes_.getRemovedEntitiesSince(component, sinceTick);}- /** @internal A `Removed` reader's claim on history, from now on. */+ /** @internal A tick-based removal lease for samples after the current tick. */registerRemovedReader(component: AnyComponentDef): number {return this.changes_.registerRemovedReader(component);}+ /** @internal A removal lease starting at the current event sequence. */+ registerRemovedCursorReader(component: AnyComponentDef): number {+ return this.changes_.registerRemovedCursorReader(component);+ }++ /** @internal Latest removal sequence, independent of frame ticks. */+ getRemovalSequence(): number { return this.changes_.getRemovalSequence(); }++ /** @internal Unacknowledged removals belonging to this cursor reader. */+ getRemovedEntitiesForReader(component: AnyComponentDef, readerId: number): Entity[] {+ return this.changes_.getRemovedEntitiesForReader(component, readerId);+ }++ /** @internal Release only events this run observed, preserving later removals. */+ advanceRemovedCursorReader(component: AnyComponentDef, readerId: number, through: number): void {+ this.changes_.advanceRemovedCursorReader(component, readerId, through);+ }+/** @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 {diff --git a/sdk/tests/removed-retention.test.ts b/sdk/tests/removed-retention.test.tsindex 8622f765c..49d55cc28 100644--- a/sdk/tests/removed-retention.test.ts+++ b/sdk/tests/removed-retention.test.ts@@ -82,8 +82,7 @@ describe('removal history retention', () => {await app.tick(1 / 60);arm(false);- // A tick of its own: a removal recorded at the tick a reader last ran is- // outside its next window (`tick > lastRunTick`) and owed to nobody.+ // The fast reader advances while the slow reader retains its claim.await app.tick(1 / 60);const e = world.spawn();world.insert(e, Bullet, { n: 1 });@@ -156,9 +155,7 @@ describe('removal history retention', () => {let other: number | null = null;let victim: Entity | null = null;- // Removed IN-FRAME: the window is `tick > lastRunTick`, so a removal- // between two frames carries the tick the reader just ran at and is- // outside the next window by construction.+ // Produce before the async reader, whose claim must survive its await.app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {if (!armed || victim === null) return;@@ -241,7 +238,7 @@ describe('removal history retention', () => {world.advanceTick();const T = world.getWorldTick();- // A `Removed()` system reader, and a sampler that reads `tick > T - 1`.+ // A tick-based reader, and a sampler that reads `tick > T - 1`.const perSystem = world.registerRemovedReader(Bullet);world.registerRemovedReaderFrom(Bullet, T);diff --git a/sdk/tests/removed-same-tick-wasm.test.ts b/sdk/tests/removed-same-tick-wasm.test.tsnew file mode 100644index 000000000..6d168a2a1--- /dev/null+++ b/sdk/tests/removed-same-tick-wasm.test.ts@@ -0,0 +1,78 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';+import { App, flushPendingRegistrations } from '../src/app/app';+import { AppContext, setDefaultContext } from '../src/ecs/context';+import { Removed } from '../src/ecs/query';+import { defineSystem, Schedule } from '../src/ecs/system';+import { UINode } from '../src/ui/core/ui-node';+import type { Entity } from '../src/types';+import type { CppRegistry, ESEngineModule } from '../src/wasm';+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';++describe.skipIf(!HAS_WASM)('builtin removal delivery on real WASM', () => {+ let engine: ESEngineModule;+ let registry: CppRegistry;+ let app: App;+ let batches: Entity[][];+ beforeAll(async () => { engine = await loadWasmModule(); });+ beforeEach(() => {+ setDefaultContext(new AppContext());+ registry = new engine.Registry();+ app = App.new();+ app.connectCpp(registry, engine);+ batches = [];+ app.addSystemToSchedule(Schedule.Update, defineSystem([Removed(UINode)], rows => {+ batches.push(rows.toArray());+ }));+ flushPendingRegistrations(app);+ });+ afterEach(() => {+ for (const entity of app.world.getAllEntities()) app.world.despawn(entity);+ app.world.disconnectCpp();+ registry.delete();+ });+ it.each(['remove', 'despawn'] as const)('delivers %s between frames exactly once', async operation => {+ const entity = app.world.spawn();+ app.world.insert(entity, UINode);+ await app.tick(1 / 60);+ if (operation === 'remove') app.world.remove(entity, UINode);+ else app.world.despawn(entity);+ await app.tick(1 / 60);+ await app.tick(1 / 60);+ expect(batches).toEqual([[], [entity], []]);+ expect(app.world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('delivers a PostUpdate removal on the next frame', async () => {+ const entity = app.world.spawn();+ app.world.insert(entity, UINode);+ let remove = false;+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => {+ if (remove) {+ app.world.remove(entity, UINode);+ remove = false;+ }+ }));+ await app.tick(1 / 60);+ remove = true;+ await app.tick(1 / 60);+ await app.tick(1 / 60);+ await app.tick(1 / 60);+ expect(batches).toEqual([[], [], [entity], []]);+ expect(app.world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('delivers repeated builtin replacements without retaining completed batches', async () => {+ const entity = app.world.spawn();+ app.world.insert(entity, UINode);+ await app.tick(1 / 60);+ for (let frame = 0; frame < 20; frame++) {+ for (let i = 0; i < 100; i++) {+ app.world.remove(entity, UINode);+ app.world.insert(entity, UINode);+ }+ await app.tick(1 / 60);+ expect(batches.at(-1)).toEqual(Array(100).fill(entity));+ expect(app.world.getStorageSizes().changes.removedRows).toBe(0);+ }+ });+});diff --git a/sdk/tests/removed-same-tick.test.ts b/sdk/tests/removed-same-tick.test.tsnew file mode 100644index 000000000..35724356c--- /dev/null+++ b/sdk/tests/removed-same-tick.test.ts@@ -0,0 +1,161 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { beforeEach, describe, expect, it } from 'vitest';+import { AppContext, setDefaultContext } from '../src/ecs/context';+import { defineComponent } from '../src/ecs/component';+import { World } from '../src/ecs/world';+import { ResourceStorage } from '../src/ecs/resource';+import { Removed } from '../src/ecs/query';+import { defineSystem, SystemRunner } from '../src/ecs/system';+import type { Entity } from '../src/types';++const Marker = defineComponent('SameTickMarker', { value: 0 });+describe('removal delivery within a world tick', () => {+ let world: World;+ let runner: SystemRunner;+ beforeEach(() => {+ setDefaultContext(new AppContext());+ world = new World();+ runner = new SystemRunner(world, new ResourceStorage());+ });+ const removeOne = () => {+ const entity = world.spawn();+ world.insert(entity, Marker);+ world.remove(entity, Marker);+ return entity;+ };+ it('delivers a removal after the previous run exactly once without advancing the tick', () => {+ const batches: Entity[][] = [];+ const reader = defineSystem([Removed(Marker)], rows => { batches.push(rows.toArray()); });+ runner.run(reader);+ const entity = removeOne();+ runner.run(reader);+ runner.run(reader);+ expect(batches).toEqual([[], [entity], []]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('preserves separate removals of a recreated component within one tick', () => {+ const batches: Entity[][] = [];+ const reader = defineSystem([Removed(Marker)], rows => { batches.push([...rows]); });+ runner.run(reader);+ const entity = removeOne();+ world.insert(entity, Marker);+ world.remove(entity, Marker);+ runner.run(reader);+ expect(batches).toEqual([[], [entity, entity]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('keeps removals made after the body last read for the following run', () => {+ const batches: Entity[][] = [];+ let victim: Entity | undefined;+ const reader = defineSystem([Removed(Marker)], rows => {+ batches.push(rows.toArray());+ if (victim !== undefined) {+ world.remove(victim, Marker);+ victim = undefined;+ }+ });+ const entity = world.spawn();+ world.insert(entity, Marker);+ victim = entity;+ runner.run(reader);+ runner.run(reader);+ expect(batches).toEqual([[], [entity]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('does not inherit older rows retained by a parked reader', () => {+ const oldBatches: Entity[][] = [], newBatches: Entity[][] = [];+ const parked = defineSystem([Removed(Marker)], rows => { oldBatches.push(rows.toArray()); });+ runner.run(parked);+ const old = removeOne();+ const fresh = defineSystem([Removed(Marker)], rows => { newBatches.push(rows.toArray()); });+ runner.run(fresh);+ const next = removeOne();+ runner.run(fresh);+ runner.run(parked);+ expect(newBatches).toEqual([[], [next]]);+ expect(oldBatches).toEqual([[], [old, next]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('keeps a removal produced after the last read when the body throws', () => {+ const batches: Entity[][] = [];+ let fail = true;+ let victim: Entity | undefined;+ const reader = defineSystem([Removed(Marker)], rows => {+ batches.push(rows.toArray());+ if (fail) {+ victim = removeOne();+ fail = false;+ throw new Error('body failed after removing');+ }+ });+ expect(() => runner.run(reader)).toThrow('body failed after removing');+ runner.run(reader);+ expect(batches).toEqual([[], [victim]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('does not let a tick-based sampler prune a cursor reader before it reads', () => {+ const batches: Entity[][] = [];+ const reader = defineSystem([Removed(Marker)], rows => { batches.push(rows.toArray()); });+ runner.run(reader);+ const sampler = world.registerRemovedReaderFrom(Marker, 0);+ const entity = removeOne();+ world.advanceRemovedReader(Marker, sampler, world.getWorldTick());+ expect(world.getStorageSizes().changes.removedRows).toBe(1);+ runner.run(reader);+ expect(batches).toEqual([[], [entity]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ world.disposeRemovedReader(Marker, sampler);+ });+ it('releases the initial window even when the body does not enumerate it', () => {+ const reader = defineSystem([Removed(Marker)], () => {});+ runner.run(reader);+ removeOne();+ expect(world.getStorageSizes().changes.removedRows).toBe(1);+ runner.run(reader);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+ it('leaves a tick samplers overlapping window intact after cursor acknowledgement', () => {+ const sampler = world.registerRemovedReaderFrom(Marker, 0);+ const reader = defineSystem([Removed(Marker)], rows => { rows.toArray(); });+ runner.run(reader);+ const entity = removeOne();+ runner.run(reader);+ expect(world.getRemovedEntitiesSince(Marker, -1)).toEqual([entity]);+ world.advanceRemovedReader(Marker, sampler, 0);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ world.disposeRemovedReader(Marker, sampler);+ });+ it('preserves a paused reader while a fast one catches up repeatedly', () => {+ const fastBatches: Entity[][] = [], slowBatches: Entity[][] = [];+ const fast = defineSystem([Removed(Marker)], rows => { fastBatches.push(rows.toArray()); });+ const slow = defineSystem([Removed(Marker)], rows => { slowBatches.push(rows.toArray()); });+ runner.run(fast);+ runner.run(slow);+ const victims = Array.from({ length: 4096 }, removeOne);+ runner.run(fast);+ for (let i = 0; i < 50; i++) runner.run(fast);+ expect(fastBatches[1]).toEqual(victims);+ expect(fastBatches.slice(2).every(batch => batch.length === 0)).toBe(true);+ expect(world.getStorageSizes().changes.removedRows).toBe(victims.length);+ runner.run(slow);+ expect(slowBatches).toEqual([[], victims]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ runner.reset();+ expect(world.removedReaderCount(Marker)).toBe(0);+ });+ it('can read rows produced during an await without releasing another readers claim', async () => {+ const batches: Entity[][] = [];+ let armed = false;+ let victim: Entity | undefined;+ const reader = defineSystem([Removed(Marker)], async rows => {+ if (armed) await Promise.resolve().then(() => { victim = removeOne(); });+ batches.push(rows.toArray());+ });+ await runner.run(reader);+ armed = true;+ await runner.run(reader);+ expect(batches).toEqual([[], [victim]]);+ expect(world.getStorageSizes().changes.removedRows).toBe(0);+ });+});diff --git a/sdk/tests/system.test.ts b/sdk/tests/system.test.tsindex c05481de0..ec849d28d 100644--- a/sdk/tests/system.test.ts+++ b/sdk/tests/system.test.ts@@ -67,6 +67,10 @@ function createMockWorld() {// nothing would let a change to that order pass unnoticed here.registerRemovedReader: vi.fn(() => 1),advanceRemovedReader: vi.fn(),+ registerRemovedCursorReader: vi.fn(() => 1),+ getRemovalSequence: vi.fn(() => 0),+ getRemovedEntitiesForReader: vi.fn(() => []),+ advanceRemovedCursorReader: vi.fn(),disposeRemovedReader: vi.fn(),resolveGetter: vi.fn(() => null),};diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 47fc41384..8405501da 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(ecs): retain same-frame removals with sequence cursors':+ { note: 'Removal queries retain events across system runs in the same frame.' },'fix(test): classify versioned navigation in the release corpus':{ internal: 'Connects the finalized navigation replacement feature note to the existing navigation certification capability and its courtyard project; no new acceptance claim is made.' },'fix(ui): reset visibility baselines for recreated components':