game-koi 0.1.2 → 0.3.0

package/dist/stats.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Host-side performance counters for the browser build.
+ *
+ * Everything here describes the *emulator*, not the emulated machine: how fast the page
+ * is managing to run it, and whether it is keeping up. A Game Boy has no idea what a
+ * wall clock is — its own notion of a frame is 70224 T-cycles, and that number never
+ * varies however slowly they are executed.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `stats.rs`, and it counts
+ * different things on purpose, because the two frontends are paced differently.
+ *
+ * # Frames are not wakes
+ *
+ * The desktop sleeps until each 16.74 ms deadline, so one loop iteration is one frame
+ * and a frame rate is just how often the loop ran. Here `requestAnimationFrame` wakes at
+ * the *display's* rate — 120 Hz on a fast panel, 0 Hz in a backgrounded tab — and each
+ * wake emulates however many frames the audio buffer is short by, which may be two, one
+ * or none. Counting wakes would report the refresh rate and say nothing about the
+ * emulator, so `fps` counts frames the emulator actually completed. `framesPerWake` is
+ * the ratio between the two clocks: 1.0 on a 60 Hz display, ~0.5 on a 120 Hz one.
+ *
+ * # There is no "blocked" figure here
+ *
+ * The desktop's most useful number is time neither spent working nor slept away, which
+ * is the compositor holding the swapchain. A page never sleeps and never presents, so
+ * that figure has no analogue. Its replacement is the audio buffer: since pacing runs
+ * off the sound card, "am I keeping up" *is* "is the buffer staying full", and a buffer
+ * that reaches zero is the audible failure the whole design exists to avoid. That is why
+ * `underruns` is the closest thing here to the desktop's late-frame count.
+ *
+ * # The clock is passed in, never read
+ *
+ * Nothing in this module calls `performance.now()`; the caller passes the timestamp it
+ * already has. That keeps the counters pure — testable with plain numbers, no timers and
+ * no fake clock.
+ */
+/** The DMG's frame rate. Not 60: 4194304 / 70224 cycles per frame. */
+export declare const TARGET_HZ = 59.7275;
+/** The wall-clock budget for one emulated frame, in milliseconds. */
+export declare const FRAME_MS: number;
+/** What one `requestAnimationFrame` wake did. */
+export interface WakeReport {
+    /** Milliseconds spent running the emulator and handing its samples to the worklet. */
+    emulate: number;
+    /** Milliseconds spent blitting to the canvas; zero when nothing was drawn. */
+    draw: number;
+    /** Frames emulated this wake — often 0 or 1, more while catching up. */
+    frames: number;
+    /** Whether `maxFramesPerWake` clamped the catch-up, leaving a deficit behind. */
+    capped: boolean;
+}
+/** The audio side's view of itself, as last reported by the worklet. */
+export interface AudioReport {
+    /** Sample frames sitting in the worklet's ring, waiting to be played. */
+    buffered: number;
+    /** How many the page tries to keep there. */
+    target: number;
+    /** Cumulative silent samples emitted because the ring was empty. */
+    underruns: number;
+    /** Cumulative samples overwritten because the ring was full. */
+    dropped: number;
+    /** The `AudioContext`'s rate — what the core resamples its output to. */
+    sampleRate: number;
+    /** `"running"`, `"suspended"` or `"closed"`. */
+    state: string;
+}
+/** Everything the panel draws, computed once per refresh. */
+export interface StatsSnapshot {
+    /** Emulated frames per second, averaged over the sampling window. */
+    fps: number;
+    /** `fps` as a percentage of real hardware, where 100% is a DMG. */
+    speedPercent: number;
+    /** Milliseconds of emulation per emulated frame. */
+    emulate: number;
+    /** Milliseconds of canvas blitting per emulated frame. */
+    draw: number;
+    /** `emulate + draw`, the work this page does per frame. */
+    work: number;
+    /** That work as a fraction of the 16.74 ms a frame is worth. */
+    workFraction: number;
+    /** Emulated frames per `rAF` wake: the ratio of the two clocks. */
+    framesPerWake: number;
+    /** How often `rAF` is firing — in practice, the display's refresh rate. */
+    wakeRate: number;
+    frames: number;
+    wakes: number;
+    /** Wakes whose catch-up hit `maxFramesPerWake`. */
+    cappedWakes: number;
+    /** `null` until the worklet has reported once. */
+    audio: (AudioReport & {
+        bufferedMs: number;
+    }) | null;
+}
+/** Rolling counters, recomputed roughly twice a second. */
+export declare class FrameStats {
+    private windowStart;
+    private framesInWindow;
+    private wakesInWindow;
+    private emulateInWindow;
+    private drawInWindow;
+    private fps;
+    private wakeRate;
+    private emulatePerFrame;
+    private drawPerFrame;
+    private framesPerWake;
+    private frames;
+    private wakes;
+    private cappedWakes;
+    private audio;
+    constructor(now: number);
+    /** Records a wake and, once the window is old enough, recomputes the averages. */
+    wake(report: WakeReport, now: number): void;
+    /** Takes the audio thread's latest report of itself. */
+    setAudio(report: AudioReport): void;
+    snapshot(): StatsSnapshot;
+}

