Shrink the per-tick worker → main update payload by ~90% (#4244)

Stacked on #4243 (the `perf:client` harness) — first step of fixing the every-100ms main-thread stutter: make the per-tick burst small before spreading what remains across frames. ## Problem The harness showed the main-thread burst was dominated by `structuredClone` of the `updates` object, and the clone was dominated by two kinds of per-tick churn that re-sent object payloads every tick: - `gold` / `troops` / `tilesOwned` change for nearly every alive player every tick → ~278 partial `PlayerUpdate` objects per tick (world/400 bots), ~508 on giantworldmap. - Attack troop counts tick down every tick → whole `outgoingAttacks`/`incomingAttacks` arrays re-cloned for every fighting player every tick. - `playerNameViewData` (an all-players record) was cloned every tick but only recomputed every 30 ticks. ## Change Three additions to the worker → main protocol (all transferable, zero-clone): 1. **`packedPlayerUpdates`** — `[smallID, tilesOwned, gold, troops]` float64 quads for players whose stats changed. These fields no longer appear in `PlayerUpdate` diffs (first emissions still carry the full snapshot). Gold is exact in a float64 (game values ≪ 2^53). 2. **`packedAttackUpdates`** — `[ownerSmallID, direction, index, troops]` quads. Attack arrays are only resent when membership/order/retreating changes — which is exactly the condition that keeps the patch indexes valid (a tick either resends an array or patches it, never both). 3. **`playerNameViewData` is now optional** — attached only on placement-rebuild ticks (spawn ticks, first ticks, every 30th, spawn end). The client keeps the last applied values; dead players' name placements freeze at death (matching the previous effective behavior). On the client, `GameView.populateFrame` now also rebuilds `names` / `relationMatrix` / `allianceClusters` only when their inputs changed that tick — field presence on a partial `PlayerUpdate` marks them dirty. (`playerStatus`, nuke telegraphs, and attack rings still recompute every tick; they're tick- or unit-dependent.) ## Results (perf:client, this machine; low-end devices ~5–20× slower) Default run (world, 400 bots, 1800 ticks): | stage | before | after | |---|---|---| | clone (serialize+deserialize) | 1.02ms | **0.09ms** | | GameView.update | 0.62ms | **0.29ms** | | WebGLFrameBuilder.update | 0.04ms | 0.04ms | | **TOTAL burst mean** | **1.67ms** | **0.42ms** | | TOTAL p99 / max | 3.47 / 10.3ms | **1.21 / 3.92ms** | giantworldmap/600t: 2.54 → 0.68ms mean. Player update objects: 278 → 6.5 per tick (world), 508 → 12 (giant). The remaining burst is mostly tile apply + per-tick derivations — the part that frame-spreading (next step) addresses. ## Verification - **Sim final hash unchanged** on all three reference configs (`5607618202213430`, `29309648281599524`, `39945089450032050`) — no simulation behavior change. - **View hash unchanged** on all three configs (`942106e9`, `a3aae227`, `cbaaf265`) — the rendered view state is provably identical tick-for-tick, including the name-freeze semantics. - New tests: `tests/PackedPlayerUpdates.test.ts` (drain + GameRunner cadence), packed-channel and freeze-at-death cases in `tests/client/view/GameView.test.ts`, `packAttackTroopDeltas` unit tests and updated diff contract in `tests/GameUpdateUtils.test.ts` / `tests/PlayerUpdateDiff.test.ts`. - `npm test` (1490 tests), `eslint`, `prettier`, `tsc --noEmit` all pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-21 09:20:47 +00:00 · 2026-06-12 16:50:56 -07:00
parent 4149b3e4cb
commit bca980f572
16 changed files with 924 additions and 74 deletions
@@ -27,9 +27,11 @@ function withPlayers(
 ) {
  const gu = makeEmptyGu(tick);
  gu.updates[GameUpdateType.Player] = players;
+  const nameViewData: NonNullable<typeof gu.playerNameViewData> = {};
  for (const p of players) {
-    gu.playerNameViewData[p.id] = nameDataMap[p.id] ?? makeNameViewData();
+    nameViewData[p.id] = nameDataMap[p.id] ?? makeNameViewData();
  }
+  gu.playerNameViewData = nameViewData;
  return gu;
 }

@@ -140,6 +142,288 @@ describe("GameView.update — players", () => {
  });
 });

