@umicat/three-sdk 0.4.0 → 0.6.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/SceneLoader3D.d.ts

@@ -46,4 +46,19 @@ export interface LoadedScene3D {
  * settled and shipped for 2D, and it is the reason an editor can render a scene
  * without starting a game.
  */
+/** One model from the manifest, loaded on its own.
+ *
+ *  `loadScene3D` only fetches what the SCENE references, which is everything a
+ *  game needs until the first thing that appears at runtime — a weapon picked
+ *  up, a projectile, a dropped item. Without this, a game reaches for
+ *  GLTFLoader itself and re-implements asset-base resolution and importScale
+ *  slightly differently from the loader beside it.
+ *
+ *  Returns a fresh object each call, so two swords do not share one transform. */
+export declare function loadModelAsset(manifest: Manifest3D, modelAssetId: string, opts?: {
+    assetBase?: string;
+}): Promise<{
+    object: THREE.Object3D;
+    clips: THREE.AnimationClip[];
+}>;
 export declare function loadScene3D(scene3d: Scene3D, manifest: Manifest3D, opts?: LoadSceneOptions): Promise<LoadedScene3D>;

package/dist/SceneLoader3D.js

@@ -45,6 +45,28 @@ function makePrimitive(e) {
  * settled and shipped for 2D, and it is the reason an editor can render a scene
  * without starting a game.
  */
+/** One model from the manifest, loaded on its own.
+ *
+ *  `loadScene3D` only fetches what the SCENE references, which is everything a
+ *  game needs until the first thing that appears at runtime — a weapon picked
+ *  up, a projectile, a dropped item. Without this, a game reaches for
+ *  GLTFLoader itself and re-implements asset-base resolution and importScale
+ *  slightly differently from the loader beside it.
+ *
+ *  Returns a fresh object each call, so two swords do not share one transform. */
+export async function loadModelAsset(manifest, modelAssetId, opts = {}) {
+    const asset = (manifest.models ?? []).find((m) => m.id === modelAssetId);
+    if (!asset) {
+        const have = (manifest.models ?? []).map((m) => m.id).join(', ');
+        throw new Error(`[umicat] manifest has no model '${modelAssetId}'. It has: ${have || '(none)'}`);
+    }
+    const gltf = await new GLTFLoader().loadAsync((opts.assetBase ?? '') + asset.path);
+    const object = gltf.scene;
+    if (asset.importScale !== undefined)
+        object.scale.setScalar(asset.importScale);
+    object.userData.modelAssetId = modelAssetId;
+    return { object, clips: gltf.animations };
+}
 export async function loadScene3D(scene3d, manifest, opts = {}) {
     const problems = validateScene(scene3d);
     if (problems.length) {

package/dist/Sockets.d.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import type { Socket3D } from './scene3d';
+/**
+ * Put a thing in a character's hand.
+ *
+ * A held object is not a child of the character — it is a child of a BONE, so
+ * it inherits that bone's animated transform and follows the swing for free.
+ * Parenting to the model root instead produces a sword that hovers politely
+ * beside a character doing all the work.
+ *
+ * The catch, and the reason this is a platform primitive rather than four
+ * lines in each game: **nothing guarantees a rig has a hand bone.** The
+ * character every 3D Umicat game ships with has seven bones — root, two legs,
+ * torso, two arms, head — and no wrist at all. So "the hand" is a position
+ * along the arm bone, found by tuning, and it is a property of that model.
+ * Every game re-deriving it by eye is how you get twelve games with the sword
+ * in twelve slightly different places.
+ */
+export interface Attachment {
+    /** The bone it ended up on — useful when you want to check your work. */
+    readonly bone: THREE.Bone;
+    /** The wrapper that carries the socket offset; the object is its child. */
+    readonly holder: THREE.Object3D;
+    detach(): void;
+}
+/** Find a bone by exact name anywhere under `root`. */
+export declare function findBone(root: THREE.Object3D, name: string): THREE.Bone | null;
+/** Every bone name under `root` — what an error message should offer. */
+export declare function boneNames(root: THREE.Object3D): string[];
+/**
+ * Attach `object` to a socket on `root`.
+ *
+ * Throws if the bone is missing, and says which bones DO exist. A silent miss
+ * here is the worst outcome available: the weapon stays parented where it was,
+ * usually at the world origin, and the character walks around empty-handed
+ * while every line of the game's equip logic reports success.
+ */
+export declare function attachToSocket(root: THREE.Object3D, socket: Socket3D, object: THREE.Object3D): Attachment;

package/dist/Sockets.js

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+/** Find a bone by exact name anywhere under `root`. */
+export function findBone(root, name) {
+    let found = null;
+    root.traverse((o) => { if (!found && o.isBone && o.name === name)
+        found = o; });
+    return found;
+}
+/** Every bone name under `root` — what an error message should offer. */
+export function boneNames(root) {
+    const out = [];
+    root.traverse((o) => { if (o.isBone)
+        out.push(o.name); });
+    return out;
+}
+/**
+ * Attach `object` to a socket on `root`.
+ *
+ * Throws if the bone is missing, and says which bones DO exist. A silent miss
+ * here is the worst outcome available: the weapon stays parented where it was,
+ * usually at the world origin, and the character walks around empty-handed
+ * while every line of the game's equip logic reports success.
+ */
+export function attachToSocket(root, socket, object) {
+    const bone = findBone(root, socket.bone);
+    if (!bone) {
+        throw new Error(`[umicat] no bone "${socket.bone}" on this model. It has: ${boneNames(root).join(', ') || '(no bones at all)'}`);
+    }
+    // A holder, not the object itself: the socket offset and whatever transform
+    // the object arrives with are different things, and baking them together
+    // means a game cannot move the object within the hand without losing the
+    // socket. It also makes detaching exact.
+    const holder = new THREE.Object3D();
+    holder.name = `socket:${socket.bone}`;
+    if (socket.position)
+        holder.position.set(socket.position.x, socket.position.y, socket.position.z);
+    if (socket.rotation)
+        holder.rotation.set(socket.rotation.x, socket.rotation.y, socket.rotation.z);
+    if (socket.scale !== undefined)
+        holder.scale.setScalar(socket.scale);
+    holder.add(object);
+    bone.add(holder);
+    return {
+        bone,
+        holder,
+        detach() { holder.removeFromParent(); },
+    };
+}

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/dist/index.d.ts

@@ -1,13 +1,15 @@
 export { ThreeUmicat } from './ThreeUmicat.js';
 export type { UmicatInitOptions } from './ThreeUmicat.js';
 export * from './scene3d.js';
-export { loadScene3D } from './SceneLoader3D.js';
+export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
 export type { CharacterOptions, CharacterState, CharacterInput } from './CharacterController3D.js';
 export { CharacterAnimator } from './CharacterAnimator.js';
 export type { ClipMap, CharacterAnimatorOptions } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.js';
-export type { Input3DOptions } from './Input3D.js';
+export type { Input3DOptions, Input3DAction } from './Input3D.js';
+export { attachToSocket, findBone, boneNames } from './Sockets.js';
+export type { Attachment } from './Sockets.js';
 export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
 export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
 export type { Orientation } from '@umicat/platform-sdk/orientation.js';

package/dist/index.js

@@ -5,10 +5,11 @@
 // that turns it into a three.js scene with physics, and the runtime glue.
 export { ThreeUmicat } from './ThreeUmicat.js';
 export * from './scene3d.js';
-export { loadScene3D } from './SceneLoader3D.js';
+export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
 export { CharacterAnimator } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.js';
+export { attachToSocket, findBone, boneNames } from './Sockets.js';
 // Re-exported so a game imports one package for the common case. A game should
 // not have to know that identity and saves come from a different package than
 // the renderer.

package/dist/scene3d.d.ts

@@ -92,6 +92,26 @@ export interface Entity3D {
  * model calls its walk cycle `Walk` fails the same way, only more quietly.
  */
 export type AnimationMap = Record<string, string>;
+/**
+ * Where a held object sits on a character, named by what it is FOR rather
+ * than by which bone it happens to hang off.
+ *
+ * Rigs do not necessarily have a hand bone — this character's has seven bones
+ * and the arm is one of them, so a sword hangs off `arm-right` with an offset
+ * that puts it where a hand would be. That offset is a property of the MODEL,
+ * not of any game, so it travels in the manifest: tune it once and every game
+ * using this character gets a sword in the right place.
+ */
+export interface Socket3D {
+    /** Bone to hang from. Names are exact; the loader reports what it found. */
+    bone: string;
+    /** Offset in the bone's local space. */
+    position?: Vec3;
+    /** Euler angles in radians, applied in the bone's local space. */
+    rotation?: Vec3;
+    /** Uniform scale for whatever is attached. */
+    scale?: number;
+}
 export interface ModelAsset3D {
     id: string;
     /** Resolved by the runtime against the project's asset base url. */
@@ -99,6 +119,8 @@ export interface ModelAsset3D {
     animations?: AnimationMap;
     /** Authoring correction applied at load: most models are not born 1 unit tall. */
     importScale?: number;
+    /** Named attachment points — `{ "hand-right": { bone: "arm-right", ... } }`. */
+    sockets?: Record<string, Socket3D>;
 }
 export interface Light3D {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.4.0",
+  "version": "0.6.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",