@umicat/three-sdk 0.2.0 → 0.4.0

package/README.md

@@ -96,6 +96,27 @@ 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

package/dist/CharacterAnimator.d.ts

@@ -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

@@ -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

@@ -14,6 +14,9 @@ export interface CharacterOptions {
     stepHeight?: number;
     /** Steeper than this and they slide instead of climbing. Degrees. */
     maxSlopeDegrees?: number;
+    /** Fall acceleration, in world units. Defaults to the world's own gravity;
+     *  set it only to make this character deliberately heavier or floatier than
+     *  its surroundings. */
     gravity?: number;
     /** Start position. */
     position?: {
@@ -83,6 +86,21 @@ export declare class CharacterController3D {
     get state(): CharacterState;
     /** Rising under its own power, as opposed to merely off the ground. */
     get airborne(): boolean;
+    /** How high a HELD jump rises, in world units.
+     *
+     *  Level geometry is authored against these two numbers, so they are exposed
+     *  rather than left to be re-derived. Getting the algebra wrong is not
+     *  hypothetical: a course laid out against a mis-computed apex produced a
+     *  first step the character could not clear, which reads to a player as
+     *  "that platform is unreachable" rather than as a bug. */
+    get maxJumpRise(): number;
+    /** How high a TAPPED jump rises — the button released as early as the
+     *  variable-height cut can see it.
+     *
+     *  **Author rises against this one, not `maxJumpRise`.** A jump is a range,
+     *  not a number: releasing early cuts it deliberately, so a gap only the
+     *  held jump clears is a gap half your players will believe is closed. */
+    get minJumpRise(): number;
     /** 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. */

package/dist/CharacterController3D.js

@@ -29,7 +29,14 @@ export class CharacterController3D {
             speed: options.speed ?? 4,
             stepHeight: options.stepHeight ?? 0.4,
             maxSlopeDegrees: options.maxSlopeDegrees ?? 50,
-            gravity: options.gravity ?? 9.81,
+            // Default to the WORLD's gravity, not to Earth's. A kinematic character
+            // integrates its own fall, so a hard-coded 9.81 put a second gravity in
+            // the scene: in a world authored in Kenney's unit (gravity -4.17) the
+            // character fell 2.35x faster than everything around it, and every jump
+            // came out less than half the height the docs promised. One world, one
+            // gravity — pass the option only to give this character a deliberately
+            // different feel.
+            gravity: options.gravity ?? (Math.abs(world.gravity.y) || 9.81),
             jumpSpeed: options.jumpSpeed ?? 0,
             coyoteTime: options.coyoteTime ?? 0.12,
             jumpBuffer: options.jumpBuffer ?? 0.12,
@@ -53,6 +60,30 @@ export class CharacterController3D {
     get state() { return this._state; }
     /** Rising under its own power, as opposed to merely off the ground. */
     get airborne() { return !this.grounded; }
+    /** How high a HELD jump rises, in world units.
+     *
+     *  Level geometry is authored against these two numbers, so they are exposed
+     *  rather than left to be re-derived. Getting the algebra wrong is not
+     *  hypothetical: a course laid out against a mis-computed apex produced a
+     *  first step the character could not clear, which reads to a player as
+     *  "that platform is unreachable" rather than as a bug. */
+    get maxJumpRise() {
+        if (this.opts.jumpSpeed <= 0)
+            return 0;
+        return (this.opts.jumpSpeed * this.opts.jumpSpeed) / (2 * this.opts.gravity);
+    }
+    /** How high a TAPPED jump rises — the button released as early as the
+     *  variable-height cut can see it.
+     *
+     *  **Author rises against this one, not `maxJumpRise`.** A jump is a range,
+     *  not a number: releasing early cuts it deliberately, so a gap only the
+     *  held jump clears is a gap half your players will believe is closed. */
+    get minJumpRise() {
+        if (this.opts.jumpSpeed <= 0)
+            return 0;
+        const cut = this.opts.jumpSpeed * this.opts.jumpCut;
+        return (cut * cut) / (2 * this.opts.gravity);
+    }
     /** 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. */

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './scene3d.js';
 export { loadScene3D } 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 { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';

package/dist/index.js

@@ -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

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