ugly-game 0.5.19 → 0.5.20

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export * from './input/resolve';
 export * from './input/browserBackend';
 export * from './input/ControlHints';
 export * from './input/TouchControls';
+export * from './loop/pageState';
+export * from './loop/gameLoop';

package/dist/index.js

@@ -12,3 +12,5 @@ export * from './input/resolve';
 export * from './input/browserBackend';
 export * from './input/ControlHints';
 export * from './input/TouchControls';
+export * from './loop/pageState';
+export * from './loop/gameLoop';

package/dist/loop/gameLoop.d.ts

@@ -0,0 +1,47 @@
+import { type PageState, type PageTier } from './pageState';
+/** The three methods the loop needs to restore a networked sim after a pause. */
+export interface NetAdapter {
+    window: number;
+    catchUp(gapTicks: number): void;
+    resync(): void;
+}
+export interface ResumeInfo {
+    hiddenMs: number;
+    gapTicks: number;
+    tier: PageTier;
+}
+export interface FrameInfo {
+    tier: PageTier;
+    frame: number;
+    dt: number;
+    t: number;
+}
+export interface GameLoopOpts {
+    render: (info: FrameInfo) => void;
+    /** Render FPS per tier. Default { active: 60, blurred: 20, hidden: 0 }. */
+    gameFps?: {
+        active: number;
+        blurred: number;
+        hidden: number;
+    };
+    /** Fixed sim timestep + catch-up clamp. Default { fps: 60, maxCatchUpFrames: 6 }. */
+    sim?: {
+        fps: number;
+        maxCatchUpFrames: number;
+    };
+    /** Fixed-step sim callback. Omit if the sim lives elsewhere (e.g. a worker). */
+    tick?: (dt: number) => void;
+    /** Enables the default resume policy (catchUp vs resync). */
+    net?: NetAdapter;
+    /** Fully overrides the default resume policy. */
+    onResume?: (info: ResumeInfo) => void;
+    pageState?: PageState;
+    now?: () => number;
+    raf?: (cb: (t: number) => void) => number;
+    caf?: (id: number) => void;
+}
+export interface GameLoop {
+    stop(): void;
+    state(): PageTier;
+}
+export declare function runGameLoop(opts: GameLoopOpts): GameLoop;

package/dist/loop/gameLoop.js

@@ -0,0 +1,94 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GAME LOOP — the one rAF loop a game hands its render (and optionally its sim) to.
+// It owns three things a hand-rolled loop keeps getting wrong:
+//   1. RENDER PACING by page tier — active 60 / blurred 20 / hidden 0 (overridable).
+//   2. A FIXED-STEP SIM accumulator (opt-in via `tick`) that advances on wall time
+//      while visible and FREEZES while hidden, with a catch-up clamp.
+//   3. SIM RESTORE on resume — the part games forget. Hand it a NetAdapter and it
+//      does the correct thing automatically: small gap → deterministic catch-up,
+//      large gap → snapshot resync. Override with onResume for anything bespoke.
+// A single-player game passes neither net nor onResume and still gets correct
+// catch-up clamping for free. Clock/rAF/pageState are injectable for tests.
+// ─────────────────────────────────────────────────────────────────────────────
+import { createPageState } from './pageState';
+const DEFAULT_GAME_FPS = { active: 60, blurred: 20, hidden: 0 };
+const DEFAULT_SIM = { fps: 60, maxCatchUpFrames: 6 };
+export function runGameLoop(opts) {
+    const gameFps = opts.gameFps ?? DEFAULT_GAME_FPS;
+    const sim = opts.sim ?? DEFAULT_SIM;
+    const now = opts.now ?? (() => performance.now());
+    const raf = opts.raf ?? ((cb) => requestAnimationFrame(cb));
+    const caf = opts.caf ??
+        ((id) => {
+            cancelAnimationFrame(id);
+        });
+    const page = opts.pageState ?? createPageState({ now });
+    const fixedDt = 1 / sim.fps; // seconds per sim tick
+    const maxCatchUp = sim.maxCatchUpFrames * fixedDt; // seconds
+    let handle = 0;
+    let last = -1; // ms of the previous rAF callback
+    let acc = 0; // sim accumulator (seconds)
+    let renderAcc = 0; // render accumulator (seconds)
+    let frame = 0;
+    let stopped = false;
+    page.onResumeFromHidden((hiddenMs) => {
+        // Reset frame timing so the first frame after resume carries no dt/step spike.
+        last = -1;
+        acc = 0;
+        renderAcc = 0;
+        const gapTicks = Math.round(hiddenMs / (1000 * fixedDt));
+        const info = { hiddenMs, gapTicks, tier: page.tier() };
+        if (opts.onResume)
+            opts.onResume(info);
+        else if (opts.net) {
+            if (gapTicks <= opts.net.window)
+                opts.net.catchUp(gapTicks);
+            else
+                opts.net.resync();
+        }
+    });
+    const loop = (t) => {
+        if (stopped)
+            return;
+        if (last < 0)
+            last = t;
+        const wallDt = (t - last) / 1000;
+        last = t;
+        const tier = page.tier();
+        // SIM: advance whenever not hidden; freeze while hidden.
+        if (opts.tick && tier !== 'hidden') {
+            acc += Math.min(wallDt, maxCatchUp);
+            while (acc >= fixedDt) {
+                opts.tick(fixedDt);
+                acc -= fixedDt;
+            }
+        }
+        // RENDER: gate to the tier's FPS. 0 ⇒ never render (also covers a hidden tab
+        // whose browser still fires the occasional rAF).
+        const fps = gameFps[tier];
+        if (fps > 0) {
+            renderAcc += wallDt;
+            const period = 1 / fps;
+            // Carry the remainder (subtract the period, don't reset) so exact frame
+            // boundaries fire deterministically instead of being lost to fp jitter. The
+            // epsilon absorbs the last ulp when wallDt lands right on the period.
+            if (renderAcc + 1e-9 >= period) {
+                renderAcc -= period;
+                if (renderAcc > period)
+                    renderAcc = 0; // shed backlog; never render twice per frame
+                opts.render({ tier, frame, dt: wallDt, t });
+                frame++;
+            }
+        }
+        handle = raf(loop);
+    };
+    handle = raf(loop);
+    return {
+        stop: () => {
+            stopped = true;
+            caf(handle);
+            page.stop();
+        },
+        state: () => page.tier(),
+    };
+}

