@umicat/three-sdk 0.4.0 → 0.5.0

package/dist/Input3D.d.ts

@@ -1,3 +1,12 @@
+/** An extra on-screen button, and the keys that do the same thing. */
+export interface Input3DAction {
+    /** What the game calls it: `input.held('attack')`, `input.consume('attack')`. */
+    id: string;
+    /** What the button shows. Keep it one glyph. */
+    label?: string;
+    /** Keyboard equivalents, e.g. `['KeyJ']`. */
+    keys?: string[];
+}
 export interface Input3DOptions {
     /** Where key events are read from. */
     target?: Window;
@@ -14,6 +23,16 @@ export interface Input3DOptions {
      * this layer belongs to the platform.
      */
     container?: HTMLElement | null;
+    /**
+     * Extra action buttons — attack, interact, whatever the game has.
+     *
+     * These exist because a game that mounts its own button has no idea where
+     * the jump button is, and the first one to try landed exactly on top of it:
+     * same corner, and this layer sits above, so every tap in that area jumped
+     * and the attack button could not be pressed at all. Nothing errored. The
+     * platform places the controls, so the platform has to place ALL of them.
+     */
+    actions?: Input3DAction[];
 }
 /**
  * Movement and jump, from a keyboard or a thumb, behind one interface.
@@ -31,13 +50,17 @@ export interface Input3DOptions {
  * has to branch on input source.
  */
 export declare class Input3D {
-    private readonly held;
+    private readonly keysDown;
     private readonly target;
     private readonly onDown;
     private readonly onUp;
     private readonly onBlur;
     private readonly stick;
     private touchJump;
+    private actions;
+    private readonly touchHeld;
+    private readonly pressedAt;
+    private readonly unconsumed;
     private root;
     private readonly cleanups;
     constructor(options?: Input3DOptions | Window);
@@ -51,9 +74,21 @@ export declare class Input3D {
     /** Whether the jump control is held right now. Pass it to the controller —
      *  coyote time and buffering live there, not here. */
     get jump(): boolean;
+    /** Whether an action is held right now — button or bound key, same answer. */
+    held(id: string): boolean;
+    /** True exactly once per press: one tap is one swing.
+     *
+     *  Edge detection done in the game reads the button's STATE and compares it
+     *  to last frame's, which means a press that begins and ends between two
+     *  frames never happened. This latches at the event, so it cannot be missed
+     *  — and it clears on read, so holding the button does not chain. */
+    consume(id: string): boolean;
+    private held_;
+    private beginPress;
     /** Test seam: drive the controller without synthesising DOM events. */
     press(code: string): void;
     release(code: string): void;
     dispose(): void;
     private mountTouch;
+    private wireButton;
 }

package/dist/Input3D.js

@@ -1,3 +1,11 @@
+/** How long a press stays readable, however briefly it was actually made.
+ *
+ *  A tap whose down and up both land between two frames is invisible to a
+ *  loop that polls state — the game samples `false`, `false`, and the player
+ *  swears the button did nothing. Holding it for a few frames costs nothing
+ *  and makes a quick tap always count. */
+const MIN_PRESS_MS = 80;
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
 const isTouchDevice = () => typeof matchMedia === 'function' &&
     matchMedia('(pointer: coarse)').matches &&
     !matchMedia('(pointer: fine)').matches;
@@ -18,18 +26,35 @@ const isTouchDevice = () => typeof matchMedia === 'function' &&
  */
 export class Input3D {
     constructor(options = {}) {
-        this.held = new Set();
+        this.keysDown = new Set();
         this.onDown = (e) => {
-            this.held.add(e.code);
+            this.keysDown.add(e.code);
+            if (!e.repeat) {
+                if (e.code === 'Space')
+                    this.beginPress('jump');
+                for (const a of this.actions)
+                    if (a.keys?.includes(e.code))
+                        this.beginPress(a.id);
+            }
             // Space scrolls the page, which in an embedded game scrolls the HOST page
             // out from under the player.
             if (e.code === 'Space')
                 e.preventDefault();
         };
-        this.onUp = (e) => { this.held.delete(e.code); };
-        this.onBlur = () => { this.held.clear(); this.stick.x = 0; this.stick.z = 0; this.touchJump = false; };
+        this.onUp = (e) => { this.keysDown.delete(e.code); };
+        this.onBlur = () => {
+            this.keysDown.clear();
+            this.stick.x = 0;
+            this.stick.z = 0;
+            this.touchJump = false;
+            this.touchHeld.clear();
+        };
         this.stick = { x: 0, z: 0 };
         this.touchJump = false;
+        this.actions = [];
+        this.touchHeld = new Set();
+        this.pressedAt = new Map();
+        this.unconsumed = new Set();
         this.root = null;
         this.cleanups = [];
         // A Window here is the pre-touch signature; keep it working.
@@ -40,12 +65,13 @@ export class Input3D {
         this.target.addEventListener('keyup', this.onUp);
         // Losing focus mid-press would otherwise leave the character walking.
         this.target.addEventListener('blur', this.onBlur);
+        this.actions = opts.actions ?? [];
         const wantTouch = opts.touch === undefined || opts.touch === 'auto' ? isTouchDevice() : opts.touch;
         if (wantTouch && typeof document !== 'undefined') {
             this.mountTouch(opts.container ?? document.body);
         }
     }
-    isDown(...codes) { return codes.some((c) => this.held.has(c)); }
+    isDown(...codes) { return codes.some((c) => this.keysDown.has(c)); }
     /** Camera-relative would need the camera; this is world-axis movement.
      *  Keyboard and stick are merged, so both work on a device with both. */
     direction() {
@@ -64,10 +90,32 @@ export class Input3D {
     }
     /** Whether the jump control is held right now. Pass it to the controller —
      *  coyote time and buffering live there, not here. */
-    get jump() { return this.touchJump || this.isDown('Space'); }
+    get jump() { return this.held_('jump', this.touchJump || this.isDown('Space')); }
+    /** Whether an action is held right now — button or bound key, same answer. */
+    held(id) {
+        const a = this.actions.find((x) => x.id === id);
+        return this.held_(id, this.touchHeld.has(id) || (a?.keys ? this.isDown(...a.keys) : false));
+    }
+    /** True exactly once per press: one tap is one swing.
+     *
+     *  Edge detection done in the game reads the button's STATE and compares it
+     *  to last frame's, which means a press that begins and ends between two
+     *  frames never happened. This latches at the event, so it cannot be missed
+     *  — and it clears on read, so holding the button does not chain. */
+    consume(id) { return this.unconsumed.delete(id); }
+    held_(id, physical) {
+        if (physical)
+            return true;
+        const t = this.pressedAt.get(id);
+        return t !== undefined && now() - t < MIN_PRESS_MS;
+    }
+    beginPress(id) {
+        this.pressedAt.set(id, now());
+        this.unconsumed.add(id);
+    }
     /** Test seam: drive the controller without synthesising DOM events. */
-    press(code) { this.held.add(code); }
-    release(code) { this.held.delete(code); }
+    press(code) { this.keysDown.add(code); }
+    release(code) { this.keysDown.delete(code); }
     dispose() {
         this.target.removeEventListener('keydown', this.onDown);
         this.target.removeEventListener('keyup', this.onUp);
@@ -77,7 +125,7 @@ export class Input3D {
         this.cleanups.length = 0;
         this.root?.remove();
         this.root = null;
-        this.held.clear();
+        this.keysDown.clear();
     }
     // ── on-screen controls ────────────────────────────────────────────────────
     mountTouch(container) {
@@ -106,17 +154,38 @@ export class Input3D {
             transform: 'translate(-50%, -50%)', pointerEvents: 'none',
         });
         pad.appendChild(knob);
-        const btn = document.createElement('div');
-        Object.assign(btn.style, {
+        // ONE cluster holds every button, laid out by flexbox, because the bug this
+        // replaces was two buttons independently choosing "bottom right" and
+        // landing on top of each other. Jump sits at the corner where it always
+        // was; actions stack to its left and wrap upward.
+        const cluster = document.createElement('div');
+        Object.assign(cluster.style, {
             position: 'absolute', right: '6vmin', bottom: '7vmin',
-            width: '20vmin', height: '20vmin', maxWidth: '120px', maxHeight: '120px',
-            borderRadius: '50%', background: 'rgba(255,255,255,0.2)',
-            border: '2px solid rgba(255,255,255,0.4)', pointerEvents: 'auto',
-            display: 'flex', alignItems: 'center', justifyContent: 'center',
-            color: 'rgba(255,255,255,0.85)', font: '600 4vmin/1 system-ui, sans-serif',
+            display: 'flex', flexDirection: 'row-reverse', alignItems: 'flex-end',
+            flexWrap: 'wrap-reverse', justifyContent: 'flex-start',
+            gap: '3vmin', maxWidth: '52vmin', pointerEvents: 'none',
         });
-        btn.textContent = '▲';
-        root.append(pad, btn);
+        const makeButton = (label) => {
+            const el = document.createElement('div');
+            Object.assign(el.style, {
+                width: '20vmin', height: '20vmin', maxWidth: '120px', maxHeight: '120px',
+                flex: '0 0 auto',
+                borderRadius: '50%', background: 'rgba(255,255,255,0.2)',
+                border: '2px solid rgba(255,255,255,0.4)', pointerEvents: 'auto',
+                display: 'flex', alignItems: 'center', justifyContent: 'center',
+                color: 'rgba(255,255,255,0.85)', font: '600 4vmin/1 system-ui, sans-serif',
+            });
+            el.textContent = label;
+            return el;
+        };
+        const btn = makeButton('▲');
+        cluster.append(btn);
+        for (const a of this.actions) {
+            const el = makeButton(a.label ?? a.id.slice(0, 1).toUpperCase());
+            cluster.append(el);
+            this.wireButton(el, a.id);
+        }
+        root.append(pad, cluster);
         container.appendChild(root);
         this.root = root;
         // Track by pointerId so a thumb on the stick and a thumb on the button do
@@ -158,9 +227,31 @@ export class Input3D {
             on(pad, ev, (e) => { if (e.pointerId === stickId)
                 reset(); });
         }
-        on(btn, 'pointerdown', (e) => { btn.setPointerCapture(e.pointerId); this.touchJump = true; });
+        on(btn, 'pointerdown', (e) => {
+            btn.setPointerCapture(e.pointerId);
+            this.touchJump = true;
+            this.beginPress('jump');
+        });
         for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
             on(btn, ev, () => { this.touchJump = false; });
         }
     }
+    wireButton(el, id) {
+        const on = (ev, fn) => {
+            const h = fn;
+            el.addEventListener(ev, h);
+            this.cleanups.push(() => el.removeEventListener(ev, h));
+        };
+        on('pointerdown', (e) => {
+            e.preventDefault();
+            el.setPointerCapture(e.pointerId);
+            this.touchHeld.add(id);
+            this.beginPress(id);
+        });
+        // pointercancel included: a system gesture steals the pointer with no `up`,
+        // and the button would read as held for the rest of the run.
+        for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
+            on(ev, () => { this.touchHeld.delete(id); });
+        }
+    }
 }

package/dist/ThreeUmicat.js

@@ -21,6 +21,33 @@ export class ThreeUmicat extends UmicatCore {
         this.dialogue = new DialogueModule(this.saves, () => transport.locale ?? 'en', () => transport.user?.name ?? null);
     }
     static async init(options = {}) {
-        return new ThreeUmicat(await UmicatCore.connect(SDK_VERSION, options));
+        const game = new ThreeUmicat(await UmicatCore.connect(SDK_VERSION, options));
+        announceScaleMode();
+        return game;
+    }
+}
+/**
+ * Tell the host this game fills the frame.
+ *
+ * The host letterboxes to the game's authored aspect UNLESS the game says
+ * otherwise, and it reads silence as "built before the SDK announced anything"
+ * — which every 3D game was, because only the Phaser SDK ever sent this. So a
+ * 3D game on a phone rendered into a 16:9 box with black down the side, losing
+ * a third of the screen, and the only symptom was a black band nobody could
+ * attribute to anything.
+ *
+ * A 3D game is always `resize`: the camera's aspect follows the window, so
+ * there is no authored pixel canvas to preserve. That is a property of drawing
+ * in 3D, not a per-game preference, which is why this is not an option.
+ */
+function announceScaleMode() {
+    try {
+        // Safe no-op when not embedded — the same game runs standalone in dev.
+        if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
+            window.parent.postMessage({ type: 'umicat:scaleMode', mode: 'resize' }, '*');
+        }
+    }
+    catch {
+        /* cross-origin parent access can throw in odd embeds — non-fatal */
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
   "type": "module",
   "main": "dist/index.js",