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

package/dist/types/character.d.ts

@@ -0,0 +1,540 @@
+import { Vector3 } from 'three';
+import type { Object3D } from 'three';
+import { Armature } from './armature';
+import type { SplatEngine } from './engine';
+import type { CharacterBundle } from './loader/character/load';
+import type { AnimEventCallback } from './skeletal/animation-player';
+import type { BodyRegion, BoneMask } from './skeletal/bone-mask';
+import { Splat } from './splat/splat';
+/**
+ * Options for {@link Character.load}.
+ *
+ * @group Characters & Animation
+ */
+export interface LoadCharacterOptions {
+    /**
+     * Name used for the armature and any embedded animation registered on the
+     * engine. Defaults to the file basename (stripped of extension).
+     */
+    name?: string;
+    /** Initial position, `y` at GROUND CONTACT - same convention as
+     *  {@link Character.setPosition}. Defaults to the origin. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Which rest translations pose the rig.
+     *
+     * - `'auto'` (default) - `'bundled'` for a bundle carrying a correction
+     *   receipt, `'builtin'` for one without. Apps should pass nothing: the
+     *   discriminator lives in the file, so the decision belongs here rather than
+     *   in each consuming app, where the copies would otherwise drift apart.
+     * - `'builtin'` - the canonical std-male tables from the skeleton library.
+     *   Every character is posed on one shared skeleton.
+     * - `'bundled'` - the per-character `joints` array for BODY bones, canonical
+     *   for `FACIAL_*` ones and for toes. See `keepsCanonicalRest` for the
+     *   measurements behind both exclusions.
+     *
+     * The explicit values exist for the comparison scenes, which show one
+     * character both ways on purpose.
+     *
+     * The body tables disagree, and not subtly: on a sample character 81 of 86
+     * body bones differ by more than 1 mm, worst 36 mm at `foot_r`, with the
+     * canonical limbs uniformly SHORTER (thigh -14.7 mm, calf -36.4 mm). That
+     * leaves the canonical knee ~36 mm high and the canonical foot floating
+     * ~72 mm off the ground on a character whose own skeleton reaches it.
+     *
+     * At rest the choice is invisible - skinning cancels `worldPose · inverseBind`
+     * to identity either way. It only shows once a joint ROTATES, because the
+     * rotation happens about the chosen pivot: a splat at the true knee swung
+     * about a centre 36 mm away lands ~51 mm off through a 90° bend.
+     *
+     * Clips are authored on the canonical rig - their body translations match
+     * `REST_TRANSLATIONS_441` to 0.0007 mm - which USED to make a canonical bind
+     * the only one that agreed with the pose, and `'bundled'` a diagnostic.
+     * That is no longer so: a bone whose translation never changes across a clip
+     * is now read as a rest declaration and left to the character
+     * (`Animation`'s `translationMask`, derived for `.anim`, GLB and the
+     * `.bin`-embedded clip alike). Playback is effectively rotation-only for
+     * every bone the clip does not actually translate - 341 of 342 on the body
+     * rig, 829 of 1185 on the full one - so `'bundled'` now inherits the
+     * character's own lengths instead of having them overwritten.
+     *
+     * Bundles carry translations only, never rotations, so `'bundled'` yields
+     * per-character bone LENGTHS with canonical joint ORIENTATIONS - a hybrid.
+     * Falls back to `'builtin'` when the bundle has no joints (older files) or
+     * the array length disagrees with the bone count.
+     */
+    restSource?: 'auto' | 'builtin' | 'bundled';
+}
+export declare class Character {
+    /** Render-LOD level pyramid - when more than one entry, only one is
+     *  enabled at a time (the active level). `splats[0]` is always the
+     *  highest-fidelity (L0). Single-LOD characters have `splats.length === 1`. */
+    splats: Splat[];
+    /**
+     * The currently-rendered splat. For single-bin characters this is
+     * always `splats[0]`; for multi-LOD characters it tracks the active
+     * render-LOD level and flips with `setRenderLod` / `setRenderLevel`.
+     *
+     * Safe for read-only queries (`.numSplats`, `.object3D`, `.isInFrustum`,
+     * etc.). For **state mutations** that should persist across LOD swaps
+     * (tint, sort, visibility) prefer the Character-level helpers
+     * ({@link setTint}, {@link requestSort}) - writing to a single splat
+     * here only affects whichever level is active right now and the change
+     * vanishes when the active level swaps.
+     */
+    get splat(): Splat;
+    private _renderLodEnabled;
+    private _renderLodNearDist;
+    private _renderLodFarDist;
+    private _activeLevel;
+    private _variantSplats;
+    /** Whether this character is live (ticking + rendering). Toggled by
+     *  {@link setActive} for object pooling - a deactivated character keeps all
+     *  its GPU resources (splats, textures, compiled shaders) but stops
+     *  updating and rendering, so it can be reactivated at a new position with
+     *  none of the ~tens-of-ms `new Splat` setup cost. */
+    private _active;
+    /** Set by {@link destroy}. Async loaders that resolve afterwards (LOD
+     *  upgrades, variant splats) check this so they don't re-add splats that
+     *  nothing owns or ticks anymore - without it, a character destroyed while
+     *  a finer LOD is still downloading leaks that splat into the scene as a
+     *  frozen, orphaned figure. */
+    private _destroyed;
+    /** True once {@link destroy} has run. Progressive-load choreography
+     *  (coarse-first upgrade loops) should stop streaming when this flips. */
+    get destroyed(): boolean;
+    private _bakedGroundShiftY;
+    /**
+     * The ground shift a `VIGGCHAR` v1 bake folded into this character, in
+     * metres. `0` for legacy `.bin` bundles and for anything without one.
+     *
+     * Diagnostics and ground-snap tooling only. {@link setPosition},
+     * {@link getPosition} and {@link Character.load}'s `position` option already
+     * apply it, so game code should not need to read this - and code that
+     * measures ground contact empirically (a {@link getLowestWorldY} probe) must
+     * NOT apply it, because such a probe observes the shift's result already and
+     * would double-correct.
+     */
+    get bakedGroundShiftY(): number;
+    /**
+     * Convert a ground-contact Y - the convention {@link setPosition} takes -
+     * into the raw Y to write on `armature.object3D`.
+     *
+     * For hot paths that must bypass {@link setPosition} and write the pivot
+     * directly (a per-frame sync with a pooled `Vec3`, say). Everything else
+     * should use {@link setPosition} and never see this.
+     */
+    groundToEntityY(groundY: number): number;
+    /**
+     * Exact inverse of {@link groundToEntityY}: a raw `armature.object3D` Y back
+     * into the ground-contact convention.
+     *
+     * Read positions back through this (or through {@link getPosition}) so that a
+     * read/modify/write round-trip - a motor integrating velocity, a tween
+     * sampling its own start value - can never apply the shift twice.
+     */
+    entityToGroundY(entityY: number): number;
+    private _updateHandler;
+    /** Skeleton + animation controller. */
+    armature: Armature;
+    private _engine;
+    /**
+     * The three.js object for the whole character - the armature's pivot, with
+     * the character's splats parented under it. Already added to the engine's
+     * content root; reparent it if you need the character under something else.
+     */
+    get object3D(): Object3D;
+    constructor(armature: Armature, splats: Splat[], engine: SplatEngine);
+    /**
+     * Load a character bundle and add it to the engine's content root.
+     *
+     * The bundle's bone count selects the rig: 441 bones = full body + facial
+     * rig, otherwise the 86-bone standard-male body rig. If the bundle contains
+     * an embedded animation, it is registered on the engine under
+     * {@link LoadCharacterOptions.name} (or the file basename).
+     *
+     * @param engine - Target engine.
+     * @param urlOrUrls - One bundle URL, or an array of LOD levels for the same
+     *   character, finest first. Every level shares the armature and animation
+     *   from the FIRST entry; see {@link setRenderLod} for how a level is picked
+     *   at runtime and {@link addLodLevel} for adding one later.
+     * @param opts - See {@link LoadCharacterOptions}.
+     * @returns A fully-wired character whose armature drives the splat every frame.
+     *
+     * @example
+     * ```ts
+     * const character = await Character.load(engine, '/assets/hero.vsplat');
+     * character.playAnimation('idle', { loop: true });
+     * ```
+     */
+    static load(engine: SplatEngine, urlOrUrls: string | string[], opts?: LoadCharacterOptions): Promise<Character>;
+    /**
+     * Load a `.bin` character bundle from in-memory bytes.
+     *
+     * Same shape as {@link Character.load} but consumes bytes directly. Use for
+     * runtime-generated content (an offline generation pipeline's output, hot
+     * swaps, tests) where there is no fetchable URL.
+     *
+     * @param engine - Target engine.
+     * @param bytes - Raw `.bin` bundle bytes.
+     * @param opts - See {@link LoadCharacterOptions}. `opts.name` is required for
+     *   anim registration since there is no URL basename to fall back on.
+     * @returns A fully-wired character whose armature drives the splat every frame.
+     *
+     * @example
+     * ```ts
+     * const character = await Character.loadFromBytes(engine, generatedBundle, { name: 'hero' });
+     * character.playAnimation('idle', { loop: true });
+     * ```
+     */
+    static loadFromBytes(engine: SplatEngine, bytes: Uint8Array, opts?: LoadCharacterOptions): Promise<Character>;
+    /**
+     * Load a `.vsplat` bundle.
+     *
+     * The extension is advisory: the bytes go to the same magic-dispatching
+     * reader {@link Character.load} uses, so a `.vsplat` may be a `VIGGCHAR`
+     * version 1 bundle or one of the legacy planar containers. None of those
+     * carries an animation chunk, so the character comes up in its rest pose;
+     * register clips separately with {@link Animation.loadGlb} if you need motion.
+     *
+     * Differs from {@link Character.load} only in skipping the in-memory
+     * `ArrayBuffer` cache - see `loader/shared/asset-loader.ts`.
+     *
+     * @param engine - Target engine.
+     * @param source - URL, or raw `.vsplat` bytes.
+     * @param opts - See {@link LoadCharacterOptions}.
+     */
+    static loadVsplat(engine: SplatEngine, source: string | Uint8Array, opts?: LoadCharacterOptions): Promise<Character>;
+    /**
+     * Build a character from bundles that are already decoded. The bundles are
+     * read, never modified, so the same ones can back any number of characters.
+     * @internal
+     */
+    static fromBundles(engine: SplatEngine, bundles: CharacterBundle[], defaultName: string, opts?: LoadCharacterOptions): Character;
+    private static _buildFromLoadResult;
+    /** Build + register the per-frame update handler. Called once at
+     *  construction; kept separate so the handler can close over `this`. */
+    private _wireUpdate;
+    /** Pick the render-LOD level for this frame based on camera distance.
+     *  near band → L0; far band → last; in between → intermediate level. */
+    private _pickRenderLevel;
+    /**
+     * Enable distance-based render LOD. Per frame, the character switches
+     * between the loaded LOD splats (`splats[0..N-1]`, from finest to
+     * coarsest). Near the camera → L0 (full); beyond `farDist` → last level;
+     * in between → intermediate levels split evenly across the band.
+     *
+     * Composes with {@link Armature.setAnimationLod} / {@link Armature.setSortLod}:
+     * render LOD throws away splats at distance, the other two throttle
+     * animation / sort work - stack all three for maximum CPU savings.
+     *
+     * No-op if only one LOD level was loaded.
+     *
+     * @example
+     * ```ts
+     * const c = await Character.load(engine, ['hero.l0.vsplat', 'hero.l1.vsplat', 'hero.l2.vsplat']);
+     * c.setRenderLod({ nearDist: 8, farDist: 20 });
+     * ```
+     */
+    setRenderLod(opts: {
+        nearDist: number;
+        farDist: number;
+    }): void;
+    /** Disable render LOD - pins the character to the highest-fidelity level
+     *  (L0). Other loaded LOD splats remain in memory but are not rendered. */
+    disableRenderLod(): void;
+    /** Force a specific render-LOD level, bypassing distance bands. Useful
+     *  for debugging / A-B comparisons in the profiling scene. */
+    setRenderLevel(level: number): void;
+    /** Number of LOD levels loaded for this character (>=1). */
+    get renderLodLevels(): number;
+    /** Active render-LOD level (0 = highest fidelity). */
+    get activeRenderLevel(): number;
+    /**
+     * Tint every LOD splat. Fans out to `splats[*]` so the tint persists
+     * across render-LOD swaps - writing to a single splat (e.g. the legacy
+     * `c.splat.setTint(...)`) only affects that level, and the tint
+     * "vanishes" the next time `setRenderLod` swaps the visible level.
+     *
+     * Same signature as {@link Splat.setTint}.
+     */
+    setTint(intensity: number, color?: {
+        r: number;
+        g: number;
+        b: number;
+    }): void;
+    /**
+     * Re-sort every LOD splat. Cheap when called on inactive splats (no GPU
+     * sort runs there), and necessary for the active one to reflect a fresh
+     * transform on the next frame. Fans out so a swap to a previously-
+     * inactive LOD doesn't render with a stale sort order.
+     */
+    requestSort(): void;
+    /**
+     * World-space Y of the character's lowest point, using
+     * {@link Splat.getGroundWorldY}'s noise-robust low-quantile estimate across
+     * every enabled splat (the active render-LOD level, plus any variant splats
+     * that are currently visible). Returns `null` if no splat is enabled (e.g.
+     * mid-load). Ground-snap tooling only - the per-frame render path doesn't
+     * use it.
+     *
+     * This is a MEASUREMENT of where the character actually renders, so it
+     * already includes {@link bakedGroundShiftY}. A caller that snaps to ground
+     * from this number must not also apply that shift, or it corrects twice.
+     */
+    getLowestWorldY(quantile?: number): number | null;
+    /**
+     * Async primitive: load one more LOD level from `url` and link it to this
+     * character's armature, leaving it disabled (not rendered) until the caller
+     * explicitly picks it via {@link setRenderLevel}.
+     *
+     * Lets game code compose its own LOD-loading policy on top of an existing
+     * Character without the engine deciding when to swap. Typical pattern is
+     * progressive: load the smallest LOD via {@link Character.load} for instant
+     * first-frame, then background-load finer levels with `addLodLevel` and
+     * `setRenderLevel(splats.length - 1)` each time one arrives.
+     *
+     * Skeleton + animation are shared with the existing armature - any joints
+     * / animation data inside the additional `.bin` is intentionally ignored
+     * (it must match the original; only the splat + bone-weights chunks are
+     * consumed). The newly loaded `Splat` is pushed onto `this.splats` and
+     * starts in the disabled state.
+     *
+     * @param url - URL of another `.bin` (any LOD level of the same character).
+     * @returns Resolves once the splat is fully loaded, linked, and GPU-uploaded.
+     *
+     * @example
+     * ```ts
+     * // Progressive: start at L2 (smallest), upgrade as finer levels arrive.
+     * const c = await Character.load(engine, urls[2], opts);
+     * (async () => {
+     *   await c.addLodLevel(urls[1]);
+     *   c.setRenderLevel(c.splats.length - 1);
+     *   await c.addLodLevel(urls[0]);
+     *   c.setRenderLevel(c.splats.length - 1);
+     * })();
+     * ```
+     */
+    addLodLevel(url: string): Promise<void>;
+    /**
+     * Load an additional splat cloud, link it to this character's armature,
+     * and leave it ENABLED so it renders alongside the LOD pyramid. Returns
+     * the newly-created {@link Splat} so higher-level systems can drive it
+     * directly (typically via {@link Splat.setSplatGroups} +
+     * {@link Splat.setVariantMask}).
+     *
+     * Use case: damage / outfit / state variants where two skinned clouds
+     * share one skeleton and per-region visibility masks decide which
+     * gaussians each cloud contributes. See the `DamageVariant` preset for
+     * the body-part scheme built on top of this primitive.
+     *
+     * The variant splat's lifecycle is owned by this Character - it is
+     * destroyed in {@link destroy} and enabled/disabled by {@link setActive}.
+     * Call {@link removeVariantSplat} to retire one early.
+     *
+     * @param url - URL of a `.bin` rigged to the same skeleton as this
+     *   character. The skeleton/animation chunks (if present) are ignored.
+     */
+    addVariantSplat(url: string): Promise<Splat>;
+    /** Remove and destroy a splat previously added via {@link addVariantSplat}.
+     *  No-op if `splat` was not from this character. */
+    removeVariantSplat(splat: Splat): void;
+    /** Read-only view of currently-attached variant splats (in insertion order). */
+    get variantSplats(): readonly Splat[];
+    /**
+     * Set the character's position, with `y` measured at GROUND CONTACT: pass the
+     * floor height and the feet land on it, whichever container the character
+     * came from. Triggers a splat re-sort.
+     *
+     * `y` goes through {@link groundToEntityY} on the way to the pivot. That is
+     * the identity for every legacy `.bin` character, so this is byte-identical
+     * to the historical "y is the model origin" behaviour for everything already
+     * shipped; only `VIGGCHAR` v1 bundles move. Read the position back with
+     * {@link getPosition}, never with `armature.object3D.position`, or a
+     * round-trip will double-apply the shift.
+     */
+    setPosition(x: number, y: number, z: number): void;
+    /**
+     * The character's current position in the armature pivot's parent space, in
+     * the same convention {@link setPosition} takes (`y` at ground contact).
+     *
+     * The exact inverse of {@link setPosition}: reading a position and writing it
+     * straight back is a no-op. That is the property to preserve - it is what
+     * lets a caller integrate velocity, tween, or clamp against a position it
+     * read without the ground shim compounding once per frame.
+     *
+     * Returns a fresh {@link Vec3}; the pivot's own vector is not exposed.
+     */
+    getPosition(out?: Vector3): Vector3;
+    /** Set the character's rotation in Euler degrees. Triggers a splat re-sort. */
+    setRotation(xDeg: number, yDeg: number, zDeg: number): void;
+    /** Set non-uniform scale. Triggers a splat re-sort. */
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * Immediately start a registered animation (no crossfade).
+     *
+     * The animation must have been registered on the engine via
+     * {@link Animation.register} or embedded in the `.bin` bundle.
+     *
+     * @param animName - Animation name in `engine.skeletalAnimationLibrary`.
+     * @param opts.loop - Loop playback. Default `true`.
+     * @param opts.rootMotion - Drive the armature position from the pelvis X/Z channel. Default `false`.
+     * @returns `true` if the animation was found and started; `false` otherwise.
+     */
+    playAnimation(animName: string, opts?: {
+        loop?: boolean;
+        rootMotion?: boolean;
+    }): boolean;
+    /**
+     * Smoothly blend from the current pose to a new animation.
+     *
+     * Snapshots the current bone poses and interpolates toward the new
+     * animation over `duration` seconds. Safe to call mid-crossfade - always
+     * starts from wherever bones actually are.
+     *
+     * @param animName - Animation name in `engine.skeletalAnimationLibrary`.
+     * @param opts.duration - Crossfade length in seconds. Default `0.08`.
+     * @param opts.loop - Loop the target animation. Default `true`.
+     * @param opts.rootMotion - Drive the armature position from the pelvis X/Z channel. Default `false`.
+     * @returns `true` if the animation was found and the blend started; `false` otherwise.
+     */
+    crossfadeTo(animName: string, opts?: {
+        duration?: number;
+        loop?: boolean;
+        rootMotion?: boolean;
+        preserveTime?: boolean;
+    }): boolean;
+    /**
+     * Play `animName` on the named overlay layer, restricted to a bone mask.
+     * Layers compose over the base animation each frame - masked bones blend
+     * toward the overlay by `opts.weight` (defaults to `1`).
+     *
+     * Pass `opts.region: 'upperBody' | 'lowerBody'` to use the built-in masks
+     * (canonical 86-bone rig), or `opts.mask` directly to supply your own.
+     *
+     * Typical use: `character.playAnimation('walk_loop'); character.playLayer('aim', 'aim_rifle', { region: 'upperBody' });`
+     */
+    playLayer(layerName: string, animName: string, opts?: {
+        region?: BodyRegion;
+        mask?: BoneMask;
+        loop?: boolean;
+        crossfade?: number;
+        weight?: number;
+    }): boolean;
+    /** Set the overlay weight (0..1) on a layer. */
+    setLayerWeight(layerName: string, weight: number): void;
+    /** Stop and tear down a layer; ramps weight to zero over `fadeDuration` if > 0. */
+    stopLayer(layerName: string, fadeDuration?: number): void;
+    /** Pause or resume every active overlay layer at once. */
+    setAllLayersPaused(paused: boolean): void;
+    /**
+     * Name of the currently-playing animation, or `null` if no animation is
+     * active. Mirrors {@link Armature.currentAnimationName}.
+     */
+    get currentAnimationName(): string | null;
+    /** `true` if an animation is currently active. */
+    get isPlaying(): boolean;
+    /**
+     * Playback-speed multiplier for the active clip (`1` = author speed, `2` =
+     * double speed). Scales only how fast animation time advances, not the
+     * authored frame rate or crossfade timing. Mirrors
+     * {@link Armature.playbackSpeed}. Use it to tie a locomotion clip's speed
+     * to the pivot's movement speed.
+     */
+    get playbackSpeed(): number;
+    set playbackSpeed(v: number);
+    /**
+     * `true` when a non-looping animation has reached its last frame and is no
+     * longer advancing.
+     */
+    get isFinished(): boolean;
+    /**
+     * Subscribe to frame-aligned animation events fired as `animTime` advances.
+     * The active animation's {@link Animation.events} array is the source; the
+     * engine doesn't interpret `name` or `payload` - games define their own
+     * vocabulary and route inside the callback.
+     *
+     * Listeners persist across animation switches. Returns an unsubscribe handle.
+     *
+     * @example
+     * ```ts
+     * character.onAnimEvent((e) => {
+     *   if (e.name === 'footstep') playFootstepSfx(e.payload);
+     * });
+     * ```
+     */
+    onAnimEvent(cb: AnimEventCallback): () => void;
+    /**
+     * Stop playback.
+     *
+     * With `fadeDuration = 0` (the default), snaps immediately to the rest
+     * pose. A positive value crossfades back to rest over that many seconds.
+     */
+    stop(fadeDuration?: number): void;
+    /**
+     * Read and reset the pelvis X/Z delta the animation produced since the
+     * last call. Only meaningful when
+     * {@link Armature.rootMotionMode | armature.rootMotionMode} is `'extract'`;
+     * returns `{0, 0}` otherwise.
+     *
+     * Typical use: a motor / character controller reads this each tick and
+     * feeds it into its own velocity integration, so animation root motion
+     * composes cleanly with physics, networking, or input.
+     *
+     * ```ts
+     * // in your render loop, after engine.update(dt):
+     * const { dx, dz } = character.consumeRootMotionDelta();
+     * motor.setMoveVelocity(dx / dt, dz / dt);
+     * motor.update(dt);
+     * ```
+     */
+    consumeRootMotionDelta(): {
+        dx: number;
+        dz: number;
+    };
+    /** True while the character is ticking + rendering (see {@link setActive}). */
+    get active(): boolean;
+    /**
+     * Activate / deactivate this character WITHOUT releasing GPU resources -
+     * the basis for object pooling. Deactivating detaches the per-frame update
+     * handler and disables every splat object and the armature pivot, so the
+     * character stops animating and rendering but keeps all its splats,
+     * textures and compiled shaders alive. Reactivating re-attaches the update
+     * handler and re-enables the armature; render-LOD then re-picks which splat
+     * shows on the next frame (so we only force the current level visible to
+     * cover the LOD-disabled case).
+     *
+     * Reactivate is the cheap path that skips the entire `new Splat` setup cost
+     * (texture creation + bone upload + shader compile, ~tens of ms per
+     * character) that a fresh {@link load} pays. Callers reposition via
+     * `armature.move(...)` and restart animation via `playAnimation(...)` after
+     * reactivating.
+     *
+     * Idempotent.
+     */
+    setActive(on: boolean): void;
+    /**
+     * Detach the per-frame playback tick without touching rendering/GPU
+     * resources (unlike {@link setActive}). For hosts that drive the armature's
+     * clock themselves and apply their own per-frame pose edits, the auto-tick
+     * would re-evaluate and overwrite those edits. Idempotent.
+     */
+    detachAutoUpdate(): void;
+    /**
+     * Advance this character by `dt` seconds: pick the render LOD, evaluate the
+     * pose, push it to the splats. `engine.update()` calls this for every
+     * character still on auto-update; call it yourself after
+     * {@link detachAutoUpdate}.
+     */
+    update(dt: number): void;
+    /**
+     * Release all GPU/CPU resources: removes the engine update handler, unlinks
+     * the splat from the armature, destroys both, and removes the armature
+     * pivot from the scene graph.
+     */
+    destroy(): void;
+}