@rydr/game-sdk 7.0.0 → 7.1.0

package/dist/ui/controller/control-trainer.d.ts

@@ -0,0 +1,132 @@
+/**
+ * CONTROL TRAINER — a guided lesson: "here's what to press; now you do it."
+ *
+ * Where {@link mountComboDemo} only *shows* a combination on a loop, this one **watches the rider** and
+ * gates on them actually performing it. It exists for the paired lessons where two related controls have
+ * to be taught together — the case that named it being the trainer resistance, which is one concept
+ * (`Changer la résistance`) with two opposite halves (`−` and `+`).
+ *
+ * ```ts
+ * mountControlTrainer(modalBody, {
+ *   title: "Changer la résistance",
+ *   press: shellInput,
+ *   steps: [
+ *     { label: "Réduire la résistance",   combo: ["LSTICK_PRESS", "LB"] },
+ *     { label: "Augmenter la résistance", combo: ["LSTICK_PRESS", "RB"] },
+ *   ],
+ *   onComplete: () => closeModal(),
+ * });
+ * ```
+ *
+ * Layout: the title, then one panel per step laid left → right, then **one shared controller drawing
+ * spanning the full width** underneath. Sharing the drawing is the point — both halves of the lesson are
+ * on the same physical pad, and seeing the left paddle and the right paddle light up on one picture is
+ * what teaches the pairing.
+ *
+ * Each step walks three states, and each one has to *look* like what it means:
+ *
+ *   1. **hint** — whitish, pulsing, on both the panel's chips and the pad's buttons. This is an
+ *      instruction, so it must not look like a press; the pulse is what separates the two, since a solid
+ *      fill is what a real press already looks like. The prompt shows **one step at a time, alternating**,
+ *      and builds each combination up **cumulatively** — the first control lights, STAYS lit, and the next
+ *      joins it a beat later. Prompting both halves at once would light four controls on one pad and read
+ *      as "press all of this"; blinking them in turn would never show that they are held together.
+ *   2. **active** — the accent colour, and the pulse STOPS. The rider has started but the combination
+ *      isn't complete yet: on a two-control step this is the state between the first control and the
+ *      second.
+ *   3. **done** — the step's PANEL turns green and its ✓ pops, the moment the WHOLE combination is held.
+ *      Holding all of it is doing it; there is nothing further to wait for, and it stays done whether or
+ *      not the rider keeps the controls down.
+ *
+ * **The controller drawing is never green.** White and blue have already taught the rider that colour on
+ * the pad means *now*, so progress there would be a third colour breaking that rule — a green button
+ * beside a white one reads as "and this one too". Progress lives on the panels, whose chips picture the
+ * same combination one line up, so the confirmation still lands on the controls they just pressed. See
+ * `paint` for the two languages.
+ *
+ * When every step is done, `onComplete` fires after a short beat so the last ✓ is actually seen. The
+ * component does not close anything itself — it has no idea it's in a modal. The host owns that, exactly
+ * as with every other piece of this kit.
+ *
+ * ⚠️ **The resistance case needs a shell-side input source.** `LB`/`RB` are shell-owned: the
+ * SDK client turns those keys into `trainer.adjustResistance` intents and they never reach a game's
+ * `onButton` (see {@link ShellControl}). So a *game* can build a trainer for its own buttons, but a
+ * resistance lesson has to be driven by the shell, which is also the only place that lesson belongs.
+ */
+import type { ButtonEdge } from "../../protocol/buttons.js";
+import type { AxisName } from "../../protocol/buttons.js";
+import type { GlyphSet } from "../../protocol/glyphs.js";
+import { type ControllerPad } from "./controller-pad.js";
+import type { StickPictogramStyle } from "./input-chip.js";
+import { type ComboToken, type ControlName } from "./tokens.js";
+import type { PadBrandKey } from "./types.js";
+/**
+ * The input the lesson watches.
+ *
+ * Typed on {@link ControlName}, not `ButtonName`, so a shell-side source can report `LB`/`RB`.
+ * A `PlatformSession` satisfies it structurally and can drive any lesson made of game buttons.
+ */
+export interface TrainerInputSource {
+    onButton(cb: (e: {
+        name: ControlName;
+        edge: ButtonEdge;
+    }) => void): () => void;
+    axis?(name: AxisName): number;
+    hardware?: {
+        current: {
+            glyphSet?: GlyphSet;
+        };
+        subscribe?(cb: (snapshot: {
+            glyphSet?: GlyphSet;
+        }) => void): () => void;
+    };
+}
+export interface TrainerStep {
+    /** What the rider has to do — the panel heading. */
+    label: string;
+    /** The controls that do it. Several tokens = they must all be engaged together. */
+    combo: readonly ComboToken[];
+    /** The controls must be engaged IN ORDER rather than together. */
+    sequence?: boolean;
+    /** A quieter line under the label. */
+    hint?: string;
+    /** Stable key, for `onStepComplete`. Falls back to `label`. */
+    id?: string;
+}
+export interface ControlTrainerOptions {
+    /** The one thing the lesson is about — e.g. "Changer la résistance". */
+    title: string;
+    /** One panel per step, laid left → right in the order given. */
+    steps: readonly TrainerStep[];
+    /** The input to watch. Without it the lesson still renders and prompts, but can never complete. */
+    press?: TrainerInputSource;
+    brand?: PadBrandKey;
+    glyphSet?: GlyphSet;
+    labels?: boolean;
+    accent?: string;
+    colored?: boolean;
+    stickStyle?: StickPictogramStyle;
+    /** Pad size preset. Default `"lg"` — the drawing is the shared reference here, so make it readable. */
+    size?: "sm" | "md" | "lg";
+    /**
+     * How long to hold on the final ✓ before `onComplete`. Default 900ms.
+     *
+     * Not decoration: firing the instant the last control is released would yank the lesson away before the
+     * rider sees that they got it right, which is the only feedback the whole exercise exists to give.
+     */
+    completionDelayMs?: number;
+    onStepComplete?(step: TrainerStep, index: number): void;
+    /** Every step done. The host closes its modal here — the component never closes itself. */
+    onComplete?(): void;
+}
+export interface ControlTrainer {
+    readonly root: HTMLDivElement;
+    readonly pad: ControllerPad;
+    /** Which steps are done, by index. */
+    completed(): readonly boolean[];
+    /** Back to square one — every step un-done, prompts pulsing again. */
+    reset(): void;
+    dispose(): void;
+}
+export declare function mountControlTrainer(host: HTMLElement, opts: ControlTrainerOptions): ControlTrainer;
+//# sourceMappingURL=control-trainer.d.ts.map

package/dist/ui/controller/control-trainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-trainer.d.ts","sourceRoot":"","sources":["../../../src/ui/controller/control-trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAkB,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3E,OAAO,EAAgD,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9G,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,YAAY,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC/E,IAAI,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE;YAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;SAAE,CAAC;QACjC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE;YAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;SAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KACzE,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,mGAAmG;IACnG,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,uGAAuG;IACvG,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,2FAA2F;IAC3F,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,sCAAsC;IACtC,SAAS,IAAI,SAAS,OAAO,EAAE,CAAC;IAChC,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,IAAI,CAAC;CACjB;AA0DD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,qBAAqB,GAAG,cAAc,CAuelG"}