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

package/dist/types/loader/character/legacy/planar-splat.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Planar character-splat decoder - the payload half of `VFCHARB2`.
+ *
+ * A planar container stores one contiguous, component-major byte plane per
+ * attribute (all x, then all y, then all z) instead of the per-splat records
+ * `VFCHARB1` uses. Two precision modes share the one layout:
+ *
+ *   `fp16` - the same half-float values the shipping v2 `VFCHARB1` bundle
+ *            carries, only re-laid-out. It decodes bit-identically to the v2
+ *            path, which is what makes it the control when judging q23.
+ *   `q23`  - ~23 B/gaussian: u16 position against per-file bounds, u8 rotation
+ *            (w derived), u8 log-scale, u8 logit-opacity, u8 weights (the last
+ *            one derived), bone indices through a per-file palette.
+ *
+ * This module is deliberately free of Worker glue so it can be driven directly
+ * (from `binary-gsplat-worker.ts`, and from a plain Node process when the
+ * decode is being compared against the Python reference implementation).
+ */
+/**
+ * Magic -> the `format` string a file under that magic must declare.
+ *
+ * The MAGIC is the container generation and the one field this decoder refuses
+ * to guess at: a planar payload published under `VFCHARB1` would sail past
+ * every version check in the interleaved reader and decode to silent garbage.
+ * `format` is then checked as well - dispatching on `version` alone is exactly
+ * how a file can be misparsed without anything throwing.
+ *
+ * `VSPLAT01` is the pre-release prototype of the same layout. It is kept
+ * readable so the `.vsplat` LOD/quantisation A/B rig keeps working, and because
+ * routing it through this same decoder means the prototype exercises the
+ * production code path rather than a copy of it.
+ */
+declare const PLANAR_CONTAINERS: Record<string, string>;
+/** First planar `version`. `1` = fp32 interleaved, `2` = fp16 interleaved. */
+declare const FIRST_PLANAR_VERSION = 3;
+type PlaneDtype = 'f32' | 'f16' | 'u16' | 'u8';
+/**
+ * Per-plane compression codec, as written in the header.
+ *
+ * WHY DEFLATE AND NOT BROTLI OR ZSTD, which both compress ~10% better: these
+ * three are the only formats `DecompressionStream` accepts, and the equivalents
+ * (`GZipStream` / `DeflateStream`) are in the .NET base library, so a file with
+ * compressed planes decodes on both targets with ZERO shipped decoder. Browsers
+ * expose brotli and zstd only to the HTTP layer, never to script, so choosing
+ * either would put a WASM decoder on the critical path of every character load.
+ *
+ * In-file compression is for platforms with no HTTP layer (Unity
+ * StreamingAssets, AssetBundles, local files). On the web the file is served
+ * flat with `Content-Encoding: br` instead, which is free and compresses
+ * better. This decoder honours whichever the file declares.
+ */
+type PlaneCodec = 'gzip' | 'deflate' | 'deflate-raw';
+interface PlaneInfo {
+    offset: number;
+    /** Bytes IN THE FILE - the compressed size when `compression` is set. */
+    length: number;
+    dtype: PlaneDtype;
+    /** Values per splat. Stored COMPONENT-major: all c0, then all c1, ... */
+    components: number;
+    count: number;
+    compression?: PlaneCodec;
+    /** Bytes after inflation. Normative when `compression` is set. */
+    uncompressedLength?: number;
+}
+interface PlanarHeader {
+    format: string;
+    version: number;
+    precision: 'fp16' | 'q23';
+    numSplats: number;
+    numBones: number;
+    topK: number;
+    bounds: {
+        min: number[];
+        max: number[];
+    };
+    /** q23 only - normative, positions cannot be reconstructed without them. */
+    logScale?: {
+        min: number[];
+        max: number[];
+    };
+    logitOpacity?: {
+        min: number;
+        max: number;
+    };
+    bonePalette?: number[];
+    joints?: {
+        count: number;
+    };
+    /** Free-form; informational. The plane table is what the decoder obeys. */
+    encoding?: {
+        planeCompression?: PlaneCodec | null;
+    };
+    planes: Record<string, PlaneInfo>;
+}
+/** The 8-byte ASCII magic, or `''` when the buffer is too short to have one. */
+declare function readMagic(buffer: ArrayBuffer): string;
+/** True when `magic` names a planar container this module can decode. */
+declare function isPlanarMagic(magic: string): boolean;
+/**
+ * Decode a planar character bundle into the Float32 arrays the GPU pipeline
+ * expects, plus the skinning and joint data.
+ *
+ * Returns the same shape `parseBinaryGsplat` returns for the interleaved
+ * container (minus the animation chunk, which planar files do not carry - clips
+ * are registered separately), so both feed one `loadBinaryGsplat`.
+ */
+declare function parsePlanarSplats(buffer: ArrayBuffer): Promise<{
+    result: {
+        header: PlanarHeader;
+        numSplats: number;
+        splats: {
+            x: Float32Array<ArrayBuffer>;
+            y: Float32Array<ArrayBuffer>;
+            z: Float32Array<ArrayBuffer>;
+            scale_0: Float32Array<ArrayBuffer>;
+            scale_1: Float32Array<ArrayBuffer>;
+            scale_2: Float32Array<ArrayBuffer>;
+            rot_0: Float32Array<ArrayBuffer>;
+            rot_1: Float32Array<ArrayBuffer>;
+            rot_2: Float32Array<ArrayBuffer>;
+            rot_3: Float32Array<ArrayBuffer>;
+            f_dc_0: Float32Array<ArrayBuffer>;
+            f_dc_1: Float32Array<ArrayBuffer>;
+            f_dc_2: Float32Array<ArrayBuffer>;
+            opacity: Float32Array<ArrayBuffer>;
+        };
+        boneIndices: Uint16Array<ArrayBufferLike> | null;
+        boneWeights: Float32Array<ArrayBufferLike> | null;
+        animationArray: Float32Array | null;
+        animNumFrames: number;
+        animNumBones: number;
+        jointsArray: Float32Array<ArrayBufferLike> | null;
+        nativeFloat16: boolean;
+        planeCompression: PlaneCodec | null;
+    };
+    transferables: ArrayBuffer[];
+}>;
+export { parsePlanarSplats, readMagic, isPlanarMagic, PLANAR_CONTAINERS, FIRST_PLANAR_VERSION };
+export type { PlanarHeader, PlaneInfo, PlaneCodec, PlaneDtype };

