@rydr/game-sdk 8.14.0 → 8.15.0

package/dist/three/controller/press-pulse.js

@@ -0,0 +1,309 @@
+/**
+ * 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";
+/** A ring thick enough to read at a small on-screen size; the disc is the same circle, filled. */
+const RING_INNER = 0.72;
+/** The sonar's rings are thinner — two of them at the wave's weight would be a blob. */
+const SONAR_INNER = 0.86;
+/** Segments. A pulse is never more than a couple of hundred pixels across; 48 is already generous. */
+const SEGMENTS = 48;
+/**
+ * How far the pulse floats off the surface it sits on, ÷ shell width.
+ *
+ * A HAIR, and deliberately so. It is measured from the top of the key's own bounding box, which
+ * already clears the dome — this only has to beat z-fighting. Anything larger (a fraction of the
+ * button's radius, say) and the ring visibly hovers in front of the key instead of lying on it, which
+ * the perspective then gives away as a parallax slide when the pad tilts.
+ */
+const LIFT = 0.008;
+/** The sonar's second ring, ms behind the first. */
+const SONAR_STAGGER = 90;
+/** Gap between echoes while a key is held, ms. Slower than a press — this is a murmur, not a beat. */
+const HOLD_ECHO_MS = 700;
+/** How much quieter an echo is than the press that started it. The first one has to stay the loud one. */
+const ECHO_DIM = 0.45;
+/** The collar sits just outside the key's edge, so the key itself stays unobscured. */
+const COLLAR_SCALE = 1.18;
+/** Its opacity breathes between these, over {@link COLLAR_BREATH_MS}. */
+const COLLAR_MIN = 0.26;
+const COLLAR_MAX = 0.58;
+const COLLAR_BREATH_MS = 1200;
+/** Peak opacity per style. The wave is the brightest because it is the thinnest thing on screen. */
+const PEAK = {
+    wave: 0.85,
+    flash: 0.62,
+    sonar: 0.8,
+};
+/** Ease-out cubic: fast off the mark, settling at the end. A press is an impact, not a drift. */
+function easeOut(t) {
+    return 1 - Math.pow(1 - t, 3);
+}
+/**
+ * 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 function createPressPulses(opts) {
+    const { parent, style, hold, ms, scale, unit } = opts;
+    if (style === "none") {
+        return {
+            fire: () => { },
+            release: () => { },
+            cancelAll: () => { },
+            step: () => false,
+            dispose: () => { },
+        };
+    }
+    // One geometry for every pulse on this pad, unit-radius, resized per instance through `mesh.scale`.
+    const geometry = style === "flash"
+        ? new THREE.CircleGeometry(1, SEGMENTS)
+        : new THREE.RingGeometry(style === "sonar" ? SONAR_INNER : RING_INNER, 1, SEGMENTS);
+    /**
+     * The collar is always a RING, even when the press itself is a filled disc: it has to sit AROUND the
+     * key without covering it, which a disc cannot do. Built only if it will be used.
+     */
+    const collarGeometry = hold === "collar" ? new THREE.RingGeometry(SONAR_INNER, 1, SEGMENTS) : undefined;
+    const pool = [];
+    const held = new Map();
+    /** One steady ring per held key, kept and reused rather than re-minted on every press. */
+    const collars = new Map();
+    /** Scratch, so a press allocates nothing. */
+    const v = new THREE.Vector3();
+    const localBox = new THREE.Box3();
+    /** A fresh pulse object around `geo`. Callers park and reuse these rather than minting per press. */
+    function make(geo) {
+        // Opacity is per-pulse, and opacity lives on the material — so each one owns its own.
+        const material = new THREE.MeshBasicMaterial({
+            color: 0xffffff,
+            transparent: true,
+            opacity: 0,
+            depthWrite: false,
+            // Additive, because this is light spilling off a key rather than paint on it. Depth TESTING
+            // stays on, so the shell still hides a pulse on a face turned away from the camera.
+            blending: THREE.AdditiveBlending,
+            side: THREE.DoubleSide,
+            toneMapped: false,
+        });
+        const mesh = new THREE.Mesh(geo, material);
+        mesh.visible = false;
+        // Drawn after the pad, whatever the traversal order — otherwise an additive quad can be discarded
+        // against geometry that has not been laid down yet.
+        mesh.renderOrder = 10;
+        parent.add(mesh);
+        return { mesh, material, born: 0, delay: 0, r0: 1, dim: 1, live: false };
+    }
+    /** Take a parked pulse from the burst pool, or grow the pool by one. */
+    function take() {
+        const parked = pool.find((p) => !p.live);
+        if (parked)
+            return parked;
+        const pulse = make(geometry);
+        pool.push(pulse);
+        return pulse;
+    }
+    /**
+     * Where a pulse goes for a given control, in the PAD's own coordinates.
+     *
+     * Read off the node's geometry rather than a table of positions: a stick cap hangs off a tilting
+     * pivot and a shoulder key is a wide crown pad, so "where is this control and how big is it" is a
+     * question only the mesh itself can answer. Corners go through the node's world matrix and back into
+     * the pad group's space, which survives any nesting and any rotation in between.
+     */
+    function placement(node, facing) {
+        const mesh = node;
+        const geo = mesh.geometry;
+        if (!geo)
+            return null;
+        if (!geo.boundingBox)
+            geo.computeBoundingBox();
+        const box = geo.boundingBox;
+        if (!box)
+            return null;
+        node.updateWorldMatrix(true, false);
+        localBox.makeEmpty();
+        for (let i = 0; i < 8; i++) {
+            v.set(i & 1 ? box.max.x : box.min.x, i & 2 ? box.max.y : box.min.y, i & 4 ? box.max.z : box.min.z);
+            v.applyMatrix4(node.matrixWorld);
+            parent.worldToLocal(v);
+            localBox.expandByPoint(v);
+        }
+        const size = localBox.getSize(new THREE.Vector3());
+        const centre = localBox.getCenter(new THREE.Vector3());
+        // The SMALLER of the two in-plane dimensions. Round keys make the choice moot, but a shoulder key
+        // is a wide band across the crown, and sizing a circle off its width would throw a hoop around the
+        // whole half of the pad.
+        const r = facing === "front"
+            ? Math.min(size.x, size.y) / 2
+            : Math.min(size.x, size.z) / 2;
+        if (!(r > 0))
+            return null;
+        // Sit on the surface that is actually facing the viewer, lifted clear of the dome.
+        const lift = unit * LIFT;
+        const pos = facing === "front"
+            ? new THREE.Vector3(centre.x, centre.y, localBox.max.z + lift)
+            : new THREE.Vector3(centre.x, localBox.max.y + lift, centre.z);
+        return { pos, r: r * scale };
+    }
+    function spawn(node, facing, now, delay, dim = 1) {
+        const at = placement(node, facing);
+        if (!at)
+            return;
+        const p = take();
+        p.born = now;
+        p.delay = delay;
+        p.r0 = at.r;
+        p.dim = dim;
+        p.live = true;
+        p.mesh.position.copy(at.pos);
+        // The ring is authored in the XY plane, which is already the face's plane. A crown key looks UP, so
+        // its pulse is laid flat.
+        p.mesh.rotation.set(facing === "up" ? -Math.PI / 2 : 0, 0, 0);
+        p.mesh.scale.setScalar(at.r);
+        p.mesh.visible = delay === 0;
+        p.material.opacity = 0;
+    }
+    /** Park the steady ring on a key, creating it the first time that key is held. */
+    function raiseCollar(key, node, facing, now) {
+        if (!collarGeometry)
+            return;
+        const at = placement(node, facing);
+        if (!at)
+            return;
+        let c = collars.get(key);
+        if (!c) {
+            c = make(collarGeometry);
+            collars.set(key, c);
+        }
+        c.born = now;
+        c.r0 = at.r;
+        c.live = true;
+        c.mesh.position.copy(at.pos);
+        c.mesh.rotation.set(facing === "up" ? -Math.PI / 2 : 0, 0, 0);
+        c.mesh.scale.setScalar(at.r * COLLAR_SCALE);
+        c.mesh.visible = true;
+    }
+    function lowerCollar(key) {
+        const c = collars.get(key);
+        if (!c)
+            return;
+        c.live = false;
+        c.mesh.visible = false;
+    }
+    return {
+        fire(key, node, facing) {
+            const now = performance.now();
+            spawn(node, facing, now, 0);
+            // The sonar's signature is the pair, not the repeat — the repeat is the hold's job now.
+            if (style === "sonar")
+                spawn(node, facing, now, SONAR_STAGGER);
+            if (hold === "echo")
+                held.set(key, { node, facing, nextAt: now + HOLD_ECHO_MS });
+            else if (hold === "collar") {
+                held.set(key, { node, facing, nextAt: 0 });
+                raiseCollar(key, node, facing, now);
+            }
+        },
+        release(key) {
+            held.delete(key);
+            lowerCollar(key);
+        },
+        cancelAll() {
+            held.clear();
+            for (const p of pool) {
+                p.live = false;
+                p.mesh.visible = false;
+            }
+            for (const key of collars.keys())
+                lowerCollar(key);
+        },
+        step(now) {
+            // A held key murmurs: the same pulse again, quieter, on a slower clock than a press.
+            if (hold === "echo") {
+                for (const h of held.values()) {
+                    if (now >= h.nextAt) {
+                        spawn(h.node, h.facing, now, 0, ECHO_DIM);
+                        if (style === "sonar")
+                            spawn(h.node, h.facing, now, SONAR_STAGGER, ECHO_DIM);
+                        h.nextAt = now + HOLD_ECHO_MS;
+                    }
+                }
+            }
+            // The collar does not repeat — it is one ring that stays and breathes.
+            for (const c of collars.values()) {
+                if (!c.live)
+                    continue;
+                const phase = ((now - c.born) % COLLAR_BREATH_MS) / COLLAR_BREATH_MS;
+                const breath = 0.5 - 0.5 * Math.cos(phase * Math.PI * 2);
+                c.material.opacity = COLLAR_MIN + (COLLAR_MAX - COLLAR_MIN) * breath;
+            }
+            let alive = held.size > 0;
+            for (const p of pool) {
+                if (!p.live)
+                    continue;
+                const t = (now - p.born - p.delay) / ms;
+                if (t < 0) {
+                    alive = true;
+                    continue;
+                }
+                if (t >= 1) {
+                    p.live = false;
+                    p.mesh.visible = false;
+                    p.material.opacity = 0;
+                    continue;
+                }
+                alive = true;
+                const e = easeOut(t);
+                p.mesh.visible = true;
+                if (style === "flash") {
+                    // Opens wide on the strike and CLOSES back onto the key, which is why it never spills.
+                    p.mesh.scale.setScalar(p.r0 * (1.7 - 0.7 * e));
+                    p.material.opacity = PEAK.flash * Math.pow(1 - e, 1.5) * p.dim;
+                }
+                else {
+                    // Leaves the key's edge and swells away from it.
+                    p.mesh.scale.setScalar(p.r0 * (1 + (style === "sonar" ? 1.35 : 1.1) * e));
+                    p.material.opacity = PEAK[style] * (1 - e) * p.dim;
+                }
+            }
+            return alive;
+        },
+        dispose() {
+            for (const p of [...pool, ...collars.values()]) {
+                parent.remove(p.mesh);
+                p.material.dispose();
+            }
+            pool.length = 0;
+            collars.clear();
+            held.clear();
+            geometry.dispose();
+            collarGeometry?.dispose();
+        },
+    };
+}
+//# sourceMappingURL=press-pulse.js.map