package/dist/stats.js

@@ -0,0 +1,120 @@
+/**
+ * Host-side performance counters for the browser build.
+ *
+ * Everything here describes the *emulator*, not the emulated machine: how fast the page
+ * is managing to run it, and whether it is keeping up. A Game Boy has no idea what a
+ * wall clock is — its own notion of a frame is 70224 T-cycles, and that number never
+ * varies however slowly they are executed.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `stats.rs`, and it counts
+ * different things on purpose, because the two frontends are paced differently.
+ *
+ * # Frames are not wakes
+ *
+ * The desktop sleeps until each 16.74 ms deadline, so one loop iteration is one frame
+ * and a frame rate is just how often the loop ran. Here `requestAnimationFrame` wakes at
+ * the *display's* rate — 120 Hz on a fast panel, 0 Hz in a backgrounded tab — and each
+ * wake emulates however many frames the audio buffer is short by, which may be two, one
+ * or none. Counting wakes would report the refresh rate and say nothing about the
+ * emulator, so `fps` counts frames the emulator actually completed. `framesPerWake` is
+ * the ratio between the two clocks: 1.0 on a 60 Hz display, ~0.5 on a 120 Hz one.
+ *
+ * # There is no "blocked" figure here
+ *
+ * The desktop's most useful number is time neither spent working nor slept away, which
+ * is the compositor holding the swapchain. A page never sleeps and never presents, so
+ * that figure has no analogue. Its replacement is the audio buffer: since pacing runs
+ * off the sound card, "am I keeping up" *is* "is the buffer staying full", and a buffer
+ * that reaches zero is the audible failure the whole design exists to avoid. That is why
+ * `underruns` is the closest thing here to the desktop's late-frame count.
+ *
+ * # The clock is passed in, never read
+ *
+ * Nothing in this module calls `performance.now()`; the caller passes the timestamp it
+ * already has. That keeps the counters pure — testable with plain numbers, no timers and
+ * no fake clock.
+ */
+/** The DMG's frame rate. Not 60: 4194304 / 70224 cycles per frame. */
+export const TARGET_HZ = 59.7275;
+/** The wall-clock budget for one emulated frame, in milliseconds. */
+export const FRAME_MS = 1000 / TARGET_HZ;
+/**
+ * How long to gather before recomputing the averages.
+ *
+ * A rate computed over a single wake is pure noise — one scheduler hiccup and it reads
+ * 12 fps. Averaging over about half a second gives numbers steady enough to read, which
+ * matters more here than on the desktop because these are rendered as text that a person
+ * is trying to follow rather than a graph.
+ */
+const SAMPLE_WINDOW_MS = 500;
+/** Rolling counters, recomputed roughly twice a second. */
+export class FrameStats {
+    windowStart;
+    framesInWindow = 0;
+    wakesInWindow = 0;
+    emulateInWindow = 0;
+    drawInWindow = 0;
+    fps = 0;
+    wakeRate = 0;
+    emulatePerFrame = 0;
+    drawPerFrame = 0;
+    framesPerWake = 0;
+    frames = 0;
+    wakes = 0;
+    cappedWakes = 0;
+    audio = null;
+    constructor(now) {
+        this.windowStart = now;
+    }
+    /** Records a wake and, once the window is old enough, recomputes the averages. */
+    wake(report, now) {
+        this.wakes++;
+        this.wakesInWindow++;
+        this.frames += report.frames;
+        this.framesInWindow += report.frames;
+        this.emulateInWindow += report.emulate;
+        this.drawInWindow += report.draw;
+        if (report.capped)
+            this.cappedWakes++;
+        const elapsed = now - this.windowStart;
+        if (elapsed < SAMPLE_WINDOW_MS)
+            return;
+        const seconds = elapsed / 1000;
+        this.fps = this.framesInWindow / seconds;
+        this.wakeRate = this.wakesInWindow / seconds;
+        // Per *frame*, not per wake: a wake that emulated nothing did no work, and
+        // averaging those in would report a machine faster than it is.
+        const frames = this.framesInWindow;
+        this.emulatePerFrame = frames > 0 ? this.emulateInWindow / frames : 0;
+        this.drawPerFrame = frames > 0 ? this.drawInWindow / frames : 0;
+        this.framesPerWake = this.wakesInWindow > 0 ? frames / this.wakesInWindow : 0;
+        this.windowStart = now;
+        this.framesInWindow = 0;
+        this.wakesInWindow = 0;
+        this.emulateInWindow = 0;
+        this.drawInWindow = 0;
+    }
+    /** Takes the audio thread's latest report of itself. */
+    setAudio(report) {
+        this.audio = report;
+    }
+    snapshot() {
+        const work = this.emulatePerFrame + this.drawPerFrame;
+        return {
+            fps: this.fps,
+            speedPercent: (this.fps / TARGET_HZ) * 100,
+            emulate: this.emulatePerFrame,
+            draw: this.drawPerFrame,
+            work,
+            workFraction: work / FRAME_MS,
+            framesPerWake: this.framesPerWake,
+            wakeRate: this.wakeRate,
+            frames: this.frames,
+            wakes: this.wakes,
+            cappedWakes: this.cappedWakes,
+            audio: this.audio
+                ? { ...this.audio, bufferedMs: (this.audio.buffered / this.audio.sampleRate) * 1000 }
+                : null,
+        };
+    }
+}