package/dist/types/loader/character/load.d.ts

@@ -0,0 +1,33 @@
+import type { SplatSource } from '../../splat/splat';
+import type { ArmatureData } from '../../types';
+/** A clip embedded in a legacy character bundle: per-frame, per-bone 4x4 matrices. */
+export interface RawAnimationData {
+    data: Float32Array;
+    numFrames: number;
+    numBones: number;
+    keyframeFrames?: number[];
+}
+/** A decoded character bundle, ready to become a {@link Splat} and an {@link Armature}. */
+export interface CharacterBundle {
+    source: SplatSource;
+    armatureData?: ArmatureData;
+    animationData?: RawAnimationData;
+}
+/**
+ * Decode a character bundle held in memory.
+ *
+ * Accepts every container the reader implements - `VIGGCHAR` (`.vsplat`) and
+ * the legacy `.bin` layouts - and dispatches on the file's own magic, never on
+ * a filename.
+ *
+ * Decoding runs on the calling thread. A bundle is a few megabytes and decodes
+ * in single-digit milliseconds, which does not earn the packaging cost of a
+ * separate worker file.
+ *
+ * @throws {CharacterBundleError} carrying the format spec's error category.
+ */
+export declare function decodeCharacterBundle(file: ArrayBuffer): Promise<CharacterBundle>;
+/** Fetch and decode a character bundle. */
+export declare function loadCharacterBundle(url: string): Promise<CharacterBundle>;
+/** Decode a character bundle from bytes already in memory. */
+export declare function loadCharacterBundleFromBytes(bytes: Uint8Array): Promise<CharacterBundle>;

