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
feat(net): the replication registry runs on candidates, not on a full scan
esengineec57577e8e63
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 04524a2eb..7123fa913 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6533,6 +6533,7 @@ static prototype: ReplicationPlugin## ReplicationServer — class @experimental```+@internal fullScans: numberattachConnection: (transport: ReliableOrderedTransport) => numberbeginTick: (fixedDelta: number) => voidclientIds: number[]@@ -9495,6 +9496,7 @@ tabIndex: number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void+@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean@internal applyEntityOrder: (entities: readonly Entity[]) => void@internal beginIteration: () => void@@ -9503,12 +9505,14 @@ tabIndex: number | undefined@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void+@internal disposeTopologyReader: (component: AnyComponentDef, readerId: number) => void@internal enableChangeTracking: (component: AnyComponentDef) => void@internal endIteration: () => void@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats@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[]@internal getWasmModule: () => ESEngineModule | null@internal getWorldTick: () => number@internal getWorldVersion: () => number@@ -9524,6 +9528,7 @@ tabIndex: number | undefined@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 registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@@ -9536,6 +9541,7 @@ tabIndex: number | undefined@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number+@internal topologyReaderCount: (component: AnyComponentDef) => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddespawn: (entity: Entity) => voidentityCount: () => numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 42099df87..8cdcafc01 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6726,6 +6726,7 @@ static prototype: ReplicationPlugin## ReplicationServer — class @experimental```+@internal fullScans: numberattachConnection: (transport: ReliableOrderedTransport) => numberbeginTick: (fixedDelta: number) => voidclientIds: number[]@@ -9688,6 +9689,7 @@ tabIndex: number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void+@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean@internal applyEntityOrder: (entities: readonly Entity[]) => void@internal beginIteration: () => void@@ -9696,12 +9698,14 @@ tabIndex: number | undefined@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void+@internal disposeTopologyReader: (component: AnyComponentDef, readerId: number) => void@internal enableChangeTracking: (component: AnyComponentDef) => void@internal endIteration: () => void@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats@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[]@internal getWasmModule: () => ESEngineModule | null@internal getWorldTick: () => number@internal getWorldVersion: () => number@@ -9717,6 +9721,7 @@ tabIndex: number | undefined@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 registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@@ -9729,6 +9734,7 @@ tabIndex: number | undefined@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number+@internal topologyReaderCount: (component: AnyComponentDef) => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddespawn: (entity: Entity) => voidentityCount: () => numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 55d54e423..83ba211d9 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6528,6 +6528,7 @@ static prototype: ReplicationPlugin## ReplicationServer — class @experimental```+@internal fullScans: numberattachConnection: (transport: ReliableOrderedTransport) => numberbeginTick: (fixedDelta: number) => voidclientIds: number[]@@ -9490,6 +9491,7 @@ tabIndex: number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void+@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean@internal applyEntityOrder: (entities: readonly Entity[]) => void@internal beginIteration: () => void@@ -9498,12 +9500,14 @@ tabIndex: number | undefined@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void+@internal disposeTopologyReader: (component: AnyComponentDef, readerId: number) => void@internal enableChangeTracking: (component: AnyComponentDef) => void@internal endIteration: () => void@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats@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[]@internal getWasmModule: () => ESEngineModule | null@internal getWorldTick: () => number@internal getWorldVersion: () => number@@ -9519,6 +9523,7 @@ tabIndex: number | undefined@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 registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@@ -9531,6 +9536,7 @@ tabIndex: number | undefined@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number+@internal topologyReaderCount: (component: AnyComponentDef) => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddespawn: (entity: Entity) => voidentityCount: () => numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex b8af69f87..ae3a41c95 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6774,6 +6774,7 @@ static prototype: ReplicationPlugin## ReplicationServer — class @experimental```+@internal fullScans: numberattachConnection: (transport: ReliableOrderedTransport) => numberbeginTick: (fixedDelta: number) => voidclientIds: number[]@@ -9742,6 +9743,7 @@ tabIndex: number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void+@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean@internal applyEntityOrder: (entities: readonly Entity[]) => void@internal beginIteration: () => void@@ -9750,12 +9752,14 @@ tabIndex: number | undefined@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void+@internal disposeTopologyReader: (component: AnyComponentDef, readerId: number) => void@internal enableChangeTracking: (component: AnyComponentDef) => void@internal endIteration: () => void@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats@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[]@internal getWasmModule: () => ESEngineModule | null@internal getWorldTick: () => number@internal getWorldVersion: () => number@@ -9771,6 +9775,7 @@ tabIndex: number | undefined@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 registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@@ -9783,6 +9788,7 @@ tabIndex: number | undefined@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number+@internal topologyReaderCount: (component: AnyComponentDef) => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddespawn: (entity: Entity) => voidentityCount: () => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 00f182a53..09794b7b5 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6535,6 +6535,7 @@ static prototype: ReplicationPlugin## ReplicationServer — class @experimental```+@internal fullScans: numberattachConnection: (transport: ReliableOrderedTransport) => numberbeginTick: (fixedDelta: number) => voidclientIds: number[]@@ -9518,6 +9519,7 @@ tabIndex: number | undefined@internal addressResolver: (component: AnyComponentDef) => (entity: Entity) => number | undefined@internal advanceRemovedReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal advanceTick: () => void+@internal advanceTopologyReader: (component: AnyComponentDef, readerId: number, lastRunTick: number) => void@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean@internal applyEntityOrder: (entities: readonly Entity[]) => void@internal beginIteration: () => void@@ -9526,12 +9528,14 @@ tabIndex: number | undefined@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void+@internal disposeTopologyReader: (component: AnyComponentDef, readerId: number) => void@internal enableChangeTracking: (component: AnyComponentDef) => void@internal endIteration: () => void@internal getCppRegistry: () => CppRegistry | null@internal getQueryCacheStats: () => QueryCacheStats@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[]@internal getWasmModule: () => ESEngineModule | null@internal getWorldTick: () => number@internal getWorldVersion: () => number@@ -9547,6 +9551,7 @@ tabIndex: number | undefined@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 registerTopologyReaderFrom: (component: AnyComponentDef, retainFromTick: number) => number@internal removedReaderCount: (component: AnyComponentDef) => number@internal resetIterationDepth: () => void@internal resetQueryCacheStats: () => void@@ -9559,6 +9564,7 @@ tabIndex: number | undefined@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal suspendIteration: () => number+@internal topologyReaderCount: (component: AnyComponentDef) => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddespawn: (entity: Entity) => voidentityCount: () => numberdiff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex afd41ae3a..05bec25fb 100644--- a/sdk/src/ecs/ChangeTracker.ts+++ b/sdk/src/ecs/ChangeTracker.ts@@ -8,19 +8,102 @@import { Entity } from '../types';import { AnyComponentDef } from './component';+/**+ * Per-component history with per-component retention: rows exist only while a+ * reader holds the component, pruned to the LOWEST claim on it. Two of these+ * exist — removal history and membership topology — because a consumer of one+ * must not keep the other alive; the ownership rule is written once.+ */+class ReaderOwnedJournal {+ private rows_ = new Map<symbol, Array<{ entity: Entity; tick: number }>>();+ private readers_ = new Map<symbol, Map<number, number>>();++ hasReaders(componentId: symbol): boolean {+ return this.readers_.has(componentId);+ }++ record(componentId: symbol, entity: Entity, tick: number): void {+ let buffer = this.rows_.get(componentId);+ if (!buffer) {+ buffer = [];+ this.rows_.set(componentId, buffer);+ }+ buffer.push({ entity, tick });+ }++ /** Rows after `sinceTick`, in the order they happened. May repeat an entity. */+ since(componentId: symbol, sinceTick: number): Entity[] {+ const buffer = this.rows_.get(componentId);+ if (!buffer) return [];+ const out: Entity[] = [];+ for (const row of buffer) if (row.tick > sinceTick) out.push(row.entity);+ return out;+ }++ register(componentId: symbol, readerId: number, retainFromTick: number): void {+ let readers = this.readers_.get(componentId);+ if (!readers) {+ readers = new Map();+ this.readers_.set(componentId, readers);+ }+ readers.set(readerId, retainFromTick);+ }++ advance(componentId: symbol, readerId: number, lastTick: number): void {+ const readers = this.readers_.get(componentId);+ if (!readers?.has(readerId)) return;+ readers.set(readerId, lastTick + 1);+ this.prune_(componentId);+ }++ dispose(componentId: symbol, readerId: number): void {+ const readers = this.readers_.get(componentId);+ if (!readers) return;+ readers.delete(readerId);+ this.prune_(componentId);+ }++ readerCount(componentId: symbol): number {+ return this.readers_.get(componentId)?.size ?? 0;+ }++ totalRows(): number {+ let n = 0;+ for (const buffer of this.rows_.values()) n += buffer.length;+ return n;+ }++ private prune_(componentId: symbol): void {+ const readers = this.readers_.get(componentId);+ if (!readers || readers.size === 0) {+ this.readers_.delete(componentId);+ 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];+ }+ buffer.length = writeIdx;+ if (writeIdx === 0) this.rows_.delete(componentId);+ }+}+export class ChangeTracker {private worldTick_ = 0;private componentAddedTicks_ = new Map<symbol, Map<Entity, number>>();private componentChangedTicks_ = new Map<symbol, Map<Entity, number>>();- private componentRemovedBuffer_ = new Map<symbol, Array<{ entity: Entity; tick: number }>>();+ private readonly removals_ = new ReaderOwnedJournal();+ /** Membership moves, independent of ordinary change tracking. */+ private readonly topology_ = new ReaderOwnedJournal();private trackedComponents_ = new Set<symbol>();// The most recent worldTick at which ANY entity changed each component — an// O(1) "did anything change since tick T" gate (vs scanning the per-entity map).private componentLastChangedTick_ = new Map<symbol, number>();- // Who still needs removal history, and from which tick. Removal rows are- // produced ONLY for a component in here: `Changed(C)` needs to know the- // topology moved, never which entity lost C at tick 738.- private removedReaders_ = new Map<symbol, Map<number, number>>();private nextReaderId_ = 1;advanceTick(): void {@@ -56,15 +139,35 @@ export class ChangeTracker {}getRemovedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {- const buffer = this.componentRemovedBuffer_.get(component._id);- if (!buffer) return [];- const result: Entity[] = [];- for (const entry of buffer) {- if (entry.tick > sinceTick) {- result.push(entry.entity);- }- }- return result;+ return this.removals_.since(component._id, sinceTick);+ }++ /**+ * Entities whose MEMBERSHIP in `component` moved after `sinceTick` — gained+ * or lost, and deliberately not saying which. A consumer re-reads the world+ * to find out; this only says who is worth re-reading.+ */+ getTopologyChangedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {+ return this.topology_.since(component._id, sinceTick);+ }++ registerTopologyReaderFrom(component: AnyComponentDef, retainFromTick: number): number {+ const id = this.nextReaderId_++;+ this.topology_.register(component._id, id, retainFromTick);+ return id;+ }++ advanceTopologyReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {+ this.topology_.advance(component._id, readerId, lastRunTick);+ }++ disposeTopologyReader(component: AnyComponentDef, readerId: number): void {+ this.topology_.dispose(component._id, readerId);+ }++ /** @internal How many readers hold `component`'s membership journal. */+ topologyReaderCount(component: AnyComponentDef): number {+ return this.topology_.readerCount(component._id);}/**@@ -83,13 +186,8 @@ export class ChangeTracker {* 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, retainFromTick);+ this.removals_.register(component._id, id, retainFromTick);return id;}@@ -99,52 +197,28 @@ export class ChangeTracker {* `tick > lastRunTick`, which is why the claim is the tick after.*/advanceRemovedReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {- const readers = this.removedReaders_.get(component._id);- if (!readers?.has(readerId)) return;- readers.set(readerId, lastRunTick + 1);- this.pruneRemoved_(component._id);+ this.removals_.advance(component._id, readerId, lastRunTick);}/** Give up the claim, and let the watermark move at once — history with no* owner is not history anyone can ask for. */disposeRemovedReader(component: AnyComponentDef, readerId: number): void {- const readers = this.removedReaders_.get(component._id);- if (!readers) return;- readers.delete(readerId);- this.pruneRemoved_(component._id);+ this.removals_.dispose(component._id, readerId);}/** @internal How many readers hold `component`'s history — for the fixtures* that assert a disposed reader stopped pinning it. */removedReaderCount(component: AnyComponentDef): number {- return this.removedReaders_.get(component._id)?.size ?? 0;- }-- /**- * Drop what no reader of THIS component can still ask for. Per component,- * never global: a slow reader of one component has no business pinning- * another's history.- */- private pruneRemoved_(componentId: symbol): void {- const readers = this.removedReaders_.get(componentId);- if (!readers || readers.size === 0) {- this.removedReaders_.delete(componentId);- this.componentRemovedBuffer_.delete(componentId);- return;- }- const buffer = this.componentRemovedBuffer_.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];- }- buffer.length = writeIdx;- if (writeIdx === 0) this.componentRemovedBuffer_.delete(componentId);+ return this.removals_.readerCount(component._id);}recordAdded(component: AnyComponentDef, entity: Entity): void {+ // BEFORE the tracking gate: a membership journal is what lets a consumer+ // follow arrivals and departures WITHOUT enrolling the component in+ // ordinary change tracking, and paying that tax on every field write.+ if (this.topology_.hasReaders(component._id)) {+ this.topology_.record(component._id, entity, this.worldTick_);+ }if (!this.trackedComponents_.has(component._id)) return;let map = this.componentAddedTicks_.get(component._id);if (!map) {@@ -185,16 +259,15 @@ export class ChangeTracker {* recorded for one kind and dropped for the other.*/recordRemovedById(componentId: symbol, entity: Entity): void {+ // Same reason as `recordAdded`: first, and gated on its own readers.+ if (this.topology_.hasReaders(componentId)) {+ this.topology_.record(componentId, entity, this.worldTick_);+ }// A row is stored only for a component someone reads history of. With// `Changed(C)` alone this is the whole difference between a buffer that// grows with every despawn for the life of the world, and none at all.- if (this.removedReaders_.has(componentId)) {- let buffer = this.componentRemovedBuffer_.get(componentId);- if (!buffer) {- buffer = [];- this.componentRemovedBuffer_.set(componentId, buffer);- }- buffer.push({ entity, tick: this.worldTick_ });+ if (this.removals_.hasReaders(componentId)) {+ this.removals_.record(componentId, entity, this.worldTick_);}if (!this.trackedComponents_.has(componentId)) return;this.componentAddedTicks_.get(componentId)?.delete(entity);@@ -220,8 +293,7 @@ export class ChangeTracker {for (const m of maps.values()) n += m.size;return n;};- let removedRows = 0;- for (const buffer of this.componentRemovedBuffer_.values()) removedRows += buffer.length;+ const removedRows = this.removals_.totalRows();return {tracked: this.trackedComponents_.size,addedRows: rowsIn(this.componentAddedTicks_),diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 6f3de4dff..2d49a3cd6 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1223,6 +1223,32 @@ export class World {return this.changes_.removedReaderCount(component);}+ /** @internal A claim on `component`'s MEMBERSHIP journal — who gained or+ * lost it — independent of ordinary change tracking. */+ registerTopologyReaderFrom(component: AnyComponentDef, retainFromTick: number): number {+ return this.changes_.registerTopologyReaderFrom(component, retainFromTick);+ }++ /** @internal Entities worth re-reading because their membership moved. */+ getTopologyChangedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {+ return this.changes_.getTopologyChangedEntitiesSince(component, sinceTick);+ }++ /** @internal That reader is done with everything up to `lastRunTick`. */+ advanceTopologyReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {+ this.changes_.advanceTopologyReader(component, readerId, lastRunTick);+ }++ /** @internal The reader is gone; its share of the watermark goes with it. */+ disposeTopologyReader(component: AnyComponentDef, readerId: number): void {+ this.changes_.disposeTopologyReader(component, readerId);+ }++ /** @internal How many readers hold `component`'s membership journal. */+ topologyReaderCount(component: AnyComponentDef): number {+ return this.changes_.topologyReaderCount(component);+ }+/** @internal Mark component as changed without writing data (for in-place Mut query) */markChanged(entity: Entity, component: AnyComponentDef): void {this.changes_.recordChanged(component, entity);diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.tsindex 502e9c05d..57e030da6 100644--- a/sdk/src/net/replication/server.ts+++ b/sdk/src/net/replication/server.ts@@ -140,6 +140,15 @@ export class ReplicationServer {private changeFloor_ = -1;private readonly offDespawn_: () => void;private disposed_ = false;+ /**+ * The registry's own window and claim. Separate from `changeFloor_` on+ * purpose: field observation installs with the LAZY table, this one watches+ * the fixed `Replicated` marker and lives as long as the server does.+ */+ private registryFloor_: number;+ private readonly registryReader_: number;+ /** @internal Full-world reconciliations run — a steady-state sample must do none. */+ fullScans = 0;constructor(world: World) {this.world_ = world;@@ -147,6 +156,8 @@ export class ReplicationServer {// Sampling handles replicated despawns; this catches direct holes.this.netIds_.unregisterEntity(e);});+ this.registryFloor_ = world.getWorldTick() - 1;+ this.registryReader_ = world.registerTopologyReaderFrom(Replicated, this.registryFloor_ + 1);}/** Lazily built so components defined after plugin install still count. */@@ -186,6 +197,14 @@ export class ReplicationServer {this.changeFloor_ = nextFloor;}+ /** The registry's window, closed the same way and at the same moment. Two+ * functions rather than one: the two lifecycles have already diverged once. */+ private advanceRegistryFloor_(): void {+ const nextFloor = this.world_.getWorldTick() - 1;+ this.world_.advanceTopologyReader(Replicated, this.registryReader_, nextFloor);+ this.registryFloor_ = nextFloor;+ }+/*** Give back everything this server holds outside itself: its channels, its* claims on removal history, and its despawn subscription. Idempotent — the@@ -198,6 +217,7 @@ export class ReplicationServer {for (const id of [...this.connections_.keys()]) this.detachConnection(id);for (const o of this.observations_) this.world_.disposeRemovedReader(o.def, o.readerId);this.observations_.length = 0;+ this.world_.disposeTopologyReader(Replicated, this.registryReader_);this.offDespawn_();}@@ -344,12 +364,13 @@ export class ReplicationServer {this.tick_ = tick;if (this.connections_.size === 0) {// No world scan, but the claims still move: a reader parked on an old- // floor pins removal history for as long as the server runs empty.+ // floor pins history for as long as the server runs empty.this.advanceObservationFloor_();+ this.advanceRegistryFloor_();return;}- const { spawnedEntities, despawned } = this.reconcileRegistry_();+ const { spawnedEntities, despawned } = this.reconcileRegistryIncremental_();// Diff once against the shadow; frames below share the result.const sample = this.collectDirty_();@@ -368,8 +389,9 @@ export class ReplicationServer {this.sendTo_(conn, (c) => c.channel.send<ReplAckMsg>(ReplMsg.ack, { tick, seq: conn.ackedSeq }));}- // Last: the window is given up only once its rows are on the wire.+ // Last: the windows are given up only once their rows are on the wire.this.advanceObservationFloor_();+ this.advanceRegistryFloor_();}/** Fast path (no policy): everything to every ready connection on shared@@ -507,14 +529,16 @@ export class ReplicationServer {}/**- * Bring the registry level with the world, and say what moved. netIds are- * captured before unregistering so a per-connection despawn can still name- * an entity that vanished this tick.+ * The registry rebuilt against the whole world — a baseline, not a steady+ * state. A reconciliation, not a reconstruction: entities still present keep+ * the netId the clients hold. netIds are captured before unregistering so a+ * per-connection despawn can still name what vanished this tick.*/- private reconcileRegistry_(): {+ private reconcileRegistryFromWorld_(): {spawnedEntities: Entity[];despawned: { entity: Entity; netId: number }[];} {+ this.fullScans++;const current = this.world_.getEntitiesWithComponents([Replicated]);const currentSet = new Set(current);@@ -544,6 +568,43 @@ export class ReplicationServer {return { spawnedEntities, despawned };}+ /**+ * Which entities entered or left replication. Topology history SELECTS+ * candidates; `known × current world` DECIDES: added-and-removed before the+ * sample is one candidate that is neither known nor live, removed-and-re-added+ * is one that is both, and the clients hear about neither.+ */+ private reconcileRegistryIncremental_(): {+ spawnedEntities: Entity[];+ despawned: { entity: Entity; netId: number }[];+ } {+ const spawnedEntities: Entity[] = [];+ const despawned: { entity: Entity; netId: number }[] = [];+ const candidates = new Set(+ this.world_.getTopologyChangedEntitiesSince(Replicated, this.registryFloor_),+ );+ for (const e of candidates) {+ const isKnown = this.known_.has(e);+ const isLive = this.world_.valid(e) && this.world_.has(e, Replicated);+ if (!isKnown && isLive) {+ this.registerEntity_(e);+ spawnedEntities.push(e);+ } else if (isKnown && !isLive) {+ const netId = this.knownNetIds_.get(e);+ if (netId !== undefined) {+ despawned.push({ entity: e, netId });+ this.netIds_.unregister(netId);+ }+ this.known_.delete(e);+ this.knownNetIds_.delete(e);+ this.shadow_.delete(e);+ } else if (isKnown && isLive) {+ this.restoreNetId_(e);+ }+ }+ return { spawnedEntities, despawned };+ }+/*** The registry, rebuilt from the world for a client arriving when nothing is* ready. `sample` returns early with no connections, so the registry stops@@ -551,10 +612,11 @@ export class ReplicationServer {* re-seeded so the frame after does not re-send what the spawn carried.*/private rebaseRegistry_(): void {- this.reconcileRegistry_();+ this.reconcileRegistryFromWorld_();for (const e of this.known_) this.seedShadow_(e);- // The shadow is now the world, so the observation window starts here too.+ // The shadow is now the world, so both windows start here too.this.advanceObservationFloor_();+ this.advanceRegistryFloor_();}/**diff --git a/sdk/tests/replication-candidate.test.ts b/sdk/tests/replication-candidate.test.tsindex 9330bbbfa..ad7bdc666 100644--- a/sdk/tests/replication-candidate.test.ts+++ b/sdk/tests/replication-candidate.test.ts@@ -284,3 +284,112 @@ describe('the server owns what it registered', () => {expect(serverApp.world.getStorageSizes().changes.removedRows).toBeLessThan(10);});});++describe('the registry runs on candidates too', () => {+ it('gives back its membership claim on dispose', () => {+ const app = makeApp();+ const net = app.getResource(Net);+ const world = app.world;+ const before = world.topologyReaderCount(Replicated);++ net.startServer();+ expect(world.topologyReaderCount(Replicated)).toBe(before + 1);++ net.stop();+ expect(world.topologyReaderCount(Replicated)).toBe(before);++ net.startServer();+ net.stop();+ net.stop();+ expect(world.topologyReaderCount(Replicated)).toBe(before);+ });++ it('does no full world scan in a steady-state sample', async () => {+ const { serverApp, server, step } = await connected();+ spawn(serverApp, 1);+ await step();++ // The baseline is behind us; from here the registry must run on the+ // membership journal alone. A helper that "just checks" with a full scan+ // is what this counts, whatever it is called.+ const baseline = server.fullScans;+ await step(5);+ expect(server.fullScans).toBe(baseline);+ });++ it('does exactly one when a client arrives to a quiet server', async () => {+ const { serverApp, server, step } = await connected();+ spawn(serverApp, 1);+ await step();+ for (let id = 0; id < 8; id++) server.detachConnection(id);+ const before = server.fullScans;++ const [sb, cb] = MemoryTransport.pair();+ server.attachConnection(sb);+ const appB = makeApp();+ await appB.getResource(Net).connect(cb, { interpolationDelayTicks: 0 });++ expect(server.fullScans).toBe(before + 1);+ });++ it('handles an entity slot reused by a new generation', async () => {+ const { serverApp, server, clientApp, step } = await connected();+ const world = serverApp.world;+ const old = spawn(serverApp, 1);+ await step();+ const oldNetId = server.netIds.netIdOf(old);+ expect(oldNetId).toBeGreaterThan(0);++ world.despawn(old);+ // Same slot, new generation: two DIFFERENT candidates in one window.+ const fresh = spawn(serverApp, 2);+ expect(fresh).not.toBe(old);+ expect(world.valid(old)).toBe(false);+ expect(world.valid(fresh)).toBe(true);++ await step(2);++ expect(server.netIds.entityOf(oldNetId!)).toBeUndefined();+ const freshNetId = server.netIds.netIdOf(fresh);+ expect(freshNetId).toBeGreaterThan(0);+ expect(freshNetId).not.toBe(oldNetId);+ expect(clientApp.world.getEntitiesWithComponents([Replicated]).length).toBe(1);+ });++ it('reconciles the registry BEFORE collecting fields, on the way out', async () => {+ const { serverApp, seen, step } = await connected();+ const world = serverApp.world;+ const e = spawn(serverApp, 1);+ world.insert(e, Tag, { v: 7 });+ await step();+ seen.sent.length = 0;++ // The registry drops the entity first, so the field pass never sees a+ // shadow to reconcile. The other order emits a componentRemove for an+ // entity the client is about to be told no longer exists.+ world.despawn(e);+ await step(2);++ expect(removes(seen.sent)).toBe(0);+ });++ it('reconciles the registry BEFORE collecting fields, on the way in', async () => {+ const { serverApp, clientApp, seen, step } = await connected();+ const world = serverApp.world;+ await step();+ seen.sent.length = 0;++ // Arrives and is written in the same window: the spawn payload carries+ // the current value, so the field pass must find nothing left to send.+ const e = world.spawn();+ world.insert(e, Replicated, { owner: 0 });+ world.insert(e, NetPos, { x: 5, y: 0, z: 0 });+ world.set(e, NetPos, { x: 6, y: 0, z: 0 });+ await step();++ expect(deltas(seen.sent)).toBe(0);+ const xs = clientApp.world.getEntitiesWithComponents([Replicated])+ .map((g) => (clientApp.world.tryGet(g, NetPos) as { x: number } | null)?.x);+ expect(xs).toContain(6);+ });+});diff --git a/sdk/tests/topology-journal.test.ts b/sdk/tests/topology-journal.test.tsnew file mode 100644index 000000000..2edeb9c09--- /dev/null+++ b/sdk/tests/topology-journal.test.ts@@ -0,0 +1,127 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The membership journal: who gained or lost a component, and who owns+ * that history.+ *+ * Separate from change tracking on purpose. A consumer that follows arrivals and+ * departures should not have to enrol the component in `Changed` tracking and+ * pay that tax on every field write — which is the whole reason this exists+ * rather than `Added()` plus `Removed()`.+ */+import { describe, it, expect } from 'vitest';+import { World } from '../src/ecs/world';+import { defineComponent } from '../src/ecs/component';++const Mark = defineComponent('TjMark', { v: 0 });+const Other = defineComponent('TjOther', { v: 0 });++describe('membership journal', () => {+ it('records arrivals and departures without ordinary change tracking', () => {+ const world = new World();+ world.advanceTick();+ const floor = world.getWorldTick() - 1;+ world.registerTopologyReaderFrom(Mark, floor + 1);++ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });+ world.remove(e, Mark);++ expect(world.getTopologyChangedEntitiesSince(Mark, floor)).toEqual([e, e]);+ // The value path was never enrolled, so it costs nothing and says nothing.+ expect(world.isChangedSince(e, Mark, floor)).toBe(false);+ });++ it('writes nothing for a component nobody watches', () => {+ const world = new World();+ world.advanceTick();+ const floor = world.getWorldTick() - 1;+ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });+ world.remove(e, Mark);++ expect(world.getTopologyChangedEntitiesSince(Mark, floor)).toEqual([]);+ });++ it('does not record an ordinary field write', () => {+ const world = new World();+ world.advanceTick();+ const floor = world.getWorldTick() - 1;+ world.registerTopologyReaderFrom(Mark, floor + 1);+ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });++ world.update(e, Mark, (d) => { d.v = 2; });+ world.set(e, Mark, { v: 3 });++ // One row: the insert. Membership did not move again.+ expect(world.getTopologyChangedEntitiesSince(Mark, floor)).toEqual([e]);+ });++ it('holds history to the lowest claim on that component', () => {+ const world = new World();+ world.advanceTick();+ const early = world.getWorldTick() - 1;+ const slow = world.registerTopologyReaderFrom(Mark, early + 1);+ const fast = world.registerTopologyReaderFrom(Mark, early + 1);++ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });+ const at = world.getWorldTick();++ // The fast one is done; the slow one has not read, so the row stays.+ world.advanceTopologyReader(Mark, fast, at);+ expect(world.getTopologyChangedEntitiesSince(Mark, early)).toEqual([e]);++ world.advanceTopologyReader(Mark, slow, at);+ expect(world.getTopologyChangedEntitiesSince(Mark, early)).toEqual([]);+ });++ it('lets go at once when the slow reader is disposed', () => {+ const world = new World();+ world.advanceTick();+ const early = world.getWorldTick() - 1;+ const slow = world.registerTopologyReaderFrom(Mark, early + 1);+ const fast = world.registerTopologyReaderFrom(Mark, early + 1);++ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });+ world.advanceTopologyReader(Mark, fast, world.getWorldTick());+ expect(world.getTopologyChangedEntitiesSince(Mark, early)).toEqual([e]);++ world.disposeTopologyReader(Mark, slow);+ expect(world.getTopologyChangedEntitiesSince(Mark, early)).toEqual([]);+ expect(world.topologyReaderCount(Mark)).toBe(1);+ });++ it('a slow reader of one component does not pin another', () => {+ const world = new World();+ world.advanceTick();+ const early = world.getWorldTick() - 1;+ const fast = world.registerTopologyReaderFrom(Mark, early + 1);+ world.registerTopologyReaderFrom(Other, early + 1);++ const a = world.spawn();+ world.insert(a, Mark, { v: 1 });+ const b = world.spawn();+ world.insert(b, Other, { v: 1 });++ world.advanceTopologyReader(Mark, fast, world.getWorldTick());++ // A single global watermark would hold Mark's row for Other's sake.+ expect(world.getTopologyChangedEntitiesSince(Mark, early)).toEqual([]);+ expect(world.getTopologyChangedEntitiesSince(Other, early)).toEqual([b]);+ });++ it('records a despawn as a departure', () => {+ const world = new World();+ world.advanceTick();+ const floor = world.getWorldTick() - 1;+ world.registerTopologyReaderFrom(Mark, floor + 1);+ const e = world.spawn();+ world.insert(e, Mark, { v: 1 });+ world.despawn(e);++ expect(world.getTopologyChangedEntitiesSince(Mark, floor)).toEqual([e, e]);+ });+});