@rydr/game-sdk 7.0.0 → 7.1.0

package/dist/ui/controller/controller-pad.js

@@ -0,0 +1,200 @@
+/**
+ * CONTROLLER PAD — the live drawing of the controller in the rider's hands.
+ *
+ * ```ts
+ * const pad = mountControllerPad(host, { press: session, size: "lg" });
+ * // …buttons light as they're pressed, stick caps follow the real axes. Nothing to call per frame.
+ * pad.dispose();
+ * ```
+ *
+ * This is the game-side counterpart of the shell's own controller diagram, and it is deliberately fed by
+ * **canonical input, not raw hardware**: a game never sees gamepad indices, per-device bindings or analog
+ * trigger travel, so this module translates `ButtonName` → drawn position (`parts-map.ts`) and polls
+ * `session.axis()` for the sticks. Three consequences worth knowing:
+ *
+ * 1. **Axes are polled, buttons are not.** `onButton` is an edge stream, so presses cost nothing between
+ *    events; axes have no event, so when the source exposes `axis()` the pad runs its own
+ *    `requestAnimationFrame` loop. It stops on `dispose()` and while the tab is hidden, and the
+ *    `PadDriver` dirty-guard means an idle stick performs zero DOM writes per frame.
+ *
+ * 2. **The d-pad is shared with the left stick.** `UP`/`DOWN`/`LEFT`/`RIGHT` are emitted by the d-pad
+ *    *and* by the left stick past its deadzone (see `protocol/buttons.ts`), and nothing in the canonical
+ *    stream says which. When `axis()` is available we suppress the d-pad highlight for a direction the
+ *    stick already explains — so pushing the stick moves the cap instead of falsely lighting the d-pad.
+ *    Without `axis()` the d-pad lights for both, which is the honest best we can do.
+ *
+ * 3. **Triggers are clicks.** `LT`/`RT` have no analog travel in this protocol, so their travel meters
+ *    are driven 0/1 from button state.
+ *
+ * It also **re-letters itself.** A keycap resolves its glyph set once, on the reasoning that keycaps are
+ * cheap to recreate; a controls screen is long-lived and `/hardware` is exactly where a rider swaps pads.
+ * So if the source exposes `hardware.subscribe`, the pad rebuilds its drawing in place when the resolved
+ * set changes, restoring anything currently held. Callers keep their handle and need to know nothing.
+ */
+import { DEFAULT_GLYPH_SET } from "../../protocol/glyphs.js";
+import { layoutForBrand } from "./layouts/index.js";
+import { DPAD_DIRECTIONS, litPartOfButton, litPartOfControl } from "./parts-map.js";
+import { buildPadSvg, createPadDriver, STICK_LIT_DEADZONE } from "./pad-svg.js";
+import { injectPadCss } from "./styles.js";
+const DPAD_NAMES = ["UP", "DOWN", "LEFT", "RIGHT"];
+/** Explicit option → what the rider's hardware reports → the SDK-wide fallback. */
+function resolveGlyphSet(opts) {
+    return opts.glyphSet ?? opts.press?.hardware?.current?.glyphSet ?? DEFAULT_GLYPH_SET;
+}
+export function mountControllerPad(host, opts = {}) {
+    injectPadCss();
+    const root = document.createElement("div");
+    root.className = `rydr-pad ${opts.size ?? "md"}${opts.ghost ? " ghost" : ""}`;
+    if (opts.accent) {
+        root.style.setProperty("--pad-accent", opts.accent);
+        root.style.setProperty("--pad-glow", opts.accent);
+    }
+    host.appendChild(root);
+    const live = !opts.ghost && opts.press != null;
+    const source = opts.press;
+    const hasAxis = live && typeof source?.axis === "function";
+    /** Everything currently held, so a rebuild can restore the lit state rather than dropping it. */
+    const held = new Set();
+    const rebuildCbs = new Set();
+    let glyphSet = resolveGlyphSet(opts);
+    let pad;
+    let driver;
+    let layout;
+    const availableParts = () => {
+        if (!opts.available)
+            return null;
+        const parts = [];
+        for (const name of opts.available) {
+            const part = litPartOfButton(name);
+            if (part)
+                parts.push(part);
+        }
+        return parts;
+    };
+    function build() {
+        layout = layoutForBrand(opts.brand ?? glyphSet);
+        pad = buildPadSvg(layout, { labels: opts.labels ?? true });
+        driver = createPadDriver(pad, layout, { allowShellOwned: opts.allowShellOwned });
+        root.textContent = "";
+        root.appendChild(pad.svg);
+        driver.setAvailable(availableParts());
+    }
+    build();
+    /**
+     * Apply one button's state to the drawing.
+     *
+     * The d-pad directions are skipped when we have axes, because the rAF loop is then their single
+     * writer — it has to be, since only it knows whether the left stick is explaining the direction. Two
+     * writers on the same part would fight every frame.
+     */
+    function applyButton(name, down) {
+        if (hasAxis && DPAD_NAMES.includes(name))
+            return;
+        const part = litPartOfControl(name);
+        if (part)
+            driver.setPart(part, down);
+        if (name === "LT")
+            driver.setMeter("l", down ? 1 : 0);
+        if (name === "RT")
+            driver.setMeter("r", down ? 1 : 0);
+    }
+    function applyAllHeld() {
+        for (const name of held)
+            applyButton(name, true);
+    }
+    const offButton = live
+        ? source?.onButton((e) => {
+            if (e.edge === "down")
+                held.add(e.name);
+            else
+                held.delete(e.name);
+            applyButton(e.name, e.edge === "down");
+        })
+        : undefined;
+    // Seed from whatever is already held, so mounting mid-press shows the truth immediately.
+    if (live && source?.buttonsDown) {
+        for (const name of source.buttonsDown())
+            held.add(name);
+        applyAllHeld();
+    }
+    // ── axis polling ────────────────────────────────────────────────────────────────────────────────
+    let raf = 0;
+    function frame() {
+        raf = requestAnimationFrame(frame);
+        const axis = source?.axis;
+        if (!axis)
+            return;
+        const lx = axis("LX");
+        const ly = axis("LY");
+        driver.setStick("l", lx, ly);
+        driver.setStick("r", axis("RX"), axis("RY"));
+        // The suppression rule: light a d-pad arm only if it's held AND the left stick isn't already
+        // showing that direction (projection of the stick vector onto the direction, past the deadzone).
+        for (const name of DPAD_NAMES) {
+            const [vx, vy] = DPAD_DIRECTIONS[name];
+            const explained = lx * vx + ly * vy > STICK_LIT_DEADZONE;
+            const part = litPartOfButton(name);
+            if (part)
+                driver.setPart(part, held.has(name) && !explained);
+        }
+    }
+    function startFrames() {
+        if (hasAxis && !raf)
+            raf = requestAnimationFrame(frame);
+    }
+    function stopFrames() {
+        if (raf)
+            cancelAnimationFrame(raf);
+        raf = 0;
+    }
+    const onVisibility = () => {
+        if (document.visibilityState === "hidden")
+            stopFrames();
+        else
+            startFrames();
+    };
+    if (hasAxis) {
+        startFrames();
+        document.addEventListener("visibilitychange", onVisibility);
+    }
+    // ── re-lettering ────────────────────────────────────────────────────────────────────────────────
+    // Only when the caller did NOT pin a glyph set: an explicit one is a deliberate preview.
+    const offHardware = !opts.glyphSet && live
+        ? source?.hardware?.subscribe?.((snapshot) => {
+            const next = snapshot.glyphSet ?? DEFAULT_GLYPH_SET;
+            if (next === glyphSet)
+                return; // a second pad of the same family is a non-event
+            glyphSet = next;
+            build();
+            applyAllHeld();
+            for (const cb of rebuildCbs)
+                cb();
+        })
+        : undefined;
+    return {
+        root,
+        svg: () => pad,
+        driver: () => driver,
+        layout: () => layout,
+        glyphSet: () => glyphSet,
+        onRebuild(cb) {
+            rebuildCbs.add(cb);
+            return () => rebuildCbs.delete(cb);
+        },
+        setVisible(on) {
+            root.style.display = on ? "" : "none";
+        },
+        dispose() {
+            offButton?.();
+            offHardware?.();
+            stopFrames();
+            document.removeEventListener("visibilitychange", onVisibility);
+            // Release everything before detaching: a button held at teardown must never leave a lit pad
+            // behind if the caller re-parents or re-mounts the node.
+            driver.clearAll();
+            rebuildCbs.clear();
+            root.remove();
+        },
+    };
+}
+//# sourceMappingURL=controller-pad.js.map