package/dist/loop/pageState.d.ts

@@ -0,0 +1,17 @@
+export type PageTier = 'active' | 'blurred' | 'hidden';
+export interface PageStateTarget {
+    hidden(): boolean;
+    hasFocus(): boolean;
+    onVisibilityChange(cb: () => void): void;
+    offVisibilityChange(cb: () => void): void;
+}
+export interface PageStateDeps {
+    now?: () => number;
+    target?: PageStateTarget | null;
+}
+export interface PageState {
+    tier(): PageTier;
+    onResumeFromHidden(cb: (hiddenMs: number) => void): void;
+    stop(): void;
+}
+export declare function createPageState(deps?: PageStateDeps): PageState;

package/dist/loop/pageState.js

@@ -0,0 +1,62 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// PAGE STATE — "how present is this tab right now?" resolves the coarse tier that
+// drives frame pacing (active / blurred / hidden), and timestamps hidden spans so a
+// game can restore its sim on resume. requestAnimationFrame STOPS firing while a tab
+// is hidden, so a running loop cannot detect its own return — this module owns the
+// one visibilitychange listener that can. tier() polls hidden()/hasFocus() live, so
+// blur/focus need no listeners. The DOM is injected (defaults to the real document/
+// window) to keep it pure/testable, matching SharedClock's injected-clock style.
+// ─────────────────────────────────────────────────────────────────────────────
+function realTarget() {
+    if (typeof document === 'undefined' || typeof window === 'undefined')
+        return null;
+    return {
+        hidden: () => document.hidden,
+        hasFocus: () => document.hasFocus(),
+        onVisibilityChange: (cb) => {
+            document.addEventListener('visibilitychange', cb);
+        },
+        offVisibilityChange: (cb) => {
+            document.removeEventListener('visibilitychange', cb);
+        },
+    };
+}
+export function createPageState(deps = {}) {
+    const now = deps.now ?? (() => performance.now());
+    const target = deps.target === undefined ? realTarget() : deps.target;
+    const resumeCbs = [];
+    let hiddenAt = -1;
+    const tier = () => {
+        if (!target)
+            return 'active';
+        if (target.hidden())
+            return 'hidden';
+        return target.hasFocus() ? 'active' : 'blurred';
+    };
+    const onVisibility = () => {
+        if (!target)
+            return;
+        if (target.hidden()) {
+            if (hiddenAt < 0)
+                hiddenAt = now();
+        }
+        else if (hiddenAt >= 0) {
+            const hiddenMs = now() - hiddenAt;
+            hiddenAt = -1;
+            for (const cb of resumeCbs)
+                cb(hiddenMs);
+        }
+    };
+    if (target)
+        target.onVisibilityChange(onVisibility);
+    return {
+        tier,
+        onResumeFromHidden: (cb) => {
+            resumeCbs.push(cb);
+        },
+        stop: () => {
+            if (target)
+                target.offVisibilityChange(onVisibility);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.5.19",
+  "version": "0.5.20",
   "type": "module",
   "exports": {
     ".": {
@@ -15,14 +15,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "preinstall": "npx only-allow pnpm",
-    "build": "tsc -p tsconfig.json",
-    "lint": "ugly-app lint",
-    "lint:fix": "ugly-app lint --fix",
-    "pretty": "prettier --write .",
-    "prepublishOnly": "pnpm run pretty && ugly-app lint && tsc -p tsconfig.json"
-  },
   "dependencies": {
     "meshoptimizer": "^1.2.0"
   },
@@ -35,5 +27,12 @@
     "@webgpu/types": "^0.1.40",
     "prettier": "^3.9.5",
     "ugly-app": "^0.1.841"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "build": "tsc -p tsconfig.json",
+    "lint": "ugly-app lint",
+    "lint:fix": "ugly-app lint --fix",
+    "pretty": "prettier --write ."
   }
-}
+}