package/dist/types/loader/character/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The one interface every character-bundle version handler satisfies, and the
+ * one error type they all fail with.
+ *
+ * This module is version-agnostic on purpose and holds no knowledge of any
+ * particular version: it is the boundary that lets `index.ts` treat `v1/` and
+ * `legacy/` as interchangeable, and the reason adding version N+1 costs exactly
+ * one module and one registry entry
+ * (character-bundle format spec, R2/R3).
+ */
+/**
+ * Error categories, from the spec's `Errors` table.
+ *
+ * A caller distinguishes "not our file" (`WrongMagic`) from "our file, broken"
+ * (everything else) without parsing a message string.
+ */
+type BundleErrorCategory = 'WrongMagic' | 'UnknownVersion' | 'Truncated' | 'MalformedHeader' | 'UnalignedPayload' | 'MissingField' | 'UnexpectedField' | 'BadFieldValue' | 'BlockSizeMismatch' | 'InconsistentHeader';
+/**
+ * A rejection carrying its category.
+ *
+ * The category travels over the worker boundary alongside the message, so the
+ * main thread can tell a foreign file from a corrupt one without re-reading the
+ * bytes. The message names the offending block or field and reports the value
+ * found next to the value expected.
+ */
+declare class CharacterBundleError extends Error {
+    readonly category: BundleErrorCategory;
+    constructor(category: BundleErrorCategory, message: string);
+}
+/** The 14 Float32 attribute arrays the GPU pipeline consumes, one per column. */
+interface SplatAttributes {
+    x: Float32Array;
+    y: Float32Array;
+    z: Float32Array;
+    scale_0: Float32Array;
+    scale_1: Float32Array;
+    scale_2: Float32Array;
+    /** Quaternion `w`. The engine wants `wxyz`, whatever order the file stores. */
+    rot_0: Float32Array;
+    rot_1: Float32Array;
+    rot_2: Float32Array;
+    rot_3: Float32Array;
+    f_dc_0: Float32Array;
+    f_dc_1: Float32Array;
+    f_dc_2: Float32Array;
+    /** The LOGIT, not the alpha. */
+    opacity: Float32Array;
+}
+/**
+ * The version-independent decode output. Every handler returns this shape and a
+ * caller cannot tell from it which handler ran.
+ *
+ * Three of these fields exist because the answer differs per version and the
+ * QUESTION does not, so asking it downstream would put a per-version branch
+ * outside the handlers - the one thing R2 forbids:
+ *
+ * - `rigBoneCount` - the legacy containers spell the rig's size three
+ *   different ways across two magics; version 1 has no header key for it at all
+ *   and derives it from `blocks.joints.count`.
+ * - `corrected` - the legacy containers carry a correction receipt, in either
+ *   of two spellings, and files exist both with and without it. Version 1 needs
+ *   no receipt: the version itself means corrected, and the spec forbids a
+ *   reader from looking for a signal.
+ * - `bundledRestIsPerCharacter` - whether `jointsArray` is this character's own
+ *   vetted rest pose, i.e. whether a consumer may pose the splats against it
+ *   instead of against the shared canonical tables.
+ */
+interface DecodedBundle {
+    /** The version's own header, verbatim. Diagnostics; nothing dispatches on it. */
+    header: unknown;
+    numSplats: number;
+    splats: SplatAttributes;
+    /** `numSplats * K` global rig indices, or `null` when unskinned. */
+    boneIndices: Uint16Array | null;
+    /** `numSplats * K` weights, matching `boneIndices`, or `null`. */
+    boneWeights: Float32Array | null;
+    animationArray: Float32Array | null;
+    animNumFrames: number;
+    animNumBones: number;
+    /** Flat `[x,y,z] * rigBoneCount` rest translations, or `null` when no rig. */
+    jointsArray: Float32Array | null;
+    /** Bones in the rig this bundle poses. `0` when it carries no rig. */
+    rigBoneCount: number;
+    /** Whether the geometric corrections are baked into the splats and joints. */
+    corrected: boolean;
+    /**
+     * Whether `jointsArray` is this character's OWN rest pose, vetted against the
+     * gaussians it ships with - i.e. whether posing the splats from it (rather
+     * than from the shared canonical rest tables) is correct.
+     *
+     * A separate question from `corrected`, and deliberately not derived from it.
+     * `corrected` answers "did the correction pipeline run", which some legacy
+     * files answer yes to and others no, from the same generation of writer;
+     * this one answers "is the joints block authoritative", which is a property
+     * of the CONTAINER:
+     *
+     * - version 1 - yes, by definition. The joint canonicalisation, the ankle
+     *   pitch bake and the ground shift are all baked into the gaussians AND
+     *   into this block, so the two agree and nothing else does.
+     * - legacy    - no. Those joints were written for diagnostics, were never
+     *   vetted as a posing rest, and the shipped characters render today against
+     *   the canonical tables.
+     *
+     * Read by `Character`'s ground-convention shim, which must be able to tell
+     * a v1 bundle from a legacy one WITHOUT keying on `corrected` - some legacy
+     * bundles carry a receipt, and moving those would move already-shipped
+     * characters. See `Character.bakedGroundShiftY`.
+     */
+    bundledRestIsPerCharacter: boolean;
+}
+/**
+ * What a handler hands back: the bundle, plus the buffers the worker may
+ * transfer instead of copying.
+ */
+interface DecodeResult {
+    result: DecodedBundle;
+    transferables: ArrayBuffer[];
+}
+/**
+ * One payload version's reader.
+ *
+ * Given the whole file, the offset its payload begins at, and how long that
+ * payload is. A handler is total over its own version, never learns that
+ * another version exists, and never re-checks the magic or the version - the
+ * dispatcher owns both.
+ */
+type VersionHandler = (file: ArrayBuffer, payloadOffset: number, payloadLength: number) => Promise<DecodeResult>;
+export { CharacterBundleError };
+export type { BundleErrorCategory, DecodeResult, DecodedBundle, SplatAttributes, VersionHandler, };