package/dist/ui/controller/controller-pad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-pad.js","sourceRoot":"","sources":["../../../src/ui/controller/controller-pad.ts"],"names":[],"mappings":"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"}

package/dist/ui/controller/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The controller family of `@rydr/game-sdk/ui` — one drawing of the rider's controller, and the two
+ * views built on it.
+ *
+ *   mountControllerPad   the live pad: buttons light on press, stick caps follow the real axes
+ *   mountControllerMap   STATIC — the pad flanked by action callouts, each joined by a line to its button
+ *   mountComboDemo       DYNAMIC — a looping animation of the combination one action requires
+ *
+ * A game describes its controls once, declaratively, and the SDK owns everything else — which physical
+ * button that is on the rider's pad, the letter printed on it, where the callout sits, how the line
+ * routes, and how the demo animates. See `tokens.ts` for the vocabulary and `parts-map.ts` for the
+ * positional mapping that makes one action list correct on every controller.
+ */
+export * from "./types.js";
+export * from "./tokens.js";
+export * from "./parts-map.js";
+export * from "./layouts/index.js";
+export * from "./pad-svg.js";
+export * from "./input-chip.js";
+export * from "./combo-strip.js";
+export * from "./controller-pad.js";
+export * from "./controller-map.js";
+export * from "./combo-demo.js";
+export * from "./control-trainer.js";
+export { injectPadCss } from "./styles.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/controller/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/ui/controller/index.js

