@rydr/game-sdk 8.14.0 → 8.16.0

package/dist/protocol/identity.d.ts

@@ -87,5 +87,44 @@ export interface ScopedIdentity {
      * be server-side as well. Absent means {@link DEFAULT_ACCESS_TIER}.
      */
     accessTier?: AccessTier;
+    /**
+     * The event this machine is at, if any (see {@link EventContext}). Absent on an ordinary
+     * machine — which is almost always, so treat its presence as the exception and never require it.
+     *
+     * Read it as `if (identity.event)`, show `identity.event.label`, and do not look at the slug.
+     */
+    event?: EventContext;
+}
+/**
+ * The EVENT this machine is standing at, when it is standing at one (PLAT-1591).
+ *
+ * At an event RYDR takes a bike to a venue and strangers take turns on it. The shell already knows
+ * that — it is what lets someone with no riding account play, and what grants them a tier for the
+ * session (`platform/eventMode.ts`). This is the same fact, told to the game.
+ *
+ * ## It describes the MACHINE, not the rider
+ *
+ * The odd member of {@link ScopedIdentity}: everything else there is a property of the person, and
+ * this is a property of the bike they happen to be sitting on. It travels on the identity anyway,
+ * deliberately — the identity is rebuilt and re-pushed on every change, which is exactly the
+ * delivery a fact that can lapse mid-session needs (an event pass expires on a clock), and a second
+ * channel carrying one optional object would be a protocol message, a capability and a version bump
+ * to say something this one already says.
+ *
+ * ## One treatment for every event
+ *
+ * A game reads the {@link label} and draws it. It must NOT branch on the {@link slug}: the point of
+ * sending the name is that the next event is a change to the platform's event list and nothing
+ * else. A game with `if (event.slug === "bxl-crit")` in it has to be redeployed for every venue,
+ * which is the cost this field exists to avoid.
+ */
+export interface EventContext {
+    /**
+     * Stable id, e.g. `bxl-crit`. Stamped on the runs recorded here, so it is the key a result can be
+     * attributed by. For LOGGING and keys — never for a branch, and never on screen.
+     */
+    slug: string;
+    /** What to put on screen, e.g. "BXL Crit". Human-facing, never parsed. */
+    label: string;
 }
 //# sourceMappingURL=identity.d.ts.map

package/dist/protocol/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAAmB,CAAC;AAStD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAGlF;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAAmB,CAAC;AAStD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAGlF;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/protocol/version.d.ts

@@ -9,5 +9,5 @@
 export declare const RYDR_PROTOCOL_VERSION: 32;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging.
  *  (Bumped to 2.0.0 by `npm version major` on release — see CHANGELOG [Unreleased].) */
-export declare const RYDR_SDK_VERSION = "8.14.0";
+export declare const RYDR_SDK_VERSION = "8.16.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/protocol/version.js

@@ -217,5 +217,5 @@
 export const RYDR_PROTOCOL_VERSION = 32;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging.
  *  (Bumped to 2.0.0 by `npm version major` on release — see CHANGELOG [Unreleased].) */
-export const RYDR_SDK_VERSION = "8.14.0";
+export const RYDR_SDK_VERSION = "8.16.0";
 //# sourceMappingURL=version.js.map

package/dist/protocol/worlds.d.ts

@@ -36,6 +36,20 @@ export interface WorldObjectGroup {
     name?: string;
     memberIds: string[];
 }
