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
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.mdindex 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 viewschurn, 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 notdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: () => voidinputOf: (connectionId: number) => ReplInputMsg | nullleavesSent: numbernetIds: NetIds+populationScans: numbersample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => voidsetInterestProvider: (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 | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: () => voidinputOf: (connectionId: number) => ReplInputMsg | nullleavesSent: numbernetIds: NetIds+populationScans: numbersample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => voidsetInterestProvider: (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 | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: () => voidinputOf: (connectionId: number) => ReplInputMsg | nullleavesSent: numbernetIds: NetIds+populationScans: numbersample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => voidsetInterestProvider: (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 | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: () => voidinputOf: (connectionId: number) => ReplInputMsg | nullleavesSent: numbernetIds: NetIds+populationScans: numbersample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => voidsetInterestProvider: (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 | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: () => voidinputOf: (connectionId: number) => ReplInputMsg | nullleavesSent: numbernetIds: NetIds+populationScans: numbersample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => voidsetInterestProvider: (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 | nulldiff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});