@rydr/game-sdk 8.13.0 → 8.15.0

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

@@ -63,10 +63,75 @@ export declare const TUNING: {
     outerBottomR: number;
     innerTopR: number;
     innerBottomR: number;
+    /**
+     * ONE KNOB THAT GROWS EVERY KEY — the face diamond, the d-pad cross and `−`/`+`/Home together.
+     *
+     * The individual sizes below are what set each family's PROPORTIONS against the others; this scales
+     * all of them at once, so the keys can be made bigger or smaller without re-balancing four numbers
+     * by hand and losing the relationship between them. 1 = the sizes as written.
+     *
+     * It deliberately leaves the STICKS alone — they are sized by their well, not by the key family —
+     * and it leaves the RELIEF alone, so growing a key does not also make it taller. Those have their
+     * own knobs.
+     *
+     * The d-pad would otherwise bind almost at once — its four points nearly meet at the hub, so a key
+     * grown in place collides with its neighbours within a few percent. It does not, because the four
+     * d-pad PLACEMENTS scale with it: the cross grows as one object, about its own centre, and the hub
+     * gap stays proportional. See the placement loop in `joycon-designs.ts`.
+     */
+    buttonScale: number;
     /** Radii, ÷ width. */
     faceR: number;
-    dpadR: number;
     systemR: number;
+    /**
+     * @deprecated Drives nothing since PLAT-1579 — the d-pad is no longer round.
+     *
+     * It sized the four direction pips; they are arrow keys now, cut by `dpadKeyLength` /
+     * `dpadKeyWidth` / `dpadKeyRound` below. Kept only because `TUNING` is exported from
+     * `@rydr/game-sdk/three`, so deleting a key off it would break any consumer reading this one.
+     * Remove it in the next deliberate breaking change.
+     */
+    dpadR: number;
+    /**
+     * The d-pad's four ARROW keys — length from base to tip, and width at the base, both ÷ shell width.
+     *
+     * These replaced a radius: the directions used to be round pips like the face diamond's, and at this
+     * scale the two halves read as the same control twice. An arrow says which way it points without any
+     * lettering, which round pips can never do.
+     *
+     * Length is what sets the gap down the middle of the cross. A key is centred on its own face
+     * position, so half of it reaches back towards the centre: push the length past twice the
+     * centre-to-centre distance and opposite keys start to overlap.
+     */
+    dpadKeyLength: number;
+    dpadKeyWidth: number;
+    /**
+     * Corner rounding of a d-pad key, ÷ its own width, applied to the END UNDER THE THUMB. The shoulders
+     * and the point take a fraction of it, so the key stays pointed where it meets the other three.
+     */
+    dpadKeyRound: number;
+    /**
+     * How much of a d-pad key's length is the POINT, 0 → 1.
+     *
+     * The key is pointed towards the centre of the cross and widens outwards into a rounded rectangle —
+     * the DualSense shape. This says where the point stops and the parallel sides begin: 0.45 means the
+     * inner 45% tapers and the outer 55% is a straight-sided end.
+     *
+     * Low values give a stubby key with a blunt nose; high values a long dart. It also sets how close
+     * the four can sit: the narrower a key is where they meet, the tighter the hub can be.
+     */
+    dpadKeyTaper: number;
+    /**
+     * The little arrow ENGRAVED on each d-pad key: its size, ÷ the key's width, and where it sits along
+     * the key, as a fraction of the key's length from the middle towards the rounded end.
+     *
+     * On the hardware this is the only mark on the cross, and it is the one that actually names the
+     * direction — the key's own shape says "d-pad", the engraving says "up". It rides on the broad end
+     * under the thumb, not in the middle, which is what `dpadGlyphNudge` is for. Set the size to 0 to
+     * draw no arrows at all.
+     */
+    dpadGlyphSize: number;
+    dpadGlyphNudge: number;
     /** How far a domed button stands proud of the face, ÷ width. */
     buttonRise: number;
     /** `−` and `+` are nearly flush. */
@@ -133,7 +198,10 @@ export declare let SILHOUETTE: {
 /** Control sizes, as fractions of the shell width — so they scale with the model. */
 export declare let SIZES: {
     faceR: number;
+    /** @deprecated Drives nothing — see {@link TUNING.dpadR}. */
     dpadR: number;
+    dpadKeyLength: number;
+    dpadKeyWidth: number;
     systemR: number;
     stickWellR: number;
     stickCapR: number;
@@ -165,9 +233,17 @@ export declare function faceToLocal(p: FacePos): {
 /**
  * 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.
+ * The left half has the stick UP TOP and the four directions below it. On the real hardware those are
+ * four separate ROUND buttons, not a cross — and this file used to say so and draw them that way. We
+ * now draw them as a PS5-style cross of arrow keys instead (PLAT-1579): a deliberate trade of hardware
+ * fidelity for readability, because at this size four round pips are indistinguishable from the face
+ * diamond opposite, and nothing about them says "direction". They are still four INDEPENDENT keys —
+ * only their shape changed, so every view that lights one direction on its own still works.
+ *
+ * The four positions are spaced EQUALLY IN WORLD UNITS, not in u/v. `u` is a fraction of the width and
+ * `v` a fraction of the height, and the shell is far taller than it is wide — so the u/v values read
+ * off the flat layout (which are a diamond, wider than tall) have to be un-skewed here or the cross
+ * comes out squashed. Hence the horizontal offsets look smaller than the vertical ones.
  */
 export declare const LEFT_FACE: Record<string, FacePos>;
 /** The RIGHT half's controls: the face diamond up top, stick below it. */
@@ -230,4 +306,40 @@ export declare const VIEW: {
     /** Yaw: a slight turn so the pair isn't perfectly symmetric and the side walls catch light. */
     yaw: number;
 };
+/**
+ * NAMED ORIENTATIONS — the two questions a game actually asks, answered in words (PLAT-1582).
+ *
+ * Posing the pad used to mean naming a pitch in radians and knowing which way it leans. That is a
+ * detail of the model, not of the intent: what a game wants to say is *show the face* or *show the
+ * triggers*, and be given whatever angle does that.
+ *
+ * - `"front"` — head-on, no yaw. The face keys, the d-pad and both sticks read at their true relative
+ *   sizes, which is what a diagram wants. The triggers are edge-on and effectively invisible, so this
+ *   is the wrong view for teaching one.
+ * - `"angled"` — the three-quarter reading view, and the DEFAULT everywhere. A little pitch so the
+ *   crown is legible, a little yaw so the shell has thickness. What every existing caller already got.
+ * - `"triggers"` — rolled well forward, looking down onto the crown. `ZL`/`ZR`/`L`/`R` are the subject;
+ *   the face is foreshortened but still readable. Pair it with `triggerTilt: 0` — the automatic roll
+ *   that a lit trigger provokes is there to reach this view from `"angled"`, and applying it again from
+ *   here tips the pad past flat.
+ *
+ * Anything more specific is still a `tilt`/`yaw` away: an explicit angle always wins over a preset, so
+ * a view is a starting point rather than a cage.
+ */
+export declare const PAD_VIEWS: {
+    readonly front: {
+        readonly tilt: 0;
+        readonly yaw: 0;
+    };
+    readonly angled: {
+        tilt: number;
+        yaw: number;
+    };
+    readonly triggers: {
+        readonly tilt: 0.95;
+        readonly yaw: 0;
+    };
+};
+/** The name of one of the {@link PAD_VIEWS}. */
+export type PadViewName = keyof typeof PAD_VIEWS;
 //# sourceMappingURL=joycon-spec.d.ts.map

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;OAeG;;IAEH,sBAAsB;;;IAGtB;;;;;;;OAOG;;IAEH;;;;;;;;;;OAUG;;;IAGH;;;OAGG;;IAEH;;;;;;;;;OASG;;IAEH;;;;;;;;OAQG;;;IAGH,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;;IAEd,6DAA6D;;;;;;;;;;CAU9D,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CA2BlC;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;;;;;;;;;;;;;;GAcG;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;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS;;;;;qBAEN;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;;;;;CAIqB,CAAC;AAEnE,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,SAAS,CAAC"}

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

@@ -66,12 +66,77 @@ export const TUNING = {
     innerTopR: 0.09,
     innerBottomR: 0.09,
     // ── controls ──
+    /**
+     * ONE KNOB THAT GROWS EVERY KEY — the face diamond, the d-pad cross and `−`/`+`/Home together.
+     *
+     * The individual sizes below are what set each family's PROPORTIONS against the others; this scales
+     * all of them at once, so the keys can be made bigger or smaller without re-balancing four numbers
+     * by hand and losing the relationship between them. 1 = the sizes as written.
+     *
+     * It deliberately leaves the STICKS alone — they are sized by their well, not by the key family —
+     * and it leaves the RELIEF alone, so growing a key does not also make it taller. Those have their
+     * own knobs.
+     *
+     * The d-pad would otherwise bind almost at once — its four points nearly meet at the hub, so a key
+     * grown in place collides with its neighbours within a few percent. It does not, because the four
+     * d-pad PLACEMENTS scale with it: the cross grows as one object, about its own centre, and the hub
+     * gap stays proportional. See the placement loop in `joycon-designs.ts`.
+     */
+    buttonScale: 1,
     /** Radii, ÷ width. */
-    faceR: 0.07,
+    faceR: 0.08,
+    systemR: 0.05,
+    /**
+     * @deprecated Drives nothing since PLAT-1579 — the d-pad is no longer round.
+     *
+     * It sized the four direction pips; they are arrow keys now, cut by `dpadKeyLength` /
+     * `dpadKeyWidth` / `dpadKeyRound` below. Kept only because `TUNING` is exported from
+     * `@rydr/game-sdk/three`, so deleting a key off it would break any consumer reading this one.
+     * Remove it in the next deliberate breaking change.
+     */
     dpadR: 0.07,
-    systemR: 0.06,
+    /**
+     * The d-pad's four ARROW keys — length from base to tip, and width at the base, both ÷ shell width.
+     *
+     * These replaced a radius: the directions used to be round pips like the face diamond's, and at this
+     * scale the two halves read as the same control twice. An arrow says which way it points without any
+     * lettering, which round pips can never do.
+     *
+     * Length is what sets the gap down the middle of the cross. A key is centred on its own face
+     * position, so half of it reaches back towards the centre: push the length past twice the
+     * centre-to-centre distance and opposite keys start to overlap.
+     */
+    dpadKeyLength: 0.145,
+    dpadKeyWidth: 0.135,
+    /**
+     * Corner rounding of a d-pad key, ÷ its own width, applied to the END UNDER THE THUMB. The shoulders
+     * and the point take a fraction of it, so the key stays pointed where it meets the other three.
+     */
+    dpadKeyRound: 0.335,
+    /**
+     * How much of a d-pad key's length is the POINT, 0 → 1.
+     *
+     * The key is pointed towards the centre of the cross and widens outwards into a rounded rectangle —
+     * the DualSense shape. This says where the point stops and the parallel sides begin: 0.45 means the
+     * inner 45% tapers and the outer 55% is a straight-sided end.
+     *
+     * Low values give a stubby key with a blunt nose; high values a long dart. It also sets how close
+     * the four can sit: the narrower a key is where they meet, the tighter the hub can be.
+     */
+    dpadKeyTaper: 0.55,
+    /**
+     * The little arrow ENGRAVED on each d-pad key: its size, ÷ the key's width, and where it sits along
+     * the key, as a fraction of the key's length from the middle towards the rounded end.
+     *
+     * On the hardware this is the only mark on the cross, and it is the one that actually names the
+     * direction — the key's own shape says "d-pad", the engraving says "up". It rides on the broad end
+     * under the thumb, not in the middle, which is what `dpadGlyphNudge` is for. Set the size to 0 to
+     * draw no arrows at all.
+     */
+    dpadGlyphSize: 0.52,
+    dpadGlyphNudge: 0.17,
     /** How far a domed button stands proud of the face, ÷ width. */
-    buttonRise: 0.042,
+    buttonRise: 0.032,
     /** `−` and `+` are nearly flush. */
     systemRise: 0.008,
     stickWellR: 0.215,
@@ -80,7 +145,7 @@ export const TUNING = {
     /** 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,
+    stickCapDish: 0.36,
     // ── shoulders ──
     /**
      * The shoulder keys are the reference model's own triangles, so their SHAPE is fixed. What is
@@ -138,9 +203,12 @@ export let SILHOUETTE = {
 };
 /** Control sizes, as fractions of the shell width — so they scale with the model. */
 export let SIZES = {
-    faceR: W * TUNING.faceR,
+    faceR: W * TUNING.faceR * TUNING.buttonScale,
+    /** @deprecated Drives nothing — see {@link TUNING.dpadR}. */
     dpadR: W * TUNING.dpadR,
-    systemR: W * TUNING.systemR,
+    dpadKeyLength: W * TUNING.dpadKeyLength * TUNING.buttonScale,
+    dpadKeyWidth: W * TUNING.dpadKeyWidth * TUNING.buttonScale,
+    systemR: W * TUNING.systemR * TUNING.buttonScale,
     stickWellR: W * TUNING.stickWellR,
     stickCapR: W * TUNING.stickCapR,
     stickHeight: W * TUNING.stickHeight,
@@ -169,9 +237,12 @@ export function applyTuning() {
         innerBottomR: W * TUNING.innerBottomR,
     };
     SIZES = {
-        faceR: W * TUNING.faceR,
+        faceR: W * TUNING.faceR * TUNING.buttonScale,
+        /** @deprecated Drives nothing — see {@link TUNING.dpadR}. */
         dpadR: W * TUNING.dpadR,
-        systemR: W * TUNING.systemR,
+        dpadKeyLength: W * TUNING.dpadKeyLength * TUNING.buttonScale,
+        dpadKeyWidth: W * TUNING.dpadKeyWidth * TUNING.buttonScale,
+        systemR: W * TUNING.systemR * TUNING.buttonScale,
         stickWellR: W * TUNING.stickWellR,
         stickCapR: W * TUNING.stickCapR,
         stickHeight: W * TUNING.stickHeight,
@@ -192,16 +263,24 @@ export function faceToLocal(p) {
 /**
  * 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.
+ * The left half has the stick UP TOP and the four directions below it. On the real hardware those are
+ * four separate ROUND buttons, not a cross — and this file used to say so and draw them that way. We
+ * now draw them as a PS5-style cross of arrow keys instead (PLAT-1579): a deliberate trade of hardware
+ * fidelity for readability, because at this size four round pips are indistinguishable from the face
+ * diamond opposite, and nothing about them says "direction". They are still four INDEPENDENT keys —
+ * only their shape changed, so every view that lights one direction on its own still works.
+ *
+ * The four positions are spaced EQUALLY IN WORLD UNITS, not in u/v. `u` is a fraction of the width and
+ * `v` a fraction of the height, and the shell is far taller than it is wide — so the u/v values read
+ * off the flat layout (which are a diamond, wider than tall) have to be un-skewed here or the cross
+ * comes out squashed. Hence the horizontal offsets look smaller than the vertical ones.
  */
 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 },
+    stick: { u: 0.554, v: 0.32 },
+    dpadUp: { u: 0.558, v: 0.5558 },
+    dpadDown: { u: 0.558, v: 0.6968 },
+    dpadLeft: { u: 0.428, v: 0.6258 },
+    dpadRight: { u: 0.688, v: 0.6258 },
     /** `−`, top INNER corner — towards the right half. */
     select: { u: 0.79, v: 0.124 },
     /** The square capture button, bottom. */
@@ -210,17 +289,17 @@ export const LEFT_FACE = {
 /** 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 },
+    faceTop: { u: 0.4419, v: 0.2269 },
     /** A — right. */
-    faceRight: { u: 0.633, v: 0.297 },
+    faceRight: { u: 0.612, v: 0.32 },
     /** B — bottom. */
-    faceBottom: { u: 0.442, v: 0.365 },
+    faceBottom: { u: 0.4419, v: 0.42 },
     /** Y — left. */
-    faceLeft: { u: 0.237, v: 0.297 },
-    stick: { u: 0.429, v: 0.569 },
+    faceLeft: { u: 0.2718, v: 0.32 },
+    stick: { u: 0.462, v: 0.634 },
     /** `+`, top INNER corner — towards the left half. */
     start: { u: 0.21, v: 0.124 },
-    home: { u: 0.299, v: 0.738 },
+    home: { u: 0.268, v: 0.846 },
 };
 /**
  * The shoulder row, on the TOP face of each half.
@@ -282,4 +361,31 @@ export const VIEW = {
     /** Yaw: a slight turn so the pair isn't perfectly symmetric and the side walls catch light. */
     yaw: -0.34,
 };
+/**
+ * NAMED ORIENTATIONS — the two questions a game actually asks, answered in words (PLAT-1582).
+ *
+ * Posing the pad used to mean naming a pitch in radians and knowing which way it leans. That is a
+ * detail of the model, not of the intent: what a game wants to say is *show the face* or *show the
+ * triggers*, and be given whatever angle does that.
+ *
+ * - `"front"` — head-on, no yaw. The face keys, the d-pad and both sticks read at their true relative
+ *   sizes, which is what a diagram wants. The triggers are edge-on and effectively invisible, so this
+ *   is the wrong view for teaching one.
+ * - `"angled"` — the three-quarter reading view, and the DEFAULT everywhere. A little pitch so the
+ *   crown is legible, a little yaw so the shell has thickness. What every existing caller already got.
+ * - `"triggers"` — rolled well forward, looking down onto the crown. `ZL`/`ZR`/`L`/`R` are the subject;
+ *   the face is foreshortened but still readable. Pair it with `triggerTilt: 0` — the automatic roll
+ *   that a lit trigger provokes is there to reach this view from `"angled"`, and applying it again from
+ *   here tips the pad past flat.
+ *
+ * Anything more specific is still a `tilt`/`yaw` away: an explicit angle always wins over a preset, so
+ * a view is a starting point rather than a cage.
+ */
+export const PAD_VIEWS = {
+    front: { tilt: 0, yaw: 0 },
+    get angled() {
+        return { tilt: VIEW.pitch, yaw: 0 };
+    },
+    triggers: { tilt: 0.95, yaw: 0 },
+};
 //# sourceMappingURL=joycon-spec.js.map

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

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

package/dist/three/controller/press-pulse.d.ts

@@ -0,0 +1,89 @@
+/**
+ * THE PRESS PULSE — the white circle that marks the INSTANT a key goes down (PLAT-1580).
+ *
+ * The 3D pad already says a key is down twice over: it sinks along the viewing axis and it lights up.
+ * Neither reads. The sink is projected to almost nothing at the reading angle (the pad is tilted ~21°,
+ * so travel along z barely moves on screen), which leaves the colour — and a colour change is a STATE,
+ * not an EVENT. A tap of a few frames on a small key (the d-pad, `−`/`+`, Home) can come and go without
+ * the eye catching it at all.
+ *
+ * So: a circle, born on the key's own surface, that grows and fades out. The same thing a phone draws
+ * under a finger, and read the same way.
+ *
+ * ## Why it is drawn in the scene and not over the canvas
+ *
+ * The renderer can hand out a control's screen rectangle (`partRect`), so a DOM circle laid over the
+ * canvas would be a dozen lines. It would also be wrong: it would stay a perfect screen-space circle
+ * while the surface it claims to be on is tilted, yawed, and — for a trigger — rolling forward as it
+ * lights. It would read as a badge in front of the pad rather than as something ON the key. In the
+ * scene, the ring is a child of the pad's own group, so perspective, tilt and the trigger roll all
+ * apply to it for free, and the shell can occlude it.
+ *
+ * ## Not the same white as the "do this" pulse
+ *
+ * The flat pad already spends white on `hint` — *press this* — as a slow endless throb (see
+ * `ui/controller/styles.ts`). This one has to be unmistakably a different word: it fires ONCE, it is
+ * brief, and it GROWS. Nothing in the hint vocabulary grows.
+ */
+import * as THREE from "three";
+/**
+ * Which animation marks a press.
+ *
+ * - `"wave"` — a ring leaves the key's edge, swells to about twice its size and fades. The phone-tap
+ *   reading; legible even on the smallest key. The default.
+ * - `"flash"` — a filled disc, wider than the key, closing back onto it as it fades. Quieter, and it
+ *   never spills onto a neighbour — which matters in the four-button diamond, where they nearly touch.
+ * - `"sonar"` — two rings, the second ~90 ms behind, repeating slowly while the key is HELD. The most
+ *   visible at a distance and the only one that says "still down"; also the noisiest when several keys
+ *   fire at once, as they do in a combo.
+ * - `"none"` — no pulse at all.
+ */
+export type PressPulseStyle = "wave" | "flash" | "sonar" | "none";
+/**
+ * What a HELD key does, once its press has been marked.
+ *
+ * An axis of its own rather than a fourth style, because "how do I say a key went down" and "how do I
+ * say it is still down" are two questions: any of the styles above can want either answer.
+ *
+ * - `"echo"` — the same pulse again, quieter and slower (default). No new vocabulary: a held key just
+ *   keeps saying the same word, under its breath.
+ * - `"collar"` — a ring that appears at the key's edge and STAYS, breathing gently until release. A
+ *   continuous state marked by a continuous sign, with no repeated motion: the calmest option when
+ *   several keys are held at once.
+ * - `"none"` — nothing. A held key is simply a key that stayed lit, and the pad goes fully idle again.
+ */
+export type PressHoldStyle = "none" | "echo" | "collar";
+/** Which way a control's working surface looks, in the pad model's own axes. */
+export type PulseFacing = "front" | "up";
+export interface PressPulseOptions {
+    /** The pad's group. Pulses are parented here so they inherit tilt, yaw and the trigger roll. */
+    parent: THREE.Object3D;
+    style: PressPulseStyle;
+    /** What a key does while it is HELD. */
+    hold: PressHoldStyle;
+    /** Lifetime of one pulse, ms. */
+    ms: number;
+    /** Multiplier on the pulse's radius, for dialling it in against a given design. */
+    scale: number;
+    /** World units used as the "one shell width" reference, for the lift off the surface. */
+    unit: number;
+}
+export interface PressPulses {
+    /** A key just went down: start a pulse on it. No-op for `"none"`. */
+    fire(key: string, node: THREE.Object3D, facing: PulseFacing): void;
+    /** A key came back up: stop whatever the hold was doing on it. */
+    release(key: string): void;
+    /** Drop everything in flight, e.g. on `clearAll()`. */
+    cancelAll(): void;
+    /** Advance to `now`. Returns true while anything is still animating — the loop's wake-up signal. */
+    step(now: number): boolean;
+    dispose(): void;
+}
+/**
+ * Build the pulse pool for one pad.
+ *
+ * Everything is allocated lazily and then RECYCLED: a combo demo loops forever, and a pad that minted a
+ * mesh per press would leak one every second or so.
+ */
+export declare function createPressPulses(opts: PressPulseOptions): PressPulses;
+//# sourceMappingURL=press-pulse.d.ts.map

package/dist/three/controller/press-pulse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"press-pulse.d.ts","sourceRoot":"","sources":["../../../src/three/controller/press-pulse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB,KAAK,EAAE,eAAe,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,cAAc,CAAC;IACrB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACnE,kEAAkE;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,SAAS,IAAI,IAAI,CAAC;IAClB,oGAAoG;IACpG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;CACjB;AAoED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,CAuPtE"}