+/**
+ * A transform on the **world root** — the whole world (base map, every placed object) moved and
+ * uniformly resized as one, on top of each object's own transform.
+ *
+ * Uniform only, and deliberately: a non-uniform world scale would shear every rotated prop. Scaling
+ * happens about the world origin and *then* the offset is added (`p' = p * scale + position`), which
+ * is exactly what a scaled+moved root node does. Absent (or identity) on worlds that never used it.
+ */
+export interface WorldTransform {
+    /** World-space offset applied after scaling. Default `[0, 0, 0]`. */
+    position?: [number, number, number];
+    /** Uniform scale factor. Default `1`. */
+    scale?: number;
+}
 /** Changes to a base map: small and self-describing. `baseMap` is a glb URL (or "" for none). */
 export interface WorldMapDelta {
     baseMap: string;
@@ -43,6 +57,11 @@ export interface WorldMapDelta {
     addedObjects: WorldAddedObject[];
     /** Object groups (optional — absent on worlds saved before grouping existed). */
     groups?: WorldObjectGroup[];
+    /**
+     * Optional world-root transform — scales/moves the entire world as one (see {@link WorldTransform}).
+     * Applied by `applyWorld`; absent on worlds saved before it existed.
+     */
+    worldTransform?: WorldTransform;
 }
 /** Optional lighting/fog for a world. */
 export interface WorldEnv {

package/dist/protocol/worlds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worlds.d.ts","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,iFAAiF;IACjF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,aAAa,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"worlds.d.ts","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,iFAAiF;IACjF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,aAAa,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,SAAS,CAAC"}

package/dist/protocol/worlds.js.map

@@ -1 +1 @@
-{"version":3,"file":"worlds.js","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgFH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC"}
+{"version":3,"file":"worlds.js","sourceRoot":"","sources":["../../src/protocol/worlds.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoGH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC"}

package/dist/three/README.md

@@ -29,7 +29,8 @@ import { loadWorld, mergeByMaterial, PerfOverlay, ScreenAnchor } from "@rydr/gam
 | `auditScene` | fn | One-shot string report of a scene's draw calls / triangles / materials. |
 | `perfMark` / `perfMeasure` / `perfReport` / `perfAvg` / `perfPeak` | fn | Lightweight per-frame CPU timing marks + rolling stats. |
 | `createThreePadRenderer` | fn | Draw the controller as a **3D Joy-Con pair** in any `@rydr/game-sdk/ui` controller view. |
-| `buildJoyconModel` | fn | The Joy-Con `THREE.Group` on its own, if you want it in your own scene. |
+| `createJoyconObject` | fn | The Joy-Con as an **object in your own scene** — model, lighting and every animation, no canvas. |
+| `PAD_VIEWS` | const | Named orientations — `front`, `angled`, `triggers` — instead of angles in radians. |
 | `glyphTexture` | fn | A canvas-drawn letter as a `CanvasTexture` (no font file — this package ships no assets). |
 
 ---
@@ -170,7 +171,47 @@ mountControllerMap(host, {
   the shell because it has no way to draw a face you can't see; the 3D model puts them where they are
   and tilts the pad forward to reveal them. This is the reason the 3D pad exists.
 - **A press is real travel.** The button moves along the viewing axis and the stick leans, instead of
-  a shape dropping onto its own drop shadow.
+  a shape dropping onto its own drop shadow. The travel is *animated* — fast down, slower back with a
+  small spring overshoot — because an instant displacement is not something an eye can catch: it puts
+  the key at rest on one frame and at the bottom on the next, with no motion in between. `pressTravel`
+  (default `0.07`, ÷ shell width) sets how deep it goes; raise it when the pad is read from far away or
+  nearly head-on, where the viewing angle leaves even less of the travel on screen.
+
+**The press pulse.** Travel alone does not read — it happens along the viewing axis, so the pad's tilt
+flattens it to almost nothing, leaving only the colour change, which is a *state* rather than an
+*event*. So a white circle marks the instant a key goes down, on the key's own surface, in the scene
+(it tilts, foreshortens and rolls with the pad — a DOM circle over the canvas would not):
+
+```ts
+createThreePadRenderer(layout, {
+  pressPulse: "wave",     // "wave" (default) · "flash" · "sonar" · "none"
+  pressHold: "echo",      // while HELD: "echo" (default) · "collar" · "none"
+  pressPulseMs: 500,      // lifetime of one pulse
+  pressPulseScale: 1.4,   // multiplier on its radius
+  pressTravel: 0.07,      // how deep the key itself sinks, ÷ shell width
+});
+```
+
+- `"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.
+- `"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.
+- `"sonar"` — two staggered rings, 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 a combo fires several keys
+  at once.
+
+**While a key is HELD**, `pressHold` says what it keeps saying — a separate axis, because "a key went
+down" and "a key is still down" are two different things, and any style can want either answer.
+`"echo"` repeats the pulse every 700 ms at under half strength: no new vocabulary, the held key just
+keeps saying the same word under its breath. `"collar"` parks one ring just outside the key's edge and
+breathes it until release — a continuous state marked by a continuous sign, and the calmest option when
+several keys are held at once. `"none"` says nothing. Note the cost: anything but `"none"` animates for
+as long as the key is held, so the pad cannot go fully idle during a hold — a frame of work while the
+rider is holding a button, not while they are doing nothing.
+
+It is deliberately *not* the same white as `hint`, which already means **do this** as a slow endless
+throb: the pulse fires once, is brief, and grows. Nothing in the hint vocabulary grows. Compare all
+three live with `npm run pad3d` (panel on the right).
 
 **Joy-Con only.** Other brands warn and draw the Joy-Con anyway. They keep using the flat pad, which
 is not going away — the two renderers coexist.
@@ -186,6 +227,74 @@ replaces — you do not need to give it a height.
 control's box in viewport pixels on either renderer (projected from the camera in 3D). That's what the
 map's leader lines and the spotlight's captions use.
 
+**Naming the angle.** `view` takes a named orientation instead of a pitch in radians:
+
+```ts
+createThreePadRenderer(layout, { view: "triggers", triggerTilt: 0 });
+```
+
+- `"front"` — head-on. The face keys, the d-pad and the sticks at their true relative sizes; 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. What every existing
+  caller already got; nothing changes if you don't pass `view`.
+- `"triggers"` — rolled well forward, looking down onto the crown. `ZL`/`ZR`/`L`/`R` are the subject.
+  Pair it with `triggerTilt: 0`: the automatic roll a lit trigger provokes exists to *reach* this view
+  from `"angled"`, and applying it again from here tips the pad past flat.
+
+An explicit `tilt`/`yaw` still wins over the preset, so a view is a starting point, not a cage. The
+angles themselves live in `PAD_VIEWS`.
+
+**In a game's HUD.** Pinning the pad into a corner of play is the `ui` side of this — `place`, `width`
+and `highlight` on `mountControllerPad`, with this renderer passed as `renderer`. See the
+`@rydr/game-sdk/ui` README, and `npm run pad-hud` for a dev page over a fake game screen.
+
+## `createJoyconObject` — the pad in YOUR scene
+
+`createThreePadRenderer` frames the pad in its own canvas, which is right for a controls screen or a
+HUD corner and wrong for a pad that belongs to the **world**: sitting on a table, mounted on a wall,
+floating beside the rider, turning with the camera and occluded by the scenery. That is this:
+
+```ts
+import { createJoyconObject } from "@rydr/game-sdk/three";
+
+const pad = createJoyconObject({ design: "noir", view: "triggers", triggerTilt: 0 });
+pad.addLights(scene);              // lighting is part of the art direction — take the design's own
+pad.group.position.set(0, 2.6, 0);
+pad.group.scale.setScalar(0.55);
+scene.add(pad.group);
+
+pad.driver.setPartState("rt", "hint");   // "press this"
+
+function frame(now) {                    // YOUR loop
+  pad.step(now);
+  renderer.render(scene, camera);
+}
+```
+
+**You own the loop.** The object has no `requestAnimationFrame` of its own, because your game already
+has one and a second would render behind it. Call `step(now)` once a frame with the timestamp you
+already have; it returns `true` while anything is still animating. Skip the call and the pad still
+*paints* — colour is immediate — but nothing *moves*: keys teleport and pulses never fade.
+
+**You own the yaw.** `group` is yours to place, scale and rotate about Y. The reading tilt and the
+trigger roll live on an inner pivot (`tiltGroup`), so they never fight you for `rotation.x`.
+
+**Lighting comes with it.** `addLights(scene)` installs the art direction's own rig. 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.
+
+**It is the same pad.** `createThreePadRenderer` is now a thin shell around this object — canvas,
+camera, framing, projection — so both paths animate through one implementation. A press cannot look
+one way in a HUD and another way in the world.
+
+`driver` is the same `PadDriver` the flat pad and every controller view speak, so anything that can
+drive one can drive this: `setPartState(part, "off" | "hint" | "on" | "done")`, `setStick`,
+`setAvailable`, `clearAll`. `nodeOf(part)` hands back a key's `Object3D` for hanging your own things
+off it. `dispose()` releases geometry, materials and textures.
+
+See it with `npm run pad-hud` — one page showing the HUD and the in-world object at once, driven by
+the same keyboard.
+
 ## `createThreeRiderRig` — the rider on their trainer, in 3D
 
 A second renderer for `mountRiderRig` from `@rydr/game-sdk/ui`, the same way `createThreePadRenderer`
@@ -222,8 +331,27 @@ rather than merely darker.
 
 **What it costs:** a WebGL context. The renderer draws **on demand — one frame per `setPose`, with no
 animation loop of its own** — because a game calling `rig.tick(dt)` already has a loop. But it is
-still a second context beside your own scene, so prefer the flat renderer in-game and reach for this
-one where the picture *is* the content: onboarding, a store page, a "how this works" panel.
+still a second context beside your own scene, so keep it to **one** rig per screen, and reach for the
+flat renderer when the rig is decoration rather than the subject.
+
+**As a game HUD piece.** The rig can be pinned into a corner of play at any size — `width` and `place`
+on `mountRiderRig`, see `@rydr/game-sdk/ui`. Turn the ground off when you do: it is painted in the
+design's own background colour, which is invisible on a page that uses that colour and a dark slab
+across the play field over a game.
+
+```ts
+import { threeRiderRig } from "@rydr/game-sdk/three";
+
+mountRiderRig(gameRoot, {
+  ftp: session.identity.ftp,
+  width: 300,
+  gauge: "portrait",                             // narrow and tall, for a screen edge
+  place: { corner: "bottom-right", margin: 24 },
+  renderer: threeRiderRig({ floor: false }),
+});
+```
+
+`npm run rig-hud` is that, live, with a slider per knob and the matching snippet printed back.
 
 **The rider is a real procedural character**, from `@rydr/game-sdk/three`'s `character/` — skeleton,
 proportions and five art directions, lifted from the platform's `showcase/player3d` (see the

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

@@ -6,7 +6,9 @@
  */
 export * from "./glyph-texture.js";
 export * from "./three-pad-renderer.js";
+export * from "./press-pulse.js";
 export * from "./joycon-spec.js";
 export * from "./joycon-shoulder-mesh.js";
 export * from "./joycon-designs.js";
+export * from "./joycon-object.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/three/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/three/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC"}

package/dist/three/controller/index.js

@@ -6,7 +6,9 @@
  */
 export * from "./glyph-texture.js";
 export * from "./three-pad-renderer.js";
+export * from "./press-pulse.js";
 export * from "./joycon-spec.js";
 export * from "./joycon-shoulder-mesh.js";
 export * from "./joycon-designs.js";
+export * from "./joycon-object.js";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/three/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/three/controller/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC"}

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

@@ -11,6 +11,8 @@
  *                                 be read from across a room, which is the actual use case.
  *   {@link buildHoloJoycon}      "Holo" — translucent shell with lit edges and emissive controls, in
  *                                 the SDK's own accent language. Reads as UI rather than as an object.
+ *   {@link buildNoirJoycon}      "Noir" — "Toy" repainted: both shells black, white keys with dark
+ *                                 lettering, black shoulders with light lettering.
  *
  * Each returns a `JoyconBuild`: the group to add to a scene, plus the per-control nodes a driver would
  * later need, plus everything to dispose. None of them is wired to input yet — that comes once one is
@@ -30,7 +32,7 @@ export interface JoyconBuild {
         dispose(): void;
     }[];
 }
-export type JoyconDesignId = "product" | "toy" | "holo";
+export type JoyconDesignId = "product" | "toy" | "holo" | "noir";
 export interface JoyconDesign {
     id: JoyconDesignId;
     name: string;
@@ -44,6 +46,18 @@ export interface JoyconDesign {
 }
 export declare function buildProductJoycon(): JoyconBuild;
 export declare function buildToyJoycon(): JoyconBuild;
+/**
+ * "Noir" — {@link buildToyJoycon}'s proportions, in black and white.
+ *
+ * Same chunky volumes, same oversized high-relief controls, same flat matte surfaces: everything that
+ * makes the toy direction readable at two metres is kept, and ONLY the palette changes. Both shells go
+ * black, the keys go white, and the shoulder row goes black again.
+ *
+ * Which means the pad carries lettering on two opposite backgrounds at once — dark letters on the white
+ * face keys, light letters on the black shoulders — and that is the whole reason {@link Skin.shoulderInk}
+ * exists. With a single ink one of the two sets vanishes into what it is printed on.
+ */
+export declare function buildNoirJoycon(): JoyconBuild;
 export declare function buildHoloJoycon(): JoyconBuild;
 export declare const JOYCON_DESIGNS: readonly JoyconDesign[];
 //# sourceMappingURL=joycon-designs.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"joycon-designs.d.ts","sourceRoot":"","sources":["../../../src/three/controller/joycon-designs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmB/B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,gGAAgG;IAChG,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtC,4CAA4C;IAC5C,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;QAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAA;KAAE,CAAC;IAC7C,WAAW,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,cAAc,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,WAAW,CAAC;IACrB,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IAChC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwmBD,wBAAgB,kBAAkB,IAAI,WAAW,CAgBhD;AAID,wBAAgB,cAAc,IAAI,WAAW,CA0B5C;AAMD,wBAAgB,eAAe,IAAI,WAAW,CA4C7C;AAID,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAgEjD,CAAC"}
+{"version":3,"file":"joycon-designs.d.ts","sourceRoot":"","sources":["../../../src/three/controller/joycon-designs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmB/B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,gGAAgG;IAChG,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtC,4CAA4C;IAC5C,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;QAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAA;KAAE,CAAC;IAC7C,WAAW,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,cAAc,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,WAAW,CAAC;IACrB,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IAChC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAy2BD,wBAAgB,kBAAkB,IAAI,WAAW,CAgBhD;AAID,wBAAgB,cAAc,IAAI,WAAW,CA0B5C;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,WAAW,CA8B7C;AAMD,wBAAgB,eAAe,IAAI,WAAW,CA4C7C;AAID,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAyFjD,CAAC"}