@@ -0,0 +1,26 @@
+/**
+ * The controller family of `@rydr/game-sdk/ui` — one drawing of the rider's controller, and the two
+ * views built on it.
+ *
+ *   mountControllerPad   the live pad: buttons light on press, stick caps follow the real axes
+ *   mountControllerMap   STATIC — the pad flanked by action callouts, each joined by a line to its button
+ *   mountComboDemo       DYNAMIC — a looping animation of the combination one action requires
+ *
+ * A game describes its controls once, declaratively, and the SDK owns everything else — which physical
+ * button that is on the rider's pad, the letter printed on it, where the callout sits, how the line
+ * routes, and how the demo animates. See `tokens.ts` for the vocabulary and `parts-map.ts` for the
+ * positional mapping that makes one action list correct on every controller.
+ */
+export * from "./types.js";
+export * from "./tokens.js";
+export * from "./parts-map.js";
+export * from "./layouts/index.js";
+export * from "./pad-svg.js";
+export * from "./input-chip.js";
+export * from "./combo-strip.js";
+export * from "./controller-pad.js";
+export * from "./controller-map.js";
+export * from "./combo-demo.js";
+export * from "./control-trainer.js";
+export { injectPadCss } from "./styles.js";
+//# sourceMappingURL=index.js.map

package/dist/ui/controller/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ui/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/ui/controller/input-chip.d.ts

