@rydr/game-sdk 3.1.2 → 3.2.1

package/dist/three/screen-anchor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SCREEN ANCHOR — place a floating UI element (a name tag, a button prompt, a health bar) a CONSTANT
+ * height above the TOP of a 3D object, then project that point to screen pixels. The standard
+ * "something hovering over a thing" placement, so games stop hand-rolling bbox + project math (and
+ * stop guessing pixel offsets that break when the model's size changes).
+ *
+ * On construction it measures the object's bounding box ONCE and remembers how far the top sits above
+ * the object's own origin (`topOffset`). Each `project()` re-reads the object's CURRENT world position
+ * — so the tag follows it as it moves or turns — and lifts by `topOffset + worldGap`. Keeping the gap
+ * in world units makes it perspective-correct (it shrinks with distance, like the object). `pixelGap`
+ * is an extra constant screen-space nudge UP on top of that — handy to clear a keycap that dangles
+ * below a card, or any fixed-size chrome the world gap can't account for.
+ *
+ * Defaults put a tag a little above the head by default; override `worldGap`/`pixelGap` per use and
+ * adapt from there. Call `remeasure()` if the object is rescaled or its model swapped.
+ */
+import * as THREE from "three";
+export interface ScreenPoint {
+    /** Horizontal position in CSS pixels within the host element. */
+    x: number;
+    /** Vertical position in CSS pixels within the host element. */
+    y: number;
+    /** False when the anchor is behind the camera (or off the near/far range) — hide the UI element. */
+    onScreen: boolean;
+}
+export interface ScreenAnchorOptions {
+    /** World-space lift above the object's bbox top (perspective-correct). Default 0.15 — just clear of
+     *  the head. Raise it for a roomier tag; this default keeps the tag close, not floating. */
+    worldGap?: number;
+    /** Extra constant screen-space lift UP, in CSS pixels (e.g. to clear a dangling keycap). Default 0. */
+    pixelGap?: number;
+    /**
+     * Skip auto-measuring and use this fixed top height (world units above the object's origin). Pass it
+     * when you already KNOW the height — e.g. a model whose mesh loads asynchronously, so measuring at
+     * construction would read an empty bounding box. Without it the anchor measures the object instead.
+     */
+    topOffset?: number;
+}
+export declare class ScreenAnchor {
+    /** Height of the object's bbox top above its own origin, in world units (set by `remeasure`). */
+    topOffset: number;
+    worldGap: number;
+    pixelGap: number;
+    private target;
+    private _w;
+    private _p;
+    private pendingMeasure;
+    constructor(target: THREE.Object3D, opts?: ScreenAnchorOptions);
+    /** Re-measure the object's top. Call after the object is rescaled or its model is swapped. */
+    remeasure(): void;
+    /** The world-space point the UI should hover at: `worldGap` above the object's measured top. */
+    worldPoint(out?: THREE.Vector3): THREE.Vector3;
+    /**
+     * Project the anchor to CSS pixels within `host`. `onScreen` is false when the point is behind the
+     * camera — hide the element then. Pass `out` to reuse an object and avoid a per-frame allocation.
+     */
+    project(camera: THREE.Camera, host: {
+        clientWidth: number;
+        clientHeight: number;
+    }, out?: ScreenPoint): ScreenPoint;
+}
+//# sourceMappingURL=screen-anchor.d.ts.map

package/dist/three/screen-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-anchor.d.ts","sourceRoot":"","sources":["../../src/three/screen-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,CAAC,EAAE,MAAM,CAAC;IACV,+DAA+D;IAC/D,CAAC,EAAE,MAAM,CAAC;IACV,oGAAoG;IACpG,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC;gGAC4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,YAAY;IACvB,iGAAiG;IACjG,SAAS,SAAK;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,EAAE,CAAuB;IAGjC,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,GAAE,mBAAwB;IAQlE,8FAA8F;IAC9F,SAAS,IAAI,IAAI;IAQjB,gGAAgG;IAChG,UAAU,CAAC,GAAG,GAAE,KAAK,CAAC,OAA6B,GAAG,KAAK,CAAC,OAAO;IAMnE;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,WAAW;CASnH"}

package/dist/three/screen-anchor.js

@@ -0,0 +1,71 @@
+/**
+ * SCREEN ANCHOR — place a floating UI element (a name tag, a button prompt, a health bar) a CONSTANT
+ * height above the TOP of a 3D object, then project that point to screen pixels. The standard
+ * "something hovering over a thing" placement, so games stop hand-rolling bbox + project math (and
+ * stop guessing pixel offsets that break when the model's size changes).
+ *
+ * On construction it measures the object's bounding box ONCE and remembers how far the top sits above
+ * the object's own origin (`topOffset`). Each `project()` re-reads the object's CURRENT world position
+ * — so the tag follows it as it moves or turns — and lifts by `topOffset + worldGap`. Keeping the gap
+ * in world units makes it perspective-correct (it shrinks with distance, like the object). `pixelGap`
+ * is an extra constant screen-space nudge UP on top of that — handy to clear a keycap that dangles
+ * below a card, or any fixed-size chrome the world gap can't account for.
+ *
+ * Defaults put a tag a little above the head by default; override `worldGap`/`pixelGap` per use and
+ * adapt from there. Call `remeasure()` if the object is rescaled or its model swapped.
+ */
+import * as THREE from "three";
+export class ScreenAnchor {
+    /** Height of the object's bbox top above its own origin, in world units (set by `remeasure`). */
+    topOffset = 0;
+    worldGap;
+    pixelGap;
+    target;
+    _w = new THREE.Vector3();
+    _p = new THREE.Vector3();
+    // While auto-measuring, the target's mesh may not be loaded yet (async GLB) → an empty box. Keep
+    // re-measuring on each project() until it yields a real top, so the tag snaps into place on load.
+    pendingMeasure = false;
+    constructor(target, opts = {}) {
+        this.target = target;
+        this.worldGap = opts.worldGap ?? 0.15;
+        this.pixelGap = opts.pixelGap ?? 0;
+        if (opts.topOffset != null)
+            this.topOffset = opts.topOffset; // explicit known height — never measure
+        else
+            this.remeasure();
+    }
+    /** Re-measure the object's top. Call after the object is rescaled or its model is swapped. */
+    remeasure() {
+        const box = new THREE.Box3().setFromObject(this.target);
+        if (box.isEmpty()) {
+            this.topOffset = 0;
+            this.pendingMeasure = true;
+            return;
+        } // mesh not there yet
+        // Top height above the object's own origin (yaw-invariant, so it survives the object turning).
+        this.topOffset = box.max.y - this.target.getWorldPosition(this._w).y;
+        this.pendingMeasure = false;
+    }
+    /** The world-space point the UI should hover at: `worldGap` above the object's measured top. */
+    worldPoint(out = new THREE.Vector3()) {
+        this.target.getWorldPosition(out);
+        out.y += this.topOffset + this.worldGap;
+        return out;
+    }
+    /**
+     * Project the anchor to CSS pixels within `host`. `onScreen` is false when the point is behind the
+     * camera — hide the element then. Pass `out` to reuse an object and avoid a per-frame allocation.
+     */
+    project(camera, host, out) {
+        if (this.pendingMeasure)
+            this.remeasure(); // async model may have just loaded — try again
+        const r = out ?? { x: 0, y: 0, onScreen: false };
+        const p = this.worldPoint(this._p).project(camera);
+        r.onScreen = p.z <= 1;
+        r.x = (p.x * 0.5 + 0.5) * host.clientWidth;
+        r.y = (-p.y * 0.5 + 0.5) * host.clientHeight - this.pixelGap; // +pixelGap lifts UP
+        return r;
+    }
+}
+//# sourceMappingURL=screen-anchor.js.map

package/dist/three/screen-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-anchor.js","sourceRoot":"","sources":["../../src/three/screen-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAyB/B,MAAM,OAAO,YAAY;IACvB,iGAAiG;IACjG,SAAS,GAAG,CAAC,CAAC;IACd,QAAQ,CAAS;IACjB,QAAQ,CAAS;IAET,MAAM,CAAiB;IACvB,EAAE,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IACzB,EAAE,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IACjC,iGAAiG;IACjG,kGAAkG;IAC1F,cAAc,GAAG,KAAK,CAAC;IAE/B,YAAY,MAAsB,EAAE,OAA4B,EAAE;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,wCAAwC;;YAChG,IAAI,CAAC,SAAS,EAAE,CAAC;IACxB,CAAC;IAED,8FAA8F;IAC9F,SAAS;QACP,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;YAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YAAC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAAC,OAAO;QAAC,CAAC,CAAC,qBAAqB;QACpG,+FAA+F;QAC/F,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,gGAAgG;IAChG,UAAU,CAAC,MAAqB,IAAI,KAAK,CAAC,OAAO,EAAE;QACjD,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAClC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;QACxC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAoB,EAAE,IAAmD,EAAE,GAAiB;QAClG,IAAI,IAAI,CAAC,cAAc;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,+CAA+C;QAC1F,MAAM,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACnD,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QAC3C,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,qBAAqB;QACnF,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}

