@rydr/game-sdk 8.11.0 → 8.12.0

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

@@ -0,0 +1,233 @@
+/**
+ * WHAT A JOY-CON ACTUALLY IS, in numbers — the shared spec behind every 3D design.
+ *
+ * The first attempt at a 3D pad extruded the flat drawing's viewBox and gave it a little depth. That
+ * produced something that reads as *the flat pad, tilted*: the shell was 6× wider than it was thick,
+ * and the buttons stood 3% of their own diameter proud of it. Both are wrong. A real Joy-Con is
+ * **102 × 35.9 × 28.4 mm** — nearly as thick as it is wide, a bar rather than a plate — and its buttons
+ * are domes you could catch a fingernail on.
+ *
+ * So the geometry here is built from the HARDWARE's proportions, and the flat layout is used only for
+ * what it is genuinely authoritative about: **which control sits where on the face**, as a fraction of
+ * the shell. That split is deliberate —
+ *
+ *   - the layout owns the *arrangement* (stick above the d-pad on the left, diamond above the stick on
+ *     the right, `−` top-inner, Home bottom-centre), which is the thing every view depends on;
+ *   - this file owns the *proportions*, which the layout deliberately distorts because a schematic
+ *     drawing is not a scale drawing.
+ *
+ * Every number below was MEASURED off a reference Joy-Con model, not estimated: proportions, control
+ * positions, control sizes and how far each stands off the face. `u` runs 0 → 1 left-to-right across
+ * one shell, `v` runs 0 → 1 top-to-bottom.
+ *
+ * The measurements corrected two things the estimates got wrong: the halves sit much further apart
+ * than the flat drawing suggests (0.72 of a shell's width), and both control clusters are pushed
+ * INWARD, towards the middle of the pair, where the thumbs actually fall.
+ */
+/**
+ * THE TUNABLE NUMBERS.
+ *
+ * Everything below is derived from this object, and {@link applyTuning} recomputes the derived values
+ * in place. That exists so the shape can be dialled in from a control panel in the showcase instead of
+ * through an edit-rebuild-look loop — the person judging the shape is the one who should be turning
+ * the knobs.
+ *
+ * Values are RATIOS, not absolute sizes, so the pad stays coherent whatever you change: depths and
+ * radii are fractions of the shell's width, the width itself is a fraction of its height.
+ */
+export declare const TUNING: {
+    /**
+     * Shell height and width, INDEPENDENTLY.
+     *
+     * They used to be one knob (a height ÷ width ratio), which meant you could not make the pad taller
+     * without also making it narrower. Everything else in this object is a fraction of the WIDTH, so
+     * depths, radii and control sizes still follow it — only the height is now free.
+     *
+     * For reference, the measured hardware ratio is 2.9869 : 1.
+     */
+    shellHeight: number;
+    shellWidth: number;
+    /** Depth at the crown, ÷ width. */
+    depthTop: number;
+    /** Depth at the base, ÷ width. The taper that makes room for the triggers. */
+    depthBottom: number;
+    /** Height fraction (0 = crown) at which the taper happens, and how softly. */
+    breakV: number;
+    breakSoft: number;
+    /** Space between the two halves, ÷ width. */
+    gap: number;
+    /** Rounding of the shell's vertical edges, ÷ width. */
+    shellRadius: number;
+    /** Corner radii of the face outline, ÷ width. Outer is the rounded side, inner the rail side. */
+    outerTopR: number;
+    outerBottomR: number;
+    innerTopR: number;
+    innerBottomR: number;
+    /** Radii, ÷ width. */
+    faceR: number;
+    dpadR: number;
+    systemR: number;
+    /** How far a domed button stands proud of the face, ÷ width. */
+    buttonRise: number;
+    /** `−` and `+` are nearly flush. */
+    systemRise: number;
+    stickWellR: number;
+    stickCapR: number;
+    stickHeight: number;
+    /** Height of the cap itself, ÷ its own radius. A real thumb cap is roughly 0.7 — it is not a disc. */
+    stickCapDepth: number;
+    /** How deep the thumb dish sinks below the rim, ÷ cap radius. */
+    stickCapDish: number;
+    /**
+     * The shoulder keys are the reference model's own triangles, so their SHAPE is fixed. What is
+     * adjustable is how they sit: pushed out along their normals so they clear the generated crown,
+     * lifted, and scaled.
+     *
+     * `lift` matters most, and must not be 0. On the reference, `ZL`'s surface IS the shell's top —
+     * coplanar with it. Ours is a separate mesh, so at 0 the two surfaces occupy the same plane and
+     * z-fight, which shows as a ragged hole in the key.
+     */
+    shoulderLift: number;
+    /** Extra vertical raise, ÷ width. */
+    shoulderRaise: number;
+    /** Overall scale of the shoulder keys, 1 = as measured. */
+    shoulderScale: number;
+    /** Default camera pitch in DEGREES. Past ~35° the pad foreshortens into a plan view. */
+    pitchDeg: number;
+    /** Camera field of view. */
+    fovDeg: number;
+};
+/** Shell height in world units. */
+export declare let H: number;
+/** Shell width. */
+export declare let W: number;
+/** Depth at the TOP of the shell, where it is thickest. */
+export declare let DEPTH_TOP: number;
+/**
+ * Depth at the BOTTOM.
+ *
+ * Measured at 58% of the top, and it is the shape's whole point: the shell is a wedge, thick at the
+ * top and tapering down. The bulge makes room for the triggers, and it is entirely on the BACK — the
+ * front face, where every button lives, is dead flat top to bottom.
+ */
+export declare let DEPTH_BOTTOM: number;
+/** Deepest the shell ever gets — what the pair's bounding box is sized from. */
+export declare let D: number;
+/** Gap between the halves. */
+export declare let GAP: number;
+/** Corner rounding of the shell. */
+export declare let SHELL_RADIUS: number;
+/**
+ * The silhouette is ASYMMETRIC, and that is the shape's signature.
+ *
+ * The INNER edge — the one carrying the rail, that docks against the console — runs dead straight from
+ * top to bottom. All the rounding is on the OUTER edge. A symmetric rounded rectangle reads as a
+ * generic slab; this is what makes it a Joy-Con.
+ */
+export declare let SILHOUETTE: {
+    outerTopR: number;
+    outerBottomR: number;
+    innerTopR: number;
+    innerBottomR: number;
+};
+/** Control sizes, as fractions of the shell width — so they scale with the model. */
+export declare let SIZES: {
+    faceR: number;
+    dpadR: number;
+    systemR: number;
+    stickWellR: number;
+    stickCapR: number;
+    stickHeight: number;
+    buttonRise: number;
+    systemRise: number;
+};
+/**
+ * Recompute every derived value from {@link TUNING}.
+ *
+ * Call after changing TUNING and before rebuilding a model. The exports above are ES module live
+ * bindings, so importers see the new numbers without re-importing.
+ */
+export declare function applyTuning(): void;
+/** The shell's depth at height `v` (0 = top, 1 = bottom). */
+export declare function depthAtV(v: number): number;
+/** A control's place on one shell's face, as a fraction: `u` across, `v` down. */
+export interface FacePos {
+    /** Across the shell, 0 = outer edge … 1 = inner (rail) edge. */
+    u: number;
+    /** Down the shell, 0 = crown … 1 = base. */
+    v: number;
+}
+/** Convert a face position to world x/y within a shell centred on the origin. */
+export declare function faceToLocal(p: FacePos): {
+    x: number;
+    y: number;
+};
+/**
+ * The LEFT half's controls, normalised from `JOYCON_LAYOUT` (shell x 24→104, y 16→142).
+ *
+ * The left half is the one with the stick UP TOP and four discrete direction buttons below it — not a
+ * cross. That is real: a Joy-Con's left half has four separate round buttons, which is why the flat
+ * layout models them individually too.
+ */
+export declare const LEFT_FACE: Record<string, FacePos>;
+/** The RIGHT half's controls: the face diamond up top, stick below it. */
+export declare const RIGHT_FACE: Record<string, FacePos>;
+/**
+ * The shoulder row, on the TOP face of each half.
+ *
+ * `SR`/`SL` (the inner rail buttons) are omitted throughout: they only exist when a half is used
+ * sideways as its own controller, which is not how a paired set is held, and drawing a control the
+ * rider can't press is worse than drawing nothing — the same rule the flat layout follows.
+ */
+export declare const SHOULDER: {
+    /**
+     * Width and depth, PER KEY — they are not the same shape, and that is the point.
+     *
+     * Measured off the reference's top face:
+     *   `L`/`R`    a thin band across nearly the full width — 96% wide, 19% deep
+     *   `ZL`/`ZR`  a broad pad running back to the rear edge — 79% wide, 56% deep
+     *
+     * So the rear key takes almost THREE TIMES the depth of the front one while being slightly narrower.
+     * Giving them near-identical footprints (the previous version: 20% and 26% deep, same width) is what
+     * made the row read as two matching bars instead of a bumper and a trigger.
+     *
+     * The widths are pulled in slightly from the measured 0.96 / 0.79, because our crown is rounded
+     * harder than the reference's — a full-width band would hang off it.
+     */
+    readonly bumperWidthFrac: 0.9;
+    readonly bumperDepthFrac: 0.19;
+    readonly triggerWidthFrac: 0.74;
+    readonly triggerDepthFrac: 0.56;
+    /**
+     * How far each stands proud of the top face.
+     *
+     * On the reference neither really does: the front band clears the shell by 0.0018, and the rear pad
+     * IS the shell's top surface, in a different colour. We keep a small lift so the two still read as
+     * separate controls from metres away, but nothing like the blocks this started as.
+     */
+    readonly bumperRise: number;
+    readonly triggerRise: number;
+    /**
+     * How far `ZL`/`ZR` runs DOWN THE BACK of the shell, past the top-rear corner.
+     *
+     * The defining feature of the rear trigger, and the thing that separates it from a bumper: it is
+     * pressed with the index finger from behind, so it wraps the corner instead of lying on the crown.
+     * `L`/`R` has no wrap at all.
+     */
+    readonly triggerWrap: number;
+};
+/**
+ * Default viewing angles, radians.
+ *
+ * A three-quarter view is the whole point: head-on, a 3D pad is indistinguishable from the flat one,
+ * and the triggers — the reason for modelling it at all — are invisible. Tilting the top towards the
+ * viewer reveals the top face; a slight yaw gives the shell's thickness somewhere to read.
+ */
+export declare const VIEW: {
+    /** Pitch, from {@link TUNING.pitchDeg}. Kept modest: the pad is 3× taller than wide, so pitch eats
+     *  its apparent height fast and past ~35° you are looking down at its top face. */
+    readonly pitch: number;
+    /** Yaw: a slight turn so the pair isn't perfectly symmetric and the side walls catch light. */
+    yaw: number;
+};
+//# sourceMappingURL=joycon-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"joycon-spec.d.ts","sourceRoot":"","sources":["../../../src/three/controller/joycon-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM;IAEjB;;;;;;;;OAQG;;;IAGH,mCAAmC;;IAEnC,8EAA8E;;IAE9E,8EAA8E;;;IAG9E,6CAA6C;;IAE7C,uDAAuD;;IAIvD,iGAAiG;;;;;IAOjG,sBAAsB;;;;IAItB,gEAAgE;;IAEhE,oCAAoC;;;;;IAKpC,sGAAsG;;IAEtG,iEAAiE;;IAIjE;;;;;;;;OAQG;;IAEH,qCAAqC;;IAErC,2DAA2D;;IAI3D,wFAAwF;;IAExF,4BAA4B;;CAE7B,CAAC;AAEF,mCAAmC;AACnC,eAAO,IAAI,CAAC,QAAqB,CAAC;AAGlC,mBAAmB;AACnB,eAAO,IAAI,CAAC,QAAoB,CAAC;AACjC,2DAA2D;AAC3D,eAAO,IAAI,SAAS,QAAsB,CAAC;AAC3C;;;;;;GAMG;AACH,eAAO,IAAI,YAAY,QAAyB,CAAC;AACjD,gFAAgF;AAChF,eAAO,IAAI,CAAC,QAAY,CAAC;AACzB,8BAA8B;AAC9B,eAAO,IAAI,GAAG,QAAiB,CAAC;AAChC,oCAAoC;AACpC,eAAO,IAAI,YAAY,QAAyB,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,IAAI,UAAU;;;;;CAKpB,CAAC;AAEF,qFAAqF;AACrF,eAAO,IAAI,KAAK;;;;;;;;;CASf,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAwBlC;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI1C;AAED,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,gEAAgE;IAChE,CAAC,EAAE,MAAM,CAAC;IACV,4CAA4C;IAC5C,CAAC,EAAE,MAAM,CAAC;CACX;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAEhE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAU7C,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAa9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;;;;;;;;;OAaG;;;;;IAKH;;;;;;OAMG;;;IAGH;;;;;;OAMG;;CAEK,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;IACf;uFACmF;oBACtE,MAAM;IAGnB,+FAA+F;;CAEhG,CAAC"}