package/dist/worklet.d.ts

@@ -1 +1 @@
-export declare const WORKLET_SOURCE = "\n  const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.\n\n  class KoiProcessor extends AudioWorkletProcessor {\n    constructor() {\n      super();\n      this.left = new Float32Array(CAPACITY);\n      this.right = new Float32Array(CAPACITY);\n      this.readIndex = 0;\n      this.writeIndex = 0;\n\n      this.port.onmessage = (event) => {\n        const { left, right } = event.data;\n        for (let i = 0; i < left.length; i++) {\n          const next = (this.writeIndex + 1) % CAPACITY;\n          // Full: drop the oldest rather than the newest, so audio does not fall\n          // permanently further behind the picture.\n          if (next === this.readIndex) {\n            this.readIndex = (this.readIndex + 1) % CAPACITY;\n          }\n          this.left[this.writeIndex] = left[i];\n          this.right[this.writeIndex] = right[i];\n          this.writeIndex = next;\n        }\n      };\n    }\n\n    available() {\n      return (this.writeIndex - this.readIndex + CAPACITY) % CAPACITY;\n    }\n\n    process(_inputs, outputs) {\n      const output = outputs[0];\n      const outL = output[0];\n      const outR = output.length > 1 ? output[1] : output[0];\n\n      for (let i = 0; i < outL.length; i++) {\n        if (this.readIndex === this.writeIndex) {\n          // Silence on underrun. Holding the last sample turns a click into a buzz,\n          // which is worse.\n          outL[i] = 0;\n          outR[i] = 0;\n        } else {\n          outL[i] = this.left[this.readIndex];\n          outR[i] = this.right[this.readIndex];\n          this.readIndex = (this.readIndex + 1) % CAPACITY;\n        }\n      }\n\n      // The main thread paces itself off this number, so it goes back every block.\n      this.port.postMessage({ buffered: this.available() });\n      return true;\n    }\n  }\n\n  registerProcessor(\"koi-processor\", KoiProcessor);\n";
+export declare const WORKLET_SOURCE = "\n  const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.\n\n  class KoiProcessor extends AudioWorkletProcessor {\n    constructor() {\n      super();\n      this.left = new Float32Array(CAPACITY);\n      this.right = new Float32Array(CAPACITY);\n      this.readIndex = 0;\n      this.writeIndex = 0;\n      // The two ways this can go wrong, counted for the stats panel. Both are\n      // cumulative: what matters is whether they are climbing, not their value.\n      this.underruns = 0;\n      this.dropped = 0;\n\n      this.port.onmessage = (event) => {\n        const { left, right } = event.data;\n        for (let i = 0; i < left.length; i++) {\n          const next = (this.writeIndex + 1) % CAPACITY;\n          // Full: drop the oldest rather than the newest, so audio does not fall\n          // permanently further behind the picture.\n          if (next === this.readIndex) {\n            this.readIndex = (this.readIndex + 1) % CAPACITY;\n            this.dropped++;\n          }\n          this.left[this.writeIndex] = left[i];\n          this.right[this.writeIndex] = right[i];\n          this.writeIndex = next;\n        }\n      };\n    }\n\n    available() {\n      return (this.writeIndex - this.readIndex + CAPACITY) % CAPACITY;\n    }\n\n    process(_inputs, outputs) {\n      const output = outputs[0];\n      const outL = output[0];\n      const outR = output.length > 1 ? output[1] : output[0];\n\n      for (let i = 0; i < outL.length; i++) {\n        if (this.readIndex === this.writeIndex) {\n          // Silence on underrun. Holding the last sample turns a click into a buzz,\n          // which is worse.\n          outL[i] = 0;\n          outR[i] = 0;\n          this.underruns++;\n        } else {\n          outL[i] = this.left[this.readIndex];\n          outR[i] = this.right[this.readIndex];\n          this.readIndex = (this.readIndex + 1) % CAPACITY;\n        }\n      }\n\n      // The main thread paces itself off \"buffered\", so it goes back every block. The\n      // counters ride along in the same message rather than in one of their own \u2014\n      // there is no cheaper time to send them, and a second postMessage per block from\n      // the audio thread would cost more than the numbers are worth.\n      this.port.postMessage({\n        buffered: this.available(),\n        underruns: this.underruns,\n        dropped: this.dropped,\n      });\n      return true;\n    }\n  }\n\n  registerProcessor(\"koi-processor\", KoiProcessor);\n";

