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

package/dist/index.js

@@ -0,0 +1,56 @@
+import {
+  Animation,
+  Armature,
+  Character,
+  CharacterBundleError,
+  EngineDisposedError,
+  Environment,
+  PointLight,
+  SkyLight,
+  Splat,
+  SplatCharacter,
+  SplatClipLoader,
+  SplatEngine,
+  SplatMesh,
+  SplatPLYLoader,
+  SplatQuality,
+  SunLight,
+  VSplatLoader,
+  WebGLSplatBackend,
+  decodeCharacterBundle,
+  loadCharacterBundle,
+  loadCharacterBundleFromBytes,
+  makeRegionMask,
+  packSplats,
+  parseGaussianPly,
+  pruneSplats
+} from "./chunks/chunk-WN5WBKM4.js";
+export {
+  Animation,
+  Armature,
+  Character,
+  CharacterBundleError,
+  EngineDisposedError,
+  Environment,
+  PointLight,
+  SkyLight,
+  Splat,
+  SplatCharacter,
+  Animation as SplatClip,
+  SplatClipLoader,
+  SplatEngine,
+  SplatMesh,
+  SplatPLYLoader,
+  SplatQuality,
+  SunLight,
+  VSplatLoader,
+  WebGLSplatBackend,
+  decodeCharacterBundle,
+  loadCharacterBundle,
+  loadCharacterBundleFromBytes,
+  makeRegionMask,
+  packSplats,
+  parseGaussianPly,
+  pruneSplats
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/types/anim/animation-conversion.d.ts

@@ -0,0 +1,25 @@
+import { Animation } from '../animation';
+import type { SkeletonLibrary } from '../types';
+/**
+ * Walk the raw 4×4 bone matrices stored in `animationData.data` and produce
+ * the per-bone keyframe + spline cache used at playback time.
+ *
+ * Idempotent - subsequent calls on the same `Animation` are no-ops (guarded
+ * by `Animation.skeletalConverted`). {@link Animation.register} calls this
+ * for you.
+ *
+ * Side effect: clears `animationData.data` once converted, since the raw
+ * matrices are no longer needed and would otherwise hold ~16 floats per bone
+ * per frame in memory for the lifetime of the animation.
+ */
+export declare function convertSkeletalAnimation(animationData: Animation, _skeletonLibrary: SkeletonLibrary): void;
+/**
+ * Return a view of `animationData` remapped to the target armature's bone
+ * count, handling rig mismatches (e.g. a 1185-bone source animation played on
+ * an 86-bone body rig). Target bones with no matching source bone stay at
+ * rest pose during playback.
+ *
+ * Result is cached on the input via `Animation.filteredForBones`, so repeated
+ * calls for the same target bone count reuse the filtered copy.
+ */
+export declare function filterAnimationForArmature(animationData: Animation, targetBoneCount: number, skeletonLibrary: SkeletonLibrary): Animation;

package/dist/types/anim/bind-pose.d.ts

@@ -0,0 +1,15 @@
+import { Mat4 } from '../math';
+/**
+ * Walk the rig's rest pose to produce world-space bind-pose matrices, one per
+ * bone. Parents are expected to come before their children in index order (the
+ * skeleton library's bone arrays satisfy this).
+ *
+ * Returns `null` if any of the three arrays is missing - the armature's
+ * `armatureData` carries them as optional fields.
+ */
+export declare function computeBindPoseTransforms(numBones: number, restTranslations: Float32Array, restRotations: Float32Array, parents: Int32Array): Mat4[];
+/**
+ * Compute the inverse of each matrix in `bindPose`. Returns a new array; the
+ * input is left untouched.
+ */
+export declare function invertBindPose(bindPose: Mat4[]): Mat4[];

package/dist/types/anim/keyframe-splines.d.ts

@@ -0,0 +1,59 @@
+import { Quat, Vec3 } from '../math';
+import type { RestPose } from './rest-relative';
+import { CubicSpline } from './spline';
+/** One sample on a per-bone animation curve. */
+export interface Pose {
+    frame: number;
+    position: Vec3;
+    rotation: Quat;
+    scale: Vec3;
+}
+/**
+ * Per-bone keyframe entry: a list of poses sorted by frame plus the cached
+ * cubic spline that interpolates them. `spline` is null when there are fewer
+ * than two poses (a constant-pose bone - the consumer samples `poses[0]`).
+ */
+export interface KeyframeEntryData {
+    poses: Pose[];
+    spline: CubicSpline | null;
+}
+interface RebuildOptions {
+    /** Include poses where `frame === duration`. Default `false`. */
+    includeEnd?: boolean;
+    /** Build a looping spline that wraps at `duration`. Default `false`. */
+    looping?: boolean;
+}
+/**
+ * Filter `poses` against `[0, duration)` (or `[0, duration]` when
+ * `options.includeEnd`), sort by frame, and build the cubic spline that
+ * interpolates them.
+ *
+ * Returns `{ poses, spline }`: a fresh sorted poses array (callers should
+ * replace their original) and the spline, or `null` if fewer than two poses
+ * survive the filter.
+ *
+ * Quaternion sign is normalized along the timeline so neighboring keys take
+ * the short arc - without this the spline would interpolate the long way
+ * around whenever a sample flips hemisphere.
+ */
+export declare function rebuildKeyframeSpline(poses: Pose[], duration: number, options?: RebuildOptions): {
+    poses: Pose[];
+    spline: CubicSpline | null;
+};
+/**
+ * Build the per-bone keyframe array an armature samples from at playback time.
+ *
+ * For each bone in `libraryKeyframes` whose index is below `numBones`:
+ *  1. convert every pose into the bone's rest-relative space (so playback can
+ *     blend a delta on top of the rest pose), and
+ *  2. rebuild the cubic spline, filtered+sorted by frame and wrapped for
+ *     looping if requested.
+ *
+ * Result is a sparse array of length `numBones`; bones not referenced by the
+ * source map stay `null` and fall back to rest pose at evaluation time.
+ *
+ * If `restPose.positions` is empty (rig has no rest data), poses are emitted
+ * unchanged - the rest-relative conversion no-ops.
+ */
+export declare function buildArmatureKeyframes(libraryKeyframes: Map<number, KeyframeEntryData>, numFrames: number, numBones: number, restPose: RestPose, looping: boolean, translationMask?: Uint8Array): Array<KeyframeEntryData | null>;
+export {};

package/dist/types/anim/rest-relative.d.ts

@@ -0,0 +1,32 @@
+import { Quat } from '../math';
+import type { Vec3 } from '../math';
+/**
+ * Rest pose for a rig, stored as parallel arrays indexed by bone. An empty
+ * `positions` array marks an uninitialized rest pose - the rest-relative
+ * conversion functions pass poses through unchanged in that case.
+ */
+export interface RestPose {
+    positions: Vec3[];
+    rotations: Quat[];
+    scales: Vec3[];
+}
+/** A bone-space transform: position, rotation (as quaternion), and scale. */
+export interface BonePose {
+    position: Vec3;
+    rotation: Quat;
+    scale: Vec3;
+}
+/**
+ * Express `pose` relative to the bone's rest transform. Writes the result
+ * into `out`. Safe to call with `out === pose` (in-place).
+ *
+ * If `boneIndex` is out of range or `rest` is uninitialized, `pose` is copied
+ * to `out` unchanged.
+ */
+export declare function toRestRelative(boneIndex: number, pose: BonePose, rest: RestPose, out: BonePose): void;
+/**
+ * Inverse of {@link toRestRelative}: compose a rest-relative `delta` back into
+ * an absolute bone pose. Writes the result into `out`. Safe to call with
+ * `out === delta` (in-place).
+ */
+export declare function fromRestRelative(boneIndex: number, delta: BonePose, rest: RestPose, out: BonePose): void;

package/dist/types/anim/spline.d.ts

@@ -0,0 +1,14 @@
+declare class CubicSpline {
+    times: number[];
+    knots: number[];
+    dim: number;
+    readonly keyframeOffset: number;
+    constructor(times: number[], knots: number[], keyframeOffset?: number);
+    evaluate(time: number, result: number[]): void;
+    getKnot(index: number, result: number[]): void;
+    evaluateSegment(segment: number, t: number, result: number[]): void;
+    static calcKnots(times: number[], points: number[], smoothness: number): number[];
+    static fromPoints(times: number[], points: number[], smoothness?: number): CubicSpline;
+    static fromPointsLooping(length: number, times: number[], points: number[], smoothness?: number): CubicSpline;
+}
+export { CubicSpline };

package/dist/types/animation.d.ts

@@ -0,0 +1,216 @@
+import type { Quat, Vec3 } from './math';
+import type { CubicSpline } from './anim/spline';
+import type { SplatEngine } from './engine';
+/**
+ * A frame-aligned event attached to an {@link Animation}. Events are fired by
+ * {@link AnimationPlayer} as `animTime` crosses each `frame`, dispatched
+ * through {@link Armature.onAnimEvent} / {@link Character.onAnimEvent}.
+ *
+ * The engine treats `name` and `payload` as opaque - games define their own
+ * vocabulary (e.g. `'footstep'`, `'hit-impact'`, `'screen-shake'`) and route
+ * via the listener.
+ *
+ * @group Characters & Animation
+ */
+export interface AnimationEvent {
+    /** Frame index (integer, `0 .. numFrames-1`). */
+    frame: number;
+    /** Game-defined event name. */
+    name: string;
+    /** Optional game-defined payload, opaque to the engine. */
+    payload?: unknown;
+}
+/**
+ * Per-bone keyframe entry inside a {@link SkeletalStore}.
+ * @internal
+ */
+export interface SkeletalKeyframeEntry {
+    poses: Array<{
+        frame: number;
+        position: Vec3;
+        rotation: Quat;
+        scale: Vec3;
+    }>;
+    spline: CubicSpline | null;
+}
+/**
+ * Engine-private cache attached to an {@link Animation} after
+ * {@link convertSkeletalAnimation} processes the raw matrices into
+ * per-bone keyframes + splines. Subsequent registrations and playback reads
+ * go through this store rather than re-walking the raw `Float32Array`.
+ *
+ * @internal
+ */
+export interface SkeletalStore {
+    keyframes: Map<number, SkeletalKeyframeEntry>;
+    manualBones: Set<number>;
+    source: string;
+}
+/**
+ * Parsed skeletal animation data.
+ *
+ * An `Animation` is the deserialized form of one clip, whatever it was
+ * authored as. It holds a flat `Float32Array` of per-bone 4×4 matrices indexed
+ * by frame and bone. Once registered on an engine under a name, characters can play
+ * it via {@link Character.playAnimation} / {@link Character.crossfadeTo}.
+ *
+ * The primary entry point is {@link Animation.loadGlb}, which fetches a
+ * MetaHuman GLB, parses and registers it in one call. For custom fetch
+ * pipelines, use {@link Animation.fromGlb} on an already-fetched
+ * `ArrayBuffer`, then {@link Animation#register} to attach it to the engine.
+ * The `.anim` container is still read, by {@link Animation.load} and
+ * {@link Animation.parse}.
+ *
+ * @group Characters & Animation
+ */
+export declare class Animation {
+    /** Column-major bone matrices (translation at `[12..14]`, the layout
+     *  `THREE.Matrix4.elements` uses), length `numFrames * numBones * 16`. */
+    data: Float32Array;
+    /** Number of animation frames. */
+    numFrames: number;
+    /** Number of bones per frame. */
+    numBones: number;
+    /** Optional sparse keyframe indices. If present, frames between keyframes are interpolated. */
+    keyframeFrames?: number[];
+    /**
+     * Per bone: `1` if this clip drives the bone's translation, `0` if the bone
+     * must keep the armature's own rest translation.
+     *
+     * A constant translation track is not motion - it is the source rig's bone
+     * length. Applied to a character whose skeleton differs, it silently replaces
+     * that character's bone lengths mid-clip while the bind pose keeps the
+     * originals, which compresses the skin. Both readers are built with that in
+     * mind and set a `0` for every bone whose translation holds still, judged from
+     * the decoded data: {@link Animation.fromGlb} per channel, {@link Animation.parse}
+     * across the per-frame matrices. `undefined` means every bone genuinely
+     * translates, and every bone drives its own translation.
+     *
+     * Set once, at parse time, and never mutated afterwards. Playback caches
+     * keyframes per `Animation` object, so a mask that could change would go stale
+     * inside them. `filterAnimationForArmature` remaps rather than edits, onto a
+     * new `Animation` that is its own cache key.
+     *
+     * Consumed by `buildArmatureKeyframes`, which zeroes the position delta for
+     * masked bones so `fromRestRelative` yields `pose.position = restPosition`.
+     */
+    translationMask?: Uint8Array;
+    /**
+     * Frame-aligned events fired as `animTime` advances. Set by
+     * {@link Animation.parse} from the `.anim` header's optional `events` array,
+     * or assigned directly by game code before {@link Animation.register}.
+     */
+    events?: AnimationEvent[];
+    /** @internal Set by convertSkeletalAnimation on first registration. */
+    /** The clip's own name, where its file gave one. Not the name it is registered under. */
+    name: string;
+    /** Frames per second the clip was authored at. `30` unless the file says otherwise. */
+    frameRate: number;
+    /** The name of the most recent {@link Animation.register}, if any. */
+    registeredName?: string;
+    private _registeredIn;
+    /** Length in seconds at the authored frame rate. */
+    get duration(): number;
+    skeletalConverted: boolean;
+    /** @internal Per-bone keyframe cache produced by convertSkeletalAnimation. */
+    skeletalStore?: SkeletalStore;
+    /** @internal Per-target-bone-count cache of `filterAnimationForArmature` outputs. */
+    filteredForBones?: Map<number, Animation>;
+    constructor(data: Float32Array, numFrames: number, numBones: number, keyframeFrames?: number[]);
+    /**
+     * Parse an in-memory `.anim` buffer.
+     *
+     * Accepts both v2 (float32) and v3 (float16) data encodings. Use this when
+     * fetching through a custom pipeline; pair with {@link Animation#register}
+     * to make the result playable. Otherwise prefer {@link Animation.load}, the
+     * fetching wrapper around this one. For a MetaHuman GLB, the current
+     * container, the pair is {@link Animation.fromGlb} / {@link Animation.loadGlb}.
+     *
+     * Also derives {@link Animation#translationMask} from the decoded matrices, so
+     * bones whose translation never moves keep the *target* character's bone
+     * lengths instead of the source rig's.
+     *
+     * @throws If the header is missing, malformed, or not of type `skeletal_animation`.
+     */
+    static parse(buffer: ArrayBuffer): Animation;
+    /**
+     * Parse an in-memory *MetaHuman GLB* - a glTF 2.0 binary holding a bone
+     * hierarchy and one animation clip, carrying no real geometry (as produced
+     * by the offline MetaHuman GLB exporter).
+     *
+     * The result is indistinguishable from {@link Animation.parse} output: the
+     * clip's absolute parent-local TRS is packed into the same flat 4x4 bone
+     * matrices, so every downstream stage - `convertSkeletalAnimation`,
+     * `filterAnimationForArmature`, `AnimationPlayer` - behaves exactly as it
+     * does for a `.anim`.
+     *
+     * `animationName` selects a clip by name when the GLB holds more than one;
+     * omitted, the first clip is used. Pair with {@link Animation#register} to
+     * make the result playable, or use {@link Animation.loadGlb}.
+     *
+     * @throws If the container is not GLB 2.0, or the clip does not supply a
+     * translation and a rotation channel for every bone on one shared timeline.
+     */
+    static fromGlb(buffer: ArrayBuffer, animationName?: string): Animation;
+    /**
+     * {@link Animation.fromGlb} without the frame-rate warning: the clip's own
+     * rate is recorded on {@link Animation.frameRate} for a caller that applies it.
+     * @internal
+     */
+    static parseGlb(buffer: ArrayBuffer, animationName?: string): Animation;
+    /**
+     * Fetch, parse, and register a `.anim` file on the engine under `name`.
+     *
+     * After this resolves, characters can play it via
+     * `character.playAnimation(name)` / `character.crossfadeTo(name)`.
+     *
+     * @throws If the network request fails or the file is not a valid animation.
+     * @example
+     * ```ts
+     * await Animation.load(engine, '/assets/idle.anim', 'idle');
+     * character.playAnimation('idle', { loop: true });
+     * ```
+     */
+    static load(engine: SplatEngine, url: string, name: string): Promise<Animation>;
+    /**
+     * Fetch, parse, and register a MetaHuman GLB on the engine under `name`.
+     * The GLB counterpart of {@link Animation.load}.
+     *
+     * `animationName` selects a clip inside the GLB by name; omitted, the first
+     * clip is used. After this resolves, characters can play it via
+     * `character.playAnimation(name)` / `character.crossfadeTo(name)` - the
+     * source format is invisible from that point on.
+     *
+     * @throws If the network request fails or the GLB is not a valid armature clip.
+     * @example
+     * ```ts
+     * await Animation.loadGlb(engine, '/assets/metahuman_full.glb', 'walk');
+     * character.playAnimation('walk', { loop: true });
+     * ```
+     */
+    static loadGlb(engine: SplatEngine, url: string, name: string, animationName?: string): Promise<Animation>;
+    /**
+     * Process-wide ArrayBuffer cache for .anim URLs. Each `SplatEngine` still
+     * gets its own parsed `Animation` (storage arrays are mutated by the
+     * skeletal converter so they're not safely shareable across scenes),
+     * but the network bytes are shared. Avoids re-downloading the same
+     * idle/walk clips every time the app swaps one engine for another.
+     */
+    private static _bufferCache;
+    private static _bufferLoading;
+    private static _fetchBuffer;
+    /**
+     * Convert the animation data against the engine's skeleton library and
+     * register it under `name` so characters can play it.
+     *
+     * Must be called before {@link Character.playAnimation} / {@link Character.crossfadeTo}
+     * reference this animation.
+     */
+    register(engine: SplatEngine, name: string): void;
+    /**
+     * Remove the clip from the engine it is registered with, so it can be
+     * garbage-collected once nothing is playing it. A character already playing
+     * the clip keeps playing; starting it again registers it afresh.
+     */
+    dispose(): void;
+}