From d2a950660573199d54bcbc08a4ea5c165c397b0a Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Sun, 23 Nov 2025 14:07:12 +0100
Subject: [PATCH 01/13] Add client catch-up mode

Increase worker heartbeats per frame when far behind server to fast-forward simulation.
Track backlog and expose catch-up status via TickMetricsEvent.
Extend performance overlay to display backlog turns and indicate active catch-up mode.
---
 src/client/ClientGameRunner.ts                | 62 ++++++++++++++++++-
 src/client/InputHandler.ts                    |  4 ++
 .../graphics/layers/PerformanceOverlay.ts     | 32 +++++++++-
 3 files changed, 94 insertions(+), 4 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 575977f9a..c7c95a24b 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -208,6 +208,16 @@ export class ClientGameRunner {
   private lastTickReceiveTime: number = 0;
   private currentTickDelay: number | undefined = undefined;
 
+  // Track how far behind the client simulation is compared to the server.
+  private serverTurnHighWater: number = 0;
+  private lastProcessedTick: number = 0;
+  private backlogTurns: number = 0;
+
+  private catchUpMode: boolean = false;
+  private readonly CATCH_UP_ENTER_BACKLOG = 120; // turns behind to enter catch-up
+  private readonly CATCH_UP_EXIT_BACKLOG = 20; // turns behind to exit catch-up
+  private readonly CATCH_UP_HEARTBEATS_PER_FRAME = 5;
+
   constructor(
     private lobby: LobbyConfig,
     private eventBus: EventBus,
@@ -299,9 +309,43 @@ export class ClientGameRunner {
       this.gameView.update(gu);
       this.renderer.tick();
 
+      // Update tick / backlog metrics
+      if (!("errMsg" in gu)) {
+        this.lastProcessedTick = gu.tick;
+        this.backlogTurns = Math.max(
+          0,
+          this.serverTurnHighWater - this.lastProcessedTick,
+        );
+
+        const wasCatchUp = this.catchUpMode;
+        if (
+          !this.catchUpMode &&
+          this.backlogTurns >= this.CATCH_UP_ENTER_BACKLOG
+        ) {
+          this.catchUpMode = true;
+        } else if (
+          this.catchUpMode &&
+          this.backlogTurns <= this.CATCH_UP_EXIT_BACKLOG
+        ) {
+          this.catchUpMode = false;
+        }
+        if (wasCatchUp !== this.catchUpMode) {
+          console.log(
+            `Catch-up mode ${this.catchUpMode ? "enabled" : "disabled"} (backlog: ${
+              this.backlogTurns
+            } turns)`,
+          );
+        }
+      }
+
       // Emit tick metrics event for performance overlay
       this.eventBus.emit(
-        new TickMetricsEvent(gu.tickExecutionDuration, this.currentTickDelay),
+        new TickMetricsEvent(
+          gu.tickExecutionDuration,
+          this.currentTickDelay,
+          this.backlogTurns,
+          this.catchUpMode,
+        ),
       );
 
       // Reset tick delay for next measurement
@@ -314,7 +358,12 @@ export class ClientGameRunner {
     const worker = this.worker;
     const keepWorkerAlive = () => {
       if (this.isActive) {
-        worker.sendHeartbeat();
+        const beatsPerFrame = this.catchUpMode
+          ? this.CATCH_UP_HEARTBEATS_PER_FRAME
+          : 1;
+        for (let i = 0; i < beatsPerFrame; i++) {
+          worker.sendHeartbeat();
+        }
         requestAnimationFrame(keepWorkerAlive);
       }
     };
@@ -363,6 +412,10 @@ export class ClientGameRunner {
         }
 
         for (const turn of message.turns) {
+          this.serverTurnHighWater = Math.max(
+            this.serverTurnHighWater,
+            turn.turnNumber,
+          );
           if (turn.turnNumber < this.turnsSeen) {
             continue;
           }
@@ -415,6 +468,11 @@ export class ClientGameRunner {
         }
         this.lastTickReceiveTime = now;
 
+        this.serverTurnHighWater = Math.max(
+          this.serverTurnHighWater,
+          message.turn.turnNumber,
+        );
+
         if (this.turnsSeen !== message.turn.turnNumber) {
           console.error(
             `got wrong turn have turns ${this.turnsSeen}, received turn ${message.turn.turnNumber}`,
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index 26d8f6c27..5ecc23915 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -129,6 +129,10 @@ export class TickMetricsEvent implements GameEvent {
   constructor(
     public readonly tickExecutionDuration?: number,
     public readonly tickDelay?: number,
+    // Number of turns the client is behind the server (if known)
+    public readonly backlogTurns?: number,
+    // Whether the client is currently in catch-up mode
+    public readonly inCatchUpMode?: boolean,
   ) {}
 }
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index fb744d4a0..0fc50ffdf 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -229,7 +229,12 @@ export class PerformanceOverlay extends LitElement implements Layer {
       this.setVisible(this.userSettings.performanceOverlay());
     });
     this.eventBus.on(TickMetricsEvent, (event: TickMetricsEvent) => {
-      this.updateTickMetrics(event.tickExecutionDuration, event.tickDelay);
+      this.updateTickMetrics(
+        event.tickExecutionDuration,
+        event.tickDelay,
+        event.backlogTurns,
+        event.inCatchUpMode,
+      );
     });
   }
 
@@ -418,7 +423,18 @@ export class PerformanceOverlay extends LitElement implements Layer {
     this.layerBreakdown = breakdown;
   }
 
-  updateTickMetrics(tickExecutionDuration?: number, tickDelay?: number) {
+  @state()
+  private backlogTurns: number = 0;
+
+  @state()
+  private inCatchUpMode: boolean = false;
+
+  updateTickMetrics(
+    tickExecutionDuration?: number,
+    tickDelay?: number,
+    backlogTurns?: number,
+    inCatchUpMode?: boolean,
+  ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
     // Update tick execution duration stats
@@ -455,6 +471,13 @@ export class PerformanceOverlay extends LitElement implements Layer {
       }
     }
 
+    if (backlogTurns !== undefined) {
+      this.backlogTurns = backlogTurns;
+    }
+    if (inCatchUpMode !== undefined) {
+      this.inCatchUpMode = inCatchUpMode;
+    }
+
     this.requestUpdate();
   }
 
@@ -600,6 +623,11 @@ export class PerformanceOverlay extends LitElement implements Layer {
           <span>${this.tickDelayAvg.toFixed(2)}ms</span>
           (max: <span>${this.tickDelayMax}ms</span>)
         </div>
+        <div class="performance-line">
+          Backlog turns:
+          <span>${this.backlogTurns}</span>
+          ${this.inCatchUpMode ? html`<span> (catch-up)</span>` : html``}
+        </div>
         ${this.layerBreakdown.length
           ? html`<div class="layers-section">
               <div class="performance-line">

From f8ce8d71c0b7a51fae9132042eb0ca6886ad53b2 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Sun, 23 Nov 2025 19:28:34 +0100
Subject: [PATCH 02/13] Batch worker updates in client catch-up mode to reduce
 render cost

- Refactor worker update handling into processPendingUpdates so multiple GameUpdateViewData objects are batched per frame.
- Combine all tick updates in a batch into a single GameUpdateViewData before applying it to GameView, while still running per-tick side effects (turnComplete, hashes, backlog metrics, win saving).
- Ensure layers using updatesSinceLastTick and recentlyUpdatedTiles see all events in a batch, fixing visual artifacts during fast-forward resync.
---
 src/client/ClientGameRunner.ts | 183 +++++++++++++++++++++++----------
 1 file changed, 131 insertions(+), 52 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index c7c95a24b..dcf769b8b 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -12,7 +12,7 @@ import {
 import { createPartialGameRecord, replacer } from "../core/Util";
 import { ServerConfig } from "../core/configuration/Config";
 import { getConfig } from "../core/configuration/ConfigLoader";
-import { PlayerActions, UnitType } from "../core/game/Game";
+import { GameUpdates, PlayerActions, UnitType } from "../core/game/Game";
 import { TileRef } from "../core/game/GameMap";
 import { GameMapLoader } from "../core/game/GameMapLoader";
 import {
@@ -218,6 +218,9 @@ export class ClientGameRunner {
   private readonly CATCH_UP_EXIT_BACKLOG = 20; // turns behind to exit catch-up
   private readonly CATCH_UP_HEARTBEATS_PER_FRAME = 5;
 
+  private pendingUpdates: GameUpdateViewData[] = [];
+  private isProcessingUpdates = false;
+
   constructor(
     private lobby: LobbyConfig,
     private eventBus: EventBus,
@@ -302,57 +305,9 @@ export class ClientGameRunner {
         this.stop();
         return;
       }
-      this.transport.turnComplete();
-      gu.updates[GameUpdateType.Hash].forEach((hu: HashUpdate) => {
-        this.eventBus.emit(new SendHashEvent(hu.tick, hu.hash));
-      });
-      this.gameView.update(gu);
-      this.renderer.tick();
-
-      // Update tick / backlog metrics
-      if (!("errMsg" in gu)) {
-        this.lastProcessedTick = gu.tick;
-        this.backlogTurns = Math.max(
-          0,
-          this.serverTurnHighWater - this.lastProcessedTick,
-        );
-
-        const wasCatchUp = this.catchUpMode;
-        if (
-          !this.catchUpMode &&
-          this.backlogTurns >= this.CATCH_UP_ENTER_BACKLOG
-        ) {
-          this.catchUpMode = true;
-        } else if (
-          this.catchUpMode &&
-          this.backlogTurns <= this.CATCH_UP_EXIT_BACKLOG
-        ) {
-          this.catchUpMode = false;
-        }
-        if (wasCatchUp !== this.catchUpMode) {
-          console.log(
-            `Catch-up mode ${this.catchUpMode ? "enabled" : "disabled"} (backlog: ${
-              this.backlogTurns
-            } turns)`,
-          );
-        }
-      }
-
-      // Emit tick metrics event for performance overlay
-      this.eventBus.emit(
-        new TickMetricsEvent(
-          gu.tickExecutionDuration,
-          this.currentTickDelay,
-          this.backlogTurns,
-          this.catchUpMode,
-        ),
-      );
-
-      // Reset tick delay for next measurement
-      this.currentTickDelay = undefined;
-
-      if (gu.updates[GameUpdateType.Win].length > 0) {
-        this.saveGame(gu.updates[GameUpdateType.Win][0]);
+      this.pendingUpdates.push(gu);
+      if (!this.catchUpMode) {
+        this.processPendingUpdates();
       }
     });
     const worker = this.worker;
@@ -364,6 +319,7 @@ export class ClientGameRunner {
         for (let i = 0; i < beatsPerFrame; i++) {
           worker.sendHeartbeat();
         }
+        this.processPendingUpdates();
         requestAnimationFrame(keepWorkerAlive);
       }
     };
@@ -503,6 +459,129 @@ export class ClientGameRunner {
     }
   }
 
+  private processPendingUpdates() {
+    if (this.isProcessingUpdates) {
+      return;
+    }
+    if (this.pendingUpdates.length === 0) {
+      return;
+    }
+
+    this.isProcessingUpdates = true;
+    const batch = this.pendingUpdates.splice(0);
+
+    let processedCount = 0;
+    let lastTickDuration: number | undefined;
+    let lastTick: number | undefined;
+
+    try {
+      for (const gu of batch) {
+        processedCount++;
+
+        this.transport.turnComplete();
+        gu.updates[GameUpdateType.Hash].forEach((hu: HashUpdate) => {
+          this.eventBus.emit(new SendHashEvent(hu.tick, hu.hash));
+        });
+        this.updateBacklogMetrics(gu.tick);
+
+        if (gu.updates[GameUpdateType.Win].length > 0) {
+          this.saveGame(gu.updates[GameUpdateType.Win][0]);
+        }
+
+        if (gu.tickExecutionDuration !== undefined) {
+          lastTickDuration = gu.tickExecutionDuration;
+        }
+        lastTick = gu.tick;
+      }
+    } finally {
+      this.isProcessingUpdates = false;
+    }
+
+    if (processedCount > 0 && lastTick !== undefined) {
+      const combinedGu = this.mergeGameUpdates(batch);
+      if (combinedGu) {
+        this.gameView.update(combinedGu);
+      }
+
+      this.renderer.tick();
+      this.eventBus.emit(
+        new TickMetricsEvent(
+          lastTickDuration,
+          this.currentTickDelay,
+          this.backlogTurns,
+          this.catchUpMode,
+        ),
+      );
+      // Reset tick delay for next measurement
+      this.currentTickDelay = undefined;
+    }
+  }
+
+  private mergeGameUpdates(
+    batch: GameUpdateViewData[],
+  ): GameUpdateViewData | null {
+    if (batch.length === 0) {
+      return null;
+    }
+
+    const last = batch[batch.length - 1];
+    const combinedUpdates: GameUpdates = {} as GameUpdates;
+
+    // Initialize combinedUpdates with empty arrays for each existing key
+    for (const key in last.updates) {
+      const type = Number(key) as GameUpdateType;
+      combinedUpdates[type] = [];
+    }
+
+    const combinedPackedTileUpdates: bigint[] = [];
+
+    for (const gu of batch) {
+      for (const key in gu.updates) {
+        const type = Number(key) as GameUpdateType;
+        // We don't care about the specific update subtype here; just treat it
+        // as an array we can concatenate.
+        const updatesForType = gu.updates[type] as unknown as any[];
+        (combinedUpdates[type] as unknown as any[]).push(...updatesForType);
+      }
+      gu.packedTileUpdates.forEach((tu) => {
+        combinedPackedTileUpdates.push(tu);
+      });
+    }
+
+    return {
+      tick: last.tick,
+      updates: combinedUpdates,
+      packedTileUpdates: new BigUint64Array(combinedPackedTileUpdates),
+      playerNameViewData: last.playerNameViewData,
+      tickExecutionDuration: last.tickExecutionDuration,
+    };
+  }
+
+  private updateBacklogMetrics(processedTick: number) {
+    this.lastProcessedTick = processedTick;
+    this.backlogTurns = Math.max(
+      0,
+      this.serverTurnHighWater - this.lastProcessedTick,
+    );
+
+    const wasCatchUp = this.catchUpMode;
+    if (!this.catchUpMode && this.backlogTurns >= this.CATCH_UP_ENTER_BACKLOG) {
+      this.catchUpMode = true;
+    } else if (
+      this.catchUpMode &&
+      this.backlogTurns <= this.CATCH_UP_EXIT_BACKLOG
+    ) {
+      this.catchUpMode = false;
+    }
+    if (wasCatchUp !== this.catchUpMode) {
+      console.log(
+        `Catch-up mode ${this.catchUpMode ? "enabled" : "disabled"} (backlog: ${
+          this.backlogTurns
+        } turns)`,
+      );
+    }
+  }
+
   private inputEvent(event: MouseUpEvent) {
     if (!this.isActive || this.renderer.uiState.ghostStructure !== null) {
       return;

From ddbd2d7b40bc42ff3c6c20a87c2aca9c22f70d4a Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Sun, 23 Nov 2025 21:02:22 +0100
Subject: [PATCH 03/13] frameskip

---
 src/client/ClientGameRunner.ts                | 66 ++++++++++++++++++-
 src/client/InputHandler.ts                    |  2 +
 .../graphics/layers/PerformanceOverlay.ts     | 22 +++++++
 3 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index dcf769b8b..e0804b885 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -216,11 +216,18 @@ export class ClientGameRunner {
   private catchUpMode: boolean = false;
   private readonly CATCH_UP_ENTER_BACKLOG = 120; // turns behind to enter catch-up
   private readonly CATCH_UP_EXIT_BACKLOG = 20; // turns behind to exit catch-up
-  private readonly CATCH_UP_HEARTBEATS_PER_FRAME = 5;
+  private readonly CATCH_UP_HEARTBEATS_PER_FRAME = 5; //upper bound on heartbeats per frame when in catch-up mode
 
   private pendingUpdates: GameUpdateViewData[] = [];
   private isProcessingUpdates = false;
 
+  // Adaptive rendering during catch-up: render at most once every N frames.
+  private renderEveryN: number = 1;
+  private renderSkipCounter: number = 0;
+  private lastFrameTime: number = 0;
+  private readonly MAX_RENDER_EVERY_N = 60;
+  private lastBeatsPerFrame: number = 1;
+
   constructor(
     private lobby: LobbyConfig,
     private eventBus: EventBus,
@@ -313,13 +320,36 @@ export class ClientGameRunner {
     const worker = this.worker;
     const keepWorkerAlive = () => {
       if (this.isActive) {
+        const now = performance.now();
+        let frameDuration = 0;
+        if (this.lastFrameTime !== 0) {
+          frameDuration = now - this.lastFrameTime;
+        }
+        this.lastFrameTime = now;
+
         const beatsPerFrame = this.catchUpMode
           ? this.CATCH_UP_HEARTBEATS_PER_FRAME
           : 1;
+        this.lastBeatsPerFrame = beatsPerFrame;
         for (let i = 0; i < beatsPerFrame; i++) {
           worker.sendHeartbeat();
         }
-        this.processPendingUpdates();
+
+        // Decide whether to render (and thus process pending updates) this frame.
+        let shouldRender = true;
+        if (this.catchUpMode && this.renderEveryN > 1) {
+          if (this.renderSkipCounter < this.renderEveryN - 1) {
+            shouldRender = false;
+            this.renderSkipCounter++;
+          } else {
+            this.renderSkipCounter = 0;
+          }
+        }
+
+        if (shouldRender) {
+          this.processPendingUpdates();
+        }
+        this.adaptRenderFrequency(frameDuration);
         requestAnimationFrame(keepWorkerAlive);
       }
     };
@@ -510,13 +540,45 @@ export class ClientGameRunner {
           this.currentTickDelay,
           this.backlogTurns,
           this.catchUpMode,
+          this.renderEveryN,
+          this.lastBeatsPerFrame,
         ),
       );
+
       // Reset tick delay for next measurement
       this.currentTickDelay = undefined;
     }
   }
 
+  private adaptRenderFrequency(frameDuration: number) {
+    if (!this.catchUpMode) {
+      // Back to normal rendering.
+      this.renderEveryN = 1;
+      this.renderSkipCounter = 0;
+      return;
+    }
+
+    const HIGH_BACKLOG = 200;
+    const LOW_BACKLOG = 50;
+    const HIGH_FRAME_MS = 25;
+    const LOW_FRAME_MS = 18;
+
+    if (this.backlogTurns > HIGH_BACKLOG && frameDuration > HIGH_FRAME_MS) {
+      // We are far behind and frames are heavy → render less often.
+      if (this.renderEveryN < this.MAX_RENDER_EVERY_N) {
+        this.renderEveryN++;
+      }
+    } else if (
+      this.backlogTurns < LOW_BACKLOG ||
+      (frameDuration > 0 && frameDuration < LOW_FRAME_MS)
+    ) {
+      // Either mostly caught up or frames are cheap again → move back toward normal.
+      if (this.renderEveryN > 1) {
+        this.renderEveryN--;
+      }
+    }
+  }
+
   private mergeGameUpdates(
     batch: GameUpdateViewData[],
   ): GameUpdateViewData | null {
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index 5ecc23915..2cfa212cb 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -133,6 +133,8 @@ export class TickMetricsEvent implements GameEvent {
     public readonly backlogTurns?: number,
     // Whether the client is currently in catch-up mode
     public readonly inCatchUpMode?: boolean,
+    public readonly renderEveryN?: number,
+    public readonly beatsPerFrame?: number,
   ) {}
 }
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index 0fc50ffdf..3cd688449 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -234,6 +234,8 @@ export class PerformanceOverlay extends LitElement implements Layer {
         event.tickDelay,
         event.backlogTurns,
         event.inCatchUpMode,
+        event.renderEveryN,
+        event.beatsPerFrame,
       );
     });
   }
@@ -429,11 +431,19 @@ export class PerformanceOverlay extends LitElement implements Layer {
   @state()
   private inCatchUpMode: boolean = false;
 
+  @state()
+  private renderEveryN: number = 1;
+
+  @state()
+  private beatsPerFrame: number = 1;
+
   updateTickMetrics(
     tickExecutionDuration?: number,
     tickDelay?: number,
     backlogTurns?: number,
     inCatchUpMode?: boolean,
+    renderEveryN?: number,
+    beatsPerFrame?: number,
   ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
@@ -477,6 +487,12 @@ export class PerformanceOverlay extends LitElement implements Layer {
     if (inCatchUpMode !== undefined) {
       this.inCatchUpMode = inCatchUpMode;
     }
+    if (renderEveryN !== undefined) {
+      this.renderEveryN = renderEveryN;
+    }
+    if (beatsPerFrame !== undefined) {
+      this.beatsPerFrame = beatsPerFrame;
+    }
 
     this.requestUpdate();
   }
@@ -628,6 +644,12 @@ export class PerformanceOverlay extends LitElement implements Layer {
           <span>${this.backlogTurns}</span>
           ${this.inCatchUpMode ? html`<span> (catch-up)</span>` : html``}
         </div>
+        ${this.inCatchUpMode
+          ? html`<div class="performance-line">
+              Render every <span>${this.renderEveryN}</span> frame(s),
+              heartbeats per frame: <span>${this.beatsPerFrame}</span>
+            </div>`
+          : html``}
         ${this.layerBreakdown.length
           ? html`<div class="layers-section">
               <div class="performance-line">

From b458d00157061b9dac2957f00caeb59008964c84 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Sun, 23 Nov 2025 21:03:22 +0100
Subject: [PATCH 04/13] Worker now self-clocks; no heartbeats needed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GameRunner exposes pending work via a new hasPendingTurns() so the worker can check whether more ticks need to be processed.
Worker auto-runs ticks: as soon as it initializes or receives a new turn, it calls processPendingTurns() and loops executeNextTick() while hasPendingTurns() is true. No more "heartbeat" message type; the worker no longer depends on the main thread’s RAF loop to advance the simulation.
Client main thread simplified:
Removed CATCH_UP_HEARTBEATS_PER_FRAME, the heartbeat loop, and the lastBeatsPerFrame tracking.
keepWorkerAlive now just manages frame skipping + draining. When it decides to render (based on renderEveryN), it drains pendingUpdates, merges them, updates GameView, and runs renderer.tick().
Because rendering a batch always implies draining, we restored the invariant that every GameView.update is paired with a layer tick() (no more lost incremental updates).
MAX_RENDER_EVERY_N is now 5 to keep the queue from growing too large while the worker sprints.
---
 src/client/ClientGameRunner.ts                | 14 +--------
 .../graphics/layers/PerformanceOverlay.ts     |  7 +++--
 src/core/GameRunner.ts                        |  4 +++
 src/core/worker/Worker.worker.ts              | 29 +++++++++++++++++--
 4 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index e0804b885..348e80d6d 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -216,7 +216,6 @@ export class ClientGameRunner {
   private catchUpMode: boolean = false;
   private readonly CATCH_UP_ENTER_BACKLOG = 120; // turns behind to enter catch-up
   private readonly CATCH_UP_EXIT_BACKLOG = 20; // turns behind to exit catch-up
-  private readonly CATCH_UP_HEARTBEATS_PER_FRAME = 5; //upper bound on heartbeats per frame when in catch-up mode
 
   private pendingUpdates: GameUpdateViewData[] = [];
   private isProcessingUpdates = false;
@@ -225,8 +224,7 @@ export class ClientGameRunner {
   private renderEveryN: number = 1;
   private renderSkipCounter: number = 0;
   private lastFrameTime: number = 0;
-  private readonly MAX_RENDER_EVERY_N = 60;
-  private lastBeatsPerFrame: number = 1;
+  private readonly MAX_RENDER_EVERY_N = 5;
 
   constructor(
     private lobby: LobbyConfig,
@@ -317,7 +315,6 @@ export class ClientGameRunner {
         this.processPendingUpdates();
       }
     });
-    const worker = this.worker;
     const keepWorkerAlive = () => {
       if (this.isActive) {
         const now = performance.now();
@@ -327,14 +324,6 @@ export class ClientGameRunner {
         }
         this.lastFrameTime = now;
 
-        const beatsPerFrame = this.catchUpMode
-          ? this.CATCH_UP_HEARTBEATS_PER_FRAME
-          : 1;
-        this.lastBeatsPerFrame = beatsPerFrame;
-        for (let i = 0; i < beatsPerFrame; i++) {
-          worker.sendHeartbeat();
-        }
-
         // Decide whether to render (and thus process pending updates) this frame.
         let shouldRender = true;
         if (this.catchUpMode && this.renderEveryN > 1) {
@@ -541,7 +530,6 @@ export class ClientGameRunner {
           this.backlogTurns,
           this.catchUpMode,
           this.renderEveryN,
-          this.lastBeatsPerFrame,
         ),
       );
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index 3cd688449..bd101f80d 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -435,7 +435,7 @@ export class PerformanceOverlay extends LitElement implements Layer {
   private renderEveryN: number = 1;
 
   @state()
-  private beatsPerFrame: number = 1;
+  private beatsPerFrame: number | null = null;
 
   updateTickMetrics(
     tickExecutionDuration?: number,
@@ -491,7 +491,7 @@ export class PerformanceOverlay extends LitElement implements Layer {
       this.renderEveryN = renderEveryN;
     }
     if (beatsPerFrame !== undefined) {
-      this.beatsPerFrame = beatsPerFrame;
+      this.beatsPerFrame = beatsPerFrame ?? null;
     }
 
     this.requestUpdate();
@@ -647,7 +647,8 @@ export class PerformanceOverlay extends LitElement implements Layer {
         ${this.inCatchUpMode
           ? html`<div class="performance-line">
               Render every <span>${this.renderEveryN}</span> frame(s),
-              heartbeats per frame: <span>${this.beatsPerFrame}</span>
+              heartbeats per frame:
+              <span>${this.beatsPerFrame ?? "auto"}</span>
             </div>`
           : html``}
         ${this.layerBreakdown.length
diff --git a/src/core/GameRunner.ts b/src/core/GameRunner.ts
index a78e39699..d6de468fb 100644
--- a/src/core/GameRunner.ts
+++ b/src/core/GameRunner.ts
@@ -268,4 +268,8 @@ export class GameRunner {
     }
     return player.bestTransportShipSpawn(targetTile);
   }
+
+  public hasPendingTurns(): boolean {
+    return this.currTurn < this.turns.length;
+  }
 }
diff --git a/src/core/worker/Worker.worker.ts b/src/core/worker/Worker.worker.ts
index 1014968fb..a6bb92510 100644
--- a/src/core/worker/Worker.worker.ts
+++ b/src/core/worker/Worker.worker.ts
@@ -16,6 +16,7 @@ import {
 const ctx: Worker = self as any;
 let gameRunner: Promise<GameRunner> | null = null;
 const mapLoader = new FetchGameMapLoader(`/maps`, version);
+let isProcessingTurns = false;
 
 function gameUpdate(gu: GameUpdateViewData | ErrorUpdate) {
   // skip if ErrorUpdate
@@ -32,13 +33,33 @@ function sendMessage(message: WorkerMessage) {
   ctx.postMessage(message);
 }
 
+async function processPendingTurns() {
+  if (isProcessingTurns) {
+    return;
+  }
+  if (!gameRunner) {
+    return;
+  }
+
+  const gr = await gameRunner;
+  if (!gr || !gr.hasPendingTurns()) {
+    return;
+  }
+
+  isProcessingTurns = true;
+  try {
+    while (gr.hasPendingTurns()) {
+      gr.executeNextTick();
+    }
+  } finally {
+    isProcessingTurns = false;
+  }
+}
+
 ctx.addEventListener("message", async (e: MessageEvent<MainThreadMessage>) => {
   const message = e.data;
 
   switch (message.type) {
-    case "heartbeat":
-      (await gameRunner)?.executeNextTick();
-      break;
     case "init":
       try {
         gameRunner = createGameRunner(
@@ -51,6 +72,7 @@ ctx.addEventListener("message", async (e: MessageEvent<MainThreadMessage>) => {
             type: "initialized",
             id: message.id,
           } as InitializedMessage);
+          processPendingTurns();
           return gr;
         });
       } catch (error) {
@@ -67,6 +89,7 @@ ctx.addEventListener("message", async (e: MessageEvent<MainThreadMessage>) => {
       try {
         const gr = await gameRunner;
         await gr.addTurn(message.turn);
+        processPendingTurns();
       } catch (error) {
         console.error("Failed to process turn:", error);
         throw error;

From 8508baee84d206d3b78915084e2c4fdfd8176a39 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Mon, 24 Nov 2025 15:01:17 +0100
Subject: [PATCH 05/13] Clean up previous implementations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

removed:
- catchUpMode and its CATCH_UP_ENTER/EXIT thresholds in ClientGameRunner
- tick metrics fields and overlay UI for inCatchUpMode and beatsPerFrame
- leftover worker heartbeat plumbing (message type + WorkerClient.sendHeartbeat) that was no longer used after self-clocking

changed:
- backlog tracking: keep serverTurnHighWater / lastProcessedTick / backlogTurns, but simplify it to just compute backlog and a backlogGrowing flag instead of driving a dedicated catch-up mode
- frame skip: adaptRenderFrequency now only increases renderEveryN when backlog > 0 and still growing; when backlog is stable/shrinking or zero, it decays renderEveryN back toward 1
- render loop: uses the backlog-aware renderEveryN unconditionally (no catch-up flag), and resets skipping completely when backlog reaches 0
- metrics/overlay: TickMetricsEvent now carries backlogTurns and renderEveryN; the performance overlay displays backlog and current “render every N frames” but no longer mentions catch-up or heartbeats

Learnings during branch development leading to this

Once the worker self-clocks, a separate “catch-up mode” and beats-per-frame knob don’t add real control; they just complicate the model.
Backlog is still a valuable signal, but it’s more effective as a quantitative input (backlog size and whether it’s growing) than as a boolean mode toggle.
Frame skipping should be driven by actual backlog pressure plus frame cost: throttle only while backlog is growing and frames are heavy, and automatically relax back to full-rate rendering once the simulation catches up.
---
 src/client/ClientGameRunner.ts                | 60 +++++++------------
 src/client/InputHandler.ts                    |  3 -
 .../graphics/layers/PerformanceOverlay.ts     | 25 +-------
 src/core/worker/WorkerClient.ts               |  6 --
 src/core/worker/WorkerMessages.ts             |  6 --
 5 files changed, 23 insertions(+), 77 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 348e80d6d..8a92444ce 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -212,15 +212,12 @@ export class ClientGameRunner {
   private serverTurnHighWater: number = 0;
   private lastProcessedTick: number = 0;
   private backlogTurns: number = 0;
-
-  private catchUpMode: boolean = false;
-  private readonly CATCH_UP_ENTER_BACKLOG = 120; // turns behind to enter catch-up
-  private readonly CATCH_UP_EXIT_BACKLOG = 20; // turns behind to exit catch-up
+  private backlogGrowing: boolean = false;
 
   private pendingUpdates: GameUpdateViewData[] = [];
   private isProcessingUpdates = false;
 
-  // Adaptive rendering during catch-up: render at most once every N frames.
+  // Adaptive rendering when frames are heavy: render at most once every N frames.
   private renderEveryN: number = 1;
   private renderSkipCounter: number = 0;
   private lastFrameTime: number = 0;
@@ -311,7 +308,7 @@ export class ClientGameRunner {
         return;
       }
       this.pendingUpdates.push(gu);
-      if (!this.catchUpMode) {
+      if (this.renderEveryN === 1) {
         this.processPendingUpdates();
       }
     });
@@ -326,13 +323,14 @@ export class ClientGameRunner {
 
         // Decide whether to render (and thus process pending updates) this frame.
         let shouldRender = true;
-        if (this.catchUpMode && this.renderEveryN > 1) {
-          if (this.renderSkipCounter < this.renderEveryN - 1) {
-            shouldRender = false;
-            this.renderSkipCounter++;
-          } else {
-            this.renderSkipCounter = 0;
-          }
+        if (
+          this.renderEveryN > 1 &&
+          this.renderSkipCounter < this.renderEveryN - 1
+        ) {
+          shouldRender = false;
+          this.renderSkipCounter++;
+        } else if (this.renderEveryN > 1) {
+          this.renderSkipCounter = 0;
         }
 
         if (shouldRender) {
@@ -528,7 +526,6 @@ export class ClientGameRunner {
           lastTickDuration,
           this.currentTickDelay,
           this.backlogTurns,
-          this.catchUpMode,
           this.renderEveryN,
         ),
       );
@@ -539,28 +536,26 @@ export class ClientGameRunner {
   }
 
   private adaptRenderFrequency(frameDuration: number) {
-    if (!this.catchUpMode) {
-      // Back to normal rendering.
+    // Frameskip only matters while we have a backlog; otherwise stay at 1.
+    if (this.backlogTurns === 0) {
       this.renderEveryN = 1;
       this.renderSkipCounter = 0;
       return;
     }
 
-    const HIGH_BACKLOG = 200;
-    const LOW_BACKLOG = 50;
     const HIGH_FRAME_MS = 25;
     const LOW_FRAME_MS = 18;
 
-    if (this.backlogTurns > HIGH_BACKLOG && frameDuration > HIGH_FRAME_MS) {
-      // We are far behind and frames are heavy → render less often.
+    // Only throttle rendering if backlog is still growing; otherwise drift back toward 1.
+    if (this.backlogGrowing && frameDuration > HIGH_FRAME_MS) {
       if (this.renderEveryN < this.MAX_RENDER_EVERY_N) {
         this.renderEveryN++;
       }
     } else if (
-      this.backlogTurns < LOW_BACKLOG ||
-      (frameDuration > 0 && frameDuration < LOW_FRAME_MS)
+      !this.backlogGrowing &&
+      frameDuration > 0 &&
+      frameDuration < LOW_FRAME_MS
     ) {
-      // Either mostly caught up or frames are cheap again → move back toward normal.
       if (this.renderEveryN > 1) {
         this.renderEveryN--;
       }
@@ -609,27 +604,12 @@ export class ClientGameRunner {
 
   private updateBacklogMetrics(processedTick: number) {
     this.lastProcessedTick = processedTick;
+    const previousBacklog = this.backlogTurns;
     this.backlogTurns = Math.max(
       0,
       this.serverTurnHighWater - this.lastProcessedTick,
     );
-
-    const wasCatchUp = this.catchUpMode;
-    if (!this.catchUpMode && this.backlogTurns >= this.CATCH_UP_ENTER_BACKLOG) {
-      this.catchUpMode = true;
-    } else if (
-      this.catchUpMode &&
-      this.backlogTurns <= this.CATCH_UP_EXIT_BACKLOG
-    ) {
-      this.catchUpMode = false;
-    }
-    if (wasCatchUp !== this.catchUpMode) {
-      console.log(
-        `Catch-up mode ${this.catchUpMode ? "enabled" : "disabled"} (backlog: ${
-          this.backlogTurns
-        } turns)`,
-      );
-    }
+    this.backlogGrowing = this.backlogTurns > previousBacklog;
   }
 
   private inputEvent(event: MouseUpEvent) {
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index 2cfa212cb..abe01cac3 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -131,10 +131,7 @@ export class TickMetricsEvent implements GameEvent {
     public readonly tickDelay?: number,
     // Number of turns the client is behind the server (if known)
     public readonly backlogTurns?: number,
-    // Whether the client is currently in catch-up mode
-    public readonly inCatchUpMode?: boolean,
     public readonly renderEveryN?: number,
-    public readonly beatsPerFrame?: number,
   ) {}
 }
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index bd101f80d..183c4fa44 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -233,9 +233,7 @@ export class PerformanceOverlay extends LitElement implements Layer {
         event.tickExecutionDuration,
         event.tickDelay,
         event.backlogTurns,
-        event.inCatchUpMode,
         event.renderEveryN,
-        event.beatsPerFrame,
       );
     });
   }
@@ -425,25 +423,17 @@ export class PerformanceOverlay extends LitElement implements Layer {
     this.layerBreakdown = breakdown;
   }
 
-  @state()
-  private backlogTurns: number = 0;
-
-  @state()
-  private inCatchUpMode: boolean = false;
-
   @state()
   private renderEveryN: number = 1;
 
   @state()
-  private beatsPerFrame: number | null = null;
+  private backlogTurns: number = 0;
 
   updateTickMetrics(
     tickExecutionDuration?: number,
     tickDelay?: number,
     backlogTurns?: number,
-    inCatchUpMode?: boolean,
     renderEveryN?: number,
-    beatsPerFrame?: number,
   ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
@@ -484,15 +474,9 @@ export class PerformanceOverlay extends LitElement implements Layer {
     if (backlogTurns !== undefined) {
       this.backlogTurns = backlogTurns;
     }
-    if (inCatchUpMode !== undefined) {
-      this.inCatchUpMode = inCatchUpMode;
-    }
     if (renderEveryN !== undefined) {
       this.renderEveryN = renderEveryN;
     }
-    if (beatsPerFrame !== undefined) {
-      this.beatsPerFrame = beatsPerFrame ?? null;
-    }
 
     this.requestUpdate();
   }
@@ -642,13 +626,10 @@ export class PerformanceOverlay extends LitElement implements Layer {
         <div class="performance-line">
           Backlog turns:
           <span>${this.backlogTurns}</span>
-          ${this.inCatchUpMode ? html`<span> (catch-up)</span>` : html``}
         </div>
-        ${this.inCatchUpMode
+        ${this.renderEveryN > 1
           ? html`<div class="performance-line">
-              Render every <span>${this.renderEveryN}</span> frame(s),
-              heartbeats per frame:
-              <span>${this.beatsPerFrame ?? "auto"}</span>
+              Render every <span>${this.renderEveryN}</span> frame(s)
             </div>`
           : html``}
         ${this.layerBreakdown.length
diff --git a/src/core/worker/WorkerClient.ts b/src/core/worker/WorkerClient.ts
index bde436f39..4edc97dee 100644
--- a/src/core/worker/WorkerClient.ts
+++ b/src/core/worker/WorkerClient.ts
@@ -100,12 +100,6 @@ export class WorkerClient {
     });
   }
 
-  sendHeartbeat() {
-    this.worker.postMessage({
-      type: "heartbeat",
-    });
-  }
-
   playerProfile(playerID: number): Promise<PlayerProfile> {
     return new Promise((resolve, reject) => {
       if (!this.isInitialized) {
diff --git a/src/core/worker/WorkerMessages.ts b/src/core/worker/WorkerMessages.ts
index a8d30e9b1..0c5344da1 100644
--- a/src/core/worker/WorkerMessages.ts
+++ b/src/core/worker/WorkerMessages.ts
@@ -9,7 +9,6 @@ import { GameUpdateViewData } from "../game/GameUpdates";
 import { ClientID, GameStartInfo, Turn } from "../Schemas";
 
 export type WorkerMessageType =
-  | "heartbeat"
   | "init"
   | "initialized"
   | "turn"
@@ -31,10 +30,6 @@ interface BaseWorkerMessage {
   id?: string;
 }
 
-export interface HeartbeatMessage extends BaseWorkerMessage {
-  type: "heartbeat";
-}
-
 // Messages from main thread to worker
 export interface InitMessage extends BaseWorkerMessage {
   type: "init";
@@ -114,7 +109,6 @@ export interface TransportShipSpawnResultMessage extends BaseWorkerMessage {
 
 // Union types for type safety
 export type MainThreadMessage =
-  | HeartbeatMessage
   | InitMessage
   | TurnMessage
   | PlayerActionsMessage

From 9d63fcabe99e978c7846f92c5548224aa8766751 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Mon, 24 Nov 2025 17:40:11 +0100
Subject: [PATCH 06/13] Implemented time-sliced catch-up on the main thread to
 keep input responsive. src/client/ClientGameRunner.ts now drains pending game
 updates in small chunks (max 100 updates or ~8ms per slice) via
 requestAnimationFrame, merging and rendering per slice, and only clears the
 processing flag when the queue is empty.

---
 src/client/ClientGameRunner.ts | 73 ++++++++++++++++++++--------------
 1 file changed, 43 insertions(+), 30 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 8a92444ce..cd59e80b5 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -477,23 +477,25 @@ export class ClientGameRunner {
   }
 
   private processPendingUpdates() {
-    if (this.isProcessingUpdates) {
-      return;
-    }
-    if (this.pendingUpdates.length === 0) {
+    if (this.isProcessingUpdates || this.pendingUpdates.length === 0) {
       return;
     }
 
     this.isProcessingUpdates = true;
-    const batch = this.pendingUpdates.splice(0);
+    const processSlice = () => {
+      const SLICE_BUDGET_MS = 8; // keep UI responsive while catching up
+      const MAX_PER_SLICE = 100;
+      const sliceStart = performance.now();
+      const batch: GameUpdateViewData[] = [];
 
-    let processedCount = 0;
-    let lastTickDuration: number | undefined;
-    let lastTick: number | undefined;
+      let processedCount = 0;
+      let lastTickDuration: number | undefined;
+      let lastTick: number | undefined;
 
-    try {
-      for (const gu of batch) {
+      while (this.pendingUpdates.length > 0) {
+        const gu = this.pendingUpdates.shift() as GameUpdateViewData;
         processedCount++;
+        batch.push(gu);
 
         this.transport.turnComplete();
         gu.updates[GameUpdateType.Hash].forEach((hu: HashUpdate) => {
@@ -509,30 +511,41 @@ export class ClientGameRunner {
           lastTickDuration = gu.tickExecutionDuration;
         }
         lastTick = gu.tick;
-      }
-    } finally {
-      this.isProcessingUpdates = false;
-    }
 
-    if (processedCount > 0 && lastTick !== undefined) {
-      const combinedGu = this.mergeGameUpdates(batch);
-      if (combinedGu) {
-        this.gameView.update(combinedGu);
+        const elapsed = performance.now() - sliceStart;
+        if (processedCount >= MAX_PER_SLICE || elapsed >= SLICE_BUDGET_MS) {
+          break;
+        }
       }
 
-      this.renderer.tick();
-      this.eventBus.emit(
-        new TickMetricsEvent(
-          lastTickDuration,
-          this.currentTickDelay,
-          this.backlogTurns,
-          this.renderEveryN,
-        ),
-      );
+      if (processedCount > 0 && lastTick !== undefined) {
+        const combinedGu = this.mergeGameUpdates(batch);
+        if (combinedGu) {
+          this.gameView.update(combinedGu);
+        }
 
-      // Reset tick delay for next measurement
-      this.currentTickDelay = undefined;
-    }
+        this.renderer.tick();
+        this.eventBus.emit(
+          new TickMetricsEvent(
+            lastTickDuration,
+            this.currentTickDelay,
+            this.backlogTurns,
+            this.renderEveryN,
+          ),
+        );
+
+        // Reset tick delay for next measurement
+        this.currentTickDelay = undefined;
+      }
+
+      if (this.pendingUpdates.length > 0) {
+        requestAnimationFrame(processSlice);
+      } else {
+        this.isProcessingUpdates = false;
+      }
+    };
+
+    requestAnimationFrame(processSlice);
   }
 
   private adaptRenderFrequency(frameDuration: number) {

From 93647399c114d1681991b816d6539aa9407e9999 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Mon, 24 Nov 2025 19:59:10 +0100
Subject: [PATCH 07/13] Refactor slice budget calculation in ClientGameRunner
 to improve backlog handling. Introduced dynamic slice budget scaling based on
 backlog size, allowing for longer processing times when necessary while
 maintaining UI responsiveness.

---
 src/client/ClientGameRunner.ts | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index cd59e80b5..2294755c7 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -483,8 +483,24 @@ export class ClientGameRunner {
 
     this.isProcessingUpdates = true;
     const processSlice = () => {
-      const SLICE_BUDGET_MS = 8; // keep UI responsive while catching up
+      const BASE_SLICE_BUDGET_MS = 8; // keep UI responsive while catching up
+      const MAX_SLICE_BUDGET_MS = 1000; // allow longer slices when backlog is large
+      const BACKLOG_FREE_TURNS = 10; // scaling starts at this many turns
+      const BACKLOG_MAX_TURNS = 1000; // MAX_SLICE_BUDGET_MS is reached at this many turns
       const MAX_PER_SLICE = 100;
+
+      const backlogOverhead = Math.max(
+        0,
+        this.backlogTurns - BACKLOG_FREE_TURNS,
+      );
+      const backlogScale = Math.min(
+        1,
+        backlogOverhead / (BACKLOG_MAX_TURNS - BACKLOG_FREE_TURNS),
+      );
+      const sliceBudgetMs =
+        BASE_SLICE_BUDGET_MS +
+        backlogScale * (MAX_SLICE_BUDGET_MS - BASE_SLICE_BUDGET_MS);
+
       const sliceStart = performance.now();
       const batch: GameUpdateViewData[] = [];
 
@@ -513,7 +529,7 @@ export class ClientGameRunner {
         lastTick = gu.tick;
 
         const elapsed = performance.now() - sliceStart;
-        if (processedCount >= MAX_PER_SLICE || elapsed >= SLICE_BUDGET_MS) {
+        if (processedCount >= MAX_PER_SLICE || elapsed >= sliceBudgetMs) {
           break;
         }
       }

From 4268f9019f8b7eec553ecf7a134cb8e475b7a86e Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Mon, 24 Nov 2025 22:54:09 +0100
Subject: [PATCH 08/13] ClientGameRunner: simplify catch-up loop with indexed
 queue

process updates in a single budgeted loop per RAF and render once
track queue head with pendingStart and compact to avoid array shifts
---
 src/client/ClientGameRunner.ts | 37 +++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 2294755c7..a864b75aa 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -215,6 +215,7 @@ export class ClientGameRunner {
   private backlogGrowing: boolean = false;
 
   private pendingUpdates: GameUpdateViewData[] = [];
+  private pendingStart = 0;
   private isProcessingUpdates = false;
 
   // Adaptive rendering when frames are heavy: render at most once every N frames.
@@ -477,12 +478,13 @@ export class ClientGameRunner {
   }
 
   private processPendingUpdates() {
-    if (this.isProcessingUpdates || this.pendingUpdates.length === 0) {
+    const pendingCount = this.pendingUpdates.length - this.pendingStart;
+    if (this.isProcessingUpdates || pendingCount <= 0) {
       return;
     }
 
     this.isProcessingUpdates = true;
-    const processSlice = () => {
+    const processFrame = () => {
       const BASE_SLICE_BUDGET_MS = 8; // keep UI responsive while catching up
       const MAX_SLICE_BUDGET_MS = 1000; // allow longer slices when backlog is large
       const BACKLOG_FREE_TURNS = 10; // scaling starts at this many turns
@@ -501,15 +503,16 @@ export class ClientGameRunner {
         BASE_SLICE_BUDGET_MS +
         backlogScale * (MAX_SLICE_BUDGET_MS - BASE_SLICE_BUDGET_MS);
 
-      const sliceStart = performance.now();
+      const frameStart = performance.now();
       const batch: GameUpdateViewData[] = [];
-
-      let processedCount = 0;
       let lastTickDuration: number | undefined;
       let lastTick: number | undefined;
 
-      while (this.pendingUpdates.length > 0) {
-        const gu = this.pendingUpdates.shift() as GameUpdateViewData;
+      let processedCount = 0;
+
+      // Consume updates until we hit the time budget or per-slice cap.
+      while (this.pendingStart < this.pendingUpdates.length) {
+        const gu = this.pendingUpdates[this.pendingStart++];
         processedCount++;
         batch.push(gu);
 
@@ -528,13 +531,23 @@ export class ClientGameRunner {
         }
         lastTick = gu.tick;
 
-        const elapsed = performance.now() - sliceStart;
+        const elapsed = performance.now() - frameStart;
         if (processedCount >= MAX_PER_SLICE || elapsed >= sliceBudgetMs) {
           break;
         }
       }
 
-      if (processedCount > 0 && lastTick !== undefined) {
+      // Compact the queue if we've advanced far into it.
+      if (
+        this.pendingStart > 0 &&
+        (this.pendingStart > 1024 ||
+          this.pendingStart >= this.pendingUpdates.length / 2)
+      ) {
+        this.pendingUpdates = this.pendingUpdates.slice(this.pendingStart);
+        this.pendingStart = 0;
+      }
+
+      if (batch.length > 0 && lastTick !== undefined) {
         const combinedGu = this.mergeGameUpdates(batch);
         if (combinedGu) {
           this.gameView.update(combinedGu);
@@ -554,14 +567,14 @@ export class ClientGameRunner {
         this.currentTickDelay = undefined;
       }
 
-      if (this.pendingUpdates.length > 0) {
-        requestAnimationFrame(processSlice);
+      if (this.pendingStart < this.pendingUpdates.length) {
+        requestAnimationFrame(processFrame);
       } else {
         this.isProcessingUpdates = false;
       }
     };
 
-    requestAnimationFrame(processSlice);
+    requestAnimationFrame(processFrame);
   }
 
   private adaptRenderFrequency(frameDuration: number) {

From a21f066700cfd3aa6b719e2b1b140639f09131ad Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Tue, 25 Nov 2025 17:40:39 +0100
Subject: [PATCH 09/13] remove redundant logic

---
 src/client/ClientGameRunner.ts                | 96 ++++---------------
 src/client/InputHandler.ts                    |  1 -
 .../graphics/layers/PerformanceOverlay.ts     | 13 ---
 3 files changed, 17 insertions(+), 93 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index a864b75aa..2f3641b22 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -218,12 +218,6 @@ export class ClientGameRunner {
   private pendingStart = 0;
   private isProcessingUpdates = false;
 
-  // Adaptive rendering when frames are heavy: render at most once every N frames.
-  private renderEveryN: number = 1;
-  private renderSkipCounter: number = 0;
-  private lastFrameTime: number = 0;
-  private readonly MAX_RENDER_EVERY_N = 5;
-
   constructor(
     private lobby: LobbyConfig,
     private eventBus: EventBus,
@@ -309,39 +303,8 @@ export class ClientGameRunner {
         return;
       }
       this.pendingUpdates.push(gu);
-      if (this.renderEveryN === 1) {
-        this.processPendingUpdates();
-      }
+      this.processPendingUpdates();
     });
-    const keepWorkerAlive = () => {
-      if (this.isActive) {
-        const now = performance.now();
-        let frameDuration = 0;
-        if (this.lastFrameTime !== 0) {
-          frameDuration = now - this.lastFrameTime;
-        }
-        this.lastFrameTime = now;
-
-        // Decide whether to render (and thus process pending updates) this frame.
-        let shouldRender = true;
-        if (
-          this.renderEveryN > 1 &&
-          this.renderSkipCounter < this.renderEveryN - 1
-        ) {
-          shouldRender = false;
-          this.renderSkipCounter++;
-        } else if (this.renderEveryN > 1) {
-          this.renderSkipCounter = 0;
-        }
-
-        if (shouldRender) {
-          this.processPendingUpdates();
-        }
-        this.adaptRenderFrequency(frameDuration);
-        requestAnimationFrame(keepWorkerAlive);
-      }
-    };
-    requestAnimationFrame(keepWorkerAlive);
 
     const onconnect = () => {
       console.log("Connected to game server!");
@@ -488,8 +451,8 @@ export class ClientGameRunner {
       const BASE_SLICE_BUDGET_MS = 8; // keep UI responsive while catching up
       const MAX_SLICE_BUDGET_MS = 1000; // allow longer slices when backlog is large
       const BACKLOG_FREE_TURNS = 10; // scaling starts at this many turns
-      const BACKLOG_MAX_TURNS = 1000; // MAX_SLICE_BUDGET_MS is reached at this many turns
-      const MAX_PER_SLICE = 100;
+      const BACKLOG_MAX_TURNS = 500; // MAX_SLICE_BUDGET_MS is reached at this many turns
+      const MAX_TICKS_PER_SLICE = 1000;
 
       const backlogOverhead = Math.max(
         0,
@@ -532,7 +495,7 @@ export class ClientGameRunner {
         lastTick = gu.tick;
 
         const elapsed = performance.now() - frameStart;
-        if (processedCount >= MAX_PER_SLICE || elapsed >= sliceBudgetMs) {
+        if (processedCount >= MAX_TICKS_PER_SLICE || elapsed >= sliceBudgetMs) {
           break;
         }
       }
@@ -553,18 +516,20 @@ export class ClientGameRunner {
           this.gameView.update(combinedGu);
         }
 
-        this.renderer.tick();
-        this.eventBus.emit(
-          new TickMetricsEvent(
-            lastTickDuration,
-            this.currentTickDelay,
-            this.backlogTurns,
-            this.renderEveryN,
-          ),
-        );
+        // Only emit metrics when ALL processing is complete
+        if (this.pendingStart >= this.pendingUpdates.length) {
+          this.renderer.tick();
+          this.eventBus.emit(
+            new TickMetricsEvent(
+              lastTickDuration,
+              this.currentTickDelay,
+              this.backlogTurns,
+            ),
+          );
 
-        // Reset tick delay for next measurement
-        this.currentTickDelay = undefined;
+          // Reset tick delay for next measurement
+          this.currentTickDelay = undefined;
+        }
       }
 
       if (this.pendingStart < this.pendingUpdates.length) {
@@ -577,33 +542,6 @@ export class ClientGameRunner {
     requestAnimationFrame(processFrame);
   }
 
-  private adaptRenderFrequency(frameDuration: number) {
-    // Frameskip only matters while we have a backlog; otherwise stay at 1.
-    if (this.backlogTurns === 0) {
-      this.renderEveryN = 1;
-      this.renderSkipCounter = 0;
-      return;
-    }
-
-    const HIGH_FRAME_MS = 25;
-    const LOW_FRAME_MS = 18;
-
-    // Only throttle rendering if backlog is still growing; otherwise drift back toward 1.
-    if (this.backlogGrowing && frameDuration > HIGH_FRAME_MS) {
-      if (this.renderEveryN < this.MAX_RENDER_EVERY_N) {
-        this.renderEveryN++;
-      }
-    } else if (
-      !this.backlogGrowing &&
-      frameDuration > 0 &&
-      frameDuration < LOW_FRAME_MS
-    ) {
-      if (this.renderEveryN > 1) {
-        this.renderEveryN--;
-      }
-    }
-  }
-
   private mergeGameUpdates(
     batch: GameUpdateViewData[],
   ): GameUpdateViewData | null {
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index abe01cac3..e18e616e8 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -131,7 +131,6 @@ export class TickMetricsEvent implements GameEvent {
     public readonly tickDelay?: number,
     // Number of turns the client is behind the server (if known)
     public readonly backlogTurns?: number,
-    public readonly renderEveryN?: number,
   ) {}
 }
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index 183c4fa44..8bc8f4a6a 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -233,7 +233,6 @@ export class PerformanceOverlay extends LitElement implements Layer {
         event.tickExecutionDuration,
         event.tickDelay,
         event.backlogTurns,
-        event.renderEveryN,
       );
     });
   }
@@ -423,9 +422,6 @@ export class PerformanceOverlay extends LitElement implements Layer {
     this.layerBreakdown = breakdown;
   }
 
-  @state()
-  private renderEveryN: number = 1;
-
   @state()
   private backlogTurns: number = 0;
 
@@ -433,7 +429,6 @@ export class PerformanceOverlay extends LitElement implements Layer {
     tickExecutionDuration?: number,
     tickDelay?: number,
     backlogTurns?: number,
-    renderEveryN?: number,
   ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
@@ -474,9 +469,6 @@ export class PerformanceOverlay extends LitElement implements Layer {
     if (backlogTurns !== undefined) {
       this.backlogTurns = backlogTurns;
     }
-    if (renderEveryN !== undefined) {
-      this.renderEveryN = renderEveryN;
-    }
 
     this.requestUpdate();
   }
@@ -627,11 +619,6 @@ export class PerformanceOverlay extends LitElement implements Layer {
           Backlog turns:
           <span>${this.backlogTurns}</span>
         </div>
-        ${this.renderEveryN > 1
-          ? html`<div class="performance-line">
-              Render every <span>${this.renderEveryN}</span> frame(s)
-            </div>`
-          : html``}
         ${this.layerBreakdown.length
           ? html`<div class="layers-section">
               <div class="performance-line">

From 6ab7136c3c835b039a97c52df0179ffbe4b41f44 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Tue, 25 Nov 2025 17:44:54 +0100
Subject: [PATCH 10/13] add "ticks per render" metric

---
 src/client/ClientGameRunner.ts                   |  8 ++++++++
 src/client/InputHandler.ts                       |  2 ++
 src/client/graphics/layers/PerformanceOverlay.ts | 13 +++++++++++++
 3 files changed, 23 insertions(+)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 2f3641b22..ce88d861a 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -213,6 +213,7 @@ export class ClientGameRunner {
   private lastProcessedTick: number = 0;
   private backlogTurns: number = 0;
   private backlogGrowing: boolean = false;
+  private lastRenderedTick: number = 0;
 
   private pendingUpdates: GameUpdateViewData[] = [];
   private pendingStart = 0;
@@ -518,12 +519,19 @@ export class ClientGameRunner {
 
         // Only emit metrics when ALL processing is complete
         if (this.pendingStart >= this.pendingUpdates.length) {
+          const ticksPerRender =
+            this.lastRenderedTick === 0
+              ? lastTick
+              : lastTick - this.lastRenderedTick;
+          this.lastRenderedTick = lastTick;
+
           this.renderer.tick();
           this.eventBus.emit(
             new TickMetricsEvent(
               lastTickDuration,
               this.currentTickDelay,
               this.backlogTurns,
+              ticksPerRender,
             ),
           );
 
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index e18e616e8..bd95e7201 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -131,6 +131,8 @@ export class TickMetricsEvent implements GameEvent {
     public readonly tickDelay?: number,
     // Number of turns the client is behind the server (if known)
     public readonly backlogTurns?: number,
+    // Number of ticks applied since last render
+    public readonly ticksPerRender?: number,
   ) {}
 }
 
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index 8bc8f4a6a..531f19f0b 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -233,6 +233,7 @@ export class PerformanceOverlay extends LitElement implements Layer {
         event.tickExecutionDuration,
         event.tickDelay,
         event.backlogTurns,
+        event.ticksPerRender,
       );
     });
   }
@@ -425,10 +426,14 @@ export class PerformanceOverlay extends LitElement implements Layer {
   @state()
   private backlogTurns: number = 0;
 
+  @state()
+  private ticksPerRender: number = 0;
+
   updateTickMetrics(
     tickExecutionDuration?: number,
     tickDelay?: number,
     backlogTurns?: number,
+    ticksPerRender?: number,
   ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
@@ -470,6 +475,10 @@ export class PerformanceOverlay extends LitElement implements Layer {
       this.backlogTurns = backlogTurns;
     }
 
+    if (ticksPerRender !== undefined) {
+      this.ticksPerRender = ticksPerRender;
+    }
+
     this.requestUpdate();
   }
 
@@ -615,6 +624,10 @@ export class PerformanceOverlay extends LitElement implements Layer {
           <span>${this.tickDelayAvg.toFixed(2)}ms</span>
           (max: <span>${this.tickDelayMax}ms</span>)
         </div>
+        <div class="performance-line">
+          Ticks per render:
+          <span>${this.ticksPerRender}</span>
+        </div>
         <div class="performance-line">
           Backlog turns:
           <span>${this.backlogTurns}</span>

From 7cf024fb6eb75ebc4612990b11c91eb0339c1a33 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Tue, 25 Nov 2025 18:46:25 +0100
Subject: [PATCH 11/13] Refactor rendering and throttle based on backlog

- Refactor rendering and metrics emission in ClientGameRunner to ensure updates occur only after all processing is complete
- Throttle renderGame() based on the current backlog
---
 src/client/ClientGameRunner.ts      | 46 ++++++++++++++++-------------
 src/client/InputHandler.ts          |  7 +++++
 src/client/graphics/GameRenderer.ts | 34 ++++++++++++++++++++-
 3 files changed, 66 insertions(+), 21 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index ce88d861a..4d70a3f3e 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -28,6 +28,7 @@ import { UserSettings } from "../core/game/UserSettings";
 import { WorkerClient } from "../core/worker/WorkerClient";
 import {
   AutoUpgradeEvent,
+  BacklogStatusEvent,
   DoBoatAttackEvent,
   DoGroundAttackEvent,
   InputHandler,
@@ -511,33 +512,35 @@ export class ClientGameRunner {
         this.pendingStart = 0;
       }
 
-      if (batch.length > 0 && lastTick !== undefined) {
+      // Only update view and render when ALL processing is complete
+      if (
+        this.pendingStart >= this.pendingUpdates.length &&
+        batch.length > 0 &&
+        lastTick !== undefined
+      ) {
         const combinedGu = this.mergeGameUpdates(batch);
         if (combinedGu) {
           this.gameView.update(combinedGu);
         }
 
-        // Only emit metrics when ALL processing is complete
-        if (this.pendingStart >= this.pendingUpdates.length) {
-          const ticksPerRender =
-            this.lastRenderedTick === 0
-              ? lastTick
-              : lastTick - this.lastRenderedTick;
-          this.lastRenderedTick = lastTick;
+        const ticksPerRender =
+          this.lastRenderedTick === 0
+            ? lastTick
+            : lastTick - this.lastRenderedTick;
+        this.lastRenderedTick = lastTick;
 
-          this.renderer.tick();
-          this.eventBus.emit(
-            new TickMetricsEvent(
-              lastTickDuration,
-              this.currentTickDelay,
-              this.backlogTurns,
-              ticksPerRender,
-            ),
-          );
+        this.renderer.tick();
+        this.eventBus.emit(
+          new TickMetricsEvent(
+            lastTickDuration,
+            this.currentTickDelay,
+            this.backlogTurns,
+            ticksPerRender,
+          ),
+        );
 
-          // Reset tick delay for next measurement
-          this.currentTickDelay = undefined;
-        }
+        // Reset tick delay for next measurement
+        this.currentTickDelay = undefined;
       }
 
       if (this.pendingStart < this.pendingUpdates.length) {
@@ -598,6 +601,9 @@ export class ClientGameRunner {
       this.serverTurnHighWater - this.lastProcessedTick,
     );
     this.backlogGrowing = this.backlogTurns > previousBacklog;
+    this.eventBus.emit(
+      new BacklogStatusEvent(this.backlogTurns, this.backlogGrowing),
+    );
   }
 
   private inputEvent(event: MouseUpEvent) {
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index bd95e7201..85039015d 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -136,6 +136,13 @@ export class TickMetricsEvent implements GameEvent {
   ) {}
 }
 
+export class BacklogStatusEvent implements GameEvent {
+  constructor(
+    public readonly backlogTurns: number,
+    public readonly backlogGrowing: boolean,
+  ) {}
+}
+
 export class InputHandler {
   private lastPointerX: number = 0;
   private lastPointerY: number = 0;
diff --git a/src/client/graphics/GameRenderer.ts b/src/client/graphics/GameRenderer.ts
index 1410cdbbd..97e4ad909 100644
--- a/src/client/graphics/GameRenderer.ts
+++ b/src/client/graphics/GameRenderer.ts
@@ -2,7 +2,10 @@ import { EventBus } from "../../core/EventBus";
 import { GameView } from "../../core/game/GameView";
 import { UserSettings } from "../../core/game/UserSettings";
 import { GameStartingModal } from "../GameStartingModal";
-import { RefreshGraphicsEvent as RedrawGraphicsEvent } from "../InputHandler";
+import {
+  BacklogStatusEvent,
+  RefreshGraphicsEvent as RedrawGraphicsEvent,
+} from "../InputHandler";
 import { FrameProfiler } from "./FrameProfiler";
 import { TransformHandler } from "./TransformHandler";
 import { UIState } from "./UIState";
@@ -292,6 +295,9 @@ export function createRenderer(
 
 export class GameRenderer {
   private context: CanvasRenderingContext2D;
+  private backlogTurns: number = 0;
+  private backlogGrowing: boolean = false;
+  private lastRenderTime: number = 0;
 
   constructor(
     private game: GameView,
@@ -309,6 +315,10 @@ export class GameRenderer {
 
   initialize() {
     this.eventBus.on(RedrawGraphicsEvent, () => this.redraw());
+    this.eventBus.on(BacklogStatusEvent, (event: BacklogStatusEvent) => {
+      this.backlogTurns = event.backlogTurns;
+      this.backlogGrowing = event.backlogGrowing;
+    });
     this.layers.forEach((l) => l.init?.());
 
     document.body.appendChild(this.canvas);
@@ -344,6 +354,28 @@ export class GameRenderer {
   }
 
   renderGame() {
+    const now = performance.now();
+
+    if (this.backlogTurns > 0) {
+      const BASE_FPS = 60;
+      const MIN_FPS = 20;
+      const BACKLOG_MAX_TURNS = 50;
+
+      const scale = Math.min(1, this.backlogTurns / BACKLOG_MAX_TURNS);
+      const targetFps = BASE_FPS - scale * (BASE_FPS - MIN_FPS);
+      const minFrameInterval = 1000 / targetFps;
+
+      if (this.lastRenderTime !== 0) {
+        const sinceLast = now - this.lastRenderTime;
+        if (sinceLast < minFrameInterval) {
+          requestAnimationFrame(() => this.renderGame());
+          return;
+        }
+      }
+    }
+
+    this.lastRenderTime = now;
+
     FrameProfiler.clear();
     const start = performance.now();
     // Set background

From 97e7dfc0f2b0053255f2f571562679f1a3b95c5f Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Tue, 25 Nov 2025 19:21:33 +0100
Subject: [PATCH 12/13] Add performance metrics for worker and render ticks

- Introduced new metrics in ClientGameRunner to track worker simulation ticks and render tick calls per second.
- Updated TickMetricsEvent to include these new metrics.
- Enhanced PerformanceOverlay to display worker and render ticks per second, improving performance monitoring capabilities.
- Adjusted minimum FPS in GameRenderer
---
 src/client/ClientGameRunner.ts                | 24 +++++++++++++++++
 src/client/InputHandler.ts                    |  6 ++++-
 src/client/graphics/GameRenderer.ts           |  2 +-
 .../graphics/layers/PerformanceOverlay.ts     | 26 +++++++++++++++++++
 4 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 4d70a3f3e..2e6a4f108 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -215,6 +215,9 @@ export class ClientGameRunner {
   private backlogTurns: number = 0;
   private backlogGrowing: boolean = false;
   private lastRenderedTick: number = 0;
+  private workerTicksSinceSample: number = 0;
+  private renderTicksSinceSample: number = 0;
+  private metricsSampleStart: number = 0;
 
   private pendingUpdates: GameUpdateViewData[] = [];
   private pendingStart = 0;
@@ -479,6 +482,7 @@ export class ClientGameRunner {
       while (this.pendingStart < this.pendingUpdates.length) {
         const gu = this.pendingUpdates[this.pendingStart++];
         processedCount++;
+        this.workerTicksSinceSample++;
         batch.push(gu);
 
         this.transport.turnComplete();
@@ -529,6 +533,24 @@ export class ClientGameRunner {
             : lastTick - this.lastRenderedTick;
         this.lastRenderedTick = lastTick;
 
+        this.renderTicksSinceSample++;
+
+        let workerTicksPerSecond: number | undefined;
+        let renderTicksPerSecond: number | undefined;
+        const now = performance.now();
+        if (this.metricsSampleStart === 0) {
+          this.metricsSampleStart = now;
+        } else {
+          const elapsedSeconds = (now - this.metricsSampleStart) / 1000;
+          if (elapsedSeconds > 0) {
+            workerTicksPerSecond = this.workerTicksSinceSample / elapsedSeconds;
+            renderTicksPerSecond = this.renderTicksSinceSample / elapsedSeconds;
+          }
+          this.metricsSampleStart = now;
+          this.workerTicksSinceSample = 0;
+          this.renderTicksSinceSample = 0;
+        }
+
         this.renderer.tick();
         this.eventBus.emit(
           new TickMetricsEvent(
@@ -536,6 +558,8 @@ export class ClientGameRunner {
             this.currentTickDelay,
             this.backlogTurns,
             ticksPerRender,
+            workerTicksPerSecond,
+            renderTicksPerSecond,
           ),
         );
 
diff --git a/src/client/InputHandler.ts b/src/client/InputHandler.ts
index 85039015d..dbae066ee 100644
--- a/src/client/InputHandler.ts
+++ b/src/client/InputHandler.ts
@@ -131,8 +131,12 @@ export class TickMetricsEvent implements GameEvent {
     public readonly tickDelay?: number,
     // Number of turns the client is behind the server (if known)
     public readonly backlogTurns?: number,
-    // Number of ticks applied since last render
+    // Number of simulation ticks applied since last render
     public readonly ticksPerRender?: number,
+    // Approximate worker simulation ticks per second
+    public readonly workerTicksPerSecond?: number,
+    // Approximate render tick() calls per second
+    public readonly renderTicksPerSecond?: number,
   ) {}
 }
 
diff --git a/src/client/graphics/GameRenderer.ts b/src/client/graphics/GameRenderer.ts
index 97e4ad909..c99a46014 100644
--- a/src/client/graphics/GameRenderer.ts
+++ b/src/client/graphics/GameRenderer.ts
@@ -358,7 +358,7 @@ export class GameRenderer {
 
     if (this.backlogTurns > 0) {
       const BASE_FPS = 60;
-      const MIN_FPS = 20;
+      const MIN_FPS = 10;
       const BACKLOG_MAX_TURNS = 50;
 
       const scale = Math.min(1, this.backlogTurns / BACKLOG_MAX_TURNS);
diff --git a/src/client/graphics/layers/PerformanceOverlay.ts b/src/client/graphics/layers/PerformanceOverlay.ts
index 531f19f0b..64499024f 100644
--- a/src/client/graphics/layers/PerformanceOverlay.ts
+++ b/src/client/graphics/layers/PerformanceOverlay.ts
@@ -234,6 +234,8 @@ export class PerformanceOverlay extends LitElement implements Layer {
         event.tickDelay,
         event.backlogTurns,
         event.ticksPerRender,
+        event.workerTicksPerSecond,
+        event.renderTicksPerSecond,
       );
     });
   }
@@ -429,11 +431,19 @@ export class PerformanceOverlay extends LitElement implements Layer {
   @state()
   private ticksPerRender: number = 0;
 
+  @state()
+  private workerTicksPerSecond: number = 0;
+
+  @state()
+  private renderTicksPerSecond: number = 0;
+
   updateTickMetrics(
     tickExecutionDuration?: number,
     tickDelay?: number,
     backlogTurns?: number,
     ticksPerRender?: number,
+    workerTicksPerSecond?: number,
+    renderTicksPerSecond?: number,
   ) {
     if (!this.isVisible || !this.userSettings.performanceOverlay()) return;
 
@@ -479,6 +489,14 @@ export class PerformanceOverlay extends LitElement implements Layer {
       this.ticksPerRender = ticksPerRender;
     }
 
+    if (workerTicksPerSecond !== undefined) {
+      this.workerTicksPerSecond = workerTicksPerSecond;
+    }
+
+    if (renderTicksPerSecond !== undefined) {
+      this.renderTicksPerSecond = renderTicksPerSecond;
+    }
+
     this.requestUpdate();
   }
 
@@ -624,6 +642,14 @@ export class PerformanceOverlay extends LitElement implements Layer {
           <span>${this.tickDelayAvg.toFixed(2)}ms</span>
           (max: <span>${this.tickDelayMax}ms</span>)
         </div>
+        <div class="performance-line">
+          Worker ticks/s:
+          <span>${this.workerTicksPerSecond.toFixed(1)}</span>
+        </div>
+        <div class="performance-line">
+          Render ticks/s:
+          <span>${this.renderTicksPerSecond.toFixed(1)}</span>
+        </div>
         <div class="performance-line">
           Ticks per render:
           <span>${this.ticksPerRender}</span>

From cb7c94efb8a9c908ca72662d29e042c55b790507 Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Tue, 25 Nov 2025 21:22:13 +0100
Subject: [PATCH 13/13] SAB+Atomics refactor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added src/core/worker/SharedTileRing.ts, which defines a SharedArrayBuffer-backed ring buffer (SharedTileRingBuffers/SharedTileRingViews) and helpers pushTileUpdate (worker-side writer) and drainTileUpdates (main-thread reader) using Atomics.

Extended GameRunner (src/core/GameRunner.ts) with an optional tileUpdateSink?: (update: bigint) => void; when provided, tile updates are sent to the sink instead of being packed into GameUpdateViewData.packedTileUpdates (those become an empty BigUint64Array in this mode).

Extended the worker protocol (src/core/worker/WorkerMessages.ts) so the init message can optionally carry sharedTileRingHeader and sharedTileRingData (the two SABs for the ring).

Updated WorkerClient (src/core/worker/WorkerClient.ts) to accept optional SharedTileRingBuffers in its constructor and, during initialize(), include those SABs in the init message sent to Worker.worker.ts.

Updated the worker implementation (src/core/worker/Worker.worker.ts) to build sharedTileRing views from the SABs on "init" and pass a (update: bigint) => pushTileUpdate(...) sink into createGameRunner, so every tile update from the simulation goes into the shared ring instead of the message payload.

Updated the client side (src/client/ClientGameRunner.ts):
In createClientGame, when SharedArrayBuffer/Atomics are available and crossOriginIsolated is true, it allocates the ring (createSharedTileRingBuffers with capacity 262144), creates views, passes buffers into WorkerClient, and keeps the views in ClientGameRunner.
ClientGameRunner now has a tileRingViews field and, in mergeGameUpdates, if the ring is present it ignores gu.packedTileUpdates and instead drains up to MAX_TILE_UPDATES_PER_RENDER (100 000) tile updates from the SAB ring into combinedPackedTileUpdates before constructing the merged GameUpdateViewData passed to GameView.update.
If SABs are unavailable, it falls back to the original behaviour (packing gu.packedTileUpdates from messages), so the feature is opt-in and backward compatible.

Net effect: when the page is cross-origin isolated, the worker no longer sends per-tick BigUint64Array tile payloads via postMessage; it streams tile updates into a shared ring buffer, and the main thread pulls and applies them at its own pace while still batching non-tile updates and rendering exactly as before. If you’d like, I can next run the existing tests/build in your environment to sanity-check everything.
---
 src/client/ClientGameRunner.ts    | 50 +++++++++++++++++--
 src/core/GameRunner.ts            | 20 ++++++--
 src/core/worker/SharedTileRing.ts | 79 +++++++++++++++++++++++++++++++
 src/core/worker/Worker.worker.ts  | 18 +++++++
 src/core/worker/WorkerClient.ts   |  4 ++
 src/core/worker/WorkerMessages.ts |  2 +
 6 files changed, 167 insertions(+), 6 deletions(-)
 create mode 100644 src/core/worker/SharedTileRing.ts

diff --git a/src/client/ClientGameRunner.ts b/src/client/ClientGameRunner.ts
index 2e6a4f108..eb1088c66 100644
--- a/src/client/ClientGameRunner.ts
+++ b/src/client/ClientGameRunner.ts
@@ -25,6 +25,13 @@ import {
 import { GameView, PlayerView } from "../core/game/GameView";
 import { loadTerrainMap, TerrainMapData } from "../core/game/TerrainMapLoader";
 import { UserSettings } from "../core/game/UserSettings";
+import {
+  createSharedTileRingBuffers,
+  createSharedTileRingViews,
+  drainTileUpdates,
+  SharedTileRingBuffers,
+  SharedTileRingViews,
+} from "../core/worker/SharedTileRing";
 import { WorkerClient } from "../core/worker/WorkerClient";
 import {
   AutoUpgradeEvent,
@@ -162,9 +169,30 @@ async function createClientGame(
       mapLoader,
     );
   }
+
+  let sharedTileRingBuffers: SharedTileRingBuffers | undefined;
+  let sharedTileRingViews: SharedTileRingViews | null = null;
+  const isIsolated =
+    typeof (globalThis as any).crossOriginIsolated === "boolean"
+      ? (globalThis as any).crossOriginIsolated === true
+      : false;
+  const canUseSharedBuffers =
+    typeof SharedArrayBuffer !== "undefined" &&
+    typeof Atomics !== "undefined" &&
+    isIsolated;
+
+  if (canUseSharedBuffers) {
+    // Capacity is number of tile updates that can be queued.
+    // This is a compromise between memory usage and backlog tolerance.
+    const TILE_RING_CAPACITY = 262144;
+    sharedTileRingBuffers = createSharedTileRingBuffers(TILE_RING_CAPACITY);
+    sharedTileRingViews = createSharedTileRingViews(sharedTileRingBuffers);
+  }
+
   const worker = new WorkerClient(
     lobbyConfig.gameStartInfo,
     lobbyConfig.clientID,
+    sharedTileRingBuffers,
   );
   await worker.initialize();
   const gameView = new GameView(
@@ -191,6 +219,7 @@ async function createClientGame(
     transport,
     worker,
     gameView,
+    sharedTileRingViews,
   );
 }
 
@@ -222,6 +251,7 @@ export class ClientGameRunner {
   private pendingUpdates: GameUpdateViewData[] = [];
   private pendingStart = 0;
   private isProcessingUpdates = false;
+  private tileRingViews: SharedTileRingViews | null;
 
   constructor(
     private lobby: LobbyConfig,
@@ -231,8 +261,10 @@ export class ClientGameRunner {
     private transport: Transport,
     private worker: WorkerClient,
     private gameView: GameView,
+    tileRingViews: SharedTileRingViews | null,
   ) {
     this.lastMessageTime = Date.now();
+    this.tileRingViews = tileRingViews;
   }
 
   private saveGame(update: WinUpdate) {
@@ -603,9 +635,21 @@ export class ClientGameRunner {
         const updatesForType = gu.updates[type] as unknown as any[];
         (combinedUpdates[type] as unknown as any[]).push(...updatesForType);
       }
-      gu.packedTileUpdates.forEach((tu) => {
-        combinedPackedTileUpdates.push(tu);
-      });
+    }
+
+    if (this.tileRingViews) {
+      const MAX_TILE_UPDATES_PER_RENDER = 100000;
+      drainTileUpdates(
+        this.tileRingViews,
+        MAX_TILE_UPDATES_PER_RENDER,
+        combinedPackedTileUpdates,
+      );
+    } else {
+      for (const gu of batch) {
+        gu.packedTileUpdates.forEach((tu) => {
+          combinedPackedTileUpdates.push(tu);
+        });
+      }
     }
 
     return {
diff --git a/src/core/GameRunner.ts b/src/core/GameRunner.ts
index d6de468fb..dc1b03b51 100644
--- a/src/core/GameRunner.ts
+++ b/src/core/GameRunner.ts
@@ -37,6 +37,7 @@ export async function createGameRunner(
   clientID: ClientID,
   mapLoader: GameMapLoader,
   callBack: (gu: GameUpdateViewData | ErrorUpdate) => void,
+  tileUpdateSink?: (update: bigint) => void,
 ): Promise<GameRunner> {
   const config = await getConfig(gameStart.config, null);
   const gameMap = await loadGameMap(
@@ -81,6 +82,7 @@ export async function createGameRunner(
     game,
     new Executor(game, gameStart.gameID, clientID),
     callBack,
+    tileUpdateSink,
   );
   gr.init();
   return gr;
@@ -97,6 +99,7 @@ export class GameRunner {
     public game: Game,
     private execManager: Executor,
     private callBack: (gu: GameUpdateViewData | ErrorUpdate) => void,
+    private tileUpdateSink?: (update: bigint) => void,
   ) {}
 
   init() {
@@ -171,13 +174,24 @@ export class GameRunner {
       });
     }
 
-    // Many tiles are updated to pack it into an array
-    const packedTileUpdates = updates[GameUpdateType.Tile].map((u) => u.update);
+    // Many tiles are updated; either publish them via a shared sink or pack
+    // them into the view data.
+    let packedTileUpdates: BigUint64Array;
+    const tileUpdates = updates[GameUpdateType.Tile];
+    if (this.tileUpdateSink !== undefined) {
+      for (const u of tileUpdates) {
+        this.tileUpdateSink(u.update);
+      }
+      packedTileUpdates = new BigUint64Array();
+    } else {
+      const raw = tileUpdates.map((u) => u.update);
+      packedTileUpdates = new BigUint64Array(raw);
+    }
     updates[GameUpdateType.Tile] = [];
 
     this.callBack({
       tick: this.game.ticks(),
-      packedTileUpdates: new BigUint64Array(packedTileUpdates),
+      packedTileUpdates,
       updates: updates,
       playerNameViewData: this.playerViewData,
       tickExecutionDuration: tickExecutionDuration,
diff --git a/src/core/worker/SharedTileRing.ts b/src/core/worker/SharedTileRing.ts
new file mode 100644
index 000000000..0d8d0c331
--- /dev/null
+++ b/src/core/worker/SharedTileRing.ts
@@ -0,0 +1,79 @@
+export interface SharedTileRingBuffers {
+  header: SharedArrayBuffer;
+  data: SharedArrayBuffer;
+}
+
+export interface SharedTileRingViews {
+  header: Int32Array;
+  buffer: BigUint64Array;
+  capacity: number;
+}
+
+// Header indices
+export const TILE_RING_HEADER_WRITE_INDEX = 0;
+export const TILE_RING_HEADER_READ_INDEX = 1;
+export const TILE_RING_HEADER_OVERFLOW = 2;
+
+export function createSharedTileRingBuffers(
+  capacity: number,
+): SharedTileRingBuffers {
+  const header = new SharedArrayBuffer(3 * Int32Array.BYTES_PER_ELEMENT);
+  const data = new SharedArrayBuffer(
+    capacity * BigUint64Array.BYTES_PER_ELEMENT,
+  );
+  return { header, data };
+}
+
+export function createSharedTileRingViews(
+  buffers: SharedTileRingBuffers,
+): SharedTileRingViews {
+  const header = new Int32Array(buffers.header);
+  const buffer = new BigUint64Array(buffers.data);
+  return {
+    header,
+    buffer,
+    capacity: buffer.length,
+  };
+}
+
+export function pushTileUpdate(
+  views: SharedTileRingViews,
+  value: bigint,
+): void {
+  const { header, buffer, capacity } = views;
+
+  const write = Atomics.load(header, TILE_RING_HEADER_WRITE_INDEX);
+  const read = Atomics.load(header, TILE_RING_HEADER_READ_INDEX);
+  const nextWrite = (write + 1) % capacity;
+
+  // If the buffer is full, advance read (drop oldest) and mark overflow.
+  if (nextWrite === read) {
+    Atomics.store(header, TILE_RING_HEADER_OVERFLOW, 1);
+    const nextRead = (read + 1) % capacity;
+    Atomics.store(header, TILE_RING_HEADER_READ_INDEX, nextRead);
+  }
+
+  buffer[write] = value;
+  Atomics.store(header, TILE_RING_HEADER_WRITE_INDEX, nextWrite);
+}
+
+export function drainTileUpdates(
+  views: SharedTileRingViews,
+  maxItems: number,
+  out: bigint[],
+): void {
+  const { header, buffer, capacity } = views;
+
+  let read = Atomics.load(header, TILE_RING_HEADER_READ_INDEX);
+  const write = Atomics.load(header, TILE_RING_HEADER_WRITE_INDEX);
+
+  let count = 0;
+
+  while (read !== write && count < maxItems) {
+    out.push(buffer[read]);
+    read = (read + 1) % capacity;
+    count++;
+  }
+
+  Atomics.store(header, TILE_RING_HEADER_READ_INDEX, read);
+}
diff --git a/src/core/worker/Worker.worker.ts b/src/core/worker/Worker.worker.ts
index a6bb92510..3c1164849 100644
--- a/src/core/worker/Worker.worker.ts
+++ b/src/core/worker/Worker.worker.ts
@@ -2,6 +2,11 @@ import version from "../../../resources/version.txt";
 import { createGameRunner, GameRunner } from "../GameRunner";
 import { FetchGameMapLoader } from "../game/FetchGameMapLoader";
 import { ErrorUpdate, GameUpdateViewData } from "../game/GameUpdates";
+import {
+  createSharedTileRingViews,
+  pushTileUpdate,
+  SharedTileRingViews,
+} from "./SharedTileRing";
 import {
   AttackAveragePositionResultMessage,
   InitializedMessage,
@@ -17,6 +22,7 @@ const ctx: Worker = self as any;
 let gameRunner: Promise<GameRunner> | null = null;
 const mapLoader = new FetchGameMapLoader(`/maps`, version);
 let isProcessingTurns = false;
+let sharedTileRing: SharedTileRingViews | null = null;
 
 function gameUpdate(gu: GameUpdateViewData | ErrorUpdate) {
   // skip if ErrorUpdate
@@ -62,11 +68,23 @@ ctx.addEventListener("message", async (e: MessageEvent<MainThreadMessage>) => {
   switch (message.type) {
     case "init":
       try {
+        if (message.sharedTileRingHeader && message.sharedTileRingData) {
+          sharedTileRing = createSharedTileRingViews({
+            header: message.sharedTileRingHeader,
+            data: message.sharedTileRingData,
+          });
+        } else {
+          sharedTileRing = null;
+        }
+
         gameRunner = createGameRunner(
           message.gameStartInfo,
           message.clientID,
           mapLoader,
           gameUpdate,
+          sharedTileRing
+            ? (update: bigint) => pushTileUpdate(sharedTileRing!, update)
+            : undefined,
         ).then((gr) => {
           sendMessage({
             type: "initialized",
diff --git a/src/core/worker/WorkerClient.ts b/src/core/worker/WorkerClient.ts
index 4edc97dee..6df22a933 100644
--- a/src/core/worker/WorkerClient.ts
+++ b/src/core/worker/WorkerClient.ts
@@ -9,6 +9,7 @@ import { TileRef } from "../game/GameMap";
 import { ErrorUpdate, GameUpdateViewData } from "../game/GameUpdates";
 import { ClientID, GameStartInfo, Turn } from "../Schemas";
 import { generateID } from "../Util";
+import { SharedTileRingBuffers } from "./SharedTileRing";
 import { WorkerMessage } from "./WorkerMessages";
 
 export class WorkerClient {
@@ -22,6 +23,7 @@ export class WorkerClient {
   constructor(
     private gameStartInfo: GameStartInfo,
     private clientID: ClientID,
+    private sharedTileRingBuffers?: SharedTileRingBuffers,
   ) {
     this.worker = new Worker(new URL("./Worker.worker.ts", import.meta.url));
     this.messageHandlers = new Map();
@@ -70,6 +72,8 @@ export class WorkerClient {
         id: messageId,
         gameStartInfo: this.gameStartInfo,
         clientID: this.clientID,
+        sharedTileRingHeader: this.sharedTileRingBuffers?.header,
+        sharedTileRingData: this.sharedTileRingBuffers?.data,
       });
 
       // Add timeout for initialization
diff --git a/src/core/worker/WorkerMessages.ts b/src/core/worker/WorkerMessages.ts
index 0c5344da1..23a5ead5d 100644
--- a/src/core/worker/WorkerMessages.ts
+++ b/src/core/worker/WorkerMessages.ts
@@ -35,6 +35,8 @@ export interface InitMessage extends BaseWorkerMessage {
   type: "init";
   gameStartInfo: GameStartInfo;
   clientID: ClientID;
+  sharedTileRingHeader?: SharedArrayBuffer;
+  sharedTileRingData?: SharedArrayBuffer;
 }
 
 export interface TurnMessage extends BaseWorkerMessage {