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.

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.md
index 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: number
attachConnection: (transport: ReliableOrderedTransport) => number
beginTick: (fixedDelta: number) => void
clientIds: 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) => void
despawn: (entity: Entity) => void
entityCount: () => number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
attachConnection: (transport: ReliableOrderedTransport) => number
beginTick: (fixedDelta: number) => void
clientIds: 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) => void
despawn: (entity: Entity) => void
entityCount: () => number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
attachConnection: (transport: ReliableOrderedTransport) => number
beginTick: (fixedDelta: number) => void
clientIds: 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) => void
despawn: (entity: Entity) => void
entityCount: () => number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
attachConnection: (transport: ReliableOrderedTransport) => number
beginTick: (fixedDelta: number) => void
clientIds: 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) => void
despawn: (entity: Entity) => void
entityCount: () => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
attachConnection: (transport: ReliableOrderedTransport) => number
beginTick: (fixedDelta: number) => void
clientIds: 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) => void
despawn: (entity: Entity) => void
entityCount: () => number
diff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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]);
+ });
+});