package/dist/three/waypoint-beacon.d.ts

@@ -0,0 +1,56 @@
+/**
+ * WAYPOINT BEACON — the canonical "go here" world marker: a soft glow column rising from a filled
+ * base disc, ringed by expanding ground waves, that gracefully **fades out** once the player reaches
+ * it. The standard "the game (or an NPC, or a quest) is sending you to this spot" affordance, so games
+ * stop re-modelling the beam + rings + dismissal every time.
+ *
+ * It owns ONLY the world-space visuals + the fade. It deliberately does NOT:
+ *   - decide what "reached" means — proximity, an NPC line, a quest flag are the GAME's call; you tell
+ *     the beacon when to go with {@link WaypointBeacon.trigger} (and {@link WaypointBeacon.reset} to rearm).
+ *   - draw any DOM (a name card / distance pill). Float those with {@link ScreenAnchor} + your own HTML.
+ *
+ * Placement: `new WaypointBeacon()`, parent `.group` into your scene, set `group.position` to the
+ * ground point, then call `update(t, dt)` every frame (steady clock seconds + delta). The flat ground
+ * graphics (base + rings) render depth-test-OFF so undulating terrain never clips them (a flat decal
+ * at a fixed height otherwise sinks behind any rise in the ground); the vertical column keeps normal
+ * depth so it still tucks behind trees/hills. Everything is additive / shadow-free so it reads as UI
+ * light, not geometry.
+ */
+import * as THREE from "three";
+export interface WaypointBeaconOptions {
+    /** The beacon hue. Default `0x66e0ff` (a cyan that pops on grass). */
+    color?: number;
+    /** Glow-column height in world units. Default `13` — tall enough to read over props. */
+    height?: number;
+    /** Seconds the graceful fade-out takes once {@link WaypointBeacon.trigger} fires. Default `0.5`. */
+    fadeDuration?: number;
+}
+export declare class WaypointBeacon {
+    /** Parent this into your scene and set `group.position` to the beacon's ground point. */
+    readonly group: THREE.Group<THREE.Object3DEventMap>;
+    private readonly geos;
+    private readonly mats;
+    private readonly halo;
+    private readonly haloMat;
+    private readonly base;
+    private readonly baseMat;
+    private readonly rings;
+    private readonly fadeDuration;
+    /** <0 = idle; >=0 = seconds into the fade-out. */
+    private anim;
+    constructor(opts?: WaypointBeaconOptions);
+    /** Start the graceful fade-out. Idempotent — ignored if it's already fading or gone. */
+    trigger(): void;
+    /** Snap back to the idle beacon (rearm), e.g. when the player walks away from the spot. */
+    reset(): void;
+    /** True once the fade-out has finished and the beacon is fully invisible. */
+    get gone(): boolean;
+    /** Advance the beacon. `t` = a steady clock in seconds (drives the idle breathing/waves), `dt` = delta. */
+    update(t: number, dt: number): void;
+    /** Draw the breathing idle beacon (column + base + expanding waves), every opacity scaled by `fade`. */
+    private draw;
+    private hide;
+    /** Dispose geometries + materials and empty the group. Call on teardown. */
+    dispose(): void;
+}
+//# sourceMappingURL=waypoint-beacon.d.ts.map