package/dist/types/loader/character/v1/decode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `VIGGCHAR` version 1 - the quantised block payload.
+ *
+ * Written from the character-bundle format spec and from nothing else.
+ * A JSON header with exactly two keys, `numSplats` and `blocks`, followed by
+ * the blocks it lists. Each block holds one attribute for every gaussian,
+ * stored component-major, and each block's entry carries everything needed to
+ * decode THAT block - its dequantisation bounds, its palette. There is no
+ * top-level decoding parameter and no file-wide precision mode.
+ *
+ * This handler is total over version 1 and knows that no other version exists.
+ * It never re-checks the magic or the version: the dispatcher owns both.
+ *
+ * Vocabulary note: this format says BLOCKS. The legacy containers next door say
+ * planes and chunks. The difference is deliberate - a block is self-describing
+ * in a way a plane was not, and keeping the words apart keeps the two readers
+ * from being read as one.
+ */
+import type { DecodeResult } from '../types';
+/**
+ * Decode a `VIGGCHAR` version 1 payload.
+ *
+ * Version 1 means CORRECTED: the ankle pitch bake and then the ground shift are
+ * already in the gaussians and in the `joints` block, and the character stands
+ * on `y = 0` by construction. There is no in-file signal about that and nothing
+ * below looks for one - the version answered it.
+ *
+ * The decode is straight-line and never yields; it is declared `async` only
+ * because `VersionHandler` is promise-shaped for the handlers that must be.
+ */
+declare function decodeV1(file: ArrayBuffer, payloadOffset: number, payloadLength: number): Promise<DecodeResult>;
+export { decodeV1 };

package/dist/types/loader/environment/ply.d.ts

@@ -0,0 +1,16 @@
+import type { SplatAttributes } from '../character/types';
+/**
+ * Parse an uncompressed 3D Gaussian Splatting `.ply` (the layout written by
+ * the reference trainer and most tools since): one binary little-endian
+ * `vertex` element carrying position, log-scale, a `wxyz` rotation, the
+ * spherical-harmonic DC colour and a logit opacity.
+ *
+ * Higher-order SH (`f_rest_*`) and normals are skipped: splats here are lit
+ * flat, by their DC colour.
+ *
+ * @throws If the file is not a binary little-endian PLY, or lacks a required property.
+ */
+export declare function parseGaussianPly(file: ArrayBuffer): {
+    numSplats: number;
+    splats: SplatAttributes;
+};

package/dist/types/loader/shared/bin-cache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Fetch through a persistent Cache API layer with a 1-hour TTL.
+ *   - Assets with cacheable extensions (.bin, .vsplat, .anim, .ply, …) →
+ *     cached in Cache API
+ *   - Signed URLs (with ?verify= or ?X-Amz-) → query stripped for cache key
+ *   - No-store assets → never persisted. `NO_STORE_EXTENSIONS` is empty
+ *     today, so nothing takes this branch; see its declaration.
+ * Server `Cache-Control: max-age` and `Expires` headers are honored as a cap
+ * when they provide a positive TTL.
+ * On network error, a stale cached copy is returned in preference to throwing.
+ */
+declare function cachedFetch(url: string, init?: RequestInit): Promise<Response>;
+/**
+ * Sweep the persistent cache and delete every entry whose stamp is in the
+ * past. Intended to run once per app boot, non-blocking, to keep the Cache
+ * API store from accumulating dead entries across sessions.
+ */
+declare function evictExpired(): Promise<number>;
+export { cachedFetch, evictExpired };

