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

package/dist/types/three/splat-character.d.ts

@@ -0,0 +1,192 @@
+import { Matrix4, Object3D, Vector3 } from 'three';
+import type { ColorRepresentation, Object3DEventMap } from 'three';
+import type { Animation } from '../animation';
+import type { Armature } from '../armature';
+import { Character } from '../character';
+import type { SplatEngine } from '../engine';
+import type { CharacterBundle } from '../loader/character/load';
+import type { BodyRegion, BoneMask } from '../skeletal/bone-mask';
+import type { Splat } from '../splat/splat';
+/**
+ * What a clip's horizontal travel does to the character.
+ *
+ * - `'off'` - the clip plays in place.
+ * - `'apply'` - the character's body moves with the clip, beneath
+ *   {@link SplatCharacter.position}, which stays where you put it.
+ * - `'extract'` - the clip plays in place and its travel is handed to you by
+ *   {@link SplatCharacter.consumeRootMotion}, to feed a controller or physics.
+ *
+ * @group Characters & Animation
+ */
+export type SplatRootMotion = 'off' | 'apply' | 'extract';
+/** @group Characters & Animation */
+export interface SplatPlayOptions {
+    /** Repeat when the clip ends. Default `true`. */
+    loop?: boolean;
+}
+/** @group Characters & Animation */
+export interface SplatCrossFadeOptions extends SplatPlayOptions {
+    /** Start the new clip at the same fraction of its length the old one had reached. Default `false`. */
+    preserveTime?: boolean;
+}
+/** @group Characters & Animation */
+export interface SplatLayerOptions {
+    /** The bones the layer drives, as a named region. Give this or `mask`. */
+    region?: BodyRegion;
+    /** The bones the layer drives, as an explicit mask. Give this or `region`. */
+    mask?: BoneMask;
+    /** Repeat when the clip ends. Default `true`. */
+    loop?: boolean;
+    /** Seconds to blend the layer in. Default `0`. */
+    fadeDuration?: number;
+    /** How strongly the layer overrides the base pose, 0..1. Default `1`. */
+    weight?: number;
+}
+/**
+ * Events a {@link SplatCharacter} dispatches, alongside the usual `Object3D` ones.
+ * @group Characters & Animation
+ */
+export interface SplatCharacterEventMap extends Object3DEventMap {
+    /** A non-looping clip reached its last frame. */
+    finished: {
+        clip: Animation;
+    };
+    /** A looping clip wrapped around to its start. */
+    loop: {
+        clip: Animation;
+    };
+    /** An event authored into the clip was crossed. */
+    clipevent: {
+        clip: Animation | null;
+        name: string;
+        frame: number;
+        payload?: unknown;
+    };
+}
+/**
+ * A gaussian-splat character, as a three.js object.
+ *
+ * Add it to a scene, move it with `position` / `rotation` / `scale`, and call
+ * {@link SplatCharacter.update} once per frame - the role `AnimationMixer.update`
+ * plays for a skinned mesh. Create one with {@link VSplatLoader}.
+ *
+ * ```ts
+ * const character = await new VSplatLoader().loadAsync('/assets/hero.vsplat');
+ * scene.add(character);
+ * character.position.set(1, 0, 0);
+ *
+ * const run = await new SplatClipLoader().loadAsync('/assets/run.glb');
+ * character.play(run);
+ *
+ * renderer.setAnimationLoop(() => {
+ *   character.update(clock.getDelta());
+ *   renderer.render(scene, camera);
+ * });
+ * ```
+ *
+ * `position` is the model origin. A character in its rest pose stands on it;
+ * how closely a clip keeps the feet on it depends on the clip.
+ *
+ * Animation is driven by this class rather than by `AnimationMixer`: a splat
+ * character has no `Bone` hierarchy for a mixer to write to. Clips are
+ * {@link Animation} objects from {@link SplatClipLoader}.
+ *
+ * @group Characters & Animation
+ */
+export declare class SplatCharacter extends Object3D<SplatCharacterEventMap> {
+    /** Type flag, in the three.js manner. */
+    readonly isSplatCharacter = true;
+    readonly type: string;
+    /**
+     * The engine-level character this object wraps. Everything not surfaced
+     * here - multi-level LOD, variant splats, animation LOD - is reachable
+     * through it.
+     */
+    readonly character: Character;
+    private readonly _engine;
+    private readonly _bundles;
+    private _clip;
+    private _loop;
+    private _finishedSent;
+    private _rootMotion;
+    private _disposed;
+    /**
+     * @param bundles - Decoded character bundles, finest level of detail first.
+     * They are read, never modified, so clones share them.
+     * @internal Use {@link VSplatLoader}.
+     */
+    constructor(engine: SplatEngine, bundles: CharacterBundle[], name?: string);
+    /** The rig: bone names, bone matrices, bone-length scaling. */
+    get armature(): Armature;
+    /** The splats that draw this character, one per level of detail. */
+    get splats(): readonly Splat[];
+    /**
+     * Advance the animation by `delta` seconds and pose the splats. Call once
+     * per frame, before rendering.
+     */
+    update(delta: number): void;
+    /** Start `clip` from its first frame, cutting from whatever was playing. */
+    play(clip: Animation, options?: SplatPlayOptions): this;
+    /** Blend from the current pose into `clip` over `duration` seconds. */
+    crossFadeTo(clip: Animation, duration?: number, options?: SplatCrossFadeOptions): this;
+    /** Stop playback and return to the rest pose, blending over `fadeDuration` seconds. */
+    stop(fadeDuration?: number): this;
+    /**
+     * Play `clip` on a named layer that overrides part of the body - an upper
+     * body wave over a full-body run, say. Calling it again with the same layer
+     * name replaces what that layer plays.
+     */
+    playLayer(layer: string, clip: Animation, options: SplatLayerOptions): this;
+    setLayerWeight(layer: string, weight: number): this;
+    stopLayer(layer: string, fadeDuration?: number): this;
+    /** The clip the base track is playing, or `null`. */
+    get clip(): Animation | null;
+    get isPlaying(): boolean;
+    get paused(): boolean;
+    set paused(value: boolean);
+    /** Playback speed multiplier. `1` is the authored speed. */
+    get timeScale(): number;
+    set timeScale(value: number);
+    /** Position in the current clip, in seconds. */
+    get time(): number;
+    set time(seconds: number);
+    /** Length of the current clip in seconds, or `0` when nothing is playing. */
+    get duration(): number;
+    /** See {@link SplatRootMotion}. Applies to the current clip and every later one. */
+    get rootMotion(): SplatRootMotion;
+    set rootMotion(mode: SplatRootMotion);
+    /**
+     * The clip's horizontal travel since the last call, in this object's local
+     * space. Non-zero only in `'extract'` mode. `y` is always `0`.
+     */
+    consumeRootMotion(target?: Vector3): Vector3;
+    /**
+     * Blend the character's colour toward `color` by `amount` (0..1) - a hit
+     * flash, a selection highlight. `amount = 0` restores the authored colour.
+     */
+    setTint(color: ColorRepresentation, amount?: number): this;
+    /** Contrast and saturation multipliers for the character's colour. `(1, 1)` is unchanged. */
+    setGrade(contrast: number, saturation: number): this;
+    /** Bone names, in rig order. */
+    get boneNames(): readonly string[];
+    /**
+     * World matrix of a bone as of the last {@link SplatCharacter.update} - for
+     * attaching a prop to a hand, or aiming a camera at a head.
+     *
+     * @returns `target`, or `null` when the rig has no bone of that name.
+     */
+    getBoneWorldMatrix(name: string, target?: Matrix4): Matrix4 | null;
+    /**
+     * A second character from the same decoded data, at the same transform. The
+     * copy starts in the rest pose with nothing playing; it does not share this
+     * one's animation state.
+     */
+    clone(): this;
+    /**
+     * Release every GPU resource the character holds. The object stays in the
+     * scene graph, empty; remove it yourself if you no longer want it there.
+     */
+    dispose(): void;
+    private _keyFor;
+    private _started;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared data shapes used across the loader, skeletal and splat layers.
+ */
+/**
+ * Rig description handed to {@link Armature}.
+ *
+ * The `stdMale*` field names are inherited from the skeleton library and mean
+ * "the rest pose this armature binds to", whichever rig that is.
+ */
+export interface ArmatureData {
+    numBones: number;
+    /** Flat `[x,y,z] * numBones` rest translations carried by the character bundle. */
+    joints?: Float32Array;
+    /** Whether the bundle's geometric corrections are baked into its splats and joints. */
+    corrected?: boolean;
+    /** Whether `joints` is this character's own vetted rest pose. */
+    restIsPerCharacter?: boolean;
+    skeleton?: Int32Array;
+    stdMaleRestTranslations?: Float32Array;
+    stdMaleRestRotations?: Float32Array;
+    stdMaleParents?: Int32Array;
+}
+/** Per-splat skinning influences, `K` slots per splat. */
+export interface SplatWeights {
+    /** `numSplats * K` rig bone indices. */
+    indices: Uint16Array;
+    /** `numSplats * K` weights, matching `indices`. */
+    weights: Float32Array;
+}
+export type { SkeletonLibrary } from './loader/skeleton';

package/dist/types/webgpu.d.ts

@@ -0,0 +1,5 @@
+import { WebGPUSplatBackend } from './splat/webgpu/backend';
+export * from './index';
+export { WebGPUSplatBackend };
+export { MAX_POINT_LIGHTS } from './splat/webgpu/lighting';
+export { MAX_VARIANT_GROUPS } from './splat/webgpu/splat-mesh';