package/dist/three/controller/joycon-spec.js

@@ -0,0 +1,285 @@
+/**
+ * WHAT A JOY-CON ACTUALLY IS, in numbers — the shared spec behind every 3D design.
+ *
+ * The first attempt at a 3D pad extruded the flat drawing's viewBox and gave it a little depth. That
+ * produced something that reads as *the flat pad, tilted*: the shell was 6× wider than it was thick,
+ * and the buttons stood 3% of their own diameter proud of it. Both are wrong. A real Joy-Con is
+ * **102 × 35.9 × 28.4 mm** — nearly as thick as it is wide, a bar rather than a plate — and its buttons
+ * are domes you could catch a fingernail on.
+ *
+ * So the geometry here is built from the HARDWARE's proportions, and the flat layout is used only for
+ * what it is genuinely authoritative about: **which control sits where on the face**, as a fraction of
+ * the shell. That split is deliberate —
+ *
+ *   - the layout owns the *arrangement* (stick above the d-pad on the left, diamond above the stick on
+ *     the right, `−` top-inner, Home bottom-centre), which is the thing every view depends on;
+ *   - this file owns the *proportions*, which the layout deliberately distorts because a schematic
+ *     drawing is not a scale drawing.
+ *
+ * Every number below was MEASURED off a reference Joy-Con model, not estimated: proportions, control
+ * positions, control sizes and how far each stands off the face. `u` runs 0 → 1 left-to-right across
+ * one shell, `v` runs 0 → 1 top-to-bottom.
+ *
+ * The measurements corrected two things the estimates got wrong: the halves sit much further apart
+ * than the flat drawing suggests (0.72 of a shell's width), and both control clusters are pushed
+ * INWARD, towards the middle of the pair, where the thumbs actually fall.
+ */
+/**
+ * THE TUNABLE NUMBERS.
+ *
+ * Everything below is derived from this object, and {@link applyTuning} recomputes the derived values
+ * in place. That exists so the shape can be dialled in from a control panel in the showcase instead of
+ * through an edit-rebuild-look loop — the person judging the shape is the one who should be turning
+ * the knobs.
+ *
+ * Values are RATIOS, not absolute sizes, so the pad stays coherent whatever you change: depths and
+ * radii are fractions of the shell's width, the width itself is a fraction of its height.
+ */
+export const TUNING = {
+    // ── proportions ──
+    /**
+     * Shell height and width, INDEPENDENTLY.
+     *
+     * They used to be one knob (a height ÷ width ratio), which meant you could not make the pad taller
+     * without also making it narrower. Everything else in this object is a fraction of the WIDTH, so
+     * depths, radii and control sizes still follow it — only the height is now free.
+     *
+     * For reference, the measured hardware ratio is 2.9869 : 1.
+     */
+    shellHeight: 1.42,
+    shellWidth: 0.77,
+    /** Depth at the crown, ÷ width. */
+    depthTop: 0.625,
+    /** Depth at the base, ÷ width. The taper that makes room for the triggers. */
+    depthBottom: 0.461,
+    /** Height fraction (0 = crown) at which the taper happens, and how softly. */
+    breakV: 0.25,
+    breakSoft: 0.36,
+    /** Space between the two halves, ÷ width. */
+    gap: 0.7162,
+    /** Rounding of the shell's vertical edges, ÷ width. */
+    shellRadius: 0.17,
+    // ── silhouette ──
+    /** Corner radii of the face outline, ÷ width. Outer is the rounded side, inner the rail side. */
+    outerTopR: 0.5,
+    outerBottomR: 0.5,
+    innerTopR: 0.09,
+    innerBottomR: 0.09,
+    // ── controls ──
+    /** Radii, ÷ width. */
+    faceR: 0.07,
+    dpadR: 0.07,
+    systemR: 0.06,
+    /** How far a domed button stands proud of the face, ÷ width. */
+    buttonRise: 0.042,
+    /** `−` and `+` are nearly flush. */
+    systemRise: 0.008,
+    stickWellR: 0.215,
+    stickCapR: 0.15,
+    stickHeight: 0.17,
+    /** Height of the cap itself, ÷ its own radius. A real thumb cap is roughly 0.7 — it is not a disc. */
+    stickCapDepth: 0.7,
+    /** How deep the thumb dish sinks below the rim, ÷ cap radius. */
+    stickCapDish: 0.26,
+    // ── shoulders ──
+    /**
+     * The shoulder keys are the reference model's own triangles, so their SHAPE is fixed. What is
+     * adjustable is how they sit: pushed out along their normals so they clear the generated crown,
+     * lifted, and scaled.
+     *
+     * `lift` matters most, and must not be 0. On the reference, `ZL`'s surface IS the shell's top —
+     * coplanar with it. Ours is a separate mesh, so at 0 the two surfaces occupy the same plane and
+     * z-fight, which shows as a ragged hole in the key.
+     */
+    shoulderLift: 0.008,
+    /** Extra vertical raise, ÷ width. */
+    shoulderRaise: 0.052,
+    /** Overall scale of the shoulder keys, 1 = as measured. */
+    shoulderScale: 1.07,
+    // ── view ──
+    /** Default camera pitch in DEGREES. Past ~35° the pad foreshortens into a plan view. */
+    pitchDeg: 21,
+    /** Camera field of view. */
+    fovDeg: 32,
+};
+/** Shell height in world units. */
+export let H = TUNING.shellHeight;
+/* eslint-disable prefer-const -- these are live bindings, rewritten by applyTuning(). */
+/** Shell width. */
+export let W = TUNING.shellWidth;
+/** Depth at the TOP of the shell, where it is thickest. */
+export let DEPTH_TOP = W * TUNING.depthTop;
+/**
+ * Depth at the BOTTOM.
+ *
+ * Measured at 58% of the top, and it is the shape's whole point: the shell is a wedge, thick at the
+ * top and tapering down. The bulge makes room for the triggers, and it is entirely on the BACK — the
+ * front face, where every button lives, is dead flat top to bottom.
+ */
+export let DEPTH_BOTTOM = W * TUNING.depthBottom;
+/** Deepest the shell ever gets — what the pair's bounding box is sized from. */
+export let D = DEPTH_TOP;
+/** Gap between the halves. */
+export let GAP = W * TUNING.gap;
+/** Corner rounding of the shell. */
+export let SHELL_RADIUS = W * TUNING.shellRadius;
+/**
+ * The silhouette is ASYMMETRIC, and that is the shape's signature.
+ *
+ * The INNER edge — the one carrying the rail, that docks against the console — runs dead straight from
+ * top to bottom. All the rounding is on the OUTER edge. A symmetric rounded rectangle reads as a
+ * generic slab; this is what makes it a Joy-Con.
+ */
+export let SILHOUETTE = {
+    outerTopR: W * TUNING.outerTopR,
+    outerBottomR: W * TUNING.outerBottomR,
+    innerTopR: W * TUNING.innerTopR,
+    innerBottomR: W * TUNING.innerBottomR,
+};
+/** Control sizes, as fractions of the shell width — so they scale with the model. */
+export let SIZES = {
+    faceR: W * TUNING.faceR,
+    dpadR: W * TUNING.dpadR,
+    systemR: W * TUNING.systemR,
+    stickWellR: W * TUNING.stickWellR,
+    stickCapR: W * TUNING.stickCapR,
+    stickHeight: W * TUNING.stickHeight,
+    buttonRise: W * TUNING.buttonRise,
+    systemRise: W * TUNING.systemRise,
+};
+/* eslint-enable prefer-const */
+/**
+ * Recompute every derived value from {@link TUNING}.
+ *
+ * Call after changing TUNING and before rebuilding a model. The exports above are ES module live
+ * bindings, so importers see the new numbers without re-importing.
+ */
+export function applyTuning() {
+    H = TUNING.shellHeight;
+    W = TUNING.shellWidth;
+    DEPTH_TOP = W * TUNING.depthTop;
+    DEPTH_BOTTOM = W * TUNING.depthBottom;
+    D = DEPTH_TOP;
+    GAP = W * TUNING.gap;
+    SHELL_RADIUS = W * TUNING.shellRadius;
+    SILHOUETTE = {
+        outerTopR: W * TUNING.outerTopR,
+        outerBottomR: W * TUNING.outerBottomR,
+        innerTopR: W * TUNING.innerTopR,
+        innerBottomR: W * TUNING.innerBottomR,
+    };
+    SIZES = {
+        faceR: W * TUNING.faceR,
+        dpadR: W * TUNING.dpadR,
+        systemR: W * TUNING.systemR,
+        stickWellR: W * TUNING.stickWellR,
+        stickCapR: W * TUNING.stickCapR,
+        stickHeight: W * TUNING.stickHeight,
+        buttonRise: W * TUNING.buttonRise,
+        systemRise: W * TUNING.systemRise,
+    };
+}
+/** The shell's depth at height `v` (0 = top, 1 = bottom). */
+export function depthAtV(v) {
+    const t = Math.min(1, Math.max(0, (v - TUNING.breakV) / TUNING.breakSoft));
+    const smooth = t * t * (3 - 2 * t);
+    return DEPTH_TOP + (DEPTH_BOTTOM - DEPTH_TOP) * smooth;
+}
+/** Convert a face position to world x/y within a shell centred on the origin. */
+export function faceToLocal(p) {
+    return { x: (p.u - 0.5) * W, y: (0.5 - p.v) * H };
+}
+/**
+ * The LEFT half's controls, normalised from `JOYCON_LAYOUT` (shell x 24→104, y 16→142).
+ *
+ * The left half is the one with the stick UP TOP and four discrete direction buttons below it — not a
+ * cross. That is real: a Joy-Con's left half has four separate round buttons, which is why the flat
+ * layout models them individually too.
+ */
+export const LEFT_FACE = {
+    stick: { u: 0.568, v: 0.284 },
+    dpadUp: { u: 0.600, v: 0.465 },
+    dpadDown: { u: 0.600, v: 0.600 },
+    dpadLeft: { u: 0.395, v: 0.531 },
+    dpadRight: { u: 0.792, v: 0.531 },
+    /** `−`, top INNER corner — towards the right half. */
+    select: { u: 0.79, v: 0.124 },
+    /** The square capture button, bottom. */
+    capture: { u: 0.742, v: 0.707 },
+};
+/** The RIGHT half's controls: the face diamond up top, stick below it. */
+export const RIGHT_FACE = {
+    /** X — top of the diamond. Glyphs are in TRUE PHYSICAL places, as on the hardware. */
+    faceTop: { u: 0.442, v: 0.231 },
+    /** A — right. */
+    faceRight: { u: 0.633, v: 0.297 },
+    /** B — bottom. */
+    faceBottom: { u: 0.442, v: 0.365 },
+    /** Y — left. */
+    faceLeft: { u: 0.237, v: 0.297 },
+    stick: { u: 0.429, v: 0.569 },
+    /** `+`, top INNER corner — towards the left half. */
+    start: { u: 0.21, v: 0.124 },
+    home: { u: 0.299, v: 0.738 },
+};
+/**
+ * The shoulder row, on the TOP face of each half.
+ *
+ * `SR`/`SL` (the inner rail buttons) are omitted throughout: they only exist when a half is used
+ * sideways as its own controller, which is not how a paired set is held, and drawing a control the
+ * rider can't press is worse than drawing nothing — the same rule the flat layout follows.
+ */
+export const SHOULDER = {
+    /**
+     * Width and depth, PER KEY — they are not the same shape, and that is the point.
+     *
+     * Measured off the reference's top face:
+     *   `L`/`R`    a thin band across nearly the full width — 96% wide, 19% deep
+     *   `ZL`/`ZR`  a broad pad running back to the rear edge — 79% wide, 56% deep
+     *
+     * So the rear key takes almost THREE TIMES the depth of the front one while being slightly narrower.
+     * Giving them near-identical footprints (the previous version: 20% and 26% deep, same width) is what
+     * made the row read as two matching bars instead of a bumper and a trigger.
+     *
+     * The widths are pulled in slightly from the measured 0.96 / 0.79, because our crown is rounded
+     * harder than the reference's — a full-width band would hang off it.
+     */
+    bumperWidthFrac: 0.9,
+    bumperDepthFrac: 0.19,
+    triggerWidthFrac: 0.74,
+    triggerDepthFrac: 0.56,
+    /**
+     * How far each stands proud of the top face.
+     *
+     * On the reference neither really does: the front band clears the shell by 0.0018, and the rear pad
+     * IS the shell's top surface, in a different colour. We keep a small lift so the two still read as
+     * separate controls from metres away, but nothing like the blocks this started as.
+     */
+    bumperRise: W * 0.05,
+    triggerRise: W * 0.085,
+    /**
+     * How far `ZL`/`ZR` runs DOWN THE BACK of the shell, past the top-rear corner.
+     *
+     * The defining feature of the rear trigger, and the thing that separates it from a bumper: it is
+     * pressed with the index finger from behind, so it wraps the corner instead of lying on the crown.
+     * `L`/`R` has no wrap at all.
+     */
+    triggerWrap: W * 0.34,
+};
+/**
+ * Default viewing angles, radians.
+ *
+ * A three-quarter view is the whole point: head-on, a 3D pad is indistinguishable from the flat one,
+ * and the triggers — the reason for modelling it at all — are invisible. Tilting the top towards the
+ * viewer reveals the top face; a slight yaw gives the shell's thickness somewhere to read.
+ */
+export const VIEW = {
+    /** Pitch, from {@link TUNING.pitchDeg}. Kept modest: the pad is 3× taller than wide, so pitch eats
+     *  its apparent height fast and past ~35° you are looking down at its top face. */
+    get pitch() {
+        return (TUNING.pitchDeg * Math.PI) / 180;
+    },
+    /** Yaw: a slight turn so the pair isn't perfectly symmetric and the side walls catch light. */
+    yaw: -0.34,
+};
+//# sourceMappingURL=joycon-spec.js.map