package/dist/types/loader/skeleton/index.d.ts

@@ -0,0 +1,19 @@
+/** @group Characters & Animation */
+export interface SkeletonLibrary {
+    boneNames?: string[];
+    skeleton1185Names?: string[];
+    skeleton1185StrippedNames?: string[];
+    stdMaleRestTranslations?: Float32Array;
+    stdMaleRestRotations?: Float32Array;
+    stdMaleParents?: Int32Array;
+    boneNames441?: string[];
+    restTranslations441?: Float32Array;
+    restRotations441?: Float32Array;
+    parents441?: Int32Array;
+}
+export declare function getStripped1185Names(library: SkeletonLibrary): string[] | undefined;
+/**
+ * Build the skeleton library from inlined data.
+ * No network requests - all data is bundled in the engine.
+ */
+export declare function loadSkeletonLibrary(): SkeletonLibrary;

package/dist/types/loader/skeleton/skeleton-data-441.d.ts

@@ -0,0 +1,5 @@
+export declare const NUM_BONES_441 = 441;
+export declare const BONE_NAMES_441: string[];
+export declare const PARENTS_441: number[];
+export declare const REST_TRANSLATIONS_441: number[];
+export declare const REST_ROTATIONS_441: number[];

package/dist/types/loader/skeleton/skeleton-data.d.ts

@@ -0,0 +1,6 @@
+export declare const NUM_BONES = 86;
+export declare const BONE_NAMES: string[];
+export declare const SKELETON_1185_NAMES: string[];
+export declare const REST_TRANSLATIONS: number[];
+export declare const REST_ROTATIONS: number[];
+export declare const PARENTS: number[];

package/dist/types/math.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Internal math kernel for the skeletal core.
+ *
+ * The rig, animation and skinning code is shared with the PlayCanvas build of
+ * this engine and was written against that engine's `Vec3` / `Quat` / `Mat4`.
+ * These classes keep the same method names, argument orders and formulas, so
+ * the shared files compile unchanged and the bone matrices they produce match
+ * the PlayCanvas build to float precision - which is what the A/B suite checks.
+ *
+ * Deliberately NOT `THREE.Vector3` and friends: the conventions differ in ways
+ * that silently change results (`lerp(a, b, t)` vs `lerp(v, t)`, a two-argument
+ * `cross`, a `Float32Array`-backed matrix), and a port that swapped them by
+ * hand would be a port nobody could diff against the original.
+ *
+ * Nothing here is part of the public API. Values cross into three.js types at
+ * the `Character` / `Armature` boundary.
+ */
+export declare class Vec3 {
+    x: number;
+    y: number;
+    z: number;
+    constructor(x?: number, y?: number, z?: number);
+    set(x: number, y: number, z: number): this;
+    copy(rhs: {
+        x: number;
+        y: number;
+        z: number;
+    }): this;
+    clone(): Vec3;
+    add(rhs: Vec3): this;
+    add2(lhs: Vec3, rhs: Vec3): this;
+    sub2(lhs: Vec3, rhs: Vec3): this;
+    mulScalar(scalar: number): this;
+    dot(rhs: Vec3): number;
+    cross(lhs: Vec3, rhs: Vec3): this;
+    length(): number;
+    normalize(): this;
+    lerp(lhs: Vec3, rhs: Vec3, alpha: number): this;
+}
+export declare class Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    constructor(x?: number, y?: number, z?: number, w?: number);
+    set(x: number, y: number, z: number, w: number): this;
+    copy(rhs: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }): this;
+    clone(): Quat;
+    conjugate(): this;
+    dot(other: Quat): number;
+    length(): number;
+    mulScalar(scalar: number): this;
+    normalize(): this;
+    /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
+    mul2(lhs: Quat, rhs: Quat): this;
+    mul(rhs: Quat): this;
+    slerp(lhs: Quat, rhs: Quat, alpha: number): this;
+    /** Rotation of the upper 3x3 of `m`, with any scale (and a mirror) divided out. */
+    setFromMat4(m: Mat4): this;
+}
+/** Column-major 4x4, `Float32Array`-backed. Same element layout as `THREE.Matrix4.elements`. */
+export declare class Mat4 {
+    data: Float32Array;
+    constructor();
+    copy(rhs: Mat4): this;
+    clone(): Mat4;
+    setIdentity(): this;
+    /** Copy from any 16-element column-major source (e.g. `THREE.Matrix4.elements`). */
+    setFromArray(src: ArrayLike<number>): this;
+    setTRS(t: Vec3, r: Quat, s: Vec3): this;
+    /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
+    mul2(lhs: Mat4, rhs: Mat4): this;
+    mul(rhs: Mat4): this;
+    invert(): this;
+    getTranslation(t?: Vec3): Vec3;
+    getScale(scale?: Vec3): Vec3;
+}