package/dist/three/waypoint-beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waypoint-beacon.d.ts","sourceRoot":"","sources":["../../src/three/waypoint-beacon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD,qBAAa,cAAc;IACzB,yFAAyF;IACzF,QAAQ,CAAC,KAAK,sCAAqB;IAEnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmE;IACzF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,kDAAkD;IAClD,OAAO,CAAC,IAAI,CAAM;gBAEN,IAAI,GAAE,qBAA0B;IA0B5C,wFAAwF;IACxF,OAAO,IAAI,IAAI;IAEf,2FAA2F;IAC3F,KAAK,IAAI,IAAI;IAEb,6EAA6E;IAC7E,IAAI,IAAI,IAAI,OAAO,CAA0C;IAE7D,2GAA2G;IAC3G,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAOnC,wGAAwG;IACxG,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,IAAI;IAKZ,4EAA4E;IAC5E,OAAO,IAAI,IAAI;CAKhB"}

package/dist/three/waypoint-beacon.js

@@ -0,0 +1,118 @@
+/**
+ * WAYPOINT BEACON — the canonical "go here" world marker: a soft glow column rising from a filled
+ * base disc, ringed by expanding ground waves, that gracefully **fades out** once the player reaches
+ * it. The standard "the game (or an NPC, or a quest) is sending you to this spot" affordance, so games
+ * stop re-modelling the beam + rings + dismissal every time.
+ *
+ * It owns ONLY the world-space visuals + the fade. It deliberately does NOT:
+ *   - decide what "reached" means — proximity, an NPC line, a quest flag are the GAME's call; you tell
+ *     the beacon when to go with {@link WaypointBeacon.trigger} (and {@link WaypointBeacon.reset} to rearm).
+ *   - draw any DOM (a name card / distance pill). Float those with {@link ScreenAnchor} + your own HTML.
+ *
+ * Placement: `new WaypointBeacon()`, parent `.group` into your scene, set `group.position` to the
+ * ground point, then call `update(t, dt)` every frame (steady clock seconds + delta). The flat ground
+ * graphics (base + rings) render depth-test-OFF so undulating terrain never clips them (a flat decal
+ * at a fixed height otherwise sinks behind any rise in the ground); the vertical column keeps normal
+ * depth so it still tucks behind trees/hills. Everything is additive / shadow-free so it reads as UI
+ * light, not geometry.
+ */
+import * as THREE from "three";
+const DEFAULT_COLOR = 0x66e0ff;
+/** smoothstep 0..1 */
+const smooth = (x) => { const t = x <= 0 ? 0 : x >= 1 ? 1 : x; return t * t * (3 - 2 * t); };
+const additive = (color, opacity) => new THREE.MeshBasicMaterial({ color, transparent: true, opacity, blending: THREE.AdditiveBlending, depthWrite: false, side: THREE.DoubleSide });
+export class WaypointBeacon {
+    /** Parent this into your scene and set `group.position` to the beacon's ground point. */
+    group = new THREE.Group();
+    geos = [];
+    mats = [];
+    halo;
+    haloMat;
+    base;
+    baseMat;
+    rings;
+    fadeDuration;
+    /** <0 = idle; >=0 = seconds into the fade-out. */
+    anim = -1;
+    constructor(opts = {}) {
+        const color = opts.color ?? DEFAULT_COLOR;
+        const H = opts.height ?? 13;
+        this.fadeDuration = opts.fadeDuration ?? 0.5;
+        // vertical glow column (normal depth → occluded naturally by world geometry in front of it)
+        const haloGeo = new THREE.CylinderGeometry(0.7, 0.95, H, 20, 1, true);
+        haloGeo.translate(0, H / 2, 0);
+        this.geos.push(haloGeo);
+        this.haloMat = additive(color, 0.16);
+        this.mats.push(this.haloMat);
+        this.halo = new THREE.Mesh(haloGeo, this.haloMat);
+        this.group.add(this.halo);
+        // flat ground graphics: depth-test OFF + high render order so terrain can never clip them
+        const groundMat = (opacity) => { const m = additive(color, opacity); m.depthTest = false; this.mats.push(m); return m; };
+        const baseGeo = new THREE.CircleGeometry(0.95, 32);
+        baseGeo.rotateX(-Math.PI / 2);
+        this.geos.push(baseGeo);
+        this.baseMat = groundMat(0.4);
+        this.base = new THREE.Mesh(baseGeo, this.baseMat);
+        this.base.position.y = 0.05;
+        this.base.renderOrder = 10;
+        this.group.add(this.base);
+        const ringGeo = new THREE.RingGeometry(0.5, 0.62, 40);
+        ringGeo.rotateX(-Math.PI / 2);
+        this.geos.push(ringGeo);
+        this.rings = [0, 1].map((i) => {
+            const mat = groundMat(0);
+            const mesh = new THREE.Mesh(ringGeo, mat);
+            mesh.position.y = 0.06;
+            mesh.renderOrder = 11;
+            this.group.add(mesh);
+            return { mesh, mat, ph: i / 2 };
+        });
+    }
+    /** Start the graceful fade-out. Idempotent — ignored if it's already fading or gone. */
+    trigger() { if (this.anim < 0)
+        this.anim = 0; }
+    /** Snap back to the idle beacon (rearm), e.g. when the player walks away from the spot. */
+    reset() { this.anim = -1; }
+    /** True once the fade-out has finished and the beacon is fully invisible. */
+    get gone() { return this.anim > this.fadeDuration; }
+    /** Advance the beacon. `t` = a steady clock in seconds (drives the idle breathing/waves), `dt` = delta. */
+    update(t, dt) {
+        if (this.anim >= 0)
+            this.anim += dt;
+        if (this.anim < 0) {
+            this.draw(t, 1);
+            return;
+        } // idle
+        if (this.anim > this.fadeDuration) {
+            this.hide();
+            return;
+        } // fully gone
+        this.draw(t, 1 - smooth(this.anim / this.fadeDuration)); // fading: the whole beacon dims together
+    }
+    /** Draw the breathing idle beacon (column + base + expanding waves), every opacity scaled by `fade`. */
+    draw(t, fade) {
+        this.haloMat.opacity = (0.12 + 0.07 * (0.5 + 0.5 * Math.sin(t * 1.6))) * fade;
+        this.baseMat.opacity = (0.32 + 0.12 * Math.sin(t * 3)) * fade;
+        for (const r of this.rings) {
+            const ph = (t * 0.6 + r.ph) % 1;
+            const s = 0.5 + ph * 2.4;
+            r.mesh.scale.set(s, 1, s);
+            r.mat.opacity = 0.55 * (1 - ph) * fade;
+        }
+    }
+    hide() {
+        this.haloMat.opacity = 0;
+        this.baseMat.opacity = 0;
+        for (const r of this.rings)
+            r.mat.opacity = 0;
+    }
+    /** Dispose geometries + materials and empty the group. Call on teardown. */
+    dispose() {
+        for (const g of this.geos)
+            g.dispose();
+        for (const m of this.mats)
+            m.dispose();
+        this.group.clear();
+    }
+}
+//# sourceMappingURL=waypoint-beacon.js.map

