@umicat/three-sdk 0.5.0 → 0.7.0

package/dist/Input3D.d.ts

@@ -33,6 +33,18 @@ export interface Input3DOptions {
      * platform places the controls, so the platform has to place ALL of them.
      */
     actions?: Input3DAction[];
+    /**
+     * How the thumbstick behaves on touch.
+     *
+     * `'floating'` (the default) is the phone convention Roblox made standard:
+     * nothing is drawn until a thumb lands on the left half of the screen, and
+     * then the stick appears exactly there. A fixed stick makes the player find
+     * a target before they can move, and on a screen you cannot feel, that is a
+     * thumb-sized target somewhere the hand is not.
+     *
+     * `'fixed'` keeps the old always-visible pad at the bottom left.
+     */
+    stick?: 'floating' | 'fixed';
 }
 /**
  * Movement and jump, from a keyboard or a thumb, behind one interface.
@@ -58,6 +70,7 @@ export declare class Input3D {
     private readonly stick;
     private touchJump;
     private actions;
+    private stickMode;
     private readonly touchHeld;
     private readonly pressedAt;
     private readonly unconsumed;
@@ -85,7 +98,13 @@ export declare class Input3D {
     consume(id: string): boolean;
     private held_;
     private beginPress;
-    /** Test seam: drive the controller without synthesising DOM events. */
+    /** Test seam: drive the controller without synthesising DOM events.
+     *
+     *  This latches exactly as a real keydown does. It used to only add the code
+     *  to the held set, so `consume()` never saw it — a seam that behaved
+     *  differently from the thing it stands in for, which made a test report
+     *  that an attack did not land when the only thing that had not happened was
+     *  the press. */
     press(code: string): void;
     release(code: string): void;
     dispose(): void;

package/dist/Input3D.js