@@ -0,0 +1,100 @@
+/**
+ * INPUT CHIP — the small pictogram for one control, and the atom both controller views are built from.
+ *
+ * One factory, five renderers, chosen by the token:
+ *
+ *   DIAMOND_*                    → `createKeycap`      (the kit's existing face-button keycap)
+ *   UP/DOWN/LEFT/RIGHT, R*       → `createDpadKeycap`  (the kit's chevron-on-steel keycap)
+ *   LT / RT / OPTIONS            → `createLabelKeycap` (the kit's pill: "L2"/"ZL", "Menu"/"Options"/"+")
+ *   LSTICK / RSTICK              → a stick pictogram, cap centred inside four outward arrows
+ *   LSTICK / RSTICK :direction   → the same pictogram with ONE arrow, cap already slid that way
+ *   LSTICK_PRESS / RSTICK_PRESS  → a stick pictogram of the cap CLICKED: sunk inside a collar,
+ *                                  with a chevron pressing down into it
+ *
+ * The sticks are pictures rather than lettered chips throughout, because that is the one control where
+ * the letter tells a rider nothing: "L3" does not say *click the stick*, and it changes per brand on
+ * top of that. The printed label still reaches them through the chip's tooltip and assistive tech.
+ *
+ * All the button shapes REUSE the keycap kit rather than redrawing it, so a control looks identical in a
+ * controls legend and in an in-game prompt — same shape, same per-role hue, same letter for the rider's
+ * own pad. Only the shapes the kit didn't have are new, and they're inline SVG built with
+ * `createElementNS` from string path constants, exactly as `keycap.ts` does with its `CHEVRON`: this SDK
+ * ships **no non-TS assets** and adds no build step.
+ *
+ * **Press wiring lives here, not in the keycap.** The keycaps are built without their own `press`
+ * option, because `createDpadKeycap("UP")` listens for `UP` and there is no way to ask it to listen for
+ * `RUP` instead. Doing it in one place covers all five renderers uniformly and lets the combo demo drive
+ * exactly the same `setPressed` path that real input drives.
+ */
+import type { ButtonEdge } from "../../protocol/buttons.js";
+import { type GlyphSet } from "../../protocol/glyphs.js";
+import { type ComboToken, type ControlName } from "./tokens.js";
+/**
+ * A control-event source. A `PlatformSession` satisfies it structurally.
+ *
+ * Typed on {@link ControlName} rather than `ButtonName` so a SHELL-side source can drive the shell-owned
+ * controls too — a session only ever emits the `ButtonName` subset, and still satisfies this.
+ */
+export interface ChipPressSource {
+    onButton(cb: (e: {
+        name: ControlName;
+        edge: ButtonEdge;
+    }) => void): () => void;
+}
+export interface InputChipOptions {
+    /** Which controller's lettering to draw. Default {@link DEFAULT_GLYPH_SET}. */
+    glyphSet?: GlyphSet;
+    /** Wire to real input: the chip shows its pressed state while ITS control is held. */
+    press?: ChipPressSource;
+    /** Per-role hue on face keycaps (confirm green, back amber). Default true, as elsewhere in the kit. */
+    colored?: boolean;
+    /** Drawing convention for the joystick pictograms. Default {@link DEFAULT_STICK_STYLE}. */
+    stickStyle?: StickPictogramStyle;
+}
+/**
+ * What a chip is saying, for a guided lesson. Mirrors {@link PadPartState} so the chip in the card and
+ * the button on the drawing can never disagree.
+ */
+export type InputChipState = "idle" | "hint" | "active" | "done";
+export interface InputChip {
+    /** The element to place. Sized to share a baseline with the kit's 38px keycap. */
+    readonly el: HTMLElement;
+    /** Pressed/held state. Driven by real input when `press` was given, and by the combo demo. */
+    setPressed(on: boolean): void;
+    /** Lesson state: `hint` = do this, `active` = doing it, `done` = finished. */
+    setState(state: InputChipState): void;
+    /**
+     * Deflect a stick chip's cap. `x`/`y` are −1..1 in the SDK's convention (right = +1, **up = +1**).
+     * A no-op on every other chip kind, so callers can drive a whole strip without branching.
+     */
+    setDeflection(x: number, y: number): void;
+    dispose(): void;
+}
+/**
+ * Which drawing convention to use for the joystick pictograms. Three real ones from the industry, kept
+ * as an option because they trade off differently and the right answer is a judgement call:
+ *
+ * - **`"topdown"`** — the abstract plan view: a well, a cap dot, outline chevrons. Compact and neutral,
+ *   the PlayStation/Steam-overlay convention. Weakest at small sizes, and the *click* is its hard case:
+ *   pressing along the view axis is exactly what a top-down view cannot show.
+ * - **`"profile"`** — the hybrid the free prompt packs (Kenney, Xelu) settled on, and the clearest of
+ *   the three: **plan view with bold filled arrows for directions**, and a **side view for the click** —
+ *   a real stick with a shaft and a thumb pad, being pushed down by a solid arrow. Each gesture gets the
+ *   viewpoint that can actually depict it.
+ * - **`"glyph"`** — the bold console-UI mark (Xbox / Steam Input): a solid disc with solid triangles,
+ *   and a click drawn as a heavy ring with an arrow inside it. Loudest and most legible far away;
+ *   least literal about the hardware.
+ *
+ * Compare them in the showcase's "Joystick pictograms" section before changing {@link DEFAULT_STICK_STYLE}.
+ */
+export type StickPictogramStyle = "topdown" | "profile" | "glyph";
+/** The style used when a caller doesn't ask for one. */
+export declare const DEFAULT_STICK_STYLE: StickPictogramStyle;
+/**
+ * Build the chip for one control.
+ *
+ * Always returns something drawable: an unrecognised token falls through to a text chip carrying
+ * `buttonLabel`'s own fallback (the name itself), so a caller can never render an empty box.
+ */
+export declare function createInputChip(token: ComboToken, opts?: InputChipOptions): InputChip;
+//# sourceMappingURL=input-chip.d.ts.map

package/dist/ui/controller/input-chip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-chip.d.ts","sourceRoot":"","sources":["../../../src/ui/controller/input-chip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAA+C,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGtG,OAAO,EAAgD,KAAK,UAAU,EAAE,KAAK,WAAW,EAAiB,MAAM,aAAa,CAAC;AAE7H;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAChF;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,sFAAsF;IACtF,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,uGAAuG;IACvG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAElE,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,EAAE,mBAA+B,CAAC;AA8KlE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,SAAS,CAmHzF"}