package/dist/three/waypoint-beacon.js.map

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

package/dist/ui/README.md

@@ -0,0 +1,104 @@
+# `@rydr/game-sdk/ui` — controller-button UI kit
+
+> **MANDATORY READING before you build any in-game prompt, menu, dialogue, or keycap.** This kit is
+> the shared visual language for "which button to press" across the whole RYDR library. Before you
+> hand-build a button hint, an NPC dialogue box, a choice menu, or a card, check here — if it exists,
+> use it. Rolling your own (or copy-pasting one out of another game) fragments the look and is a bug.
+
+Self-contained DOM/CSS components — no three.js, no global styles. They inject their own scoped
+`.rydr-ui-*` CSS once into `<head>`; you get the look just by constructing a component.
+
+```ts
+import { mountButtonPrompt, mountDialogueCard, mountChoiceCard } from "@rydr/game-sdk/ui";
+```
+
+---
+
+## ⛔ The one hard rule: do NOT restyle the components
+
+Every RYDR game is played on a **trainer screen viewed from a few feet away while pedaling.** The
+keycap sizes, card label type, dialogue/choice font sizes, and diamond spacing are **tuned for that
+distance** and are part of the component contract — not defaults to override.
+
+- **Don't** override `.rydr-ui-*` font sizes / paddings / widths, and **don't** wrap a component in
+  `transform: scale()`. That breaks legibility on a real setup.
+- **Do** fill the **content slot** (cards take any DOM; the diamond/prompt take a label) and use the
+  provided **state methods** (`setVisible`, `setPressed`, `setCooldown`, …).
+- If a label doesn't fit, **shorten the text — don't shrink the type.**
+
+To position a floating prompt over a 3D object, use `ScreenAnchor` from `@rydr/game-sdk/three` and
+feed its `{x, y, onScreen}` into `setScreenPos`/`setVisible` — don't compute projections by hand.
+
+---
+
+## What's available
+
+| Symbol | Kind | Use it for |
+| --- | --- | --- |
+| `createKeycap(button, opts)` | fn | A bare A/B/Y/Z keycap (the letter pip), with state setters. |
+| `createDpadKeycap(dir, opts)` | fn | A bare UP/DOWN/LEFT/RIGHT keycap (white chevron on a steel pip). |
+| `mountButtonPrompt(host, button, label)` | fn | The common case: a labelled "press A" prompt card. |
+| `createButtonDiamond(button, variant)` | fn | The bare keycap element for embedding in your own layout. |
+| `mountActionCard(host, button, opts)` | fn | A dark glass card (content slot) with a keycap straddling its bottom edge. |
+| `mountCard(host, opts)` / `buildCard(opts)` | fn | Just the dark glass card with a content slot (no keycap). |
+| `mountActionDiamond(host, opts)` | fn | The full 4-button A/B/Y/Z diamond with per-button labels/actions. |
+| `mountLabeledDiamond(host, opts)` | fn | A diamond floating over a point with labels around it (the "actions on offer" affordance). |
+| `mountDialogueCard(host, opts)` | fn | An NPC dialogue box: speaker name, typed-out line, advance cue (A). |
+| `mountChoiceCard(host, opts)` | fn | A player choice menu: prompt + highlighted option list (▲▼ move, A confirm). |
+| `mountRarityCard(host, opts)` / `buildRarityCard(opts)` | fn | A generic rarity-tinted item/creature card. |
+| `injectCss()` | fn | Force the `.rydr-ui-*` CSS into `<head>` early (components call it for you). |
+
+Types: `ButtonLetter` (`"A"\|"B"\|"Y"\|"Z"`), `DirButton`, `KeycapVariant` (`"full"\|"solo"`),
+`ButtonSource`, `Keycap`, `Card`, `ActionCard`, `ButtonPrompt`, `DialogueCard`, `ChoiceCard`,
+`LabeledDiamond`, `ActionDiamond`, `Rarity`, `RarityCard`.
+
+---
+
+## Wiring to real input
+
+Any keycap/card reflects real presses if you pass it something with `onButton` — your platform
+`session` satisfies the structural `ButtonSource`:
+
+```ts
+const prompt = mountButtonPrompt(host, "A", "JUMP");
+// pass `session` so the keycap shows its pressed sink while A is held:
+createKeycap("A", { press: session });
+```
+
+The keycap is a small state machine — pressed sink, bouncing attract pulse (`setAnimated`), a
+depleting cooldown ring + countdown (`setCooldown(frac, label)`), colored/mono (`setColored`),
+disabled (`setDisabled`), and show/hide (`setVisible`).
+
+## Common recipes
+
+**Button prompt over an NPC (with `ScreenAnchor`):**
+```ts
+const prompt = mountButtonPrompt(host, "A", "TALK");
+const tag = new ScreenAnchor(npc.group);   // sits just above the head by default
+// per frame:
+const pt = tag.project(camera, host);
+prompt.setVisible(pt.onScreen);
+if (pt.onScreen) prompt.setScreenPos(pt.x, pt.y);   // no offsets needed
+```
+> **`setScreenPos` on an action card seats it ABOVE the point.** An action card is a prompt that
+> points down at a thing, so `setScreenPos(x, y)` places the card so its straddling keycap lands just
+> over `(x, y)` — never on top of it. Pass an anchor straight from `ScreenAnchor.project` and don't
+> add pixel fudge. (The plain `mountCard`/dialogue/choice/rarity cards still centre on the point.)
+
+**Dialogue:**
+```ts
+const dlg = mountDialogueCard(host, { press: session, onLine: (i) => npc.say?.(i) });
+dlg.open("Master Orsane", ["Welcome.", "Pick a creature."]);
+// A advances; dlg.advance() returns false when the last line is done.
+```
+
+**Choice menu:**
+```ts
+const choice = mountChoiceCard(host, { press: session });
+choice.open({ name: "You", prompt: "Who will you greet?", options, selected: 0 });
+```
+
+---
+
+For exact signatures and option types, read the `.d.ts` alongside the compiled module
+(`dist/ui/*.d.ts`). This README is the map; the types are the contract.

