@rydr/game-sdk 8.14.0 → 8.16.0

package/dist/three/controller/joycon-object.d.ts

@@ -0,0 +1,216 @@
+/**
+ * THE JOY-CON AS AN OBJECT — the pad's model *and everything that makes it react*, with no camera,
+ * no canvas and no renderer attached (PLAT-1582).
+ *
+ * ```ts
+ * import { createJoyconObject } from "@rydr/game-sdk/three";
+ *
+ * const pad = createJoyconObject({ view: "triggers" });
+ * pad.addLights(scene);          // the art direction brings its own rig
+ * pad.group.position.set(2, 1.4, -3);
+ * scene.add(pad.group);
+ *
+ * pad.driver.setPartState("rt", "hint");   // "press this"
+ *
+ * // in your own loop:
+ * pad.step(performance.now());
+ * ```
+ *
+ * ## Why this exists
+ *
+ * `JOYCON_DESIGNS[i].build()` has always handed back the geometry, and that was never enough: a raw
+ * `THREE.Group` is a MUTE pad. Everything that makes it say something — a key lighting, sinking,
+ * pulsing, a stick leaning, a letter re-inking so it stays readable on a lit face, the roll that brings
+ * a trigger into view — lived inside `createThreePadRenderer`'s closure, welded to a canvas the game
+ * doesn't want. So a game placing the pad in its OWN scene (on a table, on a wall, floating beside the
+ * rider) got a prop it could not drive.
+ *
+ * This module is that logic, lifted out and given a door. `createThreePadRenderer` is now a thin shell
+ * around it: canvas, camera, framing, the render loop and `partRect`. Both paths therefore animate
+ * through the SAME code, which is the point — a press could not look one way in the HUD and another way
+ * in the world.
+ *
+ * ## What you own when you use it directly
+ *
+ * The loop. This object has no `requestAnimationFrame` of its own, because a game already has one and a
+ * second one would render behind it. Call {@link JoyconObject.step} once per frame with the same
+ * timestamp you pass everything else; it returns `true` while anything is still moving, which is all a
+ * dirty-guarded renderer needs. Miss the call and the pad still *paints* (colour is immediate) but
+ * nothing *animates* — keys teleport and pulses never fade.
+ *
+ * You also own the yaw. The object's `group` is yours to rotate, scale and place; the tilt and the
+ * trigger roll live on an inner pivot so they can't fight you for `rotation.x`.
+ */
+import * as THREE from "three";
+import type { PadDriver, PadPartState } from "../../ui/controller/pad-svg.js";
+import type { PadDriverOptions } from "../../ui/controller/pad-svg.js";
+import type { PadLayout, PadPart } from "../../ui/controller/types.js";
+import { type JoyconBuild, type JoyconDesignId } from "./joycon-designs.js";
+import { type PadViewName } from "./joycon-spec.js";
+import { type PressHoldStyle, type PressPulseStyle } from "./press-pulse.js";
+/**
+ * The four things a part can say, as colours. Same grammar and same hues as the flat pad's CSS.
+ *
+ * `off` is the FALLBACK only. A resting key is painted the colour its design built it in — see
+ * `restColor` — because a single hard-coded rest colour repainted every design into the same blue-grey
+ * pad the moment a driver touched it: the art direction survived in the showcase, which builds a model
+ * and never paints it, and was thrown away everywhere a view actually used one. That is also why a
+ * black pad with white keys came out with blue-grey keys.
+ */
+export declare const PAD_STATE_COLOR: Readonly<Record<PadPartState, number>>;
+/**
+ * How the pad is posed and how it reacts — everything both the in-scene object and the HUD renderer
+ * need, and nothing about a canvas.
+ *
+ * `createThreePadRenderer` extends this, so an option documented here means exactly the same thing
+ * there. That is deliberate: the two paths draw the same pad and must be tuned with the same words.
+ */
+export interface JoyconObjectOptions extends PadDriverOptions {
+    /** Which art direction to draw. Default `"toy"` — the one built for reading at a distance. */
+    design?: JoyconDesignId;
+    /**
+     * A named orientation — `"front"`, `"angled"` (the default) or `"triggers"`. See {@link PAD_VIEWS}.
+     *
+     * This is the plain-words version of {@link tilt} + {@link yaw}: "show me the triggers" rather than
+     * "pitch 0.95 rad". Either of those, passed explicitly, still wins over the preset — so a view can be
+     * a starting point that you then nudge.
+     */
+    view?: PadViewName;
+    /** Forward tilt in radians. Default: the tilt of {@link view}, else {@link VIEW.pitch}. */
+    tilt?: number;
+    /** Turn about the vertical axis, radians. Default: the yaw of {@link view}, else 0 — head-on. */
+    yaw?: number;
+    /** Accent colour for pressed parts, as anything `THREE.Color` accepts. */
+    accent?: string;
+    /**
+     * Colour of the `hint` state — "press this". Default: the kit's near-white.
+     *
+     * ⚠️ Setting it to {@link accent} collapses *do this* and *you are doing it* into one picture — see
+     * `PadRendererOptions.hintColor`, where that trade-off is spelt out.
+     */
+    hintColor?: string;
+    /**
+     * Extra forward tilt applied while a TRIGGER is being shown, radians. Default 0.38 (~22°).
+     *
+     * This is the reason the pad is modelled in 3D at all. `ZL`/`ZR` sit on the back of the crown: from
+     * the reading angle they are edge-on, and a view teaching one would be pointing at a sliver. When a
+     * trigger lights, the pad rolls forward so the top face — and the key — come into view, then rolls
+     * back when it is released. The flat pad had to draw the triggers floating above the shell instead,
+     * which is a picture of a controller that does not exist.
+     *
+     * Set to 0 to pin the pad still — which is what you want under `view: "triggers"`, where the crown is
+     * already facing the viewer and a roll on top of it would tip the pad past flat.
+     */
+    triggerTilt?: number;
+    /** Milliseconds the roll takes, each way. Default 420. */
+    triggerTiltMs?: number;
+    /**
+     * The white circle that marks the INSTANT a key goes down. Default `"wave"`; `"none"` turns it off.
+     *
+     * Without it a press says nothing an eye can catch: the key's travel is along the viewing axis, so
+     * the tilt projects it to almost nothing, and what is left is a colour change — a state, not an
+     * event. See `press-pulse.ts` for the three animations and what each is good for.
+     */
+    pressPulse?: PressPulseStyle;
+    /**
+     * What a key does while it is HELD, once its press has been marked. Default `"echo"`.
+     *
+     * A separate axis from {@link pressPulse}, because "a key went down" and "a key is still down" are
+     * two different things to say. `"echo"` repeats the pulse quietly, `"collar"` parks a breathing ring
+     * at the key's edge, `"none"` says nothing.
+     *
+     * Note the cost: anything but `"none"` means the pad is animating for as long as a key is held, so it
+     * cannot go fully idle during a hold. That is a frame of work while the rider is holding a button,
+     * not while they are doing nothing — but it is the one case where the dirty-guard yields.
+     */
+    pressHold?: PressHoldStyle;
+    /**
+     * How deep a pressed key sinks, as a fraction of the shell's width. Default 0.07.
+     *
+     * The travel runs along the viewing axis, so the tilt eats most of it on screen — raise this if the
+     * pad is being read from far away or nearly head-on, where there is even less of it left.
+     */
+    pressTravel?: number;
+    /** Lifetime of one press pulse, ms. Default 500. */
+    pressPulseMs?: number;
+    /** Multiplier on the pulse's radius. Default 1.4 — the size judged on the showcase. */
+    pressPulseScale?: number;
+    /**
+     * The layout whose lettering is printed on the keys. Default: the Joy-Con layout.
+     *
+     * Only the glyphs are read from it — the geometry is always the modelled Joy-Con. Pass the layout a
+     * view is already using so the printed letters match the rest of the screen.
+     */
+    layout?: PadLayout;
+}
+/**
+ * A Joy-Con you can put in a scene and drive.
+ *
+ * Everything a renderer needs is here, which is exactly why `createThreePadRenderer` is now short: what
+ * it adds on top is a canvas, a camera, a framing rule and a projection — not behaviour.
+ */
+export interface JoyconObject {
+    /**
+     * Put this in your scene. Yours to move, scale and YAW.
+     *
+     * The tilt and the trigger roll are applied to an inner pivot ({@link tiltGroup}), so setting
+     * `group.rotation.x` yourself doesn't fight them — and setting `group.rotation.y` is the supported
+     * way to turn the pad once it's in a world.
+     */
+    readonly group: THREE.Group;
+    /** The inner pivot carrying the reading tilt and the trigger roll. Read it; don't write to it. */
+    readonly tiltGroup: THREE.Group;
+    /** What the design built — geometry, control nodes, stick pivots, disposables. */
+    readonly model: JoyconBuild;
+    /** Light a key, sink it, lean a stick. The same `PadDriver` every controller view speaks. */
+    readonly driver: PadDriver;
+    /** Every part this model actually draws. */
+    readonly parts: readonly PadPart[];
+    /** The node behind a part, for hanging your own things off a key (a label, an arrow). */
+    nodeOf(part: PadPart): THREE.Object3D | undefined;
+    /**
+     * Add the design's OWN lighting rig to your scene.
+     *
+     * Lighting is part of the art direction — a separate rig makes the same pad look like a different
+     * pad. Skip it only if your scene's lighting is deliberately taking over; the materials are standard
+     * PBR, so with no lights at all the pad renders black.
+     */
+    addLights(target: THREE.Object3D): void;
+    /**
+     * Advance every animation. Call once per frame; returns `true` while anything is still moving.
+     *
+     * `now` should be a `performance.now()`-style millisecond timestamp — pass the one your loop already
+     * has rather than calling it again, so the pad is on the same clock as the rest of the frame.
+     */
+    step(now: number): boolean;
+    /**
+     * Fires whenever the pad's appearance changed and a dirty-guarded renderer should redraw.
+     *
+     * Irrelevant if you render every frame anyway — which a game does. Returns an unsubscribe.
+     */
+    onChange(cb: () => void): () => void;
+    /**
+     * Fires while the pad MOVES on its own — the roll a lit trigger provokes.
+     *
+     * Anything positioned from a projection of the pad (a caption, a leader line) has to re-place itself
+     * here or it is left behind. Returns an unsubscribe.
+     */
+    onPoseChange(cb: () => void): () => void;
+    /**
+     * Mark the parts a callout currently points at.
+     *
+     * Only meaningful for the parts drawn faint (the shell's View/Guide): a callout pointing at one makes
+     * it the subject of the screen, and leaving it at 40% then reads as "disabled".
+     */
+    setReferenced(parts: ReadonlySet<PadPart>): void;
+    /** Release geometry, materials and textures. The `group` is removed from its parent. */
+    dispose(): void;
+}
+/**
+ * Build a Joy-Con that lives in your scene and reacts like the one in the HUD.
+ *
+ * For a pad framed in its own canvas — a controls screen, a HUD corner — you want
+ * `createThreePadRenderer` (or `mountPadHud` from `@rydr/game-sdk/ui`) instead; both are built on this.
+ */
+export declare function createJoyconObject(opts?: JoyconObjectOptions): JoyconObject;
+//# sourceMappingURL=joycon-object.d.ts.map

package/dist/three/controller/joycon-object.d.ts.map

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