package/dist/three/controller/press-pulse.js.map

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

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

@@ -13,6 +13,15 @@
  * 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 this file is, and what it is not
+ *
+ * It is the FRAMING half: a canvas, a camera, a rule for fitting the pad into it, a dirty-guarded
+ * render loop, and the projection that answers "where is this key on screen". Everything the pad
+ * actually *does* — lighting a key, sinking it, pulsing, leaning a stick, rolling to show a trigger —
+ * lives in {@link createJoyconObject}, which a game can also use on its own to put the pad in its own
+ * scene. Both paths animate through that one implementation on purpose: a press must not look one way
+ * in a HUD and another way in a world.
+ *
  * ## What the third dimension actually buys
  *
  * Two things the flat pad could not say:
@@ -38,28 +47,8 @@
  */
 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;
+import { type JoyconObjectOptions } from "./joycon-object.js";
+export interface ThreePadRendererOptions extends PadRendererOptions, JoyconObjectOptions {
     /**
      * How much of the frame the pad fills, 0…1. Default 0.82.
      *

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

@@ -1 +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;AAoB5F,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,CAoXb"}
+{"version":3,"file":"three-pad-renderer.d.ts","sourceRoot":"","sources":["../../../src/three/controller/three-pad-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EAExB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQlF,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB,EAAE,mBAAmB;IACtF;;;;;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,CA+Kb"}