package/dist/types/skeletal/animation-player.d.ts

@@ -0,0 +1,185 @@
+import type { Animation, AnimationEvent } from '../animation';
+import type { Pose } from './pose';
+import type { Skeleton } from './skeleton';
+/**
+ * Resolves an animation by name and returns an already-filtered/converted
+ * {@link Animation}, or `null` if not registered. Lets {@link AnimationPlayer}
+ * stay free of `SplatEngine` and `SkeletonLibrary`.
+ *
+ * @group Characters & Animation
+ */
+export type AnimationProvider = (name: string) => Animation | null;
+/**
+ * Options for {@link AnimationPlayer.crossfadeTo}.
+ *
+ * @group Characters & Animation
+ */
+export interface CrossfadeOptions {
+    /** Blend duration in seconds. Defaults to `defaultCrossfadeDuration`. */
+    duration?: number;
+    /** Loop the target animation. Default `true`. */
+    loop?: boolean;
+    /**
+     * Preserve the current animation's normalized phase
+     * (`animTime / numFrames`) when crossfading. Useful for "style change"
+     * crossfades where the new looping animation should start at the same
+     * cycle position as the outgoing one (e.g. switching idle variants
+     * mid-cycle without a snap). Default `false` - new anim starts at
+     * frame 0.
+     */
+    preserveTime?: boolean;
+}
+/**
+ * Callback fired when {@link AnimationPlayer.tick} crosses a frame that has
+ * one or more {@link AnimationEvent}s on the active animation.
+ *
+ * @group Characters & Animation
+ */
+export type AnimEventCallback = (event: AnimationEvent) => void;
+/**
+ * Skeletal animation state machine. Owns playback state (current animation,
+ * time, loop flag, crossfade window) and writes the per-bone target pose into
+ * a caller-owned {@link Pose} each `update`.
+ *
+ * Knows nothing about splats, entities, or bone names. Output is a raw
+ * crossfaded pose; rig-convention clamps (pelvis X/Z lock, root-bone clamp,
+ * root-motion extraction onto the armature pivot) are the
+ * {@link Armature} facade's job.
+ *
+ * @group Characters & Animation
+ */
+export declare class AnimationPlayer {
+    /** Default crossfade duration when {@link CrossfadeOptions.duration} is omitted. */
+    defaultCrossfadeDuration: number;
+    /** Frame rate used to convert `dt` (seconds) to frame time. Default `30`. */
+    frameRate: number;
+    /**
+     * Playback-speed multiplier applied to `dt` in {@link tick}. `1` = author
+     * speed, `2` = double speed, `0.5` = half. Unlike {@link frameRate} this
+     * scales only how fast time advances - the clip's authored frame rate (and
+     * thus event-frame mapping) is unchanged. Lets a game tie a locomotion
+     * clip's speed to the pivot's actual movement speed. Crossfade blending is
+     * deliberately NOT sped up (it runs on real `dt`), so style swaps stay
+     * smooth regardless of playback speed.
+     */
+    playbackSpeed: number;
+    private readonly _skeleton;
+    private readonly _provider;
+    private _active;
+    private _animName;
+    private _animData;
+    private _keyframes;
+    private _keyframesReady;
+    private _animTime;
+    private _loop;
+    private _paused;
+    private _blendToRest;
+    private _crossfadeTime;
+    private _crossfadeDuration;
+    private readonly _snapshot;
+    private _lastTickFrame;
+    private readonly _eventListeners;
+    private readonly _tmpPos;
+    private readonly _tmpRot;
+    private readonly _tmpScale;
+    private readonly _tmpSlerpRot;
+    private readonly _tmpToRot;
+    private readonly _restIn;
+    private readonly _restOut;
+    private readonly _splineValues;
+    constructor(opts: {
+        skeleton: Skeleton;
+        animationProvider: AnimationProvider;
+        snapshotPose: Pose;
+    });
+    get isPlaying(): boolean;
+    get isFinished(): boolean;
+    get paused(): boolean;
+    set paused(v: boolean);
+    get animationTime(): number;
+    set animationTime(v: number);
+    get animationDuration(): number;
+    /**
+     * Crossfade alpha in `[0, 1]`. `0` when no crossfade is active or one just
+     * started; `1` when the in-progress crossfade has reached its terminal
+     * blend. Useful for games that want to gate logic on "the rig has fully
+     * committed to the new pose" without reaching into player internals.
+     */
+    get crossfadeProgress(): number;
+    /**
+     * Name of the currently-playing animation, or `null` if no animation is
+     * active (after {@link AnimationPlayer.stop} with `fadeDuration: 0`, or
+     * before the first {@link AnimationPlayer.play}).
+     */
+    get currentAnimationName(): string | null;
+    /**
+     * Subscribe to frame-aligned {@link AnimationEvent}s on the currently-
+     * playing animation. The callback fires once per crossed frame, after the
+     * `tick` advances `animTime`.
+     *
+     * @returns an unsubscribe handle.
+     */
+    onAnimEvent(cb: AnimEventCallback): () => void;
+    private _dispatchEventsForFrameTransition;
+    private _fireEvent;
+    /**
+     * Start an animation immediately (no crossfade). Restarts from frame 0.
+     * Returns `false` if `name` isn't resolvable through the provider.
+     */
+    play(name: string, opts?: {
+        loop?: boolean;
+    }): boolean;
+    /**
+     * Crossfade from `currentPose` to `name` over `opts.duration` seconds. The
+     * current pose is captured into the internal snapshot - caller can keep
+     * mutating `currentPose` after the call returns.
+     */
+    crossfadeTo(name: string, currentPose: Pose, opts?: CrossfadeOptions): boolean;
+    /**
+     * Snap any active crossfade to its terminal state (alpha = 1, target pose
+     * fully applied) on the next {@link AnimationPlayer.evaluate}. No-op if no
+     * crossfade is active. Useful when a game scrubs through animation frames
+     * for precompute and wants per-frame poses without the blend artefacts of
+     * a still-in-progress crossfade.
+     */
+    endCrossfade(): void;
+    /**
+     * Stop playback. With `fadeDuration > 0`, snapshots `currentPose` and
+     * crossfades back to bind over `fadeDuration` seconds. With `0`, deactivates
+     * immediately (the caller is expected to reset the pose to bind).
+     */
+    stop(currentPose: Pose, fadeDuration?: number): void;
+    /**
+     * Advance animation time by `dt` seconds. Always cheap - call every frame
+     * even for off-screen characters so they resume at the correct frame when
+     * the camera pans back. Does **not** write to any `Pose`.
+     *
+     * Returns `wrapped: true` if `animTime` rolled past the end of a looping
+     * animation on this tick. The facade uses that signal to suppress the
+     * end-to-start pelvis discontinuity when extracting root motion.
+     */
+    tick(dt: number): {
+        wrapped: boolean;
+    };
+    /**
+     * Evaluate the current pose at the current `animTime` into `outPose`,
+     * applying the crossfade blend with the internal snapshot if one is active.
+     *
+     * Returns `blendToRestComplete: true` once on the tick a previously-
+     * scheduled `stop(_, fade > 0)` reaches alpha 1 - the facade uses that to
+     * snap pose to bind and reset rootMotion baseline.
+     *
+     * Skip this call when the character is off-screen; `tick` keeps time
+     * advancing in the meantime, so the next on-screen frame evaluates straight
+     * to the correct pose with no visible pop.
+     */
+    evaluate(outPose: Pose): {
+        blendToRestComplete: boolean;
+    };
+    private _activate;
+    private _deactivate;
+    private _prepareKeyframes;
+    private _evalTargetPose;
+    private _evaluateSpline;
+    private _applyFromRest;
+}