npm - @umicat/three-sdk - Versions diffs - 0.1.0 → 0.3.0 - Mend

@umicat/three-sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +54 -0
package/dist/CharacterAnimator.d.ts +58 -0
package/dist/CharacterAnimator.js +103 -0
package/dist/CharacterController3D.d.ts +46 -1
package/dist/CharacterController3D.js +60 -2
package/dist/Input3D.d.ts +38 -5
package/dist/Input3D.js +134 -12
package/dist/index.d.ts +4 -1
package/dist/index.js +1 -0
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -96,6 +96,60 @@ One real bug was fixed while chasing it and is unrelated but worth having: a
 bones, so three.js culls a character against a stale volume once it moves.
 `loadScene3D` sets `frustumCulled = false` on skinned meshes.
+## 0.3.0 — actions, not just locomotion
+`CharacterAnimator` owns the two things every game was writing by hand, and
+both are character behaviour rather than game logic (ADR-034).
+**Locomotion follows `character.state`**, not the keys held — a clip chosen
+from input leaves a character walking in mid-air.
+**An action is a one-shot that interrupts and returns.** Attacking is not a
+state you enter, it is a thing that happens: `play('attack')` runs the clip
+once, holds its last frame rather than snapping to the bind pose in the gap,
+and hands control back. `busy` is there so a game can refuse a second swing
+from one press — firing twice is the usual reason an attack feels broken.
+Changing locomotion mid-action does **not** blend a walk cycle into the middle
+of a sword swing: the new locomotion clip is swapped in underneath at zero
+weight and faded up only when the action releases.
+Names resolve through the manifest's map first (`attack` -> `attack-melee-right`)
+and then by raw clip name, so a game can reach a clip nobody mapped.
+## 0.2.0 — the character's jump and controls belong to the platform
+ADR-034 makes the platform the owner of the character, so two things that used
+to be each game's problem moved in here.
+**Jump** (`jumpSpeed`, `coyoteTime`, `jumpBuffer`, `jumpCut`). 0.1.0 left jump
+to the game on the grounds that how it feels is a design decision. That is true
+right up until every game shares one character — then a badly-tuned jump is
+badly tuned everywhere. `update(dt, dir, { jump })` takes the button's CURRENT
+state and the controller owns the timing: coyote time so a press a few frames
+late still counts, buffering so a press slightly early is not lost, and a cut on
+release so a tap hops and a hold arcs.
+The cut applies **once, on release**. Applying it every airborne frame compounds
+(×0.45, ×0.2, ×0.09…) and swallows the jump entirely — caught by the
+release-before-landing test, not by reading the code.
+**`state`** (`idle` | `walk` | `jump` | `fall`) so animation follows what the
+character is DOING rather than what was pressed; deriving it from input leaves a
+character walking in mid-air. **`teleport()`** is the respawn primitive, and it
+clears vertical velocity — without that, a character rescued from a long drop
+arrives still travelling at the speed it fell.
+**Touch** (`Input3D({ touch })`, on by default for coarse-pointer devices). An
+on-screen thumbstick and jump button, merged into the same `direction()` and
+`jump` a keyboard feeds, so no game branches on input source. Before this, 3D
+was simply unplayable on a phone.
+The controls mount to `<body>`, **not** the game's `#hud`: a game that writes
+`hud.textContent = '...'` wipes every child, and the controls vanish with no
+error at all. That happened. The HUD belongs to the game; this layer belongs to
+the platform.
 ## What is deliberately missing
 No character controller (Rapier's `KinematicCharacterController` is the intended

package/dist/CharacterAnimator.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+import type { CharacterState } from './CharacterController3D.js';
+/** Semantic name -> the clip actually inside the model, as authored in the
+ *  manifest. Never guess a clip name: this character calls its run `sprint`. */
+export type ClipMap = Record<string, string>;
+export interface CharacterAnimatorOptions {
+    /** Cross-fade between locomotion clips, seconds. */
+    blend?: number;
+    /** Cross-fade in and out of a one-shot action, seconds. */
+    actionBlend?: number;
+}
+/**
+ * Locomotion plus one-shot actions, for a character whose clips all sit on one
+ * rig.
+ *
+ * Two things were being written by hand in every game, and both are character
+ * behaviour rather than game logic (ADR-034), so they live here.
+ *
+ * **Locomotion follows the CONTROLLER's state, not the keys held.** A clip
+ * chosen from input leaves a character walking in mid-air.
+ *
+ * **An action is a one-shot that interrupts and returns.** Attacking is not a
+ * state you enter, it is a thing that happens: it plays once, holds its last
+ * frame rather than snapping, and hands control back. Without that, a game
+ * either cannot attack at all or leaves the character stuck mid-swing.
+ */
+export declare class CharacterAnimator {
+    private readonly mixer;
+    private readonly map;
+    private readonly actions;
+    private locomotion;
+    private locomotionName;
+    private oneShot;
+    private oneShotName;
+    private readonly blend;
+    private readonly actionBlend;
+    private readonly onFinished;
+    constructor(mixer: THREE.AnimationMixer, clips: THREE.AnimationClip[], map?: ClipMap, options?: CharacterAnimatorOptions);
+    /** Is a one-shot still playing? Games gate input on this — swinging twice
+     *  from one press is the usual reason an attack feels broken. */
+    get busy(): boolean;
+    /** Which one-shot, if any. */
+    get action(): string;
+    /** Look a semantic name up through the manifest's map, then by raw clip name
+     *  so a game can reach a clip the manifest never mapped. */
+    private find;
+    has(name: string): boolean;
+    /** Drive locomotion. Pass `character.state` every frame. */
+    update(state: CharacterState | string): void;
+    /**
+     * Play a one-shot. Returns false if there is no such clip, or if one is
+     * already running and `interrupt` was not asked for.
+     */
+    play(name: string, opts?: {
+        interrupt?: boolean;
+    }): boolean;
+    dispose(): void;
+}

package/dist/CharacterAnimator.js ADDED Viewed

@@ -0,0 +1,103 @@
+import * as THREE from 'three';
+/**
+ * Locomotion plus one-shot actions, for a character whose clips all sit on one
+ * rig.
+ *
+ * Two things were being written by hand in every game, and both are character
+ * behaviour rather than game logic (ADR-034), so they live here.
+ *
+ * **Locomotion follows the CONTROLLER's state, not the keys held.** A clip
+ * chosen from input leaves a character walking in mid-air.
+ *
+ * **An action is a one-shot that interrupts and returns.** Attacking is not a
+ * state you enter, it is a thing that happens: it plays once, holds its last
+ * frame rather than snapping, and hands control back. Without that, a game
+ * either cannot attack at all or leaves the character stuck mid-swing.
+ */
+export class CharacterAnimator {
+    constructor(mixer, clips, map = {}, options = {}) {
+        this.mixer = mixer;
+        this.map = map;
+        this.actions = new Map();
+        this.locomotion = null;
+        this.locomotionName = '';
+        this.oneShot = null;
+        this.oneShotName = '';
+        this.blend = options.blend ?? 0.15;
+        this.actionBlend = options.actionBlend ?? 0.08;
+        for (const clip of clips)
+            this.actions.set(clip.name, mixer.clipAction(clip));
+        this.onFinished = (e) => {
+            if (this.oneShot && e.action === this.oneShot) {
+                this.oneShot.fadeOut(this.actionBlend);
+                this.oneShot = null;
+                this.oneShotName = '';
+                // Bring locomotion back explicitly — it was faded down, not stopped,
+                // so it is still running underneath at weight ~0.
+                this.locomotion?.reset().fadeIn(this.actionBlend).play();
+            }
+        };
+        mixer.addEventListener('finished', this.onFinished);
+    }
+    /** Is a one-shot still playing? Games gate input on this — swinging twice
+     *  from one press is the usual reason an attack feels broken. */
+    get busy() { return this.oneShot !== null; }
+    /** Which one-shot, if any. */
+    get action() { return this.oneShotName; }
+    /** Look a semantic name up through the manifest's map, then by raw clip name
+     *  so a game can reach a clip the manifest never mapped. */
+    find(name) {
+        return this.actions.get(this.map[name] ?? name) ?? this.actions.get(name) ?? null;
+    }
+    has(name) { return this.find(name) !== null; }
+    /** Drive locomotion. Pass `character.state` every frame. */
+    update(state) {
+        if (state === this.locomotionName)
+            return;
+        const next = this.find(state) ?? this.find('idle');
+        if (!next)
+            return;
+        this.locomotionName = state;
+        if (next === this.locomotion)
+            return;
+        next.reset().setLoop(THREE.LoopRepeat, Infinity).setEffectiveWeight(1);
+        // Under a one-shot, swap the underlying clip silently — fading it in here
+        // would blend a walk cycle into the middle of a sword swing.
+        if (this.busy) {
+            next.play().setEffectiveWeight(0);
+        }
+        else {
+            next.fadeIn(this.blend).play();
+            this.locomotion?.fadeOut(this.blend);
+        }
+        this.locomotion = next;
+    }
+    /**
+     * Play a one-shot. Returns false if there is no such clip, or if one is
+     * already running and `interrupt` was not asked for.
+     */
+    play(name, opts = {}) {
+        const next = this.find(name);
+        if (!next)
+            return false;
+        if (this.busy && !opts.interrupt)
+            return false;
+        if (this.oneShot && this.oneShot !== next)
+            this.oneShot.fadeOut(this.actionBlend);
+        this.locomotion?.fadeOut(this.actionBlend);
+        next.reset()
+            .setLoop(THREE.LoopOnce, 1)
+            .setEffectiveWeight(1)
+            .fadeIn(this.actionBlend)
+            .play();
+        // Hold the last frame instead of snapping back to the bind pose in the
+        // gap before locomotion fades in.
+        next.clampWhenFinished = true;
+        this.oneShot = next;
+        this.oneShotName = name;
+        return true;
+    }
+    dispose() {
+        this.mixer.removeEventListener('finished', this.onFinished);
+    }
+}

package/dist/CharacterController3D.d.ts CHANGED Viewed

@@ -21,6 +21,32 @@ export interface CharacterOptions {
         y: number;
         z: number;
     };
+    /** Upward speed at the moment of a jump. 0 disables jumping entirely. */
+    jumpSpeed?: number;
+    /**
+     * How long after walking off an edge a jump still counts, in seconds.
+     * Without it, players who press jump a frame or two late — which is most
+     * players, most of the time — simply fall, and the game feels like it
+     * ignored them. Named for the cartoon coyote.
+     */
+    coyoteTime?: number;
+    /**
+     * How long before landing a jump press is remembered, in seconds. The other
+     * half of the same problem: pressing slightly EARLY should also work.
+     */
+    jumpBuffer?: number;
+    /**
+     * Releasing the button early cuts upward speed by this factor, giving a
+     * short hop for a tap and a full arc for a hold. 1 disables it.
+     */
+    jumpCut?: number;
+}
+/** What the character is doing, for animation. */
+export type CharacterState = 'idle' | 'walk' | 'jump' | 'fall';
+/** Per-frame input. `jump` is the button's CURRENT state, not an event —
+ *  edge detection, coyote time and buffering all live in the controller. */
+export interface CharacterInput {
+    jump?: boolean;
 }
 /**
  * A kinematic character: walks, collides with walls, climbs steps, falls.
@@ -44,8 +70,27 @@ export declare class CharacterController3D {
     private readonly controller;
     private verticalVelocity;
     private readonly opts;
+    private coyoteLeft;
+    private bufferLeft;
+    private jumpWasHeld;
+    private jumping;
+    private jumpCutApplied;
+    private _state;
     constructor(world: any, RAPIER: RapierRuntime, options?: CharacterOptions);
     get grounded(): boolean;
+    /** What the character is doing — map this to a clip rather than deriving it
+     *  from input, or a character keeps walking in mid-air. */
+    get state(): CharacterState;
+    /** Rising under its own power, as opposed to merely off the ground. */
+    get airborne(): boolean;
+    /** Put the character somewhere, cancelling any fall. The respawn primitive:
+     *  without clearing the velocity, a character teleported out of a long drop
+     *  arrives still travelling at the speed it fell. */
+    teleport(p: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
     get position(): {
         x: number;
         y: number;
@@ -59,7 +104,7 @@ export declare class CharacterController3D {
     update(dt: number, dir: {
         x: number;
         z: number;
-    }): void;
+    }, input?: CharacterInput): void;
     /** Copy the simulated position onto the rendered object. */
     syncTo(object: THREE.Object3D, yOffset?: number): void;
     /** Face the direction of travel; ignores tiny inputs so idle doesn't spin. */

package/dist/CharacterController3D.js CHANGED Viewed

@@ -17,6 +17,12 @@ export class CharacterController3D {
     constructor(world, RAPIER, options = {}) {
         this.world = world;
         this.verticalVelocity = 0;
+        this.coyoteLeft = 0;
+        this.bufferLeft = 0;
+        this.jumpWasHeld = false;
+        this.jumping = false;
+        this.jumpCutApplied = false;
+        this._state = 'idle';
         this.opts = {
             halfHeight: options.halfHeight ?? 0.5,
             radius: options.radius ?? 0.35,
@@ -24,6 +30,10 @@ export class CharacterController3D {
             stepHeight: options.stepHeight ?? 0.4,
             maxSlopeDegrees: options.maxSlopeDegrees ?? 50,
             gravity: options.gravity ?? 9.81,
+            jumpSpeed: options.jumpSpeed ?? 0,
+            coyoteTime: options.coyoteTime ?? 0.12,
+            jumpBuffer: options.jumpBuffer ?? 0.12,
+            jumpCut: options.jumpCut ?? 0.45,
         };
         const p = options.position ?? { x: 0, y: 2, z: 0 };
         this.body = world.createRigidBody(RAPIER.RigidBodyDesc.kinematicPositionBased().setTranslation(p.x, p.y, p.z));
@@ -38,30 +48,78 @@ export class CharacterController3D {
         this.controller.setApplyImpulsesToDynamicBodies(true);
     }
     get grounded() { return this.controller.computedGrounded(); }
+    /** What the character is doing — map this to a clip rather than deriving it
+     *  from input, or a character keeps walking in mid-air. */
+    get state() { return this._state; }
+    /** Rising under its own power, as opposed to merely off the ground. */
+    get airborne() { return !this.grounded; }
+    /** Put the character somewhere, cancelling any fall. The respawn primitive:
+     *  without clearing the velocity, a character teleported out of a long drop
+     *  arrives still travelling at the speed it fell. */
+    teleport(p) {
+        this.body.setTranslation(p, true);
+        this.verticalVelocity = 0;
+        this.jumping = false;
+        this.jumpCutApplied = false;
+        this.coyoteLeft = 0;
+        this.bufferLeft = 0;
+    }
     get position() { return this.body.translation(); }
     /**
      * Move for one step. `dir` is a desired direction in world space (y ignored);
      * it is normalised here so diagonals aren't faster than cardinals — a bug old
      * enough to have a name.
      */
-    update(dt, dir) {
+    update(dt, dir, input = {}) {
         const len = Math.hypot(dir.x, dir.z);
         const nx = len > 0 ? (dir.x / len) * this.opts.speed * dt : 0;
         const nz = len > 0 ? (dir.z / len) * this.opts.speed * dt : 0;
-        if (this.grounded) {
+        const grounded = this.grounded;
+        const jumpHeld = input.jump === true;
+        const jumpPressed = jumpHeld && !this.jumpWasHeld;
+        this.jumpWasHeld = jumpHeld;
+        // Both timers count DOWN in real time, so they behave the same at 30fps and
+        // 144fps. A window measured in frames is a window that changes size with
+        // the machine.
+        this.coyoteLeft = grounded ? this.opts.coyoteTime : Math.max(0, this.coyoteLeft - dt);
+        this.bufferLeft = jumpPressed ? this.opts.jumpBuffer : Math.max(0, this.bufferLeft - dt);
+        if (grounded) {
             // Small constant bias, not accumulated gravity: enough for snap-to-ground
             // to hold contact over stairs and slopes without pinning the character.
             this.verticalVelocity = -this.opts.gravity * dt;
+            this.jumping = false;
         }
         else {
             this.verticalVelocity -= this.opts.gravity * dt;
         }
+        if (this.opts.jumpSpeed > 0 && this.bufferLeft > 0 && this.coyoteLeft > 0 && !this.jumping) {
+            this.verticalVelocity = this.opts.jumpSpeed;
+            this.jumping = true;
+            this.jumpCutApplied = false;
+            // Spend both windows, or one press keeps re-triggering all the way up.
+            this.bufferLeft = 0;
+            this.coyoteLeft = 0;
+        }
+        // Variable height: let go early and the rise is cut short. Applied ONCE,
+        // on the release, not every frame — multiplying each frame while the button
+        // is up compounds (x0.45, x0.2, x0.09...) and swallows the jump entirely,
+        // which is exactly what the release-before-landing test caught.
+        if (this.jumping && !jumpHeld && !this.jumpCutApplied && this.verticalVelocity > 0) {
+            this.verticalVelocity *= this.opts.jumpCut;
+            this.jumpCutApplied = true;
+        }
         this.controller.computeColliderMovement(this.collider, {
             x: nx, y: this.verticalVelocity * dt, z: nz,
         });
         const move = this.controller.computedMovement();
         const t = this.body.translation();
         this.body.setNextKinematicTranslation({ x: t.x + move.x, y: t.y + move.y, z: t.z + move.z });
+        // State is read AFTER the move so a landing this frame reads as landed.
+        // Note `grounded` above is the PRE-move value — the two differ exactly on
+        // the frames that matter for animation.
+        this._state = this.grounded
+            ? (len > 0 ? 'walk' : 'idle')
+            : (this.verticalVelocity > 0 ? 'jump' : 'fall');
     }
     /** Copy the simulated position onto the rendered object. */
     syncTo(object, yOffset = 0) {

package/dist/Input3D.d.ts CHANGED Viewed

@@ -1,26 +1,59 @@
+export interface Input3DOptions {
+    /** Where key events are read from. */
+    target?: Window;
+    /**
+     * On-screen thumbstick + jump button. `'auto'` (the default) adds them when
+     * the device reports coarse pointers and no fine one — i.e. a phone, not a
+     * laptop with a touchscreen.
+     */
+    touch?: boolean | 'auto';
+    /**
+     * Where the controls are mounted. Defaults to `<body>` — deliberately NOT
+     * the game's `#hud`: a game that writes `hud.textContent = '...'` wipes every
+     * child, and the controls vanish with no error. The HUD belongs to the game;
+     * this layer belongs to the platform.
+     */
+    container?: HTMLElement | null;
+}
 /**
- * Keyboard movement, in the smallest form that is still correct.
+ * Movement and jump, from a keyboard or a thumb, behind one interface.
  *
- * Reads key STATE rather than key events, because an event-driven controller
+ * Reads input STATE rather than events, because an event-driven controller
  * drops input whenever a frame lands between keydown and the read, and holds a
  * direction forever if the keyup is lost (alt-tab is the classic way to lose
  * one). `dispose()` matters: a listener left on window outlives the scene.
+ *
+ * **Why touch is here and not in each game.** `Input3D` used to be keyboard
+ * only, so every 3D game had to build its own thumbstick — which meant none of
+ * them did, which meant 3D was unplayable on a phone. Under ADR-034 the
+ * platform owns the character, so it owns the controls too: built once,
+ * correct everywhere, and `direction()` reads the same either way so no game
+ * has to branch on input source.
  */
 export declare class Input3D {
-    private readonly target;
     private readonly held;
+    private readonly target;
     private readonly onDown;
     private readonly onUp;
     private readonly onBlur;
-    constructor(target?: Window);
+    private readonly stick;
+    private touchJump;
+    private root;
+    private readonly cleanups;
+    constructor(options?: Input3DOptions | Window);
     isDown(...codes: string[]): boolean;
-    /** Camera-relative would need the camera; this is world-axis movement. */
+    /** 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(): {
         x: number;
         z: number;
     };
+    /** Whether the jump control is held right now. Pass it to the controller —
+     *  coyote time and buffering live there, not here. */
+    get jump(): boolean;
     /** Test seam: drive the controller without synthesising DOM events. */
     press(code: string): void;
     release(code: string): void;
     dispose(): void;
+    private mountTouch;
 }

package/dist/Input3D.js CHANGED Viewed

@@ -1,27 +1,55 @@
+const isTouchDevice = () => typeof matchMedia === 'function' &&
+    matchMedia('(pointer: coarse)').matches &&
+    !matchMedia('(pointer: fine)').matches;
 /**
- * Keyboard movement, in the smallest form that is still correct.
+ * Movement and jump, from a keyboard or a thumb, behind one interface.
  *
- * Reads key STATE rather than key events, because an event-driven controller
+ * Reads input STATE rather than events, because an event-driven controller
  * drops input whenever a frame lands between keydown and the read, and holds a
  * direction forever if the keyup is lost (alt-tab is the classic way to lose
  * one). `dispose()` matters: a listener left on window outlives the scene.
+ *
+ * **Why touch is here and not in each game.** `Input3D` used to be keyboard
+ * only, so every 3D game had to build its own thumbstick — which meant none of
+ * them did, which meant 3D was unplayable on a phone. Under ADR-034 the
+ * platform owns the character, so it owns the controls too: built once,
+ * correct everywhere, and `direction()` reads the same either way so no game
+ * has to branch on input source.
  */
 export class Input3D {
-    constructor(target = window) {
-        this.target = target;
+    constructor(options = {}) {
         this.held = new Set();
-        this.onDown = (e) => { this.held.add(e.code); };
+        this.onDown = (e) => {
+            this.held.add(e.code);
+            // 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(); };
-        target.addEventListener('keydown', this.onDown);
-        target.addEventListener('keyup', this.onUp);
+        this.onBlur = () => { this.held.clear(); this.stick.x = 0; this.stick.z = 0; this.touchJump = false; };
+        this.stick = { x: 0, z: 0 };
+        this.touchJump = false;
+        this.root = null;
+        this.cleanups = [];
+        // A Window here is the pre-touch signature; keep it working.
+        const opts = (typeof Window !== 'undefined' && options instanceof Window)
+            ? { target: options } : options;
+        this.target = opts.target ?? window;
+        this.target.addEventListener('keydown', this.onDown);
+        this.target.addEventListener('keyup', this.onUp);
         // Losing focus mid-press would otherwise leave the character walking.
-        target.addEventListener('blur', this.onBlur);
+        this.target.addEventListener('blur', this.onBlur);
+        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)); }
-    /** Camera-relative would need the camera; this is world-axis movement. */
+    /** 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() {
-        let x = 0, z = 0;
+        let x = this.stick.x, z = this.stick.z;
         if (this.isDown('KeyW', 'ArrowUp'))
             z -= 1;
         if (this.isDown('KeyS', 'ArrowDown'))
@@ -30,8 +58,13 @@ export class Input3D {
             x -= 1;
         if (this.isDown('KeyD', 'ArrowRight'))
             x += 1;
-        return { x, z };
+        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 };
     }
+    /** 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'); }
     /** Test seam: drive the controller without synthesising DOM events. */
     press(code) { this.held.add(code); }
     release(code) { this.held.delete(code); }
@@ -39,6 +72,95 @@ export class Input3D {
         this.target.removeEventListener('keydown', this.onDown);
         this.target.removeEventListener('keyup', this.onUp);
         this.target.removeEventListener('blur', this.onBlur);
+        for (const c of this.cleanups)
+            c();
+        this.cleanups.length = 0;
+        this.root?.remove();
+        this.root = null;
         this.held.clear();
     }
+    // ── on-screen controls ────────────────────────────────────────────────────
+    mountTouch(container) {
+        const root = document.createElement('div');
+        root.dataset.umicatTouch = '';
+        // pointer-events:none on the layer, auto on the controls — otherwise the
+        // overlay eats every tap meant for the world.
+        Object.assign(root.style, {
+            // fixed, not absolute: on <body> an absolute layer depends on whether
+            // 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',
+        });
+        const pad = document.createElement('div');
+        Object.assign(pad.style, {
+            position: 'absolute', left: '5vmin', bottom: '5vmin',
+            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)', pointerEvents: 'auto',
+        });
+        const knob = document.createElement('div');
+        Object.assign(knob.style, {
+            position: 'absolute', left: '50%', top: '50%', width: '40%', height: '40%',
+            borderRadius: '50%', background: 'rgba(255,255,255,0.55)',
+            transform: 'translate(-50%, -50%)', pointerEvents: 'none',
+        });
+        pad.appendChild(knob);
+        const btn = document.createElement('div');
+        Object.assign(btn.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',
+        });
+        btn.textContent = '▲';
+        root.append(pad, btn);
+        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) => {
+            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;
+            const len = Math.hypot(dx, dy);
+            if (len > 1) {
+                dx /= len;
+                dy /= len;
+            }
+            this.stick.x = dx;
+            this.stick.z = dy; // screen-down is +z, matching KeyS
+            knob.style.left = `${50 + dx * 30}%`;
+            knob.style.top = `${50 + dy * 30}%`;
+        };
+        const reset = () => {
+            stickId = null;
+            this.stick.x = 0;
+            this.stick.z = 0;
+            knob.style.left = '50%';
+            knob.style.top = '50%';
+        };
+        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)
+            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)
+                reset(); });
+        }
+        on(btn, 'pointerdown', (e) => { btn.setPointerCapture(e.pointerId); this.touchJump = true; });
+        for (const ev of ['pointerup', 'pointercancel', 'lostpointercapture']) {
+            on(btn, ev, () => { this.touchJump = false; });
+        }
+    }
 }

package/dist/index.d.ts CHANGED Viewed

@@ -3,8 +3,11 @@ export type { UmicatInitOptions } from './ThreeUmicat.js';
 export * from './scene3d.js';
 export { loadScene3D } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
-export type { CharacterOptions } 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 { 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 CHANGED Viewed

@@ -7,6 +7,7 @@ export { ThreeUmicat } from './ThreeUmicat.js';
 export * from './scene3d.js';
 export { loadScene3D } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
+export { CharacterAnimator } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -33,4 +33,4 @@
     "dist",
     "README.md"
   ]
-}
+}