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
docs(net): a checkpoint, so the next profile knows which gate it hit
esengine259bfd46f2d5
diff --git a/bench/REPLICATION_SCALING.md b/bench/REPLICATION_SCALING.mdnew file mode 100644index 000000000..5578b7295--- /dev/null+++ b/bench/REPLICATION_SCALING.md@@ -0,0 +1,92 @@+# Replication scaling — checkpoint++**Phase complete. Stop optimizing until production evidence violates a frozen+budget or a reopen condition below.**++Seven cuts removed the population scans; the eighth re-took the budget and found+nothing left to remove. What follows is the shape that shipped, what each+direction was ruled, and — the part this document exists for — **what evidence+would justify opening one again**.++## Why this is a stopping point rather than fatigue++`bench/sample-budget` accounts for **over 99%** of a sample at 100k entities and+32 connections, and the remainder is under 1%. Every large phase is proportional+to something that actually happened:++- **still is 25 µs.** The idle path is gone, not cheaper.+- **Dirty discovery examines 1,000 candidates for 1,000 movers**, taking the+ journal projection every sample (3 reads, 0 population scans).+- **92–95% of the first-place phase is the provider computing** — grid walk and+ sphere test, 0.149 µs per (connection × visible entity). The host's share of+ it is 5–8%.+- **Spawn cost tracks entities that genuinely entered a view**, at 3.8 µs each.+- **Encode and transport are 1–2% of CPU.**++The shape the first seven cuts attacked — paying `O(population)` to establish+that nothing happened — is no longer present. `visibility query` is first at+31–43%, and it is first because a connection whose own anchor moved has to be+told what is near it now. That is the question, not the overhead.++## The production complexity that shipped++```+registry topology O(membership churn)+dirty discovery O(relevant write journal), population-scan escape hatch+world transform O(1) idle ensure; composed only after a mutation+spatial index persistent — O(membership + composed movement)+idle visibility O(1) generation reuse+moving visibility O(connections × actual local spatial query)+delta routing min(affected + viewer fanout, total interest membership)+spawn explicit ghost construction + declared replication baseline+wire encode/send O(actually transmitted work)+```++## Frozen directions and their reopen conditions++| direction | ruling | reopen when |+|---|---|---|+| regional visibility generation | **NO SHIP** | movement becomes sparse, anchors stable, or `cell` decouples from `radius` — AND `bench/interest-regional`'s arm A shows recomputes well under `C` |+| reverse region → connection index | **REJECTED** | only if a new spatial model makes A's and B's invalidation sets stop being equal |+| binary spawn baseline (FrameWriter) | **CLOSED for CPU** | baseline encode becomes CPU-dominant, **or** control-plane bandwidth becomes a real deployment constraint |+| dirty discovery projection | **SHIPPED** | the journal stops being sparse, or the escape hatch starts taking the population scan often |+| adaptive delta routing | **SHIPPED** | reverse viewer-index maintenance becomes a hot phase itself |+| idle visibility generation reuse | **SHIPPED** | the conditions its stamp is a function of change |+| journal retention as a lease | **ACCEPTED CONTRACT** | a real product lifecycle produces long-lived parked readers |++### CPU and bandwidth are separate budgets++`bench/sample-budget` measures CPU and says the spawn baseline is not worth+re-encoding: 3.8 µs an entity, with encode 11% of total spawn cost. It also+records that the control plane carries **178 KB a sample against the binary+plane's 4–8 KB** — twenty to forty times, invisible in a CPU budget.++Those are two gates, not one. Re-opening the binary baseline on bandwidth+evidence — real egress, congestion, mobile traffic, cloud cost — is legitimate,+and the reason must then be written as *bandwidth reduction*, never as+*serializer optimization*. Writing it the second way is how two separated+problems get merged back together.++## Where the evidence lives++| bench | question it settled |+|---|---|+| `bench/replication-interest` | what the per-connection interest path spent its `C × E` on |+| `bench/interest-floor` | the floor under a prepared provider |+| `bench/replication-routing` | push against pull, and the chooser that must not measure to decide |+| `bench/replication-dirty` | dirty-row discovery and delivery |+| `bench/interest-regional` | whether regional invalidation can pay — it cannot, at this cell size |+| `bench/spawn-contract` | what a spawn payload carried, and under which contract |+| `bench/sample-budget` | the whole sample, decomposed to >99% |+| `bench/idle-maintenance` | what a server with nothing to do costs |++## Two harness rules this campaign paid for++- **Reconcile the harness's world model against the system's own accounting,+ every census.** One connection keyed wrong owned nothing, failed open to+ `'all'`, and was handed the population every sample — that Set was every wall+ time in the campaign until `arm.mjs` started comparing `viewerLinks` against an+ independent oracle.+- **Interleave A/B, and read intervals, not points.** This machine drifted 20%+ across a session; two runs of one build produced 45,814 µs and 22,627 µs. Three+ ABA rounds where every pair agrees is the weakest claim worth making.diff --git a/bench/interest-regional/README.md b/bench/interest-regional/README.mdindex 54121bec3..e36d7f23f 100644--- a/bench/interest-regional/README.md+++ b/bench/interest-regional/README.md@@ -1,5 +1,8 @@# Does one entity moving have to invalidate every connection?+> Part of a closed phase — the rulings and their reopen conditions are in+> [`bench/REPLICATION_SCALING.md`](../REPLICATION_SCALING.md).+N3e made the sample in which NOTHING moved free — 3,863 µs to 17 at 100k × 32.What it did not touch is the sample in which something moved *somewhere else*:there is one spatial generation, so a single write re-proves all C views.diff --git a/bench/replication-routing/README.md b/bench/replication-routing/README.mdindex ff32a588e..34ccb2c46 100644--- a/bench/replication-routing/README.md+++ b/bench/replication-routing/README.md@@ -1,5 +1,8 @@# The interest send path, once visibility is local+> Part of a closed phase — the rulings and their reopen conditions are in+> [`bench/REPLICATION_SCALING.md`](../REPLICATION_SCALING.md).+The provider took the spatial question from 5504% of a core to 18%. What is leftin `sampleWithInterest_` is per connection, and two of its passes walk a GLOBALlist every time:diff --git a/bench/sample-budget/README.md b/bench/sample-budget/README.mdindex b099be438..980160dd6 100644--- a/bench/sample-budget/README.md+++ b/bench/sample-budget/README.md@@ -1,5 +1,8 @@# What a replication sample is actually spent on+> Part of a closed phase — the rulings and their reopen conditions are in+> [`bench/REPLICATION_SCALING.md`](../REPLICATION_SCALING.md).+Seven population scans came out of this path — registry, dirty discovery,ownership, position reads, grid rebuild, row routing, idle visibility. Guessingthe next wall from the source after that is how you start optimising second-orderdiff --git a/bench/spawn-contract/README.md b/bench/spawn-contract/README.mdindex 0677af178..238d3a3e7 100644--- a/bench/spawn-contract/README.md+++ b/bench/spawn-contract/README.md@@ -1,5 +1,8 @@# What a spawn payload carries, and under which contract+> Part of a closed phase — the rulings and their reopen conditions are in+> [`bench/REPLICATION_SCALING.md`](../REPLICATION_SCALING.md).+`spawnPayload_` builds its payload with `serializeEntityComponents` — the SCENEprojection. Scene serialization answers *how is this entity restored in full*.Replication answers a different question: *which facts is this client authorized