game-koi 0.2.0 → 0.3.0

package/README.md

@@ -50,6 +50,33 @@ the page:
   binding them would be confidently wrong rather than merely absent. Use
   `gamepadMap: null` and your own polling for such a pad.
 
+### Button events
+
+`koi.on("press" | "release", listener)` reports button edges from every input path —
+the built-in keyboard and gamepad handling as well as your own `press`/`release` calls —
+so an on-screen joypad can mirror whatever is driving the emulator:
+
+```ts
+const stop = koi.on("press", ({ button, source, pressed }) => {
+  // button: the one that changed. source: "keyboard" | "gamepad" | "api".
+  // pressed: everything held after this edge, as a Set — render straight from it.
+  render(pressed);
+});
+koi.on("release", ({ pressed }) => render(pressed));
+
+stop(); // or koi.off("press", listener)
+```
+
+Only *changes* are reported. A key held down with autorepeat, a stick resting past the
+threshold, and `press("a")` called twice each produce one `press` event and nothing more
+until the button comes up — so a listener never has to de-duplicate. `koi.pressed` gives
+the same set on demand, for a display built after the fact.
+
+Two cases release without anyone letting go: `loadRom()` releases everything (as
+`"api"`), since the new machine's joypad starts empty, and `pause()` releases whatever
+the gamepad was holding (as `"gamepad"`), since polling stops and nothing else would.
+Keys keep their own `keyup` while paused. `dispose()` drops every listener.
+
 ### Debug overlay
 
 Press <kbd>`</kbd> (backtick) to toggle a stats panel over the canvas, or call
@@ -90,6 +117,10 @@ element. Pass `overlayKey: null` to bind no key.
 - `koi.loadRom(rom)` — swaps in a new ROM, keeping the same canvas and audio setup.
 - `koi.press(button)` / `koi.release(button)` — `Button` is one of `"up"`, `"down"`,
   `"left"`, `"right"`, `"a"`, `"b"`, `"start"`, `"select"`.
+- `koi.on(type, listener)` / `koi.off(type, listener)` — `"press"` and `"release"`
+  button edges, from any input path. `on` returns a function that unsubscribes. The
+  payload is `{ button, source: "keyboard" | "gamepad" | "api", pressed: Set<Button> }`.
+- `koi.pressed` — everything held right now, as a `Set<Button>` snapshot.
 - `koi.toggleOverlay()` / `koi.overlayVisible` — the debug stats panel.
 - `koi.pause()` / `koi.resume()`.
 - `koi.dispose()` — stops the loop and tears down the audio graph. Call this before

package/dist/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The package's event plumbing: a tiny typed emitter, plus the button-edge types it
+ * carries.
+ *
+ * `on`/`off` rather than `EventTarget`, because a `CustomEvent`'s payload lands in
+ * `detail` typed as whatever the listener's declaration says — subclassing `EventTarget`
+ * in TypeScript means writing `addEventListener` overloads by hand and consumers still
+ * end up casting. A five-line map of sets types exactly, costs nothing, and keeps the
+ * package free of DOM globals in a module that Node's test runner has to import.
+ *
+ * The emitter deals in *edges*, not state: `GameKoi` holds the set of what is down and
+ * only emits when a button actually changes, so a key held with autorepeat, a stick
+ * resting past the threshold, and a page calling `press` twice all produce one event.
+ */
+import type { Button } from "./index.js";
+/** Where a button edge came from. */
+export type ButtonSource = "keyboard" | "gamepad" | "api";
+/** A button going down or coming up. */
+export interface ButtonEvent {
+    button: Button;
+    /**
+     * Which input path produced this edge. `"api"` covers `press`/`release` called by the
+     * page, and the releases `loadRom()` emits for a machine that is going away;
+     * `pause()`'s releases are attributed to the device that was holding them.
+     */
+    source: ButtonSource;
+    /**
+     * Everything held *after* this edge — a snapshot, safe to keep.
+     *
+     * Handy for the common case of mirroring the joypad on screen: render from this and
+     * there is no second copy of the state to keep in step.
+     */
+    pressed: ReadonlySet<Button>;
+}
+/** Event names to their payloads. See {@link GameKoi.on}. */
+export interface GameKoiEvents {
+    press: ButtonEvent;
+    release: ButtonEvent;
+}
+export type Listener<E> = (event: E) => void;
+/** Unsubscribes the listener it was returned for. Calling it twice is harmless. */
+export type Unsubscribe = () => void;
+/** A minimal typed event emitter. */
+export declare class Emitter<Events> {
+    private readonly listeners;
+    /** Registers a listener, and returns a function that removes it again. */
+    on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): Unsubscribe;
+    off<K extends keyof Events>(type: K, listener: Listener<Events[K]>): void;
+    /**
+     * Calls every listener for `type`.
+     *
+     * Each is isolated: these fire from inside a `keydown` handler and from the render
+     * loop, so a listener that throws would otherwise skip the rest of a gamepad poll or
+     * kill the loop outright. A page's display bug should not stop the emulator, so the
+     * error is reported and the remaining listeners still run.
+     *
+     * Iterates a copy, so a listener that unsubscribes itself (or another) mid-dispatch
+     * cannot disturb the walk.
+     */
+    emit<K extends keyof Events>(type: K, event: Events[K]): void;
+    /** Drops every listener. Called from `dispose()`. */
+    clear(): void;
+}

package/dist/events.js

@@ -0,0 +1,59 @@
+/**
+ * The package's event plumbing: a tiny typed emitter, plus the button-edge types it
+ * carries.
+ *
+ * `on`/`off` rather than `EventTarget`, because a `CustomEvent`'s payload lands in
+ * `detail` typed as whatever the listener's declaration says — subclassing `EventTarget`
+ * in TypeScript means writing `addEventListener` overloads by hand and consumers still
+ * end up casting. A five-line map of sets types exactly, costs nothing, and keeps the
+ * package free of DOM globals in a module that Node's test runner has to import.
+ *
+ * The emitter deals in *edges*, not state: `GameKoi` holds the set of what is down and
+ * only emits when a button actually changes, so a key held with autorepeat, a stick
+ * resting past the threshold, and a page calling `press` twice all produce one event.
+ */
+/** A minimal typed event emitter. */
+export class Emitter {
+    listeners = new Map();
+    /** Registers a listener, and returns a function that removes it again. */
+    on(type, listener) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        set.add(listener);
+        return () => this.off(type, listener);
+    }
+    off(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+    }
+    /**
+     * Calls every listener for `type`.
+     *
+     * Each is isolated: these fire from inside a `keydown` handler and from the render
+     * loop, so a listener that throws would otherwise skip the rest of a gamepad poll or
+     * kill the loop outright. A page's display bug should not stop the emulator, so the
+     * error is reported and the remaining listeners still run.
+     *
+     * Iterates a copy, so a listener that unsubscribes itself (or another) mid-dispatch
+     * cannot disturb the walk.
+     */
+    emit(type, event) {
+        const set = this.listeners.get(type);
+        if (!set)
+            return;
+        for (const listener of [...set]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error(`game-koi: "${String(type)}" listener threw`, error);
+            }
+        }
+    }
+    /** Drops every listener. Called from `dispose()`. */
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  * ships as a normal ES module asset next to this file, and the audio worklet is
  * inlined as a Blob URL.
  */
+import { type GameKoiEvents } from "./events.js";
+export type { ButtonEvent, ButtonSource, GameKoiEvents, Listener, Unsubscribe, } from "./events.js";
 export type Button = "up" | "down" | "left" | "right" | "a" | "b" | "start" | "select";
 export interface GameKoiOptions {
     /** Canvas the emulator draws into. Resized to the Game Boy's 160x144. */
@@ -53,6 +55,9 @@ export declare class GameKoi {
     private readonly targetBuffer;
     private readonly maxFramesPerWake;
     private readonly stats;
+    private readonly emitter;
+    /** What the joypad currently has down, whichever device put it there. */
+    private readonly held;
     private emulator;
     private buffered;
     /** Cumulative worklet counters, as last reported. See `worklet.ts`. */
@@ -77,6 +82,36 @@ export declare class GameKoi {
     loadRom(rom: Uint8Array): void;
     press(button: Button): void;
     release(button: Button): void;
+    /** Everything the joypad has down right now — a snapshot, safe to keep. */
+    get pressed(): ReadonlySet<Button>;
+    /**
+     * Listens for button edges, from any input path — the built-in keyboard and gamepad
+     * handling as well as `press`/`release` calls.
+     *
+     * Returns a function that removes the listener again:
+     *
+     * ```ts
+     * const stop = koi.on("press", ({ button, pressed }) => render(pressed));
+     * koi.on("release", ({ button, pressed }) => render(pressed));
+     * ```
+     *
+     * Only *changes* are reported: a key held down with autorepeat, a stick resting past
+     * the threshold, or `press("a")` twice in a row each produce one `press` event and no
+     * `release` until the button actually comes up.
+     */
+    on<K extends keyof GameKoiEvents>(type: K, listener: (event: GameKoiEvents[K]) => void): () => void;
+    /** Removes a listener registered with {@link on}. */
+    off<K extends keyof GameKoiEvents>(type: K, listener: (event: GameKoiEvents[K]) => void): void;
+    /**
+     * The one path to the emulated joypad, so every device's edges are counted once.
+     *
+     * A repeat is dropped here rather than forwarded: `Joypad::press` is idempotent, so
+     * skipping it changes nothing for the machine, and it is what makes the events edges
+     * instead of a restatement of whatever the browser felt like repeating.
+     */
+    private setButton;
+    /** Lets go of everything held, emitting the releases. */
+    private releaseAll;
     /**
      * Shows or hides the debug stats panel — the same thing the ` key does.
      *

