@viggle/splat-engine-three 0.0.0-stage → 0.1.0

package/dist/types/armature.d.ts

@@ -0,0 +1,524 @@
+import { Group } from 'three';
+import { Mat4, Quat, Vec3 } from './math';
+import type { SplatEngine } from './engine';
+import type { AnimEventCallback } from './skeletal/animation-player';
+import type { BoneMask } from './skeletal/bone-mask';
+import type { BoneScaleInput } from './skeletal/bone-stretch';
+import { Pose } from './skeletal/pose';
+import { Skeleton } from './skeletal/skeleton';
+import type { Splat } from './splat/splat';
+import type { ArmatureData } from './types';
+/**
+ * Distance-based animation-LOD knobs. Used as the engine-wide preset
+ * (`SplatEngine.animLodPreset`) and as the per-armature override shape in
+ * {@link Armature.setAnimationLod}.
+ */
+export interface AnimLodPreset {
+    /** World-space distance (m) below which the armature animates full rate. */
+    nearDist?: number;
+    /** World-space distance (m) beyond which `farStride` applies. */
+    farDist?: number;
+    /** Frames-per-update between `nearDist` and `farDist`. 1 = every frame. */
+    nearStride?: number;
+    /** Frames-per-update beyond `farDist`. */
+    farStride?: number;
+}
+/**
+ * Pluggable override that drives the per-frame pose in place of
+ * animation. The Armature has no knowledge of what's on the other end -
+ * ragdoll physics, an IK solver, an AI behavior tree's pose output, a
+ * network-replicated remote character - they all attach the same way.
+ *
+ * When `armature.poseProvider` is non-null, the Armature's animation
+ * player is **not advanced** that frame; the provider has total control
+ * of the pose. The Armature still owns the skinning pipeline (LOD,
+ * frustum cull, world-transform composition, GPU palette upload), so a
+ * provider only needs to fill `pose`.
+ *
+ * Implementations: {@link Ragdoll}.
+ *
+ * @group Characters & Animation
+ */
+export interface PoseProvider {
+    /**
+     * Fill `pose` (per-bone TRS in armature-local bone space) for this
+     * frame. The Armature runs this between its LOD/frustum gate and the
+     * `Skeleton.applyLocal` composition step. To restore animation,
+     * detach by setting `armature.poseProvider = null`.
+     */
+    writePose(pose: Pose, armature: Armature, dt: number): void;
+    /**
+     * Optional teardown hook fired when the Armature is destroyed (or
+     * when a new provider replaces this one). Use to release external
+     * resources - e.g. ragdoll physics bodies.
+     */
+    onDetach?(): void;
+}
+/**
+ * How the armature handles the pelvis X/Z motion extracted from the active
+ * animation.
+ *
+ * - `'off'` - Pelvis X/Z is clamped to bind in bone space. The character
+ *   looks "in-place" regardless of whether the underlying clip is
+ *   locomotive. The pivot is not touched by animation. **Default.**
+ * - `'apply'` - The pivot tracks the pelvis as an absolute offset from a captured
+ *   baseline: `object3D.position = baseline + (pelvis_pose − bind)` each
+ *   frame. Switching `off → apply` captures the current pivot position as
+ *   the baseline; switching `apply → off` snaps the pivot back to the
+ *   baseline. Best for toggling-on/off demos and in-place looping animations
+ *   (pelvis returns to bind at loop end → no teleport). Locomotive clips
+ *   visibly snap at loop wrap; use `'extract'` for those.
+ * - `'extract'` - Engine computes the per-frame pelvis Δ
+ *   (`pelvis(t) − pelvis(t − dt)`) and accumulates it into an internal
+ *   buffer; the caller reads it via {@link Armature.consumeRootMotionDelta}
+ *   and feeds it to a motor / physics body / network layer. Unity-style
+ *   `OnAnimatorMove` pattern. The engine does **not** write to the pivot in
+ *   this mode. Loop wraps and hard `play` calls suppress the resulting
+ *   pelvis discontinuity so the next Δ is `0`.
+ *
+ * In every mode the pelvis bone itself is clamped to bind X/Z in bone space -
+ * the motion lives on the pivot (or in the consumed delta), never on the
+ * bone.
+ *
+ * @group Characters & Animation
+ */
+export type RootMotionMode = 'off' | 'apply' | 'extract';
+/**
+ * Composition root for one character: holds the three.js pivot object and
+ * wires together a {@link Skeleton}, an {@link AnimationPlayer}, a working
+ * {@link Pose}, and a {@link SplatSkinning} unit.
+ *
+ * Thin facade - `playAnimation` / `crossfadeTo` / `stop` / `update` delegate
+ * to the underlying modules. The rig-convention rules (pelvis X/Z clamp,
+ * pelvis-Y lock, root-bone clamp, root-motion extraction) live here, because
+ * they're a *character-setup* concern, not a pose-evaluation concern.
+ *
+ * Most users won't construct this directly - {@link Character.load} builds
+ * one automatically. It's exported for custom pipelines that need direct
+ * control over skeletal evaluation.
+ *
+ * @group Characters & Animation
+ */
+export declare class Armature {
+    /** Pivot object; all linked splats become children of this. */
+    object3D: Group;
+    /** Rig data (bone count, rest translations/rotations, parents). */
+    armatureData: ArmatureData;
+    /** Number of bones in the rig. */
+    numBones: number;
+    private readonly _skeleton;
+    private readonly _currentPose;
+    private readonly _snapshotPose;
+    private readonly _worldTransforms;
+    private _engine;
+    private readonly _worldMatrix;
+    private _player;
+    private _skinning;
+    private _provider;
+    private readonly _layers;
+    private readonly _layerTmpQ;
+    /**
+     * Optional override that drives the pose in place of animation.
+     * Setting this to a non-null value skips animation evaluation; the
+     * provider has full control of `_currentPose`. Setting back to `null`
+     * resumes animation immediately. See {@link PoseProvider}.
+     *
+     * Replacing the provider (set non-null while another is attached)
+     * fires the outgoing provider's `onDetach()` first.
+     */
+    get poseProvider(): PoseProvider | null;
+    set poseProvider(p: PoseProvider | null);
+    private _poseProvider;
+    private _rootBoneIndex;
+    private _pelvisBoneIndex;
+    /**
+     * When true, {@link update} advances the animation player (so timers,
+     * crossfade, and event callbacks still fire) but skips pose evaluation
+     * and the skinning push. The previous frame's pose stays on the GPU
+     * palette and the splat keeps rendering at its last bone state.
+     *
+     * Use for dynamic animation LOD - e.g. when fps drops, set true on
+     * every other (or every Nth) frame to halve the per-frame skeletal
+     * cost. Cleared when fps recovers.
+     */
+    skipPose: boolean;
+    /**
+     * When true, {@link update} still pushes bone transforms to the GPU
+     * palette (so items, hitboxes, and outlines tracking bones still move
+     * correctly) but skips the CPU-side `splat.updatePositions(...)` call
+     * that recomputes sort centers from the deformed mesh. The depth-sort
+     * order lags one frame behind the visual pose.
+     *
+     * Use for alternate-frame throttling - `updatePositions` is the heavy
+     * call (full center buffer re-upload to the sort worker), and most
+     * frames don't visibly need a fresh sort.
+     */
+    skipPositions: boolean;
+    /**
+     * Update rate divider. `1` = pose evaluation runs on every {@link update}
+     * call (default - one pose update per `engine.update()`).
+     * Set to N>1 to advance the animation player every call but only do the
+     * heavy pose-eval + skinning push every Nth call.
+     *
+     * `dt` from skipped frames is accumulated and passed to the next
+     * evaluated frame, so animation time stays correct - only the GPU
+     * palette refresh rate drops.
+     *
+     * Typical use: set to `2` on background characters so the per-character
+     * armature cost halves while the engine still ticks at 30 Hz.
+     */
+    updateInterval: number;
+    private _updateCounter;
+    private _updateAccumDt;
+    private _lockPelvisY;
+    private _rootMotionMode;
+    private _baseLocalPosition;
+    private _lastPelvisPos;
+    private _hasLastPelvis;
+    private _rootMotionAccumDx;
+    private _rootMotionAccumDz;
+    private _lodNearDist;
+    private _lodFarDist;
+    private _lodNearStride;
+    private _lodFarStride;
+    private _lodFrameCounter;
+    private _sortLodNearDist;
+    private _sortLodFarDist;
+    private _sortLodNearStride;
+    private _sortLodFarStride;
+    private _sortLodFrameCounter;
+    constructor(name: string, armatureData: ArmatureData);
+    /** Splats currently being driven by this armature. */
+    get linkedSplats(): Set<Splat>;
+    /**
+     * Detach the armature from its engine and remove its pivot object. Splats
+     * still linked at the time of destroy are also destroyed so they stop
+     * holding GPU resources alive. The armature itself is not safe to
+     * reuse after this call.
+     *
+     * Use {@link Character.destroy} instead if you have the owning
+     * {@link Character} - it disposes both the armature and its primary splat.
+     */
+    destroy(): void;
+    /**
+     * Attach this armature to an engine. Required before playback. Adds the
+     * armature pivot as a child of `engine.contentRoot` and wires up the
+     * animation provider + splat skinning.
+     */
+    addToScene(engine: SplatEngine): void;
+    /**
+     * Register a {@link Splat} to be driven by this armature.
+     *
+     * Reparents the splat under the armature's pivot and pushes the current
+     * bone transforms so the splat appears in the correct pose immediately.
+     */
+    linkSplat(splat: Splat): void;
+    /**
+     * Stop driving the given splat. The splat is not destroyed; it just no
+     * longer receives bone transform updates.
+     */
+    unlinkSplat(splat: Splat): void;
+    /**
+     * Apply any combination of position, rotation, and scale to the armature
+     * pivot. All linked splats are requested to re-sort.
+     */
+    move(position?: Vec3, rotation?: Quat, scale?: Vec3): void;
+    /**
+     * How pelvis X/Z motion is routed each frame. See {@link RootMotionMode}.
+     * Default `'off'`.
+     *
+     * Transitions are coordinated so toggling is well-behaved:
+     *
+     *   - `off → apply` captures the current pivot position as the baseline.
+     *     The pivot then tracks `baseline + (pelvis − bind)` each frame.
+     *   - `apply → off` (or `apply → extract`) snaps the pivot back to the
+     *     baseline so the apply-mode offset doesn't leak into the next mode.
+     *     This is what prevents the toggle-ratchet bug.
+     *   - `* → extract` resets the per-frame Δ tracker so the next Δ is `0`.
+     */
+    get rootMotionMode(): RootMotionMode;
+    set rootMotionMode(m: RootMotionMode);
+    /**
+     * Convenience boolean alias for {@link rootMotionMode}.
+     * `true` ⇔ `'apply'`, `false` ⇔ `'off'`. To use `'extract'`, set
+     * {@link rootMotionMode} directly.
+     */
+    get rootMotion(): boolean;
+    set rootMotion(v: boolean);
+    /**
+     * Return the pelvis X/Z delta accumulated since the previous call (or since
+     * the armature was created / `rootMotionMode` was changed), and reset the
+     * accumulator. The delta is in the pivot's parent space - feed it directly
+     * to a motor's velocity input or to a physics body.
+     *
+     * Returns `{ dx: 0, dz: 0 }` in `'off'` or `'apply'` modes. In `'apply'`
+     * mode the delta has already been written to {@link object3D}, so consumers
+     * shouldn't read and re-apply it.
+     */
+    consumeRootMotionDelta(): {
+        dx: number;
+        dz: number;
+    };
+    /**
+     * When `true`, clamp the pelvis bone's Y translation to bind each frame.
+     * Use for in-place idle / gesture captures where vertical bob would push
+     * the character out of a tightly-framed thumbnail.
+     */
+    get lockPelvisY(): boolean;
+    set lockPelvisY(v: boolean);
+    get isPlaying(): boolean;
+    get isFinished(): boolean;
+    get paused(): boolean;
+    set paused(v: boolean);
+    get animationTime(): number;
+    set animationTime(v: number);
+    get animationDuration(): number;
+    /**
+     * Crossfade progress in `[0, 1]`. `0` when no crossfade is active; `1`
+     * once the active crossfade has fully blended into the target animation.
+     */
+    get crossfadeProgress(): number;
+    get frameRate(): number;
+    set frameRate(v: number);
+    /** Playback-speed multiplier (`1` = author speed). Scales how fast the
+     *  active clip advances without touching its authored frame rate or
+     *  crossfade timing. See {@link AnimationPlayer.playbackSpeed}. */
+    get playbackSpeed(): number;
+    set playbackSpeed(v: number);
+    hasAnimation(animName: string): boolean;
+    /**
+     * Bone names from the attached engine's skeleton library, or an empty array
+     * if the armature isn't bound yet. Consumers that need bone-name lookup
+     * (bone-tracked colliders, attachments, debug overlays) read from here
+     * instead of reaching into private armature state.
+     */
+    get boneNames(): readonly string[];
+    /**
+     * Bone names matching THIS armature's rig size. {@link boneNames} always
+     * returns the 86-bone std-male list; the 441-bone facial rig has its own
+     * name table (`boneNames441`). Name-keyed per-bone features (bone stretch,
+     * body-part classification) must use this accessor or they silently
+     * misclassify every bone on the large rig.
+     */
+    get rigBoneNames(): readonly string[];
+    /** The engine this armature is attached to, or `null` if not yet attached. */
+    get engine(): SplatEngine | null;
+    /** The skeleton owned by this armature (rest pose, parents, bind data). */
+    get skeleton(): Skeleton;
+    /**
+     * Live reference to the per-bone world-transform array filled in by
+     * the most recent {@link update}. Same Mat4 instances are reused
+     * across frames - callers may hold the array reference and re-read,
+     * or call {@link getBoneWorldMatrix} for a single bone. Empty until
+     * the first update.
+     */
+    get boneWorldMatrices(): readonly Mat4[];
+    /**
+     * Snap any active crossfade to its terminal state (target pose fully
+     * applied) on the next {@link Armature.update}. Useful when scrubbing
+     * through animation frames for precompute, where the per-frame pose
+     * needs to be the pure animation evaluation without crossfade blend.
+     */
+    endCrossfade(): void;
+    /**
+     * Return the world-space transform of bone `boneIdx` as computed by the
+     * most recent {@link Armature.update}. Returns a live reference into the
+     * armature's internal array - callers must not mutate it; copy first if
+     * you need to retain.
+     *
+     * Returns `null` if `boneIdx` is out of range, or if the bone transform
+     * array has not been populated yet (no `update()` has run, or the armature
+     * isn't attached to an engine).
+     *
+     * Used by per-bone attachments - bone-tracked colliders, weapon GLBs
+     * mounted to a bone, particle emitters following a bone, etc.
+     */
+    getBoneWorldMatrix(boneIdx: number): Mat4 | null;
+    /**
+     * Name of the currently-playing animation, or `null` if no animation is
+     * active. Mirrors {@link AnimationPlayer.currentAnimationName}.
+     */
+    get currentAnimationName(): string | null;
+    /**
+     * Subscribe to frame-aligned {@link AnimationEvent}s on the currently-
+     * playing animation. Events come from the active animation's
+     * {@link Animation.events} array; the engine doesn't interpret `name` or
+     * `payload` - games define their own vocabulary and route inside the
+     * callback.
+     *
+     * Listeners are kept across animation switches; one subscription is enough
+     * for the armature's lifetime. Returns an unsubscribe handle.
+     */
+    onAnimEvent(cb: AnimEventCallback): () => void;
+    /**
+     * Start playing an animation immediately (no crossfade). Restarts from
+     * frame 0. Returns `false` if not registered, or if the armature isn't
+     * attached to an engine yet.
+     *
+     * Passing `rootMotion: true` sets {@link rootMotionMode} to `'apply'`;
+     * passing `false` sets it to `'off'`. For `'extract'`, set the mode
+     * separately and pass `rootMotion: false` (or omit) here - the per-clip
+     * flag is just a convenience shortcut for the common case.
+     */
+    playAnimation(animName: string, rootMotion?: boolean, loop?: boolean): boolean;
+    /**
+     * Crossfade from the current pose to a new animation over `opts.duration`
+     * seconds. Snapshots current bone poses, then blends toward the new
+     * animation target. Pelvis motion stays continuous across the blend.
+     *
+     * `opts.rootMotion` is mapped to {@link rootMotionMode} the same way as
+     * {@link playAnimation}.
+     */
+    crossfadeTo(animName: string, opts?: {
+        duration?: number;
+        rootMotion?: boolean;
+        loop?: boolean;
+        preserveTime?: boolean;
+    }): boolean;
+    /**
+     * Play `animName` on the named overlay layer, gated to `mask`'s bone set.
+     * Layers compose on top of the base animation in {@link update} - for each
+     * bone in the mask, the current pose is interpolated toward the overlay's
+     * pose by the layer weight.
+     *
+     * Creates the layer lazily on first use (allocates a per-layer
+     * {@link AnimationPlayer} sharing the same skeleton and animation provider
+     * as the base). Subsequent calls reuse the same player.
+     */
+    playLayerAnimation(layerName: string, animName: string, mask: BoneMask, opts?: {
+        loop?: boolean;
+        crossfade?: number;
+        weight?: number;
+    }): boolean;
+    /** Set the overlay weight for a layer in `[0, 1]`. No-op if the layer doesn't exist. */
+    setLayerWeight(layerName: string, weight: number): void;
+    /**
+     * Pause or resume every active overlay layer. The base animation is
+     * controlled separately via {@link paused}. Useful so a single play/pause
+     * toggle in an editor or pause menu freezes the whole stack together.
+     */
+    setAllLayersPaused(paused: boolean): void;
+    /**
+     * Stop and remove the named layer. With `fadeDuration > 0`, ramps the
+     * layer weight to zero over `fadeDuration` seconds before tearing down.
+     */
+    stopLayer(layerName: string, fadeDuration?: number): void;
+    /** Stop with optional crossfade back to rest pose. */
+    stop(fadeDuration?: number): void;
+    /**
+     * Advance animation time by `dt` seconds, evaluate pose, and push bone
+     * transforms to linked splats. Called for you by `engine.update()` unless auto-update is detached.
+     */
+    update(dt: number): void;
+    /**
+     * Resolve named rig conventions once skeleton library is available.
+     * If `boneNames` is present, looks up "root" and any name containing
+     * "pelvis"; otherwise falls back to bone index 0 as root.
+     */
+    private _resolveRigIndices;
+    /**
+     * Compose overlay layers onto `_currentPose`. Each layer ticks its own
+     * player, evaluates a full pose into a scratch buffer, then per masked
+     * bone interpolates the current pose toward the overlay by the layer
+     * weight. Runs before `_applyRigPostClamps` so pelvis/root clamps stay
+     * authoritative.
+     */
+    private _evaluateLayers;
+    /**
+     * Apply rig-convention rules to the freshly-evaluated pose:
+     *   - root-motion routing - `'apply'` writes `baseline + (pelvis − bind)`
+     *     to the pivot; `'extract'` accumulates the per-frame pelvis Δ;
+     *     `'off'` does nothing.
+     *   - pelvis X/Z clamp to bind in bone space (always - the motion lives on
+     *     the pivot / in the consumed delta, not on the bone).
+     *   - pelvis-Y lock to bind (when {@link lockPelvisY} is set).
+     *   - root-bone full clamp to bind.
+     */
+    private _applyRigPostClamps;
+    /**
+     * Apply runtime bone scaling. Each entry scales a bone's flesh + segment in
+     * its own frame - `{ along, width, thickness }` (each defaulting to `1`), or
+     * a bare number for uniform scale. e.g. `{ thigh_l: { along: 1.3 }, calf_l:
+     * { along: 1.3 } }` → a 1.3× longer left leg; `{ upperarm_l: { width: 1.4,
+     * thickness: 1.4 } }` → a beefier arm. Bones not listed stay at `1`. Pass
+     * `null` to clear. Works for any bone set (limbs, spine, …); see
+     * {@link computeBoneStretch} for the model. Recompute only when factors
+     * change - the result is applied every frame by the skeleton + skinning.
+     */
+    setBoneStretch(factors: Record<string, BoneScaleInput> | null): void;
+    /** Push the current pose through skeleton + skinning. Called at link time. */
+    private _pushPose;
+    private _cameraFrustum;
+    /**
+     * The pivot's world matrix in the skeletal core's own matrix type. Refreshes
+     * the three.js world matrix first, so a transform set this frame is seen
+     * this frame.
+     */
+    private _worldTransform;
+    /**
+     * Squared distance from the pivot's world origin to the engine camera, or
+     * `null` when the engine has no camera. Drives the distance-LOD bands.
+     * @internal
+     */
+    cameraDistanceSq(): number | null;
+    /**
+     * Enable / configure distance-based animation LOD for THIS armature.
+     * LOD is off by default (full rate); calling this is the opt-in.
+     *
+     * - **No args**: pull the engine's `animLodPreset` (set via
+     *   `SplatEngine.animLodPreset`). If the engine has no preset, fall back to a
+     *   built-in default (full rate ≤12 m, every-2nd ≤24 m, every-4th
+     *   beyond). Typical gameplay use: set the preset once, then call
+     *   `armature.setAnimationLod()` on each throttle-able character.
+     * - **Partial opts**: tweak individual knobs on top of current values.
+     *
+     * `nearDist` / `farDist` are world-space distances (m) from the camera;
+     * `nearStride` / `farStride` are frames-per-update in the mid / far
+     * bands. A stride of 1 means every frame.
+     */
+    setAnimationLod(opts?: {
+        nearDist?: number;
+        farDist?: number;
+        nearStride?: number;
+        farStride?: number;
+    }): void;
+    /** Disable LOD throttling - every character animates at full rate
+     *  regardless of distance (frustum cull still applies). */
+    disableAnimationLod(): void;
+    /**
+     * Enable / configure distance-based SORT LOD for THIS armature.
+     *
+     * Throttles only the CPU-side `splat.updatePositions` call (the dominant
+     * cost - ~88% of per-character CPU at high counts) without freezing the
+     * rendered pose. On throttled frames the GPU palette still uploads, so
+     * animation looks correct; only the depth-sort order lags one frame.
+     *
+     * Composes with {@link setAnimationLod} - when anim LOD throttles a
+     * frame, sort LOD is moot for that frame; when anim LOD evaluates, sort
+     * LOD can independently decide to skip the positions push.
+     *
+     * Typical use: tighter near band than anim LOD (e.g. 5–10 m) so even
+     * mid-distance characters skip the sort re-upload most frames.
+     *
+     * - **No args**: enable with a built-in default
+     *   (nearDist=5, farDist=15, nearStride=2, farStride=4).
+     * - **Partial opts**: tweak individual knobs on top of current values.
+     */
+    setSortLod(opts?: {
+        nearDist?: number;
+        farDist?: number;
+        nearStride?: number;
+        farStride?: number;
+    }): void;
+    /** Disable sort LOD - every character does the full updatePositions
+     *  every frame (still gated by `skipPositions` and anim LOD). */
+    disableSortLod(): void;
+    /** Frames-per-update for this armature this frame, based on camera
+     *  distance. 1 = full rate. Returns 1 when no camera is available so
+     *  we never freeze a character due to missing engine state. */
+    private _lodStride;
+    /** True when sort LOD says "skip the CPU positions re-upload this frame".
+     *  Uses the same camera-distance bands shape as anim LOD, but a separate
+     *  counter so the two strides don't lock-step. */
+    private _sortLodSkipThisFrame;
+}