ugly-game 0.7.1 → 0.7.2

package/dist/loop/controlBlock.d.ts

@@ -30,6 +30,12 @@ export interface ControlView<S extends string> {
     raw(): Int32Array;
     /** Atomically read-and-zero STEP_BUDGET — the worker consumes the burst so it can't be applied twice. */
     takeStepBudget(): number;
+    /** Atomically add to the LATE counter — the worker flags each command that arrived after its tick (co-op
+     *  divergence signal). Add (not store) so concurrent late flags in one batch accumulate. */
+    addLate(n: number): void;
+    /** Atomically read-and-zero LATE — the main thread drains the divergence count each frame without racing the
+     *  worker's adds (an `exchange`, so an add landing between read and reset is never lost). */
+    takeLate(): number;
     /** Spin-wait (bounded) until PAUSED reaches `target`; returns true if it did. Main-thread safe (no Atomics.wait). */
     waitPaused(target: boolean, spinMax?: number): boolean;
     notify(slot: number): void;

package/dist/loop/controlBlock.js

@@ -104,6 +104,13 @@ export function createControlView(buf, scalarNames) {
         takeStepBudget() {
             return Atomics.exchange(a, H.STEP_BUDGET, 0);
         },
+        addLate(n) {
+            if (n)
+                Atomics.add(a, H.LATE, n | 0);
+        },
+        takeLate() {
+            return Atomics.exchange(a, H.LATE, 0);
+        },
         scalar(name) {
             const slot = idx.get(name);
             if (slot === undefined) {

package/dist/loop/simCore.d.ts

@@ -21,6 +21,10 @@ export interface CoopStepOpts<S, I> {
     tickOf: (s: S) => number;
     maxCatchUpFrames?: number;
     onLate?: (count: number) => void;
+    /** Called once per tick, with the commands due THIS tick, immediately before `sim.tick`. The seam a game uses
+     *  to drive per-tick co-op diagnostics (a command journal + a checkpoint hash trail) without the primitive
+     *  needing to know their shape. `state` is passed so a checkpoint can hash it (at the top of the tick). */
+    beforeTick?: (due: I[], state: S) => void;
 }
 export interface SoloStepOpts<S, I> {
     sim: SimHostSim<S, I>;
@@ -34,6 +38,8 @@ export interface SoloStepOpts<S, I> {
     };
     fps?: number;
     maxCatchUpFrames?: number;
+    onLate?: (count: number) => void;
+    beforeTick?: (due: I[], state: S) => void;
 }
 /** Single-player stepping: derive a target tick from elapsed wall time (a free-run 60-UPS accumulator, clamped by
  *  maxCatchUpFrames), publish it to `ctl.targetTick`, then reuse `coopStepBatch` — so solo and co-op run the identical

package/dist/loop/simCore.js

@@ -20,6 +20,8 @@ export function soloStepBatch(opts, acc) {
         queue: opts.queue,
         tickOf: opts.tickOf,
         maxCatchUpFrames: maxCatch,
+        ...(opts.onLate ? { onLate: opts.onLate } : {}),
+        ...(opts.beforeTick ? { beforeTick: opts.beforeTick } : {}),
     });
     if (stepped > 0)
         opts.ctl.ups = Math.round(stepped / Math.max(elapsed, T)) || opts.ctl.ups;
@@ -43,7 +45,12 @@ export function coopStepBatch(opts) {
             if (late && opts.onLate)
                 opts.onLate(late);
         }
-        opts.sim.tick(opts.state, due.map((d) => d.c));
+        const inputs = due.map((d) => d.c);
+        // Per-tick diagnostics seam: the game records the applied stream + a checkpoint hash of the top-of-tick state,
+        // BEFORE the tick mutates it. Fires every tick (solo + co-op) so a journal can't silently skip history.
+        if (opts.beforeTick)
+            opts.beforeTick(inputs, opts.state);
+        opts.sim.tick(opts.state, inputs);
         stepped++;
     };
     // STEP_BUDGET burst first (forced, deterministic — independent of the target).

package/dist/loop/simHost.d.ts

@@ -3,6 +3,7 @@ import { type ControlView } from './controlBlock';
 import { type SimClock, type SimHostSim } from './simCore';
 import { type Lockstep, type LockstepTransport, type LockstepClock } from './lockstep';
 import type { NetAdapter } from './gameLoop';
+import type { SimWorkerReply } from './simHost.worker';
 export interface WorkerLike {
     postMessage(m: unknown): void;
     onmessage: ((e: {
@@ -17,6 +18,7 @@ export interface CoopOpts {
     hashEvery?: number;
     onNeedSnap?: (from: string) => void;
     onSnapReady?: (from: string) => void;
+    onLate?: (n: number) => void;
 }
 export interface SimHostOpts<State, Input> {
     layout: Layout<State>;
@@ -35,6 +37,8 @@ export interface SimHostOpts<State, Input> {
     initParams?: Record<string, unknown>;
 }
 export interface SimHost<State, Input> {
+    /** The live sim state view. In the worker path it's a zero-copy SAB view the worker mutates; a world-swap
+     *  (`reinit`) re-points it, so read it fresh each frame rather than capturing it once. */
     readonly state: State;
     readonly available: boolean;
     send(input: Input): void;
@@ -43,8 +47,22 @@ export interface SimHost<State, Input> {
     hash(): string;
     netAdapter(): NetAdapter;
     lockstep?: Lockstep<Input>;
+    /** Call once per rendered frame. Co-op: publishes the server-derived `targetTick`, emits the probe hash on the
+     *  grid, and drains the LATE divergence count (→ `coop.onLate`). In the fallback (no-worker) path it also steps
+     *  the sim to `nowMs`. A worker-backed solo host needs no per-frame call, but calling `frame` is harmless. */
+    frame(nowMs: number): void;
+    /** Swap the whole world (new game / load / resync) to `fill` over a fresh buffer of `layout`'s size. `resync`
+     *  keeps in-flight future commands (drops applied history); otherwise the command stream restarts. */
+    reinit(layout: Layout<State>, fill: (s: State) => void, opts?: {
+        resync?: boolean;
+        initParams?: Record<string, unknown>;
+    }): void;
+    /** Round-trip a message to the worker and await its reply (echoing `rid`). Resolves `null` in the fallback path
+     *  (no worker) or on timeout — the caller computes a degraded answer locally. */
+    request(msg: Record<string, unknown>): Promise<SimWorkerReply | null>;
     stop(): void;
-    /** Fallback/test only: advance the main-thread sim to wall time `nowMs`. Undefined when a worker owns stepping. */
+    /** Fallback/test only: advance the main-thread sim to wall time `nowMs`. Undefined when a worker owns stepping.
+     *  Retained for existing callers/tests; `frame` supersedes it. */
     pump?(nowMs: number): void;
 }
 export declare function createSimHost<State, Input>(opts: SimHostOpts<State, Input>): SimHost<State, Input>;

package/dist/loop/simHost.js

@@ -15,7 +15,7 @@ export function createSimHost(opts) {
     const ctlBuf = useWorker
         ? new SharedArrayBuffer(controlByteLength(scalars))
         : new ArrayBuffer(controlByteLength(scalars));
-    const state = opts.layout.attach(dataBuf);
+    let state = opts.layout.attach(dataBuf); // `let`: a world-swap (reinit) re-points this at a fresh buffer's view
     const ctl = createControlView(ctlBuf, scalars);
     opts.seed?.(state);
     const clock = opts.clock ?? { now: () => Date.now() };
@@ -24,16 +24,28 @@ export function createSimHost(opts) {
     const sampled = new Map(); // our probe hash per grid tick (for divergence compare)
     let lastHash = opts.sim.hash(state);
     // ── Worker path ──────────────────────────────────────────────
+    // request()/reply round-trip: the game's worker `onMessage` answers a diagnostics request by posting a reply that
+    // echoes `rid`; we resolve the matching pending Promise here. Keyed on `rid` alone, so it's oblivious to payload.
+    let reqSeq = 0;
+    const reqWait = new Map();
     let worker = null;
     if (useWorker && opts.worker) {
         worker = opts.worker();
         worker.onmessage = (e) => {
             const m = e.data;
-            if (m.t === 'hash' && typeof m.hash === 'string') {
-                lastHash = m.hash;
-                if (typeof m.tick === 'number')
-                    sampled.set(m.tick, m.hash);
+            if (typeof m.rid === 'number') {
+                const r = reqWait.get(m.rid);
+                if (r) {
+                    reqWait.delete(m.rid);
+                    r(m);
+                }
+                return;
             }
+            // The worker's posted hash is the FULL digest → keep host.hash() cheap. Deliberately NOT written into
+            // `sampled`: co-op compares the PROBE hash (sampled on the main thread in `drive`), and mixing the two oracles
+            // would report perpetual divergence.
+            if (m.t === 'hash' && typeof m.hash === 'string')
+                lastHash = m.hash;
         };
         worker.postMessage({
             t: 'init',
@@ -70,28 +82,36 @@ export function createSimHost(opts) {
         });
         ctl.coop = true;
     }
-    // ── Fallback path (main-thread stepping) ─────────────────────
+    // ── Per-frame driver ─────────────────────────────────────────
+    // Co-op bookkeeping runs on the MAIN thread from the shared state, so the local sample and the value sent to
+    // peers are the SAME oracle (`probe`): the worker's own posted hash is the FULL digest, used only for host.hash()
+    // — mixing it into `sampled` would compare full-vs-probe and cry divergence forever. In the fallback path this
+    // same driver also steps the sim (there's no worker to do it).
     const lastRef = { t: clock.now() };
     let acc = 0;
     const hashEvery = opts.coop?.hashEvery ?? 600;
-    const pump = (nowMs) => {
-        const drivenClock = { now: () => nowMs };
+    const drive = (nowMs, doStep) => {
         if (lockstep) {
-            const tk = opts.tickOf(state);
-            if (tk % hashEvery === 0)
+            const tk = worker ? ctl.tick : opts.tickOf(state);
+            if (tk % hashEvery === 0 && !sampled.has(tk))
                 sampled.set(tk, probe());
             ctl.targetTick = lockstep.targetTick();
             lockstep.onFrame(tk);
-            coopStepBatch({
-                sim: opts.sim,
-                state,
-                ctl,
-                queue,
-                tickOf: opts.tickOf,
-                maxCatchUpFrames: opts.maxCatchUpFrames ?? 30,
-            });
+            if (doStep)
+                coopStepBatch({
+                    sim: opts.sim,
+                    state,
+                    ctl,
+                    queue,
+                    tickOf: opts.tickOf,
+                    maxCatchUpFrames: opts.maxCatchUpFrames ?? 30,
+                });
+            const late = ctl.takeLate();
+            if (late > 0)
+                opts.coop?.onLate?.(late);
         }
-        else {
+        else if (doStep) {
+            const drivenClock = { now: () => nowMs };
             acc = soloStepBatch({
                 sim: opts.sim,
                 state,
@@ -104,7 +124,11 @@ export function createSimHost(opts) {
                 maxCatchUpFrames: opts.maxCatchUpFrames,
             }, acc);
         }
-        lastHash = opts.sim.hash(state);
+        if (!worker)
+            lastHash = opts.sim.hash(state); // worker keeps lastHash fresh via its posted 'hash' messages
+    };
+    const frame = (nowMs) => {
+        drive(nowMs, !worker); // worker steps itself; fallback steps in-frame
     };
     const noop = () => undefined;
     const net = opts.net ?? {
@@ -113,7 +137,9 @@ export function createSimHost(opts) {
         resync: () => lockstep?.needSnap(),
     };
     return {
-        state,
+        get state() {
+            return state;
+        },
         available: useWorker,
         send(input) {
             if (lockstep)
@@ -142,10 +168,51 @@ export function createSimHost(opts) {
         hash: () => lastHash,
         netAdapter: () => net,
         lockstep,
+        frame,
+        reinit(newLayout, fill, ro) {
+            const nBuf = useWorker
+                ? new SharedArrayBuffer(newLayout.byteLength)
+                : new ArrayBuffer(newLayout.byteLength);
+            state = newLayout.attach(nBuf); // fill on the main thread, then hand the ready buffer to the worker
+            fill(state);
+            lastHash = opts.sim.hash(state);
+            sampled.clear();
+            acc = 0;
+            lastRef.t = clock.now();
+            if (worker) {
+                worker.postMessage({
+                    t: 'reinit',
+                    dataBuf: nBuf,
+                    coop: !!opts.coop,
+                    resync: !!ro?.resync,
+                    ...(ro?.initParams ?? {}),
+                });
+            }
+            else if (ro?.resync) {
+                queue.prune(opts.tickOf(state)); // keep in-flight future commands past the snapshot tick
+            }
+            else {
+                queue.clear();
+            }
+        },
+        request(msg) {
+            const w = worker;
+            if (!w)
+                return Promise.resolve(null);
+            const rid = ++reqSeq;
+            return new Promise((res) => {
+                reqWait.set(rid, res);
+                w.postMessage({ ...msg, rid });
+                setTimeout(() => {
+                    if (reqWait.delete(rid))
+                        res(null); // never hang a caller on a stuck worker
+                }, 4000);
+            });
+        },
         stop() {
             ctl.running = false;
             worker?.terminate();
         },
-        pump: useWorker ? undefined : pump,
+        pump: useWorker ? undefined : frame,
     };
 }

package/dist/loop/simHost.worker.d.ts

@@ -1,10 +1,23 @@
 import type { Layout } from './layout';
 import { type ControlView } from './controlBlock';
 import { type SimHostSim } from './simCore';
+/** A reply a worker posts back to the main thread. Must be structured-cloneable. Echo the originating request's
+ *  `rid` so the main thread's `host.request()` Promise resolves on it; any other fields are the game's payload. */
+export interface SimWorkerReply {
+    rid?: number;
+    [k: string]: unknown;
+}
+export interface SimWorkerContext<S> {
+    state: S;
+    ctl: ControlView<string>;
+    post(m: SimWorkerReply): void;
+}
 export interface SimWorkerConfig<S, I> {
     sim: SimHostSim<S, I>;
     layout: Layout<S> | ((init: Record<string, unknown>) => Layout<S>);
     tickOf: (s: S) => number;
     mirror?: (s: S, ctl: ControlView<string>) => void;
+    beforeTick?: (due: I[], state: S) => void;
+    onMessage?: (m: Record<string, unknown>, ctx: SimWorkerContext<S>) => void;
 }
 export declare function runSimWorker<S, I>(cfg: SimWorkerConfig<S, I>): void;

package/dist/loop/simHost.worker.js

@@ -14,6 +14,12 @@ export function runSimWorker(cfg) {
     const loop = () => {
         if (state && ctl?.running) {
             const before = cfg.tickOf(state);
+            // Auto-wire late-arrival counting into the control block so the main thread's `takeLate()` always reflects
+            // divergence — the game needs no code for this (it's the same signal on every SimHost game).
+            const c = ctl;
+            const onLate = (n) => {
+                c.addLate(n);
+            };
             if (coop) {
                 coopStepBatch({
                     sim: cfg.sim,
@@ -22,6 +28,8 @@ export function runSimWorker(cfg) {
                     queue,
                     tickOf: cfg.tickOf,
                     maxCatchUpFrames: 30,
+                    onLate,
+                    ...(cfg.beforeTick ? { beforeTick: cfg.beforeTick } : {}),
                 });
             }
             else {
@@ -34,6 +42,8 @@ export function runSimWorker(cfg) {
                     clock,
                     lastRef,
                     fps,
+                    onLate,
+                    ...(cfg.beforeTick ? { beforeTick: cfg.beforeTick } : {}),
                 }, acc);
             }
             const stepped = cfg.tickOf(state) - before;
@@ -66,21 +76,45 @@ export function runSimWorker(cfg) {
     ctx.onmessage = (e) => {
         const m = e.data;
         if (m.t === 'init') {
-            const layout = typeof cfg.layout === 'function' ? cfg.layout(m) : cfg.layout;
-            state = layout.attach(m.dataBuf);
-            ctl = createControlView(m.ctlBuf, m.scalars ?? []);
-            fps = m.simFps ?? 60;
-            coop = !!m.coop;
+            const init = m;
+            const layout = typeof cfg.layout === 'function' ? cfg.layout(init) : cfg.layout;
+            state = layout.attach(init.dataBuf);
+            ctl = createControlView(init.ctlBuf, init.scalars ?? []);
+            fps = init.simFps ?? 60;
+            coop = !!init.coop;
             ctl.running = true;
             lastRef.t = clock.now();
             loop();
         }
+        else if (m.t === 'reinit') {
+            // World-swap (new game / load / resync): re-attach to the fresh, already-filled buffer (ctl + coop flag
+            // persist). A resync keeps in-flight future commands (drops applied history); otherwise the stream restarts.
+            const init = m;
+            const layout = typeof cfg.layout === 'function' ? cfg.layout(init) : cfg.layout;
+            state = layout.attach(init.dataBuf);
+            if (init.resync)
+                queue.prune(cfg.tickOf(state));
+            else
+                queue.clear();
+            lastRef.t = clock.now();
+            acc = 0;
+        }
         else if (m.t === 'cmd') {
             queue.push(m.s);
         }
-        else {
-            // resync-req: keep future commands, drop the applied history (an authoritative snapshot is being loaded).
+        else if (m.t === 'resync-req') {
+            // keep future commands, drop the applied history (an authoritative snapshot is being loaded).
             queue.prune(state ? cfg.tickOf(state) : 0);
         }
+        else if (state && ctl) {
+            // A message this runner doesn't own — hand it to the game (diagnostics requests, etc.).
+            cfg.onMessage?.(m, {
+                state,
+                ctl,
+                post: (msg) => {
+                    ctx.postMessage(msg);
+                },
+            });
+        }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "exports": {
     ".": {