package/dist/worklet.js

@@ -10,6 +10,10 @@
 //
 // Kept as a source string, not a separate .js file, so `GameKoi` can register it via a
 // Blob URL — a consumer never needs to serve this file or point a bundler at it.
+//
+// Being a template literal, the body below cannot contain a backtick or a `${`, even in
+// a comment: either one ends the string. The failure is a parse error in *this* file
+// pointing at a line that looks fine.
 export const WORKLET_SOURCE = `
   const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.
 
@@ -20,6 +24,10 @@ export const WORKLET_SOURCE = `
       this.right = new Float32Array(CAPACITY);
       this.readIndex = 0;
       this.writeIndex = 0;
+      // The two ways this can go wrong, counted for the stats panel. Both are
+      // cumulative: what matters is whether they are climbing, not their value.
+      this.underruns = 0;
+      this.dropped = 0;
 
       this.port.onmessage = (event) => {
         const { left, right } = event.data;
@@ -29,6 +37,7 @@ export const WORKLET_SOURCE = `
           // permanently further behind the picture.
           if (next === this.readIndex) {
             this.readIndex = (this.readIndex + 1) % CAPACITY;
+            this.dropped++;
           }
           this.left[this.writeIndex] = left[i];
           this.right[this.writeIndex] = right[i];
@@ -52,6 +61,7 @@ export const WORKLET_SOURCE = `
           // which is worse.
           outL[i] = 0;
           outR[i] = 0;
+          this.underruns++;
         } else {
           outL[i] = this.left[this.readIndex];
           outR[i] = this.right[this.readIndex];
@@ -59,8 +69,15 @@ export const WORKLET_SOURCE = `
         }
       }
 
-      // The main thread paces itself off this number, so it goes back every block.
-      this.port.postMessage({ buffered: this.available() });
+      // The main thread paces itself off "buffered", so it goes back every block. The
+      // counters ride along in the same message rather than in one of their own —
+      // there is no cheaper time to send them, and a second postMessage per block from
+      // the audio thread would cost more than the numbers are worth.
+      this.port.postMessage({
+        buffered: this.available(),
+        underruns: this.underruns,
+        dropped: this.dropped,
+      });
       return true;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-koi",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A Game Boy (DMG) emulator, compiled to WebAssembly, with a drop-in canvas + audio wrapper",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.js\"",
     "prepublishOnly": "npm run build"
   },
   "keywords": [