package/dist/three/controller/joycon-spec.js.map

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

package/dist/three/controller/three-pad-renderer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * THE 3D PAD RENDERER — a Joy-Con pair in three.js, drop-in wherever the flat drawing goes.
+ *
+ * ```ts
+ * import { createThreePadRenderer } from "@rydr/game-sdk/three";
+ * import { mountControllerMap } from "@rydr/game-sdk/ui";
+ *
+ * mountControllerMap(host, { press: session, actions, renderer: createThreePadRenderer });
+ * ```
+ *
+ * It satisfies `PadRenderer` (see `ui/controller/renderer.ts`), which is the entire contract the five
+ * controller views speak. So the map's leader lines, the combo demo's timeline, the spotlight's
+ * captions and the guided lesson's gating all work against it **unchanged** — none of them knows or
+ * cares that there is a WebGL canvas where an `<svg>` used to be.
+ *
+ * ## What the third dimension actually buys
+ *
+ * Two things the flat pad could not say:
+ *
+ *   1. **The triggers are visible.** `ZL`/`ZR` live on the back of each half. The flat drawing had to
+ *      float them above the shell (that's what the `y −20` band in `PAD_VIEWBOX` is for). Here they sit
+ *      where they really are, and the pad tilts forward just enough to show them.
+ *   2. **A press is a press.** The flat pad simulates depth by dropping a shape onto its own drop
+ *      shadow. Here the button actually moves along the viewing axis, and a stick actually leans.
+ *
+ * ## Only the Joy-Con
+ *
+ * `brand: "joycon"` is the one silhouette modelled — it's what PLAT-1556 asked for, and it happens to
+ * be the most tractable shape in the kit (two rounded slabs rather than one organic shell). Ask this
+ * renderer for any other brand and it says so and draws the Joy-Con anyway, rather than failing: a
+ * caller who pinned `brand` has a bug, and a blank canvas hides it.
+ *
+ * ## Cost
+ *
+ * One WebGL context per mounted pad, and browsers cap those (~8–16). A page showing several 3D views at
+ * once is close to that ceiling — which is why the render loop is shared, idle-skipping and paused on a
+ * hidden tab: a pad nobody is touching costs nothing per frame, exactly like the flat one's dirty-guard.
+ */
+import { type PadRenderer, type PadRendererOptions } from "../../ui/controller/renderer.js";
+import type { PadLayout } from "../../ui/controller/types.js";
+import { type JoyconDesignId } from "./joycon-designs.js";
+export interface ThreePadRendererOptions extends PadRendererOptions {
+    /** Which art direction to draw. Default `"toy"` — the one built for reading at a distance. */
+    design?: JoyconDesignId;
+    /** Forward tilt in radians. Default {@link VIEW.pitch}. */
+    tilt?: number;
+    /** Turn about the vertical axis, radians. Default 0 — head-on. */
+    yaw?: number;
+    /**
+     * 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.
+     */
+    triggerTilt?: number;
+    /** Seconds the roll takes, each way. Default 0.42. */
+    triggerTiltMs?: number;
+    /**
+     * How much of the frame the pad fills, 0…1. Default 0.82.
+     *
+     * A control map surrounds the pad with callout cards, so it wants a smaller pad than a view showing
+     * the pad alone; this is the knob for that rather than resizing the host.
+     */
+    fill?: number;
+    /** Nudge within the frame, in fractions of the frame. Positive x is right, positive y is up. */
+    offsetX?: number;
+    offsetY?: number;
+    /** Device pixel ratio cap. Default 2 — past that a pad this small costs pixels for nothing. */
+    maxPixelRatio?: number;
+}
+/**
+ * Build a three.js pad renderer. Matches {@link PadRendererFactory}, so it can be handed straight to
+ * any controller view's `renderer` option.
+ */
+export declare function createThreePadRenderer(layout: PadLayout, opts?: ThreePadRendererOptions): PadRenderer;
+//# sourceMappingURL=three-pad-renderer.d.ts.map

package/dist/three/controller/three-pad-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-pad-renderer.d.ts","sourceRoot":"","sources":["../../../src/three/controller/three-pad-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EAExB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAmC5F,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,8FAA8F;IAC9F,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,uBAA4B,GACjC,WAAW,CAuXb"}