+describe("GameView.update — packed channels", () => {
+  it("packedPlayerUpdates quads update tilesOwned/gold/troops in place", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [
+        makePlayerUpdate({ id: "alice", smallID: 1, troops: 100, gold: 5n }),
+      ]),
+    );
+
+    const gu = makeEmptyGu(2);
+    // [smallID, tilesOwned, gold, troops]
+    gu.packedPlayerUpdates = new Float64Array([1, 42, 999, 250]);
+    game.update(gu);
+
+    const alice = game.player("alice");
+    expect(alice.numTilesOwned()).toBe(42);
+    expect(alice.gold()).toBe(999n);
+    expect(alice.troops()).toBe(250);
+  });
+
+  it("packedAttackUpdates patches troop counts by direction and index", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [
+        makePlayerUpdate({
+          id: "alice",
+          smallID: 1,
+          outgoingAttacks: [
+            {
+              attackerID: 1,
+              targetID: 2,
+              troops: 500,
+              id: "a1",
+              retreating: false,
+            },
+            {
+              attackerID: 1,
+              targetID: 3,
+              troops: 300,
+              id: "a2",
+              retreating: false,
+            },
+          ],
+          incomingAttacks: [
+            {
+              attackerID: 4,
+              targetID: 1,
+              troops: 80,
+              id: "a3",
+              retreating: false,
+            },
+          ],
+        }),
+      ]),
+    );
+
+    const gu = makeEmptyGu(2);
+    // [ownerSmallID, direction (0=outgoing, 1=incoming), index, troops]
+    gu.packedAttackUpdates = new Float64Array([1, 0, 1, 290, 1, 1, 0, 75]);
+    game.update(gu);
+
+    const alice = game.player("alice");
+    expect(alice.outgoingAttacks().map((a) => a.troops)).toEqual([500, 290]);
+    expect(alice.incomingAttacks().map((a) => a.troops)).toEqual([75]);
+  });
+
+  it("quads for unknown smallIDs and out-of-range attack indexes are ignored", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [makePlayerUpdate({ id: "alice", smallID: 1 })]),
+    );
+    const gu = makeEmptyGu(2);
+    gu.packedPlayerUpdates = new Float64Array([99, 1, 1, 1]);
+    gu.packedAttackUpdates = new Float64Array([1, 0, 5, 123, 99, 1, 0, 7]);
+    expect(() => game.update(gu)).not.toThrow();
+  });
+
+  it("same-tick array resend and patch on different directions both apply", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [
+        makePlayerUpdate({
+          id: "alice",
+          smallID: 1,
+          outgoingAttacks: [
+            {
+              attackerID: 1,
+              targetID: 2,
+              troops: 500,
+              id: "a1",
+              retreating: false,
+            },
+          ],
+          incomingAttacks: [
+            {
+              attackerID: 4,
+              targetID: 1,
+              troops: 80,
+              id: "a3",
+              retreating: false,
+            },
+          ],
+        }),
+      ]),
+    );
+
+    // Outgoing membership changed → full array resent with fresh troops;
+    // incoming membership unchanged → troops arrive as a patch. The patch
+    // must land on the long-lived incoming array and not interfere with the
+    // resent outgoing array (a tick resends or patches each array, never
+    // both — but different directions can mix on one tick).
+    const gu = makeEmptyGu(2);
+    gu.updates[GameUpdateType.Player] = [
+      {
+        type: GameUpdateType.Player,
+        id: "alice",
+        outgoingAttacks: [
+          {
+            attackerID: 1,
+            targetID: 2,
+            troops: 450,
+            id: "a1",
+            retreating: false,
+          },
+          {
+            attackerID: 1,
+            targetID: 3,
+            troops: 100,
+            id: "a2",
+            retreating: false,
+          },
+        ],
+      },
+    ];
+    gu.packedAttackUpdates = new Float64Array([1, 1, 0, 75]);
+    game.update(gu);
+
+    const alice = game.player("alice");
+    expect(alice.outgoingAttacks().map((a) => a.troops)).toEqual([450, 100]);
+    expect(alice.incomingAttacks().map((a) => a.troops)).toEqual([75]);
+  });
+
+  it("gold survives the float64 quad exactly, including > 2^32 values", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [makePlayerUpdate({ id: "alice", smallID: 1 })]),
+    );
+    const bigGold = 2 ** 52 + 11; // integer, exactly representable in f64
+    const gu = makeEmptyGu(2);
+    gu.packedPlayerUpdates = new Float64Array([1, 0, bigGold, 0]);
+    game.update(gu);
+    expect(game.player("alice").gold()).toBe(BigInt(bigGold));
+  });
+
+  it("nameData persists across ticks without a playerNameViewData record", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [makePlayerUpdate({ id: "alice", smallID: 1 })], {
+        alice: { x: 7, y: 9, size: 3 },
+      }),
+    );
+    expect(game.frameData().names.get("alice")).toMatchObject({ x: 7, y: 9 });
+
+    // Tick without a record (worker omits it between placement rebuilds) —
+    // even with a player update present, the old placement must survive.
+    const gu = makeEmptyGu(2);
+    gu.updates[GameUpdateType.Player] = [
+      makePlayerUpdate({ id: "alice", smallID: 1 }),
+    ];
+    game.update(gu);
+    expect(game.frameData().names.get("alice")).toMatchObject({ x: 7, y: 9 });
+
+    // A new record updates the placement (alice is alive).
+    const gu3 = makeEmptyGu(3);
+    gu3.playerNameViewData = { alice: { x: 11, y: 13, size: 4 } };
+    game.update(gu3);
+    expect(game.frameData().names.get("alice")).toMatchObject({ x: 11, y: 13 });
+  });
+
+  it("dead players keep their last name placement (freeze at death)", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [makePlayerUpdate({ id: "alice", smallID: 1 })], {
+        alice: { x: 7, y: 9, size: 3 },
+      }),
+    );
+
+    // Alice dies.
+    const gu2 = makeEmptyGu(2);
+    gu2.updates[GameUpdateType.Player] = [
+      makePlayerUpdate({ id: "alice", smallID: 1, isAlive: false }),
+    ];
+    game.update(gu2);
+
+    // A later record must not move her name.
+    const gu3 = makeEmptyGu(3);
+    gu3.playerNameViewData = { alice: { x: 0, y: 0, size: 0 } };
+    game.update(gu3);
+    expect(game.frameData().names.get("alice")).toMatchObject({ x: 7, y: 9 });
+  });
+});
+
+describe("GameView.update — derived-data dirty flags", () => {
+  function twoPlayers() {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [
+        makePlayerUpdate({ id: "alice", smallID: 1 }),
+        makePlayerUpdate({ id: "bob", smallID: 2 }),
+      ]),
+    );
+    return game;
+  }
+
+  it("relationMatrix recomputes when allies arrive on a partial update", () => {
+    const game = twoPlayers();
+    const size = game.frameData().relationSize;
+    expect(game.frameData().relationMatrix[1 * size + 2]).toBe(0); // neutral
+
+    const gu = makeEmptyGu(2);
+    gu.updates[GameUpdateType.Player] = [
+      { type: GameUpdateType.Player, id: "alice", allies: [2] },
+    ];
+    game.update(gu);
+    // friendly, both directions
+    expect(game.frameData().relationMatrix[1 * size + 2]).toBe(1);
+    expect(game.frameData().relationMatrix[2 * size + 1]).toBe(1);
+  });
+
+  it("relationMatrix recomputes when embargoes arrive on a partial update", () => {
+    const game = twoPlayers();
+    const size = game.frameData().relationSize;
+
+    const gu = makeEmptyGu(2);
+    gu.updates[GameUpdateType.Player] = [
+      {
+        type: GameUpdateType.Player,
+        id: "alice",
+        embargoes: new Set(["bob"]),
+      },
+    ];
+    game.update(gu);
+    expect(game.frameData().relationMatrix[1 * size + 2]).toBe(2); // embargo
+  });
+
+  it("allianceClusters keep identity on clean ticks and recompute on allies change", () => {
+    const game = twoPlayers();
+    const before = game.frameData().allianceClusters;
+    expect(before.get(1)).not.toBe(before.get(2)); // separate clusters
+
+    // Clean tick: no relation inputs changed → cached object, untouched.
+    game.update(makeEmptyGu(2));
+    expect(game.frameData().allianceClusters).toBe(before);
+
+    // Alliance forms → recomputed: alice and bob share a cluster root.
+    const gu = makeEmptyGu(3);
+    gu.updates[GameUpdateType.Player] = [
+      { type: GameUpdateType.Player, id: "alice", allies: [2] },
+      { type: GameUpdateType.Player, id: "bob", allies: [1] },
+    ];
+    game.update(gu);
+    const after = game.frameData().allianceClusters;
+    expect(after).not.toBe(before);
+    expect(after.get(1)).toBe(after.get(2));
+  });
+
+  it("names map keeps identity and content on ticks without a record", () => {
+    const game = makeGameView();
+    game.update(
+      withPlayers(1, [makePlayerUpdate({ id: "alice", smallID: 1 })], {
+        alice: { x: 7, y: 9, size: 3 },
+      }),
+    );
+    const names = game.frameData().names;
+    const entry = names.get("alice");
+
+    game.update(makeEmptyGu(2));
+    expect(game.frameData().names).toBe(names); // long-lived map
+    expect(game.frameData().names.get("alice")).toBe(entry); // not rebuilt
+  });
+});
+
 describe("GameView.update — units", () => {
  it("creates a UnitView on first sighting and reuses it after", () => {
    const game = makeGameView();