package/dist/ui/action-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-card.d.ts","sourceRoot":"","sources":["../../src/ui/action-card.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnH,MAAM,WAAW,iBAAkB,SAAQ,aAAa,EAAE,WAAW;CAAG;AAExE,gGAAgG;AAChG,MAAM,WAAW,UAAW,SAAQ,IAAI;IACtC,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChE,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAgBjH;AAID,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,aAAsB,GAAG,WAAW,CAEtG;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEtG"}
+{"version":3,"file":"action-card.d.ts","sourceRoot":"","sources":["../../src/ui/action-card.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnH,MAAM,WAAW,iBAAkB,SAAQ,aAAa,EAAE,WAAW;CAAG;AAUxE,gGAAgG;AAChG,MAAM,WAAW,UAAW,SAAQ,IAAI;IACtC,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChE,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAyBjH;AAID,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,aAAsB,GAAG,WAAW,CAEtG;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEtG"}

package/dist/ui/action-card.js

@@ -6,6 +6,13 @@
  */
 import { buildCard } from "./card.js";
 import { createKeycap } from "./keycap.js";
+/**
+ * How far (px) the keycap hangs below the card's bottom edge — it straddles there (see styles.ts
+ * `.rydr-ui-card > .rydr-ui-diamond`: a ~38px keycap dropped ~65%+8px). `setScreenPos` uses this to
+ * seat the prompt ABOVE the tracked point, so the keycap lands just over it (an NPC head) rather than
+ * on it — callers pass the anchor point straight through, no per-call pixel fudge.
+ */
+const KEYCAP_DROP = 33;
 /**
  * Mount an action card: a dark glass card with the keycap straddling its bottom edge and a content
  * SLOT (`card.body`). Fixed bottom-centre by default (call `setScreenPos` to track a projected point),
@@ -25,6 +32,15 @@ export function mountActionCard(host, button, opts = {}) {
         setColored: keycap.setColored,
         // the whole action goes unavailable: fade the card AND make the keycap inert in one call.
         setDisabled: (on) => { card.setDisabled(on); keycap.setDisabled(on); },
+        // Override the base (centre-on-point) placement: an action card is a prompt that points DOWN at
+        // a thing, so seat it ABOVE the tracked point with the straddling keycap landing just over it.
+        // Callers pass an anchor (e.g. ScreenAnchor.project over a head) straight in — no pixel offset.
+        setScreenPos(x, y) {
+            card.root.style.left = `${x}px`;
+            card.root.style.top = `${y}px`;
+            card.root.style.bottom = "auto";
+            card.root.style.transform = `translate(-50%, calc(-100% - ${KEYCAP_DROP}px))`;
+        },
     };
 }
 /** The bare keycap (no card) for embedding — back-compat shim over {@link createKeycap}. */

package/dist/ui/action-card.js.map

@@ -1 +1 @@
-{"version":3,"file":"action-card.js","sourceRoot":"","sources":["../../src/ui/action-card.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAA+B,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,YAAY,EAA0E,MAAM,aAAa,CAAC;AAgBnH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,MAAoB,EAAE,OAA0B,EAAE;IACnG,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,gDAAgD;IAClF,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5B,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,0FAA0F;QAC1F,WAAW,EAAE,CAAC,EAAW,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;KAChF,CAAC;AACJ,CAAC;AAYD,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,MAAoB,EAAE,UAAyB,MAAM;IACvF,OAAO,YAAY,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAE,MAAoB,EAAE,KAAa;IACtF,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"action-card.js","sourceRoot":"","sources":["../../src/ui/action-card.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAA+B,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,YAAY,EAA0E,MAAM,aAAa,CAAC;AAInH;;;;;GAKG;AACH,MAAM,WAAW,GAAG,EAAE,CAAC;AAcvB;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,MAAoB,EAAE,OAA0B,EAAE;IACnG,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,gDAAgD;IAClF,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5B,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,0FAA0F;QAC1F,WAAW,EAAE,CAAC,EAAW,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC/E,gGAAgG;QAChG,+FAA+F;QAC/F,gGAAgG;QAChG,YAAY,CAAC,CAAS,EAAE,CAAS;YAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,gCAAgC,WAAW,MAAM,CAAC;QAChF,CAAC;KACF,CAAC;AACJ,CAAC;AAYD,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,MAAoB,EAAE,UAAyB,MAAM;IACvF,OAAO,YAAY,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAE,MAAoB,EAAE,KAAa;IACtF,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/dist/ui/index.d.ts

@@ -2,8 +2,8 @@
  * `@rydr/game-sdk/ui` — the reusable controller-button UI: a DOM/CSS keycap of the A/B/Y/Z face
  * buttons and the UP/DOWN/LEFT/RIGHT d-pad, plus higher-level pieces built from it (a dark glass card
  * with a content slot, an action card, the full A/B/Y/Z move diamond, an NPC dialogue card, a player
- * choice menu, and a labeled diamond). Games use it to show "which button to press" in one consistent
- * visual language across the library.
+ * choice menu, a labeled diamond, and a generic rarity card). Games use it to show "which button to
+ * press" in one consistent visual language across the library.
  *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
  * CSS once into `<head>`, depends on no global styles or CSS variables, and pulls in no three.js — so
@@ -28,4 +28,5 @@ export * from "./action-diamond.js";
 export * from "./dialogue-card.js";
 export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
+export * from "./rarity-card.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}

package/dist/ui/index.js

@@ -2,8 +2,8 @@
  * `@rydr/game-sdk/ui` — the reusable controller-button UI: a DOM/CSS keycap of the A/B/Y/Z face
  * buttons and the UP/DOWN/LEFT/RIGHT d-pad, plus higher-level pieces built from it (a dark glass card
  * with a content slot, an action card, the full A/B/Y/Z move diamond, an NPC dialogue card, a player
- * choice menu, and a labeled diamond). Games use it to show "which button to press" in one consistent
- * visual language across the library.
+ * choice menu, a labeled diamond, and a generic rarity card). Games use it to show "which button to
+ * press" in one consistent visual language across the library.
  *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
  * CSS once into `<head>`, depends on no global styles or CSS variables, and pulls in no three.js — so
@@ -28,4 +28,5 @@ export * from "./action-diamond.js";
 export * from "./dialogue-card.js";
 export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
+export * from "./rarity-card.js";
 //# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}

package/dist/ui/rarity-card.d.ts

@@ -0,0 +1,74 @@
+/**
+ * RARITY CARD — a generic, game-agnostic rarity-tinted dark-glass frame with a CONTENT SLOT
+ * (`card.body`) the game fills with whatever it wants (a creature plate, an item, a card name +
+ * stats, …). The whole frame is tinted by the rarity colour: a 2px rarity rim, an inner + outer
+ * rarity glow, and either a thin top sheen or a thick top BAND carrying the rarity label. A
+ * `selected` state adds a crisp rarity ring + a deeper glow and lifts/scales the card — for
+ * arrow-navigable rosters/pickers.
+ *
+ * Rarity is a small built-in scale (`common`…`legendary`) with an SDK-shipped {@link RARITY} palette
+ * (colour + label). Games should use the default palette so rarity reads consistently across the
+ * library; a per-card `color`/`label` override exists but is NOT recommended.
+ *
+ * Like the rest of `@rydr/game-sdk/ui`, it injects its own scoped `.rydr-ui-*` CSS and depends on no
+ * global styles. Fill the content slot and use the state methods — don't restyle the frame.
+ */
+/** The built-in rarity scale, lowest → highest. */
+export type Rarity = "common" | "uncommon" | "rare" | "epic" | "legendary";
+/** A rarity's visual identity: the tint colour + the label shown in the top band. */
+export interface RarityStyle {
+    /** Any CSS colour — tints the whole frame (rim, glow, band). */
+    color: string;
+    /** Uppercased in the band, e.g. "Legendary". */
+    label: string;
+}
+/**
+ * The SDK's default rarity palette. Prefer it as-is so rarity reads the same across every game; pass a
+ * per-card `color`/`label` override only as a last resort.
+ */
+export declare const RARITY: Record<Rarity, RarityStyle>;
+export interface RarityCardOptions {
+    /** Rarity tier — drives the frame tint + the band label from the {@link RARITY} palette. */
+    rarity?: Rarity;
+    /** Override the rarity tint colour (NOT recommended — prefer the palette default per tier). */
+    color?: string;
+    /** Override the band label (e.g. a localised rarity name). Defaults to the tier's label. */
+    label?: string;
+    /** Show the thick top band carrying the rarity label. Defaults to `true` when a `rarity` is given. */
+    band?: boolean;
+    /** Initial slot content — a string (set as text) or an element appended into `body`. */
+    content?: string | HTMLElement;
+    /** Lay the card inline (in normal flow) instead of fixed bottom-centre. */
+    inline?: boolean;
+    /** Fixed card width (number → px, or any CSS length). Omit → the card hugs its content. */
+    width?: number | string;
+    /** Fixed card height (number → px, or any CSS length). Omit → the card hugs its content. */
+    height?: number | string;
+    /** Start in the selected state (ring + deeper glow + lift). */
+    selected?: boolean;
+}
+/** A mounted rarity card: a rarity-tinted frame + a content slot the game owns. */
+export interface RarityCard {
+    root: HTMLElement;
+    /** The content SLOT — append your own DOM here, or use setContent. */
+    body: HTMLElement;
+    setContent(content: string | HTMLElement): void;
+    /** Retint the frame (and band label) for a new rarity; `override` tweaks colour/label off the default. */
+    setRarity(rarity: Rarity, override?: Partial<RarityStyle>): void;
+    /** Selected = the focused card in a picker: a rarity ring + deeper glow, lifted + scaled. */
+    setSelected(on: boolean): void;
+    setVisible(v: boolean): void;
+    /** Centre the card at a viewport pixel (e.g. an entity projected to screen). */
+    setScreenPos(x: number, y: number): void;
+    dispose(): void;
+}
+/**
+ * Build the rarity-card DOM + handle WITHOUT attaching it to a host. Also returns the inner
+ * `.rydr-ui-rcard` element. Internal building block — most callers want {@link mountRarityCard}.
+ */
+export declare function buildRarityCard(opts?: RarityCardOptions): RarityCard & {
+    card: HTMLElement;
+};
+/** Mount a rarity-tinted card (frame + content slot) into `host`. See {@link RarityCardOptions}. */
+export declare function mountRarityCard(host: HTMLElement, opts?: RarityCardOptions): RarityCard;
+//# sourceMappingURL=rarity-card.d.ts.map

package/dist/ui/rarity-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rarity-card.d.ts","sourceRoot":"","sources":["../../src/ui/rarity-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3E,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;CACf;AAKD;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAM9C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC/B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,sEAAsE;IACtE,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAChD,0GAA0G;IAC1G,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IACjE,6FAA6F;IAC7F,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,gFAAgF;IAChF,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,iBAAsB,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CA+DhG;AAED,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAI3F"}