package/dist/index.js

@@ -10,6 +10,7 @@
 import init, { Emulator } from "../wasm/game_koi_web.js";
 import { WORKLET_SOURCE } from "./worklet.js";
 import { DEFAULT_GAMEPAD_MAP, GamepadInput } from "./gamepad.js";
+import { Emitter } from "./events.js";
 import { FrameStats } from "./stats.js";
 import { StatsOverlay } from "./overlay.js";
 const DEFAULT_KEYMAP = {
@@ -42,6 +43,9 @@ export class GameKoi {
     targetBuffer;
     maxFramesPerWake;
     stats;
+    emitter = new Emitter();
+    /** What the joypad currently has down, whichever device put it there. */
+    held = new Set();
     emulator;
     buffered = 0;
     /** Cumulative worklet counters, as last reported. See `worklet.ts`. */
@@ -112,18 +116,76 @@ export class GameKoi {
     }
     /** Swaps in a new ROM, keeping the same canvas and audio graph. */
     loadRom(rom) {
-        // The new machine's joypad starts with nothing held, so the snapshot of what is
-        // held has to start over too or the first poll will emit no press for a direction
-        // that was already down.
+        // The new machine's joypad starts with nothing held, so what this side believes is
+        // held has to start over too — both the gamepad's snapshot (or the first poll would
+        // emit no press for a direction that was already down) and the set the events are
+        // edges against (or a button "already held" would never be pressed on the new
+        // machine, and a display would show it stuck down).
         this.gamepad?.releaseAll();
+        this.releaseAll();
         this.emulator.free();
         this.emulator = new Emulator(rom, this.audioContext.sampleRate);
     }
     press(button) {
-        this.emulator.press(button);
+        this.setButton(button, true, "api");
     }
     release(button) {
-        this.emulator.release(button);
+        this.setButton(button, false, "api");
+    }
+    /** Everything the joypad has down right now — a snapshot, safe to keep. */
+    get pressed() {
+        return new Set(this.held);
+    }
+    /**
+     * Listens for button edges, from any input path — the built-in keyboard and gamepad
+     * handling as well as `press`/`release` calls.
+     *
+     * Returns a function that removes the listener again:
+     *
+     * ```ts
+     * const stop = koi.on("press", ({ button, pressed }) => render(pressed));
+     * koi.on("release", ({ button, pressed }) => render(pressed));
+     * ```
+     *
+     * Only *changes* are reported: a key held down with autorepeat, a stick resting past
+     * the threshold, or `press("a")` twice in a row each produce one `press` event and no
+     * `release` until the button actually comes up.
+     */
+    on(type, listener) {
+        return this.emitter.on(type, listener);
+    }
+    /** Removes a listener registered with {@link on}. */
+    off(type, listener) {
+        this.emitter.off(type, listener);
+    }
+    /**
+     * The one path to the emulated joypad, so every device's edges are counted once.
+     *
+     * A repeat is dropped here rather than forwarded: `Joypad::press` is idempotent, so
+     * skipping it changes nothing for the machine, and it is what makes the events edges
+     * instead of a restatement of whatever the browser felt like repeating.
+     */
+    setButton(button, pressed, source) {
+        if (this.held.has(button) === pressed)
+            return;
+        if (pressed) {
+            this.held.add(button);
+            this.emulator.press(button);
+        }
+        else {
+            this.held.delete(button);
+            this.emulator.release(button);
+        }
+        this.emitter.emit(pressed ? "press" : "release", {
+            button,
+            source,
+            pressed: new Set(this.held),
+        });
+    }
+    /** Lets go of everything held, emitting the releases. */
+    releaseAll() {
+        for (const button of [...this.held])
+            this.setButton(button, false, "api");
     }
     /**
      * Shows or hides the debug stats panel — the same thing the ` key does.
@@ -161,6 +223,7 @@ export class GameKoi {
         this.detachKeyboard();
         if (this.overlayListener)
             removeEventListener("keydown", this.overlayListener);
+        this.emitter.clear();
         this.overlay?.dispose();
         this.emulator.free();
         this.worklet.disconnect();
@@ -255,24 +318,23 @@ export class GameKoi {
     }
     applyGamepadActions(actions) {
         for (const action of actions ?? []) {
-            if (action.type === "press")
-                this.press(action.button);
-            else
-                this.release(action.button);
+            this.setButton(action.button, action.type === "press", "gamepad");
         }
     }
     attachKeyboard() {
         this.keydownListener = (event) => {
             const button = this.keymap?.[event.code];
             if (button) {
-                this.press(button);
+                // Autorepeat still arrives here: `preventDefault` has to run on every repeat,
+                // and `setButton` is what collapses them into the one press edge.
+                this.setButton(button, true, "keyboard");
                 event.preventDefault();
             }
         };
         this.keyupListener = (event) => {
             const button = this.keymap?.[event.code];
             if (button) {
-                this.release(button);
+                this.setButton(button, false, "keyboard");
                 event.preventDefault();
             }
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-koi",
-  "version": "0.2.0",
+  "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",