@@ -52,6 +52,7 @@ export class Input3D {
         this.stick = { x: 0, z: 0 };
         this.touchJump = false;
         this.actions = [];
+        this.stickMode = 'floating';
         this.touchHeld = new Set();
         this.pressedAt = new Map();
         this.unconsumed = new Set();
@@ -66,6 +67,7 @@ export class Input3D {
         // Losing focus mid-press would otherwise leave the character walking.
         this.target.addEventListener('blur', this.onBlur);
         this.actions = opts.actions ?? [];
+        this.stickMode = opts.stick ?? 'floating';
         const wantTouch = opts.touch === undefined || opts.touch === 'auto' ? isTouchDevice() : opts.touch;
         if (wantTouch && typeof document !== 'undefined') {
             this.mountTouch(opts.container ?? document.body);
@@ -113,8 +115,23 @@ export class Input3D {
         this.pressedAt.set(id, now());
         this.unconsumed.add(id);
     }
-    /** Test seam: drive the controller without synthesising DOM events. */
-    press(code) { this.keysDown.add(code); }
+    /** Test seam: drive the controller without synthesising DOM events.
+     *
+     *  This latches exactly as a real keydown does. It used to only add the code
+     *  to the held set, so `consume()` never saw it — a seam that behaved
+     *  differently from the thing it stands in for, which made a test report
+     *  that an attack did not land when the only thing that had not happened was
+     *  the press. */
+    press(code) {
+        if (this.keysDown.has(code))
+            return; // held, not re-pressed
+        this.keysDown.add(code);
+        if (code === 'Space')
+            this.beginPress('jump');
+        for (const a of this.actions)
+            if (a.keys?.includes(code))
+                this.beginPress(a.id);
+    }
     release(code) { this.keysDown.delete(code); }
     dispose() {
         this.target.removeEventListener('keydown', this.onDown);
@@ -140,8 +157,28 @@ export class Input3D {
             position: 'fixed', inset: '0', pointerEvents: 'none',
             touchAction: 'none', userSelect: 'none', zIndex: '10',
         });
+        const floating = this.stickMode === 'floating';
+        // The zone a thumb may land on to summon the stick. It is the LEFT HALF,
+        // not the pad: the whole point is that the player does not have to find
+        // anything. It deliberately stops short of the buttons on the right.
+        const zone = document.createElement('div');
+        Object.assign(zone.style, {
+            position: 'absolute', left: '0', top: '0', width: '50%', height: '100%',
+            pointerEvents: floating ? 'auto' : 'none',
+        });
         const pad = document.createElement('div');
-        Object.assign(pad.style, {
+        Object.assign(pad.style, floating ? {
+            position: 'absolute', width: '30vmin', height: '30vmin',
+            maxWidth: '180px', maxHeight: '180px',
+            borderRadius: '50%', background: 'rgba(255,255,255,0.14)',
+            border: '2px solid rgba(255,255,255,0.35)',
+            // Never interactive when floating: the ZONE owns the pointer, and a pad
+            // that also captured it would steal the very first move event as the
+            // thumb crosses its edge.
+            pointerEvents: 'none', display: 'none',
+            transform: 'translate(-50%, -50%)',
+            transition: 'opacity 120ms linear',
+        } : {
             position: 'absolute', left: '5vmin', bottom: '5vmin',
             width: '30vmin', height: '30vmin', maxWidth: '180px', maxHeight: '180px',
             borderRadius: '50%', background: 'rgba(255,255,255,0.14)',
@@ -185,17 +222,37 @@ export class Input3D {
             cluster.append(el);
             this.wireButton(el, a.id);
         }
-        root.append(pad, cluster);
+        root.append(zone, pad, cluster);
         container.appendChild(root);
         this.root = root;
         // Track by pointerId so a thumb on the stick and a thumb on the button do
         // not fight over one piece of state.
         let stickId = null;
-        const setFromEvent = (e) => {
+        // Where the stick is centred. When floating this is wherever the thumb
+        // landed, so it is remembered rather than read back off the element —
+        // reading the rect would make the origin drift with the pad's own
+        // transform and the stick would feel like it was sliding away.
+        let originX = 0, originY = 0, radius = 0;
+        const measurePad = () => {
             const r = pad.getBoundingClientRect();
-            const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
-            const max = r.width / 2;
-            let dx = (e.clientX - cx) / max, dy = (e.clientY - cy) / max;
+            radius = r.width / 2;
+            if (!floating) {
+                originX = r.left + radius;
+                originY = r.top + r.height / 2;
+            }
+        };
+        const showAt = (x, y) => {
+            originX = x;
+            originY = y;
+            pad.style.display = 'block';
+            pad.style.left = `${x}px`;
+            pad.style.top = `${y}px`;
+            measurePad();
+        };
+        const setFromEvent = (e) => {
+            if (!radius)
+                measurePad();
+            let dx = (e.clientX - originX) / radius, dy = (e.clientY - originY) / radius;
             const len = Math.hypot(dx, dy);
             if (len > 1) {
                 dx /= len;
@@ -212,19 +269,34 @@ export class Input3D {
             this.stick.z = 0;
             knob.style.left = '50%';
             knob.style.top = '50%';
+            if (floating)
+                pad.style.display = 'none';
         };
         const on = (el, ev, fn) => {
             const h = fn;
             el.addEventListener(ev, h);
             this.cleanups.push(() => el.removeEventListener(ev, h));
         };
-        on(pad, 'pointerdown', (e) => { stickId = e.pointerId; pad.setPointerCapture(e.pointerId); setFromEvent(e); });
-        on(pad, 'pointermove', (e) => { if (e.pointerId === stickId)
+        // The element that owns the gesture differs by mode, but the handlers do
+        // not — which is the point: `direction()` reads the same either way.
+        const grip = floating ? zone : pad;
+        on(grip, 'pointerdown', (e) => {
+            // One thumb drives the stick. A second finger landing in the zone must
+            // not move the origin out from under the first.
+            if (stickId !== null)
+                return;
+            stickId = e.pointerId;
+            grip.setPointerCapture(e.pointerId);
+            if (floating)
+                showAt(e.clientX, e.clientY);
+            setFromEvent(e);
+        });
+        on(grip, 'pointermove', (e) => { if (e.pointerId === stickId)
             setFromEvent(e); });
         // pointercancel too: a system gesture steals the pointer without an up, and
         // the character would walk forever.
         for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
-            on(pad, ev, (e) => { if (e.pointerId === stickId)
+            on(grip, ev, (e) => { if (e.pointerId === stickId)
                 reset(); });
         }
         on(btn, 'pointerdown', (e) => {

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

@@ -0,0 +1,16 @@
+import * as THREE from 'three';
+/**
+ * Flash `object` for `ms` milliseconds. Call `updateTints` each frame.
+ *
+ * Flashing something already flashing restarts it rather than stacking, so a
+ * fast combo does not leave a character permanently red.
+ */
+export declare function flashTint(object: THREE.Object3D, opts?: {
+    color?: THREE.ColorRepresentation;
+    ms?: number;
+    intensity?: number;
+}): void;
+/** Restore anything whose flash has expired. Call once per frame. */
+export declare function updateTints(objects: Iterable<THREE.Object3D>): void;
+/** Whether this object is mid-flash — handy for tests and for not stacking. */
+export declare function isTinted(object: THREE.Object3D): boolean;

package/dist/Tint.js

@@ -0,0 +1,62 @@
+import * as THREE from 'three';
+const states = new WeakMap();
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+/** Give this object its own materials, so tinting it tints only it. */
+function isolate(object) {
+    const out = [];
+    object.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        const cloned = list.map((m) => {
+            const c = m.clone();
+            return c;
+        });
+        mesh.material = Array.isArray(mesh.material) ? cloned : cloned[0];
+        for (const m of cloned) {
+            if (!m.emissive)
+                continue;
+            out.push({ mat: m, emissive: m.emissive.clone(), intensity: m.emissiveIntensity ?? 1 });
+        }
+    });
+    return out;
+}
+/**
+ * Flash `object` for `ms` milliseconds. Call `updateTints` each frame.
+ *
+ * Flashing something already flashing restarts it rather than stacking, so a
+ * fast combo does not leave a character permanently red.
+ */
+export function flashTint(object, opts = {}) {
+    let st = states.get(object);
+    if (!st) {
+        st = { materials: isolate(object), until: 0 };
+        states.set(object, st);
+    }
+    const color = new THREE.Color(opts.color ?? 0xff3020);
+    for (const m of st.materials) {
+        m.mat.emissive.copy(color);
+        m.mat.emissiveIntensity = opts.intensity ?? 0.9;
+    }
+    st.until = now() + (opts.ms ?? 140);
+}
+/** Restore anything whose flash has expired. Call once per frame. */
+export function updateTints(objects) {
+    const t = now();
+    for (const o of objects) {
+        const st = states.get(o);
+        if (!st || st.until === 0 || t < st.until)
+            continue;
+        st.until = 0;
+        for (const m of st.materials) {
+            m.mat.emissive.copy(m.emissive);
+            m.mat.emissiveIntensity = m.intensity;
+        }
+    }
+}
+/** Whether this object is mid-flash — handy for tests and for not stacking. */
+export function isTinted(object) {
+    const st = states.get(object);
+    return !!st && st.until > now();
+}

package/dist/index.d.ts

@@ -1,13 +1,16 @@
 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 { flashTint, updateTints, isTinted } from './Tint.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,12 @@
 // 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';
+export { flashTint, updateTints, isTinted } from './Tint.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.5.0",
+  "version": "0.7.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",