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.

perf(net): what changed is a list, not a question asked of everyone

esengine8455ec5f1faf
diff --git a/bench/sample-budget/README.md b/bench/sample-budget/README.md
index 3e391bef0..a13ed6d4d 100644
--- a/bench/sample-budget/README.md
+++ b/bench/sample-budget/README.md
@@ -94,6 +94,31 @@ Whether either is worth fixing. This is a budget, not a plan: `dirty discovery`
the biggest item at realistic movement and `spawn payload` the biggest when views
churn, and which of those a game is actually shaped like decides the order.
+## Acted on: dirty discovery now takes the cheaper projection
+
+The scan is gone as the only option. A replicated component belongs to the whole
+world, so the write journal lists everything written to it — including entities
+this server does not replicate — while the scan asks each known entity and costs
+the population however few moved. Neither dominates, so the pass picks per
+sample, on the same `U >= S` shape the router uses: buffered rows bound what the
+journal would return, in O(1), so neither side is materialized to choose.
+
+Measured **ABA-interleaved**, three rounds, because the machine drifted 20% over
+the session and a straight before/after had already produced one 45,814 µs
+reading of code that runs at 22,627:
+
+| | dirty discovery | sample total |
+|---|---|---|
+| movement | 4,772 → **1,828** (2.6x) | 12,269 → **8,674** (−29%) |
+| mixed | 8,028 → **2,866** (2.8x) | 27,955 → **22,627** (−19%) |
+
+Every interleaved pair had the new side lower. What is left in the phase is the
+work rather than the search: a `tryGet` and a field-by-field compare against the
+shadow for each candidate that really did change.
+
+`bench/sample-budget` reports `journalReads` and `populationScans` so a claim
+about either projection can say which one it got.
+
## What this does not cover
- One anchor per connection, a uniform grid world, and clients connected but not
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 7e9a13686..df5e46ccc 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -6649,6 +6649,7 @@ static prototype: ReplicationPlugin
```
@internal entersSent: number
@internal fullScans: number
+@internal journalReads: number
@internal ownerScanVisits: number
@internal payloadsBuilt: number
@internal profileSample: boolean
@@ -6664,6 +6665,7 @@ dispose: () => void
inputOf: (connectionId: number) => ReplInputMsg | null
leavesSent: number
netIds: NetIds
+populationScans: number
sample: (tick: number) => void
setInterestPolicy: (policy: InterestPolicy | null) => void
setInterestProvider: (provider: InterestProvider | null) => void
@@ -9695,6 +9697,7 @@ tabIndex: number | undefined
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@internal beginIteration: () => void
+@internal bufferedWriteRows: (component: AnyComponentDef) => number
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal compositionChanges: () => CompositionDelta | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8f95607a0..a4ad8274d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -6842,6 +6842,7 @@ static prototype: ReplicationPlugin
```
@internal entersSent: number
@internal fullScans: number
+@internal journalReads: number
@internal ownerScanVisits: number
@internal payloadsBuilt: number
@internal profileSample: boolean
@@ -6857,6 +6858,7 @@ dispose: () => void
inputOf: (connectionId: number) => ReplInputMsg | null
leavesSent: number
netIds: NetIds
+populationScans: number
sample: (tick: number) => void
setInterestPolicy: (policy: InterestPolicy | null) => void
setInterestProvider: (provider: InterestProvider | null) => void
@@ -9888,6 +9890,7 @@ tabIndex: number | undefined
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@internal beginIteration: () => void
+@internal bufferedWriteRows: (component: AnyComponentDef) => number
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal compositionChanges: () => CompositionDelta | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 86ce7d58c..17c926bcf 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -6644,6 +6644,7 @@ static prototype: ReplicationPlugin
```
@internal entersSent: number
@internal fullScans: number
+@internal journalReads: number
@internal ownerScanVisits: number
@internal payloadsBuilt: number
@internal profileSample: boolean
@@ -6659,6 +6660,7 @@ dispose: () => void
inputOf: (connectionId: number) => ReplInputMsg | null
leavesSent: number
netIds: NetIds
+populationScans: number
sample: (tick: number) => void
setInterestPolicy: (policy: InterestPolicy | null) => void
setInterestProvider: (provider: InterestProvider | null) => void
@@ -9690,6 +9692,7 @@ tabIndex: number | undefined
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@internal beginIteration: () => void
+@internal bufferedWriteRows: (component: AnyComponentDef) => number
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal compositionChanges: () => CompositionDelta | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 432a9d639..178dd658d 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6890,6 +6890,7 @@ static prototype: ReplicationPlugin
```
@internal entersSent: number
@internal fullScans: number
+@internal journalReads: number
@internal ownerScanVisits: number
@internal payloadsBuilt: number
@internal profileSample: boolean
@@ -6905,6 +6906,7 @@ dispose: () => void
inputOf: (connectionId: number) => ReplInputMsg | null
leavesSent: number
netIds: NetIds
+populationScans: number
sample: (tick: number) => void
setInterestPolicy: (policy: InterestPolicy | null) => void
setInterestProvider: (provider: InterestProvider | null) => void
@@ -9942,6 +9944,7 @@ tabIndex: number | undefined
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@internal beginIteration: () => void
+@internal bufferedWriteRows: (component: AnyComponentDef) => number
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal compositionChanges: () => CompositionDelta | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f3b8fcaf8..270e0b31d 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -6651,6 +6651,7 @@ static prototype: ReplicationPlugin
```
@internal entersSent: number
@internal fullScans: number
+@internal journalReads: number
@internal ownerScanVisits: number
@internal payloadsBuilt: number
@internal profileSample: boolean
@@ -6666,6 +6667,7 @@ dispose: () => void
inputOf: (connectionId: number) => ReplInputMsg | null
leavesSent: number
netIds: NetIds
+populationScans: number
sample: (tick: number) => void
setInterestPolicy: (policy: InterestPolicy | null) => void
setInterestProvider: (provider: InterestProvider | null) => void
@@ -9718,6 +9720,7 @@ tabIndex: number | undefined
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@internal beginIteration: () => void
+@internal bufferedWriteRows: (component: AnyComponentDef) => number
@internal builtin: BuiltinBridge
@internal changes_: ChangeTracker
@internal compositionChanges: () => CompositionDelta | null
diff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.ts
index 31cc92e3d..21e33edfc 100644
--- a/sdk/src/ecs/ChangeTracker.ts
+++ b/sdk/src/ecs/ChangeTracker.ts
@@ -35,6 +35,13 @@ class ReaderOwnedJournal {
buffer.push({ entity, tick });
}
+ /** How many rows are buffered, at any tick. An UPPER bound on what `since`
+ * would return, in O(1) — enough for a caller choosing between reading this
+ * journal and a scan it can size, without materializing either. */
+ buffered(componentId: symbol): number {
+ return this.rows_.get(componentId)?.length ?? 0;
+ }
+
/** Rows after `sinceTick`, in the order they happened. May repeat an entity. */
since(componentId: symbol, sinceTick: number): Entity[] {
const buffer = this.rows_.get(componentId);
@@ -187,6 +194,10 @@ export class ChangeTracker {
return this.writes_.since(component._id, sinceTick);
}
+ bufferedWriteRows(component: AnyComponentDef): number {
+ return this.writes_.buffered(component._id);
+ }
+
registerWriteReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
const id = this.nextReaderId_++;
this.writes_.register(component._id, id, retainFromTick);
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 8d0596ae3..135f133db 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -1264,6 +1264,12 @@ export class World {
return this.changes_.getWrittenEntitiesSince(component, sinceTick);
}
+ /** @internal An O(1) upper bound on what `getWrittenEntitiesSince` returns,
+ * for a caller choosing between reading the journal and a scan. */
+ bufferedWriteRows(component: AnyComponentDef): number {
+ return this.changes_.bufferedWriteRows(component);
+ }
+
/** @internal That reader is done with everything up to `lastRunTick`. */
advanceWriteReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
this.changes_.advanceWriteReader(component, readerId, lastRunTick);
diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.ts
index 81665300d..4bad2887f 100644
--- a/sdk/src/net/replication/server.ts
+++ b/sdk/src/net/replication/server.ts
@@ -179,7 +179,9 @@ export class ReplicationServer {
private tick_ = 0;
private fixedDelta_ = 0;
/** Removal-history claims, one per replicated component. */
- private readonly observations_: { def: AnyComponentDef; readerId: number }[] = [];
+ private readonly observations_: {
+ def: AnyComponentDef; readerId: number; writeReaderId: number;
+ }[] = [];
/**
* The floor every observation reads from, one tick BEHIND the world.
* `worldTick` moves once per App frame while a frame may run several fixed
@@ -260,6 +262,13 @@ export class ReplicationServer {
}
/** @internal Candidates read to answer "who owns this" — zero once indexed. */
ownerScanVisits = 0;
+ /**
+ * @internal Which projection dirty discovery took, per component per sample.
+ * Both are correct, so a criterion meaning to exercise one of them has to be
+ * able to say which it got.
+ */
+ journalReads = 0;
+ populationScans = 0;
constructor(world: World) {
this.world_ = world;
@@ -291,7 +300,11 @@ export class ReplicationServer {
this.world_.enableChangeTracking(te.def);
// The query is `tick > changeFloor_`, so the claim starts one after.
const readerId = this.world_.registerRemovedReaderFrom(te.def, this.changeFloor_ + 1);
- this.observations_.push({ def: te.def, readerId });
+ // The write journal ENUMERATES what changed where change tracking can
+ // only be asked entity by entity. Both are claimed because neither
+ // dominates: see collectDirty_.
+ const writeReaderId = this.world_.registerWriteReaderFrom(te.def, this.changeFloor_ + 1);
+ this.observations_.push({ def: te.def, readerId, writeReaderId });
}
}
@@ -304,6 +317,7 @@ export class ReplicationServer {
const nextFloor = this.world_.getWorldTick() - 1;
for (const o of this.observations_) {
this.world_.advanceRemovedReader(o.def, o.readerId, nextFloor);
+ this.world_.advanceWriteReader(o.def, o.writeReaderId, nextFloor);
}
this.changeFloor_ = nextFloor;
}
@@ -326,7 +340,10 @@ export class ReplicationServer {
if (this.disposed_) return;
this.disposed_ = true;
for (const id of [...this.connections_.keys()]) this.detachConnection(id);
- for (const o of this.observations_) this.world_.disposeRemovedReader(o.def, o.readerId);
+ for (const o of this.observations_) {
+ this.world_.disposeRemovedReader(o.def, o.readerId);
+ this.world_.disposeWriteReader(o.def, o.writeReaderId);
+ }
this.observations_.length = 0;
this.world_.disposeTopologyReader(Replicated, this.registryReader_);
if (this.ownerReader_ !== null) {
@@ -1179,11 +1196,20 @@ export class ReplicationServer {
const floor = this.changeFloor_;
for (const te of this.table.entries) {
const candidates = new Set<Entity>();
- // O(1) gate first: with nothing changed this component is skipped
- // without walking the population at all.
- if (this.world_.anyChangedSince(te.def, floor)) {
- for (const e of this.known_) {
- if (this.world_.isChangedSince(e, te.def, floor)) candidates.add(e);
+ // The cheaper of two projections, per sample: the journal costs its
+ // rows (the whole world's writes, not this server's), the scan costs
+ // the population however few moved. Buffered rows bound the first.
+ if (this.world_.bufferedWriteRows(te.def) < this.known_.size) {
+ this.journalReads++;
+ for (const e of this.world_.getWrittenEntitiesSince(te.def, floor)) {
+ if (this.known_.has(e)) candidates.add(e);
+ }
+ } else {
+ this.populationScans++;
+ if (this.world_.anyChangedSince(te.def, floor)) {
+ for (const e of this.known_) {
+ if (this.world_.isChangedSince(e, te.def, floor)) candidates.add(e);
+ }
}
}
// A Set, so a component lost twice in one window is one candidate.
diff --git a/sdk/tests/replication-dirty-discovery.test.ts b/sdk/tests/replication-dirty-discovery.test.ts
new file mode 100644
index 000000000..b13f9b0c2
--- /dev/null
+++ b/sdk/tests/replication-dirty-discovery.test.ts
@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Finding what changed, by whichever projection is cheaper.
+ *
+ * A replicated component belongs to the whole world, not to this server: the
+ * write journal lists everything written to it, including entities nobody
+ * replicates, while the scan asks each known entity and costs the population
+ * however few moved. The pass picks per sample, so every claim below has to hold
+ * on BOTH sides of that choice — a delta that only survives one of them is a
+ * silent loss the totals would never show.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { App } from '../src/app/app';
+import { clearUserComponents, defineComponent, Name } from '../src/ecs/component';
+import { MemoryTransport } from '../src/net/MemoryTransport';
+import { replicationPlugin, Net, Replicated } from '../src/net/replication';
+import type { Entity } from '../src/types';
+
+const STEP = 1 / 60;
+let NetPos: ReturnType<typeof defineComponent<{ x: number; y: number; z: number }>>;
+let Health: ReturnType<typeof defineComponent<{ hp: number }>>;
+
+beforeEach(() => {
+ clearUserComponents();
+ NetPos = defineComponent('DiscPos', { x: 0, y: 0, z: 0 }, { replicatedFields: ['x', 'y', 'z'] });
+ Health = defineComponent('DiscHealth', { hp: 0 }, { replicatedFields: ['hp'] });
+});
+
+async function serverWith() {
+ const serverApp = App.new();
+ serverApp.addPlugin(replicationPlugin);
+ const server = serverApp.getResource(Net).startServer();
+ const app = App.new();
+ app.addPlugin(replicationPlugin);
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ await app.getResource(Net).connect(tb, { interpolationDelayTicks: 0 });
+ const step = async (n = 1) => {
+ for (let i = 0; i < n; i++) { await serverApp.tick(STEP); await app.tick(STEP); }
+ };
+ const place = (name: string, x: number): Entity => {
+ const e = serverApp.world.spawn(name);
+ serverApp.world.insert(e, Replicated, { owner: -1 });
+ serverApp.world.insert(e, NetPos, { x, y: 0, z: 0 });
+ return e;
+ };
+ /** Has the component, is not replicated: journal rows this server must skip. */
+ const bystander = (x: number): Entity => {
+ const e = serverApp.world.spawn();
+ serverApp.world.insert(e, NetPos, { x, y: 0, z: 0 });
+ return e;
+ };
+ const ghostX = (name: string): number | undefined => {
+ const e = app.world.getEntitiesWithComponents([Replicated])
+ .find((g) => (app.world.tryGet(g, Name) as { value: string } | null)?.value === name);
+ return e === undefined ? undefined : (app.world.tryGet(e, NetPos) as { x: number } | null)?.x;
+ };
+ return { serverApp, app, server, step, place, bystander, ghostX };
+}
+
+/** Which projection the pass ACTUALLY took, from the server rather than from a
+ * restatement of its rule — the two have to be able to disagree. */
+function projections(server: { journalReads: number; populationScans: number }) {
+ const j = server.journalReads, p = server.populationScans;
+ return { since: () => ({ journal: server.journalReads - j, scan: server.populationScans - p }) };
+}
+
+describe('a change is discovered whichever projection is cheaper', () => {
+ it('delivers the delta when the journal is the smaller side', async () => {
+ const h = await serverWith();
+ const tracked = h.place('tracked', 0);
+ for (let i = 0; i < 20; i++) h.place(`filler${i}`, 100 + i);
+ await h.step(3);
+
+ const took = projections(h.server);
+ h.serverApp.world.update(tracked, NetPos, (d) => { (d as { x: number }).x = 7; });
+ await h.step(2);
+ expect(took.since().journal).toBeGreaterThan(0);
+ expect(h.ghostX('tracked')).toBe(7);
+ });
+
+ it('delivers the delta when bystanders make the journal the bigger side', async () => {
+ const h = await serverWith();
+ const tracked = h.place('tracked', 0);
+ const others = [h.place('other', 1)];
+ const idle: Entity[] = [];
+ for (let i = 0; i < 40; i++) idle.push(h.bystander(500 + i));
+ await h.step(3);
+
+ // Entities this server does not replicate, writing the same component.
+ const took = projections(h.server);
+ for (const e of idle) h.serverApp.world.update(e, NetPos, (d) => { (d as { x: number }).x += 1; });
+ h.serverApp.world.update(tracked, NetPos, (d) => { (d as { x: number }).x = 9; });
+ await h.step(1);
+ expect(took.since().scan).toBeGreaterThan(0);
+ await h.step(2);
+ expect(h.ghostX('tracked')).toBe(9);
+ expect(others).toHaveLength(1);
+ });
+
+ // The `known_` filter this does NOT guard: dropping it leaves the pass
+ // correct, because a bystander has no shadow and is skipped there. It is a
+ // cost bound, and the chooser already caps it below the population.
+ it('never spawns a ghost for an entity it does not replicate', async () => {
+ const h = await serverWith();
+ h.place('tracked', 0);
+ const outsider = h.bystander(3);
+ await h.step(3);
+
+ h.serverApp.world.update(outsider, NetPos, (d) => { (d as { x: number }).x = 99; });
+ await h.step(2);
+ // One ghost, and it is not the bystander's.
+ expect(h.app.world.getEntitiesWithComponents([Replicated])).toHaveLength(1);
+ expect(h.ghostX('tracked')).toBe(0);
+ });
+});
+
+describe('what the journal alone would miss', () => {
+ it('discovers a component ADDED to an entity that is already replicated', async () => {
+ // `insert` records an add AND a write; a pass reading only membership
+ // would see the arrival, and one reading only values would see nothing.
+ const h = await serverWith();
+ const e = h.place('grower', 0);
+ for (let i = 0; i < 20; i++) h.place(`filler${i}`, 100 + i);
+ await h.step(3);
+
+ const took = projections(h.server);
+ h.serverApp.world.insert(e, Health, { hp: 55 });
+ await h.step(3);
+ expect(took.since().journal).toBeGreaterThan(0);
+ const ghost = h.app.world.getEntitiesWithComponents([Replicated])[0]!;
+ expect((h.app.world.tryGet(ghost, Health) as { hp: number } | null)?.hp).toBe(55);
+ });
+
+ it('still reports a component that left, which is not a write at all', async () => {
+ const h = await serverWith();
+ const e = h.place('shrinker', 0);
+ h.serverApp.world.insert(e, Health, { hp: 55 });
+ await h.step(3);
+
+ h.serverApp.world.remove(e, Health);
+ await h.step(3);
+ const ghost = h.app.world.getEntitiesWithComponents([Replicated])[0]!;
+ expect(h.app.world.has(ghost, Health)).toBe(false);
+ });
+});
+
+describe('the claim is a lease', () => {
+ it('advances every sample, so the journal does not grow with the session', async () => {
+ const h = await serverWith();
+ const all: Entity[] = [];
+ for (let i = 0; i < 10; i++) all.push(h.place(`e${i}`, i));
+ await h.step(3);
+
+ const perSample = () => {
+ for (const e of all) h.serverApp.world.update(e, NetPos, (d) => { (d as { x: number }).x += 1; });
+ };
+ perSample();
+ const pending = h.serverApp.world.bufferedWriteRows(NetPos);
+ await h.step(1);
+ const consumed = h.serverApp.world.bufferedWriteRows(NetPos);
+ for (let i = 0; i < 12; i++) { perSample(); await h.step(1); }
+ const afterMany = h.serverApp.world.bufferedWriteRows(NetPos);
+
+ // Written rows are there to be read, gone once the claim moves past
+ // them, and thirteen samples later still not thirteen samples deep.
+ expect(pending).toBeGreaterThanOrEqual(all.length);
+ expect(consumed).toBeLessThan(pending);
+ expect(afterMany).toBeLessThanOrEqual(pending);
+ });
+});