@umicat/three-sdk 0.6.0 → 0.7.1

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

@@ -6,6 +6,21 @@
  *  and makes a quick tap always count. */
 const MIN_PRESS_MS = 80;
 const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+/**
+ * Everything needed to stop a long press from being read as "select this text".
+ *
+ * A thumbstick REQUIRES holding still, which is exactly the gesture iOS uses to
+ * start a selection — so on a phone the Copy / Look Up / Translate callout came
+ * up over the game the first time anyone tried to walk. `user-select` alone is
+ * not enough: `-webkit-touch-callout` is a separate switch, and neither is
+ * implied by `touch-action: none`.
+ */
+const NO_SELECTION = {
+    userSelect: 'none',
+    WebkitUserSelect: 'none',
+    WebkitTouchCallout: 'none',
+    WebkitTapHighlightColor: 'transparent',
+};
 const isTouchDevice = () => typeof matchMedia === 'function' &&
     matchMedia('(pointer: coarse)').matches &&
     !matchMedia('(pointer: fine)').matches;
@@ -52,6 +67,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 +82,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 +130,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);
@@ -138,10 +170,32 @@ export class Input3D {
             // some ancestor happens to be positioned, and "happens to be" is not a
             // layout strategy.
             position: 'fixed', inset: '0', pointerEvents: 'none',
-            touchAction: 'none', userSelect: 'none', zIndex: '10',
+            touchAction: 'none', zIndex: '10',
         });
+        Object.assign(root.style, NO_SELECTION);
+        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',
+        });
+        Object.assign(zone.style, NO_SELECTION);
         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)',
@@ -176,6 +230,11 @@ export class Input3D {
                 color: 'rgba(255,255,255,0.85)', font: '600 4vmin/1 system-ui, sans-serif',
             });
             el.textContent = label;
+            // Explicitly, not by inheritance. The label IS text -- a glyph in a div
+            // -- and long-pressing the attack button is how the iOS Copy / Look Up /
+            // Translate callout came up mid-fight, with the selection handles
+            // clamped around the little crossed swords.
+            Object.assign(el.style, NO_SELECTION);
             return el;
         };
         const btn = makeButton('▲');
@@ -185,17 +244,61 @@ 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;
+        // And the page underneath. The overlay covers the controls, but a press
+        // that lands on the HUD or the canvas would still summon the callout — and
+        // a game is not a document; there is nothing here to select.
+        //
+        // A stylesheet rather than inline styles, so form fields can opt back IN:
+        // blanket `user-select: none` on <body> can stop a player selecting text
+        // inside their own name field, and a game that takes typed input would
+        // have inherited a bug from its movement controls.
+        const doc = container.ownerDocument;
+        const style = doc.createElement('style');
+        style.dataset.umicatTouch = '';
+        style.textContent = `
+      html, body { -webkit-user-select: none; user-select: none;
+                   -webkit-touch-callout: none;
+                   -webkit-tap-highlight-color: transparent; }
+      input, textarea, select, [contenteditable] {
+                   -webkit-user-select: text; user-select: text;
+                   -webkit-touch-callout: default; }
+    `;
+        doc.head.appendChild(style);
+        this.cleanups.push(() => style.remove());
+        const noMenu = (e) => e.preventDefault();
+        doc.addEventListener('contextmenu', noMenu);
+        this.cleanups.push(() => doc.removeEventListener('contextmenu', noMenu));
         // 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 +315,37 @@ 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) => {
+            // Cancel the default gesture: on iOS, holding still on the screen is how
+            // a text selection begins, and holding still is the entire thumbstick.
+            e.preventDefault();
+            // 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) => {
@@ -243,6 +364,7 @@ export class Input3D {
             this.cleanups.push(() => el.removeEventListener(ev, h));
         };
         on('pointerdown', (e) => {
+            // Cancels the selection gesture as well as the default press behaviour.
             e.preventDefault();
             el.setPointerCapture(e.pointerId);
             this.touchHeld.add(id);

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

@@ -9,6 +9,7 @@ export type { ClipMap, CharacterAnimatorOptions } from './CharacterAnimator.js';
 export { Input3D } 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';

package/dist/index.js

@@ -10,6 +10,7 @@ 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/package.json

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