@umicat/three-sdk 0.7.2 → 0.8.1

package/dist/Input3D.d.ts

@@ -45,6 +45,16 @@ export interface Input3DOptions {
      * `'fixed'` keeps the old always-visible pad at the bottom left.
      */
     stick?: 'floating' | 'fixed';
+    /**
+     * Drag the right half of the screen to turn the camera — the other half of
+     * the phone convention, and the half without which a turnable camera is
+     * unreachable on a phone. Buttons sit above this zone, so they keep their
+     * taps. Default on wherever touch controls are shown.
+     */
+    look?: boolean;
+    /** Radians of camera rotation per screen-width dragged. Same number governs
+     *  touch drags and desktop right-drags, so there is one knob to turn. */
+    lookSensitivity?: number;
 }
 /**
  * Movement and jump, from a keyboard or a thumb, behind one interface.
@@ -71,6 +81,9 @@ export declare class Input3D {
     private touchJump;
     private actions;
     private stickMode;
+    private wantLook;
+    private lookSens;
+    private readonly lookDelta;
     private readonly touchHeld;
     private readonly pressedAt;
     private readonly unconsumed;
@@ -78,9 +91,18 @@ export declare class Input3D {
     private readonly cleanups;
     constructor(options?: Input3DOptions | Window);
     isDown(...codes: string[]): boolean;
-    /** 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(): {
+    /**
+     * Which way to walk. Keyboard and stick are merged, so both work on a device
+     * with both.
+     *
+     * Pass the camera's yaw (`LoadedScene3D.cameraYaw`) and "up" means away from
+     * the camera rather than north. Once the camera can turn, movement that
+     * ignores it is the single most disorienting thing a 3D game can do: the
+     * player turns to look at something and the stick still walks them the way
+     * they were pointed before. Omit it and you get the old world-axis
+     * behaviour, which is correct for a camera that never moves.
+     */
+    direction(cameraYaw?: number): {
         x: number;
         z: number;
     };
@@ -89,6 +111,18 @@ export declare class Input3D {
     get jump(): boolean;
     /** Whether an action is held right now — button or bound key, same answer. */
     held(id: string): boolean;
+    /**
+     * How far the camera should turn this frame, in radians — and reading it
+     * CLEARS it.
+     *
+     * Consumed rather than sampled because it is a delta, not a state: a frame
+     * that forgets to read it must not lose the movement, and a frame that reads
+     * it twice must not apply it twice. Pass straight to `LoadedScene3D.orbit`.
+     */
+    look(): {
+        x: number;
+        y: number;
+    };
     /** True exactly once per press: one tap is one swing.
      *
      *  Edge detection done in the game reads the button's STATE and compares it
@@ -108,6 +142,20 @@ export declare class Input3D {
     press(code: string): void;
     release(code: string): void;
     dispose(): void;
+    /**
+     * Desktop: hold the RIGHT mouse button and drag to turn the camera.
+     *
+     * The on-screen look zone only exists where the touch controls do, so
+     * without this a mouse-and-keyboard player has a camera they cannot turn at
+     * all — and now that movement is camera-relative, a camera you cannot turn
+     * is one that has permanently decided which way "forward" is.
+     *
+     * The right button rather than the left: a left-drag is how a game selects,
+     * clicks and aims, and taking that away from every game by default would be
+     * a worse trade than the one it fixes. Right-drag is also what Roblox uses
+     * on desktop, so it is already in players' hands.
+     */
+    private mountMouseLook;
     private mountTouch;
     private wireButton;
 }

package/dist/Input3D.js

