Files
OpenFrontIO/src/core/worker/WorkerClient.ts
T
scamiv 9fc11b7b9a perf(worker): remove heartbeat; batch game updates (#3308)
## Description:
Removes the client-driven heartbeat loop and switches worker tick
execution to a worker-owned drain scheduler with batched game update
delivery.

## Why
The previous flow required the client to send a `heartbeat` every
animation frame just to keep the worker progressing turns. That had two
costs:

1. Simulation progress was coupled to browser frame cadence.
2. Catch-up periods produced many single `game_update` messages,
increasing message overhead and main-thread wakeups.

## What Changed

### 1) Remove heartbeat protocol
- Deleted `heartbeat` from `WorkerMessageType`.
- Removed `HeartbeatMessage` from `MainThreadMessage`.
- Removed `sendHeartbeat()` from `WorkerClient`.
- Removed the `requestAnimationFrame` keep-alive loop in
`ClientGameRunner`.

Files:
- `src/client/ClientGameRunner.ts`
- `src/core/worker/WorkerClient.ts`
- `src/core/worker/WorkerMessages.ts`
- `src/core/worker/Worker.worker.ts`

### 2) Add batched worker-to-client updates
- Added `game_update_batch` message type and `GameUpdateBatchMessage`.
- Worker now emits one batch message containing multiple tick updates.
- `WorkerClient` handles `game_update_batch` by replaying updates to the
existing callback in order.

Files:
- `src/core/worker/WorkerMessages.ts`
- `src/core/worker/WorkerClient.ts`

### 3) Move tick draining into worker
- Added a scheduler (`scheduleDrain`) and drain loop (`drain`) in
`Worker.worker.ts`.
- On each `turn` message, worker enqueues turn and schedules drain.
- Drain executes up to `MAX_TICKS_BEFORE_YIELD = 4` ticks per cycle,
then yields with `setTimeout(..., 0)`.
- Tick updates are collected into a batch and sent once with
transferables:
  - `packedTileUpdates.buffer`
  - `packedMotionPlans.buffer` (when present)
- If backlog remains, drain reschedules itself.

File:
- `src/core/worker/Worker.worker.ts`

## Behavioral Notes
- No server protocol changes.
- Ggame update callback contract remains the same (still receives one
`GameUpdateViewData` at a time in order).
- Ordering is preserved: `WorkerClient` iterates batch entries in
sequence.
- Error updates are still filtered from update delivery in the worker
batch path (same effective behavior as before for normal update flow).

## Expected Impact
- Fewer `postMessage` calls during backlog and burst turn delivery.
- Lower message overhead and fewer main-thread interrupts.
- Less dependence on UI frame timing for worker progress.
- Better catch-up stability due to explicit periodic yielding.

## Risk Areas
- Drain scheduling edge cases (re-entrancy / lost wake-ups).
- Mitigated with `drainScheduled`, `draining`, and `drainRequested`
flags.
- Larger per-message payloads due to batching.
  - Bounded by `MAX_TICKS_BEFORE_YIELD`.
- Any assumptions in downstream code about receiving only `game_update`.
  - Handled by adding `game_update_batch` support in `WorkerClient`.

## Please complete the following:

- [x] I have added screenshots for all UI updates
- [x] I process any text displayed to the user through translateText()
and I've added it to the en.json file
- [x] I have added relevant tests to the test directory
- [x] I confirm I have thoroughly tested these changes and take full
responsibility for any bugs introduced

## Please put your Discord username so you can be contacted if a bug or
regression is found:

DISCORD_USERNAME
2026-02-28 21:58:32 +00:00

270 lines
6.5 KiB
TypeScript

import {
Cell,
PlayerActions,
PlayerBorderTiles,
PlayerID,
PlayerProfile,
UnitType,
} from "../game/Game";
import { TileRef } from "../game/GameMap";
import { ErrorUpdate, GameUpdateViewData } from "../game/GameUpdates";
import { ClientID, GameStartInfo, Turn } from "../Schemas";
import { generateID } from "../Util";
import { WorkerMessage } from "./WorkerMessages";
export class WorkerClient {
private worker: Worker;
private isInitialized = false;
private messageHandlers: Map<string, (message: WorkerMessage) => void>;
private gameUpdateCallback?: (
update: GameUpdateViewData | ErrorUpdate,
) => void;
constructor(
private gameStartInfo: GameStartInfo,
private clientID: ClientID,
) {
this.worker = new Worker(new URL("./Worker.worker.ts", import.meta.url), {
type: "module",
});
this.messageHandlers = new Map();
// Set up global message handler
this.worker.addEventListener(
"message",
this.handleWorkerMessage.bind(this),
);
}
private handleWorkerMessage(event: MessageEvent<WorkerMessage>) {
const message = event.data;
switch (message.type) {
case "game_update":
if (this.gameUpdateCallback && message.gameUpdate) {
this.gameUpdateCallback(message.gameUpdate);
}
break;
case "game_update_batch":
if (this.gameUpdateCallback && message.gameUpdates) {
for (const gu of message.gameUpdates) {
this.gameUpdateCallback(gu);
}
}
break;
case "initialized":
default:
if (message.id && this.messageHandlers.has(message.id)) {
const handler = this.messageHandlers.get(message.id)!;
handler(message);
this.messageHandlers.delete(message.id);
}
break;
}
}
initialize(): Promise<void> {
return new Promise((resolve, reject) => {
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (message.type === "initialized") {
this.isInitialized = true;
resolve();
}
});
this.worker.postMessage({
type: "init",
id: messageId,
gameStartInfo: this.gameStartInfo,
clientID: this.clientID,
});
// Add timeout for initialization
setTimeout(() => {
if (!this.isInitialized) {
this.messageHandlers.delete(messageId);
reject(new Error("Worker initialization timeout"));
}
}, 20000); // 20 second timeout
});
}
start(gameUpdate: (gu: GameUpdateViewData | ErrorUpdate) => void) {
if (!this.isInitialized) {
throw new Error("Failed to initialize pathfinder");
}
this.gameUpdateCallback = gameUpdate;
}
sendTurn(turn: Turn) {
if (!this.isInitialized) {
throw new Error("Worker not initialized");
}
this.worker.postMessage({
type: "turn",
turn,
});
}
playerProfile(playerID: number): Promise<PlayerProfile> {
return new Promise((resolve, reject) => {
if (!this.isInitialized) {
reject(new Error("Worker not initialized"));
return;
}
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (
message.type === "player_profile_result" &&
message.result !== undefined
) {
resolve(message.result);
}
});
this.worker.postMessage({
type: "player_profile",
id: messageId,
playerID: playerID,
});
});
}
playerBorderTiles(playerID: PlayerID): Promise<PlayerBorderTiles> {
return new Promise((resolve, reject) => {
if (!this.isInitialized) {
reject(new Error("Worker not initialized"));
return;
}
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (
message.type === "player_border_tiles_result" &&
message.result !== undefined
) {
resolve(message.result);
}
});
this.worker.postMessage({
type: "player_border_tiles",
id: messageId,
playerID: playerID,
});
});
}
playerInteraction(
playerID: PlayerID,
x?: number,
y?: number,
units?: UnitType[],
): Promise<PlayerActions> {
return new Promise((resolve, reject) => {
if (!this.isInitialized) {
reject(new Error("Worker not initialized"));
return;
}
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (
message.type === "player_actions_result" &&
message.result !== undefined
) {
resolve(message.result);
}
});
this.worker.postMessage({
type: "player_actions",
id: messageId,
playerID,
x,
y,
units,
});
});
}
attackAveragePosition(
playerID: number,
attackID: string,
): Promise<Cell | null> {
return new Promise((resolve, reject) => {
if (!this.isInitialized) {
reject(new Error("Worker not initialized"));
return;
}
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (
message.type === "attack_average_position_result" &&
message.x !== undefined &&
message.y !== undefined
) {
if (message.x === null || message.y === null) {
resolve(null);
} else {
resolve(new Cell(message.x, message.y));
}
}
});
this.worker.postMessage({
type: "attack_average_position",
id: messageId,
playerID: playerID,
attackID: attackID,
});
});
}
transportShipSpawn(
playerID: PlayerID,
targetTile: TileRef,
): Promise<TileRef | false> {
return new Promise((resolve, reject) => {
if (!this.isInitialized) {
reject(new Error("Worker not initialized"));
return;
}
const messageId = generateID();
this.messageHandlers.set(messageId, (message) => {
if (
message.type === "transport_ship_spawn_result" &&
message.result !== undefined
) {
resolve(message.result);
}
});
this.worker.postMessage({
type: "transport_ship_spawn",
id: messageId,
playerID: playerID,
targetTile: targetTile,
});
});
}
cleanup() {
this.worker.terminate();
this.messageHandlers.clear();
this.gameUpdateCallback = undefined;
}
}