@@ -68,6 +68,9 @@ export class Input3D {
         this.touchJump = false;
         this.actions = [];
         this.stickMode = 'floating';
+        this.wantLook = true;
+        this.lookSens = 4.6;
+        this.lookDelta = { x: 0, y: 0 };
         this.touchHeld = new Set();
         this.pressedAt = new Map();
         this.unconsumed = new Set();
@@ -83,15 +86,29 @@ export class Input3D {
         this.target.addEventListener('blur', this.onBlur);
         this.actions = opts.actions ?? [];
         this.stickMode = opts.stick ?? 'floating';
+        this.wantLook = opts.look ?? true;
+        this.lookSens = opts.lookSensitivity ?? 4.6;
+        if (this.wantLook && typeof document !== 'undefined') {
+            this.mountMouseLook(opts.container?.ownerDocument ?? document);
+        }
         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.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() {
+    /**
+     * Which way to walk. Keyboard and stick are merged, so both work on a device
+     * with both.
+     *
+     * Pass the camera's yaw (`LoadedScene3D.cameraYaw`) and "up" means away from
+     * the camera rather than north. Once the camera can turn, movement that
+     * ignores it is the single most disorienting thing a 3D game can do: the
+     * player turns to look at something and the stick still walks them the way
+     * they were pointed before. Omit it and you get the old world-axis
+     * behaviour, which is correct for a camera that never moves.
+     */
+    direction(cameraYaw = 0) {
         let x = this.stick.x, z = this.stick.z;
         if (this.isDown('KeyW', 'ArrowUp'))
             z -= 1;
@@ -103,7 +120,14 @@ export class Input3D {
             x += 1;
         const len = Math.hypot(x, z);
         // Clamp rather than normalise: a half-pushed stick should walk slowly.
-        return len > 1 ? { x: x / len, z: z / len } : { x, z };
+        if (len > 1) {
+            x /= len;
+            z /= len;
+        }
+        if (!cameraYaw)
+            return { x, z };
+        const s = Math.sin(cameraYaw), c = Math.cos(cameraYaw);
+        return { x: x * c + z * s, z: z * c - x * s };
     }
     /** Whether the jump control is held right now. Pass it to the controller —
      *  coyote time and buffering live there, not here. */
@@ -113,6 +137,20 @@ export class Input3D {
         const a = this.actions.find((x) => x.id === id);
         return this.held_(id, this.touchHeld.has(id) || (a?.keys ? this.isDown(...a.keys) : false));
     }
+    /**
+     * How far the camera should turn this frame, in radians — and reading it
+     * CLEARS it.
+     *
+     * Consumed rather than sampled because it is a delta, not a state: a frame
+     * that forgets to read it must not lose the movement, and a frame that reads
+     * it twice must not apply it twice. Pass straight to `LoadedScene3D.orbit`.
+     */
+    look() {
+        const out = { x: this.lookDelta.x, y: this.lookDelta.y };
+        this.lookDelta.x = 0;
+        this.lookDelta.y = 0;
+        return out;
+    }
     /** True exactly once per press: one tap is one swing.
      *
      *  Edge detection done in the game reads the button's STATE and compares it
@@ -159,6 +197,58 @@ export class Input3D {
         this.root = null;
         this.keysDown.clear();
     }
+    /**
+     * Desktop: hold the RIGHT mouse button and drag to turn the camera.
+     *
+     * The on-screen look zone only exists where the touch controls do, so
+     * without this a mouse-and-keyboard player has a camera they cannot turn at
+     * all — and now that movement is camera-relative, a camera you cannot turn
+     * is one that has permanently decided which way "forward" is.
+     *
+     * The right button rather than the left: a left-drag is how a game selects,
+     * clicks and aims, and taking that away from every game by default would be
+     * a worse trade than the one it fixes. Right-drag is also what Roblox uses
+     * on desktop, so it is already in players' hands.
+     */
+    mountMouseLook(doc) {
+        let id = null;
+        let lastX = 0, lastY = 0;
+        const down = (e) => {
+            if (e.button !== 2 || e.pointerType === 'touch' || id !== null)
+                return;
+            id = e.pointerId;
+            lastX = e.clientX;
+            lastY = e.clientY;
+            e.preventDefault();
+        };
+        const move = (e) => {
+            if (e.pointerId !== id)
+                return;
+            // Radians per screen WIDTH, the same unit the touch zone uses, so one
+            // sensitivity number means the same thing on both.
+            const w = Math.max(1, doc.defaultView?.innerWidth ?? 1000);
+            this.lookDelta.x += ((e.clientX - lastX) / w) * this.lookSens;
+            this.lookDelta.y += ((e.clientY - lastY) / w) * this.lookSens;
+            lastX = e.clientX;
+            lastY = e.clientY;
+        };
+        const up = (e) => { if (e.pointerId === id)
+            id = null; };
+        const menu = (e) => { e.preventDefault(); };
+        doc.addEventListener('pointerdown', down);
+        doc.addEventListener('pointermove', move);
+        doc.addEventListener('pointerup', up);
+        doc.addEventListener('pointercancel', up);
+        // Otherwise every right-drag ends with a context menu over the game.
+        doc.addEventListener('contextmenu', menu);
+        this.cleanups.push(() => {
+            doc.removeEventListener('pointerdown', down);
+            doc.removeEventListener('pointermove', move);
+            doc.removeEventListener('pointerup', up);
+            doc.removeEventListener('pointercancel', up);
+            doc.removeEventListener('contextmenu', menu);
+        });
+    }
     // ── on-screen controls ────────────────────────────────────────────────────
     mountTouch(container) {
         const root = document.createElement('div');
@@ -183,6 +273,15 @@ export class Input3D {
             pointerEvents: floating ? 'auto' : 'none',
         });
         Object.assign(zone.style, NO_SELECTION);
+        // The other half. Buttons are appended AFTER this and sit above it, so a
+        // tap on jump or attack never reaches the look zone -- which is why this
+        // can be the whole right half rather than an awkward cut-out around them.
+        const lookZone = document.createElement('div');
+        Object.assign(lookZone.style, {
+            position: 'absolute', right: '0', top: '0', width: '50%', height: '100%',
+            pointerEvents: this.wantLook ? 'auto' : 'none',
+        });
+        Object.assign(lookZone.style, NO_SELECTION);
         const pad = document.createElement('div');
         Object.assign(pad.style, floating ? {
             position: 'absolute', width: '30vmin', height: '30vmin',
@@ -244,7 +343,7 @@ export class Input3D {
             cluster.append(el);
             this.wireButton(el, a.id);
         }
-        root.append(zone, pad, cluster);
+        root.append(zone, lookZone, pad, cluster);
         container.appendChild(root);
         this.root = root;
         // And the page underneath. The overlay covers the controls, but a press
@@ -346,6 +445,35 @@ export class Input3D {
         });
         on(grip, 'pointermove', (e) => { if (e.pointerId === stickId)
             setFromEvent(e); });
+        // Looking. A separate pointer id from the stick's, so a thumb on each side
+        // works — which is the entire point of splitting the screen in two.
+        let lookId = null;
+        let lastX = 0, lastY = 0;
+        on(lookZone, 'pointerdown', (e) => {
+            e.preventDefault();
+            if (lookId !== null)
+                return;
+            lookId = e.pointerId;
+            lookZone.setPointerCapture(e.pointerId);
+            lastX = e.clientX;
+            lastY = e.clientY;
+        });
+        on(lookZone, 'pointermove', (e) => {
+            if (e.pointerId !== lookId)
+                return;
+            // Scaled by screen WIDTH in both axes, so a drag of the same physical
+            // length turns the same amount whichever way it went. Dividing y by
+            // height instead makes vertical look wildly faster in landscape.
+            const w = Math.max(1, lookZone.getBoundingClientRect().width * 2);
+            this.lookDelta.x += ((e.clientX - lastX) / w) * this.lookSens;
+            this.lookDelta.y += ((e.clientY - lastY) / w) * this.lookSens;
+            lastX = e.clientX;
+            lastY = e.clientY;
+        });
+        for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
+            on(lookZone, ev, (e) => { if (e.pointerId === lookId)
+                lookId = null; });
+        }
         // pointercancel too: a system gesture steals the pointer without an up, and
         // the character would walk forever.
         for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {

package/dist/SceneLoader3D.d.ts

@@ -33,6 +33,15 @@ export interface LoadedScene3D {
     /** Entity id → rigid body, when physics was supplied. */
     bodies: Map<string, any>;
     world?: any;
+    /** Where the follow camera is looking from, in radians. Feed it to
+     *  `Input3D.direction(yaw)` — once the camera can turn, movement that ignores
+     *  it walks north no matter which way the player is facing, which is the
+     *  single most disorienting thing a 3D game can do. */
+    readonly cameraYaw: number;
+    readonly cameraPitch: number;
+    /** Turn the follow camera. Deltas in radians; pitch is clamped so it cannot
+     *  swing under the floor or flip over the top. No-op without a follow target. */
+    orbit(dYaw: number, dPitch: number): void;
     /** Advance animation + physics. Call once per frame with seconds. */
     update(dt: number): void;
     dispose(): void;

package/dist/SceneLoader3D.js

@@ -214,10 +214,36 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     const camera = new THREE.PerspectiveCamera(scene3d.camera?.fov ?? 55, 1, 0.1, 500);
     const camOffset = toVec(scene3d.camera?.offset ?? { x: 0, y: 4, z: 8 });
     camera.position.copy(camOffset);
+    // The follow camera orbits. The authored offset is not replaced by this --
+    // it is READ as the starting angle and distance, so a scene that never calls
+    // `orbit` looks exactly as it was laid out.
+    const camRadius = camOffset.length() || 1;
+    let camYaw = Math.atan2(camOffset.x, camOffset.z);
+    let camPitch = Math.asin(Math.max(-1, Math.min(1, camOffset.y / camRadius)));
+    // Clamped so the camera cannot swing under the floor or flip over the top --
+    // both of which leave the player looking at the underside of the world with
+    // no way to explain what happened.
+    //
+    // The LOW limit is a HEIGHT, not an angle, and that distinction is the whole
+    // of it: a fixed -0.25rad floor put a camera orbiting at radius 5.4 nearly a
+    // unit UNDERGROUND, because how low an angle puts you depends on how far out
+    // you are. Expressed as "stay at least this far above what you are looking
+    // at", it holds for any scene's camera distance.
+    const MIN_RISE = 0.3;
+    const PITCH_MIN = Math.asin(Math.min(0.9, MIN_RISE / camRadius));
+    const PITCH_MAX = 1.25;
+    camPitch = Math.max(PITCH_MIN, Math.min(PITCH_MAX, camPitch));
     const followTarget = scene3d.camera?.kind === 'follow' && scene3d.camera.target
         ? entities.get(scene3d.camera.target) : undefined;
+    const want = new THREE.Vector3();
     return {
         scene, camera, entities, mixers, mixerFor, clips, bodies, world,
+        get cameraYaw() { return camYaw; },
+        get cameraPitch() { return camPitch; },
+        orbit(dYaw, dPitch) {
+            camYaw -= dYaw;
+            camPitch = Math.max(PITCH_MIN, Math.min(PITCH_MAX, camPitch + dPitch));
+        },
         update(dt) {
             for (const m of mixers)
                 m.update(dt);
@@ -237,7 +263,8 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
                 }
             }
             if (followTarget) {
-                const want = followTarget.position.clone().add(camOffset);
+                const cp = Math.cos(camPitch);
+                want.set(followTarget.position.x + camRadius * cp * Math.sin(camYaw), followTarget.position.y + camRadius * Math.sin(camPitch), followTarget.position.z + camRadius * cp * Math.cos(camYaw));
                 camera.position.lerp(want, Math.min(1, dt * 6));
                 camera.lookAt(followTarget.position.x, followTarget.position.y + 1, followTarget.position.z);
             }

package/package.json

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