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

package/dist/types/engine.d.ts

@@ -0,0 +1,166 @@
+import { DataTexture, Frustum, Group, Vector3 } from 'three';
+import type { Camera, IUniform, Object3D } from 'three';
+import type { Animation } from './animation';
+import type { AnimLodPreset } from './armature';
+import type { PointLight } from './lighting/point-light';
+import type { SkyLight } from './lighting/sky-light';
+import type { SunLight } from './lighting/sun-light';
+import type { SkeletonLibrary } from './loader/skeleton';
+import type { SplatBackend } from './splat/backend';
+/**
+ * Lights that splats respond to. Splats carry baked colour, so this is a
+ * multiplier on that colour rather than a shading model: ambient plus sun plus
+ * distance-attenuated point lights, evaluated at each splat's centre.
+ *
+ * With no sun and no sky the factor is exactly 1 and splats render as authored.
+ *
+ * @group Lighting
+ */
+export interface SceneLighting {
+    sun: SunLight | null;
+    sky: SkyLight | null;
+    points: PointLight[];
+}
+/** @group Engine */
+export interface SplatEngineOptions {
+    /**
+     * Parent for everything the engine creates. When given, the engine's
+     * {@link SplatEngine.contentRoot} is added to it, so loaded characters and
+     * environments appear without a further `scene.add`.
+     */
+    scene?: Object3D;
+    /** Camera used for visibility gating and distance LOD. Can also be passed to {@link SplatEngine.update}. */
+    camera?: Camera;
+    /**
+     * Force a particular splat backend. Leave unset: each splat then picks the
+     * backend matching the renderer that first draws it.
+     */
+    backend?: SplatBackend;
+}
+/**
+ * Shared state for a set of splat characters and environments: the skeleton
+ * library, the registry of named animation clips, the lights, and the
+ * per-frame update that advances every character.
+ *
+ * This is the three.js counterpart of the PlayCanvas build's `Scene`, minus
+ * everything three.js already owns. It creates no renderer, canvas or camera:
+ * you keep your own `WebGLRenderer`, `Scene` and render loop, and call
+ * {@link SplatEngine.update} once per frame before rendering.
+ *
+ * ```ts
+ * const engine = new SplatEngine({ scene, camera });
+ * const character = await Character.load(engine, '/assets/hero.vsplat');
+ * await Animation.loadGlb(engine, '/assets/idle.glb', 'idle');
+ * character.playAnimation('idle', { loop: true });
+ *
+ * renderer.setAnimationLoop(() => {
+ *   engine.update(clock.getDelta());
+ *   renderer.render(scene, camera);
+ * });
+ * ```
+ *
+ * @group Engine
+ */
+export declare class SplatEngine {
+    /** Parent of every character and environment loaded through this engine. */
+    readonly contentRoot: Group;
+    /** A forced splat backend, or `null` to pick per renderer (the default). */
+    readonly backend: SplatBackend | null;
+    readonly skeletonLibrary: SkeletonLibrary;
+    /** Clips by name. Populated by {@link Animation.register} and the `Animation.load*` helpers. */
+    readonly skeletalAnimationLibrary: Map<string, Animation>;
+    readonly lighting: SceneLighting;
+    /** Camera used for visibility gating and distance LOD. `null` disables both. */
+    camera: Camera | null;
+    /** Default animation-LOD bands for `Armature.setAnimationLod()` called with no arguments. */
+    animLodPreset?: AnimLodPreset;
+    /** Number of {@link SplatEngine.update} calls so far. */
+    frame: number;
+    /** {@link SplatEngine.frame} of the most recent character pose evaluation. */
+    characterPoseUpdatedFrame: number;
+    /**
+     * Lighting uniforms shared by every splat material this engine creates.
+     * Refreshed by {@link SplatEngine.syncLighting}.
+     * @internal
+     */
+    readonly lightingUniforms: {
+        uSunColor: IUniform<Vector3>;
+        uSunIntensity: IUniform<number>;
+        uAmbientColor: IUniform<Vector3>;
+        uPointLightCount: IUniform<number>;
+        uPointLightTex: IUniform<DataTexture>;
+    };
+    private readonly _updaters;
+    private readonly _frustum;
+    private readonly _projScreen;
+    private readonly _cameraPosition;
+    private _frustumValid;
+    private _pointLightCapacity;
+    private _destroyed;
+    constructor(opts?: SplatEngineOptions);
+    get destroyed(): boolean;
+    private static _shared;
+    /**
+     * The engine the loaders use when none is given: one shared skeleton
+     * library, animation registry and set of lights for the whole page. Created
+     * on first use, attached to no scene.
+     */
+    static get shared(): SplatEngine;
+    /**
+     * Advance every auto-updating character by `dt` seconds. Call once per
+     * frame, before rendering.
+     *
+     * @param camera - Optional; replaces {@link SplatEngine.camera} when given.
+     */
+    update(dt: number, camera?: Camera): void;
+    /**
+     * Register a per-frame callback run by {@link SplatEngine.update}.
+     * @returns A function that removes it.
+     * @internal
+     */
+    addUpdater(fn: (dt: number) => void): () => void;
+    /** @internal */
+    removeUpdater(fn: (dt: number) => void): void;
+    /**
+     * The camera frustum as of the last {@link SplatEngine.update}, or
+     * `undefined` when no camera is set - callers treat that as "visible".
+     * @internal
+     */
+    get cameraFrustum(): Frustum | undefined;
+    /**
+     * World-space camera position as of the last {@link SplatEngine.update}, or
+     * `null` when no camera is set.
+     * @internal
+     */
+    get cameraWorldPosition(): Vector3 | null;
+    /**
+     * Incremented whenever {@link SplatEngine.syncLighting} finds the lights
+     * changed. Lets a backend skip work that depends on lighting.
+     * @internal
+     */
+    lightingVersion: number;
+    /**
+     * Copy {@link SplatEngine.lighting} into the shared uniforms. Called per
+     * draw, so it only compares numbers and writes on change.
+     * @internal
+     */
+    syncLighting(): void;
+    /**
+     * Detach the engine's content from the scene and stop updating. Characters
+     * and environments are not destroyed for you - destroy them first if you
+     * want their GPU resources released.
+     */
+    dispose(): void;
+}
+/**
+ * Thrown when an asset finishes loading onto an engine that has already been
+ * disposed.
+ *
+ * This is a CANCELLATION, not a failure: the bytes were fine and the engine is
+ * simply gone. It exists as its own type so a caller can tell the two apart.
+ *
+ * @group Engine
+ */
+export declare class EngineDisposedError extends Error {
+    constructor(what: string);
+}

package/dist/types/environment.d.ts

@@ -0,0 +1,53 @@
+import type { Object3D } from 'three';
+import type { SplatEngine } from './engine';
+import { Splat } from './splat/splat';
+/** @group Environment */
+export interface LoadEnvironmentOptions {
+    /** Object name. Default: basename of the URL. */
+    name?: string;
+    /** World position. Default: origin. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Euler angles in degrees. Default: no rotation. */
+    rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Uniform scale. Default: 1. */
+    scale?: number;
+    /** Explicit filename for extension detection on URLs without one. */
+    filename?: string;
+}
+/**
+ * Gaussian-splat environment loaded into an engine.
+ *
+ * A static, unskinned splat that responds to the engine's lighting registry
+ * (sun + sky + point lights). Its depth sort runs in a worker and only when
+ * the view direction changes, so a large scene costs nothing while the camera
+ * is still.
+ *
+ * Construct via {@link Environment.load} - the constructor is internal.
+ *
+ * @group Environment
+ */
+export declare class Environment {
+    /** The splat that draws the environment. */
+    readonly splat: Splat;
+    private constructor();
+    /** The three.js object for the environment. Transform it like any other. */
+    get object3D(): Object3D;
+    /**
+     * Fetch, decode and add an environment splat.
+     *
+     * Reads uncompressed 3D Gaussian Splatting `.ply` files.
+     *
+     * @param url - Location of the splat file.
+     */
+    static load(engine: SplatEngine, url: string, opts?: LoadEnvironmentOptions): Promise<Environment>;
+    /** Remove the environment and release its GPU resources. */
+    destroy(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,37 @@
+export { SplatCharacter } from './three/splat-character';
+export type { SplatCharacterEventMap, SplatCrossFadeOptions, SplatLayerOptions, SplatPlayOptions, SplatRootMotion, } from './three/splat-character';
+export { SplatClipLoader, SplatPLYLoader, VSplatLoader } from './three/loaders';
+export { Animation as SplatClip } from './animation';
+export { SplatEngine, EngineDisposedError } from './engine';
+export type { SceneLighting, SplatEngineOptions } from './engine';
+export { Character } from './character';
+export type { LoadCharacterOptions } from './character';
+export { Animation } from './animation';
+export type { AnimationEvent } from './animation';
+export { Armature } from './armature';
+export type { AnimLodPreset, PoseProvider, RootMotionMode } from './armature';
+export { Environment } from './environment';
+export type { LoadEnvironmentOptions } from './environment';
+export { Splat } from './splat/splat';
+export { SplatMesh } from './splat/splat-mesh';
+export { WebGLSplatBackend } from './splat/webgl/backend';
+export type { SplatBackend } from './splat/backend';
+export type { SplatOptions, SplatSource } from './splat/splat';
+export { packSplats } from './splat/packed-splats';
+export type { PackedSplats } from './splat/packed-splats';
+export { SunLight } from './lighting/sun-light';
+export type { CreateSunLightOptions } from './lighting/sun-light';
+export { SkyLight } from './lighting/sky-light';
+export type { CreateSkyLightOptions } from './lighting/sky-light';
+export { PointLight } from './lighting/point-light';
+export type { CreatePointLightOptions } from './lighting/point-light';
+export { makeRegionMask } from './skeletal/bone-mask';
+export type { BodyRegion, BoneMask } from './skeletal/bone-mask';
+export type { AnimEventCallback, CrossfadeOptions } from './skeletal/animation-player';
+export type { BoneScaleInput } from './skeletal/bone-stretch';
+export { decodeCharacterBundle, loadCharacterBundle, loadCharacterBundleFromBytes } from './loader/character/load';
+export type { CharacterBundle } from './loader/character/load';
+export { CharacterBundleError } from './loader/character/types';
+export { parseGaussianPly } from './loader/environment/ply';
+export type { SkeletonLibrary } from './loader/skeleton';
+export type { ArmatureData, SplatWeights } from './types';

package/dist/types/lighting/color.d.ts

@@ -0,0 +1,13 @@
+import type { Color } from 'three';
+/** Parse `#rrggbb` into raw 0..1 components. */
+export declare function parseHex(css: string): [number, number, number];
+/**
+ * Write a CSS hex colour into `color` as raw component values.
+ *
+ * Deliberately not `Color.set(hex)`: light colours here multiply baked,
+ * display-referred splat colour, so they are used as written. three.js colour
+ * management would convert the hex to linear and darken every light.
+ */
+export declare function applyHexTo(color: Color, css: string): void;
+/** A `Color` holding exactly the given component values, with no colour-space conversion. */
+export declare function rawColor(color: Color, r: number, g: number, b: number): Color;

package/dist/types/lighting/point-light.d.ts

@@ -0,0 +1,33 @@
+import { Color, Vector3 } from 'three';
+import type { SplatEngine } from '../engine';
+/** @group Lighting */
+export interface CreatePointLightOptions {
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Light colour as CSS hex string. */
+    color?: string;
+    intensity?: number;
+    /** Hard cutoff distance in world units. Contribution is 0 at and beyond this. */
+    range?: number;
+    enabled?: boolean;
+}
+/** @group Lighting */
+export declare class PointLight {
+    /** World-space position. */
+    position: Vector3;
+    /** Raw component values; not colour-managed. */
+    color: Color;
+    intensity: number;
+    range: number;
+    enabled: boolean;
+    private _engine;
+    /** @internal */
+    _attach(engine: SplatEngine): void;
+    /** Remove this light from its engine. After calling, the light stops contributing. */
+    destroy(): void;
+    /** Create a point light and register it on the engine's lighting registry. */
+    static create(engine: SplatEngine, opts?: CreatePointLightOptions): PointLight;
+}

package/dist/types/lighting/sky-light.d.ts

@@ -0,0 +1,22 @@
+import { Color } from 'three';
+import type { SplatEngine } from '../engine';
+/** @group Lighting */
+export interface CreateSkyLightOptions {
+    /** Sky colour as CSS hex string. */
+    color?: string;
+    intensity?: number;
+    enabled?: boolean;
+}
+/**
+ * Ambient light for splats: a constant `color * intensity` added to every splat.
+ *
+ * @group Lighting
+ */
+export declare class SkyLight {
+    /** Raw component values; not colour-managed. */
+    color: Color;
+    intensity: number;
+    enabled: boolean;
+    /** Create a sky light and make it the engine's sky. */
+    static create(engine: SplatEngine, opts?: CreateSkyLightOptions): SkyLight;
+}

package/dist/types/lighting/sun-light.d.ts

@@ -0,0 +1,34 @@
+import { Color, Vector3 } from 'three';
+import type { SplatEngine } from '../engine';
+/** @group Lighting */
+export interface CreateSunLightOptions {
+    /** Azimuth in degrees. 0 = +Z, 90 = +X. */
+    azimuth?: number;
+    /** Elevation in degrees. 0 = horizon, 90 = directly overhead. */
+    elevation?: number;
+    /** Sun colour as CSS hex string, e.g. '#fff4e0'. */
+    color?: string;
+    /** Brightness multiplier applied to `color` in the shader. */
+    intensity?: number;
+    /** Start disabled. Lights default to enabled. */
+    enabled?: boolean;
+}
+/**
+ * Directional light for splats. Splats have no normals, so the sun is a flat
+ * brightness term: every splat receives `color * intensity`, regardless of
+ * which way it faces.
+ *
+ * @group Lighting
+ */
+export declare class SunLight {
+    azimuth: number;
+    elevation: number;
+    /** Raw component values; not colour-managed. */
+    color: Color;
+    intensity: number;
+    enabled: boolean;
+    /** Unit vector pointing from the scene toward the sun. */
+    lightDir(out?: Vector3): Vector3;
+    /** Create a sun and make it the engine's sun. */
+    static create(engine: SplatEngine, opts?: CreateSunLightOptions): SunLight;
+}

package/dist/types/loader/animation/animation-glb.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Decoded contents of an *armature GLB* - a glTF 2.0 binary carrying a bone
+ * hierarchy, a skin, and one animation clip. Produced by the offline MetaHuman
+ * GLB exporter, and readable back after a Blender round-trip.
+ *
+ * @internal
+ */
+export interface ArmatureGlbAnimation {
+    /** Bone matrices in {@link Animation.data} layout: `numFrames * numBones * 16`. */
+    data: Float32Array;
+    numFrames: number;
+    numBones: number;
+    /** Bone names in bone-index order (canonical rig order when recognised). */
+    boneNames: string[];
+    /**
+     * Per bone: `1` if the clip drives that bone's translation, `0` if the bone
+     * must inherit the armature's rest translation. `undefined` when every bone
+     * is driven - which is what a `.anim` file means, since that format cannot
+     * say anything else.
+     *
+     * Derived from the DATA, not from which channels exist: a translation
+     * channel whose keys are all equal declares a rest pose, and a channel that
+     * varies is motion. See {@link parseArmatureGlbAnimation}.
+     */
+    translationMask?: Uint8Array;
+    /** Source frame rate derived from the main timestamp accessor. */
+    frameRate: number;
+    /** Clip name as stored in the GLB. */
+    animationName: string;
+}
+/**
+ * How far a translation channel may wander and still count as a declaration of
+ * rest rather than motion: 10 µm.
+ *
+ * The distinction cannot be drawn from channel *presence*, because a
+ * conformant writer emits a channel for every bone and Blender re-exports
+ * dense channels for everything it imports. It is drawn from the values, which
+ * survive that round trip: a constant track stays constant however densely it
+ * is written.
+ *
+ * The bound is empirical and has room on both sides. Below it: a Blender
+ * 4.2.18 import→export of our own files re-derives every bone through its own
+ * matrix pipeline and perturbs a constant translation by at most 7.96e-7 m,
+ * 12x under this. Above it: the smallest genuinely moving channel in the same
+ * files drifts 3.06e-4 m, 30x over. The writer's own collapse threshold
+ * (the exporter's own `TRANSLATION_EPS`, 1e-6 m) sits inside
+ * that gap too, so everything it calls constant still reads as constant here,
+ * before and after a round trip.
+ *
+ * Shared with the `.anim` reader ({@link Animation.parse}), which asks the same
+ * question of the same quantity, so one number keeps the two formats from ever
+ * disagreeing about what "constant" means. It has even more room there: a v3
+ * `.anim` stores float16, whose decode is deterministic, so a constant track
+ * comes back bit-identical (deviation exactly 0) while the smallest moving bone
+ * across `test_full` / `test_stripped` / `test_blend_*` drifts 2.69e-4 m. Motion
+ * finer than this bound is not representable at bone-offset magnitudes in
+ * float16 anyway (one ulp at 0.4 m is 2.4e-4 m), so it has already been
+ * quantized flat before the test sees it.
+ *
+ * @internal
+ */
+export declare const CONSTANT_TRANSLATION_EPS = 0.00001;
+/**
+ * Parse an armature GLB into the flat bone-matrix form that {@link Animation}
+ * holds after {@link Animation.parse}.
+ *
+ * **Bones are resolved by NAME, never by node index.** The joint set comes from
+ * `skins[0].joints` when a skin is present (files we write, and anything
+ * Blender exports), falling back to "every node is a bone" for older files
+ * that carried no skin. If the joint names match one of the engine's known rigs the bones are
+ * re-ordered into that rig's canonical order; otherwise the file's joint order
+ * stands. Nodes that are not joints - the armature parent, mesh nodes, cameras,
+ * anything a DCC tool adds - are ignored, and so are channels targeting them.
+ *
+ * What it accepts:
+ *
+ *  - `translation`, `rotation` and `scale` channels; `weights` is ignored,
+ *    there being no morph targets on an armature.
+ *  - Rotations as FLOAT or `normalized: true` SHORT (dequantized + renormalized).
+ *  - `LINEAR`, `STEP` and `CUBICSPLINE` samplers. Other modes throw by name.
+ *  - Per-channel timelines: each sampler rides either the main timeline - the
+ *    longest, so frame `f` is the same instant for every bone - or a one-key
+ *    timeline of its own, meaning a constant channel held for the whole clip.
+ *  - Accessors sharing one bufferView via `byteOffset`, and absent `min`/`max`.
+ *
+ * What it requires: exactly one rotation channel per bone, timestamps on a
+ * uniform grid (the engine indexes animations by frame, so key `i` must be
+ * frame `i`), and no duplicate channels.
+ *
+ * **Constant translation is a rest declaration, not motion.** A translation
+ * channel whose keys are all equal (within {@link CONSTANT_TRANSLATION_EPS})
+ * states the rig's own bone length; a channel that varies is real motion -
+ * root motion at the pelvis, and the face, which is translation-driven. The
+ * former is reported through {@link ArmatureGlbAnimation.translationMask} as a
+ * `0`, so playback keeps the TARGET character's rest translation and its limbs
+ * do not resize mid-clip. On our own clips that lands on 85 of 441 bones
+ * without a single bone name being mentioned anywhere.
+ *
+ * The test reads the data rather than the channel list on purpose. Absence
+ * could carry the same message, but only in a file nobody has touched: a
+ * conformant reader is entitled to use `nodes[b].translation` when a channel
+ * is missing, and Blender re-exports dense channels for every bone, which
+ * erases the distinction. Constancy survives both. Files that genuinely omit
+ * the channel - everything written before 2026-08 - are still read the old
+ * way, as `0`.
+ *
+ * Scale gets the same treatment, and resolves at parse time: a constant scale
+ * is a rest declaration, and every rig this engine builds rests at scale
+ * `1,1,1`, so a constant channel simply resolves to identity here and needs no
+ * mask of its own. A varying scale is honoured. Our writers emit no scale
+ * channels at all, so this only ever fires for a bone somebody scaled by hand
+ * in a DCC tool.
+ *
+ * @throws If the container, the layout, or an accessor is invalid.
+ * @internal
+ */
+export declare function parseArmatureGlbAnimation(buffer: ArrayBuffer, animationName?: string): ArmatureGlbAnimation;

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

@@ -0,0 +1,33 @@
+/**
+ * Character-bundle reader: the dispatch table and the public entry point.
+ *
+ * ONE top-level branch, and legacy behind one door:
+ *
+ *     magic == VIGGCHAR  ->  look `version` up in VERSION_HANDLERS
+ *     otherwise          ->  legacy/
+ *
+ * That is the whole structure, and it is the point of it: adding version N+1
+ * costs one module under `vN/` and one line in the table below, and removing a
+ * version costs deleting exactly those two things. If a change to support a new
+ * version has to touch an existing handler, the decomposition is not real.
+ * (Character-bundle format spec, "Reader architecture", R1-R5.)
+ *
+ * The only bytes read before dispatch are the 16 container bytes. Nothing here
+ * sniffs the payload, peeks at the header, tries a parse, or consults the
+ * filename, the extension, the URL or the MIME type - the `.vsplat` extension
+ * is advisory and says nothing this reader may act on.
+ */
+import { CharacterBundleError } from './types';
+import type { DecodeResult } from './types';
+/**
+ * Read a character bundle of any container this reader implements.
+ *
+ * @param file - the whole file as a read-only byte buffer.
+ * @returns the decoded bundle in the version-independent output type, plus the
+ * buffers a worker may transfer rather than copy. A caller cannot tell from the
+ * result which handler ran.
+ * @throws {CharacterBundleError} carrying the spec's error category.
+ */
+declare function parseCharacterBundle(file: ArrayBuffer): Promise<DecodeResult>;
+export { parseCharacterBundle, CharacterBundleError };
+export type { DecodeResult };

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

@@ -0,0 +1,34 @@
+/**
+ * The legacy door.
+ *
+ * Everything whose first 8 bytes are not `VIGGCHAR` arrives here, and nothing
+ * else does. Behind it are the two container generations that shipped before
+ * the format was respecified:
+ *
+ *   `VFCHARB1` -> interleaved per-splat records (v1 fp32, v2 fp16)
+ *   `VFCHARB2` -> planar byte planes (v3; fp16 or q23 precision)
+ *   `VSPLAT01` -> the pre-release prototype of the planar layout
+ *
+ * These readers are PERMANENT, not migration scaffolding. Files already in
+ * storage keep their old magic forever - there is no backfill - so this module
+ * is kept indefinitely and its decoders are moved, never improved. What it is
+ * NOT is entangled: it is one branch of one top-level `if`, it imports nothing
+ * from `../v1/`, and `../v1/` imports nothing from it.
+ *
+ * These containers spell `version` as one global lineage across two magics,
+ * which is precisely the accretion `VIGGCHAR` exists to end. Nothing about that
+ * lineage leaks past this file: the dispatcher upstream never reads it, and the
+ * bundle handed back is the same version-independent shape `v1/` returns.
+ */
+import type { DecodeResult } from '../types';
+/**
+ * Decode a bundle in one of the pre-`VIGGCHAR` containers.
+ *
+ * The container is identified by SNIFFING THE 8-BYTE MAGIC and never by the
+ * filename or a header key - both generations arrive through the same URLs,
+ * with no out-of-band type information, so the bytes are the only honest
+ * answer. Anything this door does not recognise throws with the magic it
+ * actually found.
+ */
+declare function decodeLegacyBundle(file: ArrayBuffer): Promise<DecodeResult>;
+export { decodeLegacyBundle };

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

@@ -0,0 +1,101 @@
+/**
+ * Interleaved character-splat decoder - the payload half of `VFCHARB1`.
+ *
+ * MOVED, NOT REWRITTEN. This is `binary-gsplat-worker.ts`'s `parseBinaryGsplat`
+ * verbatim, lifted out of the worker glue so the legacy readers sit behind one
+ * door (`../index.ts`). It decodes files that are already in storage and will
+ * stay there - there is no backfill - so any behaviour change here is a
+ * regression, and it keeps its own vocabulary: this container talks about
+ * CHUNKS, where the planar one talks about PLANES and `VIGGCHAR` talks about
+ * BLOCKS.
+ *
+ * `version` here numbers one global bundle lineage across both legacy magics
+ * (1 = fp32 interleaved, 2 = fp16 interleaved, 3 = planar), which is exactly the
+ * accretion `VIGGCHAR` was shaped to end.
+ */
+/** The interleaved container: per-splat records, v1 (fp32) and v2 (fp16). */
+declare const CHARACTER_BUNDLE_MAGIC = "VFCHARB1";
+interface BundleChunk {
+    offset: number;
+    length: number;
+    stride?: number;
+}
+interface AssetHeader {
+    format: string;
+    version: number;
+    numSplats: number;
+    numBones: number;
+    bounds: {
+        min: number[];
+        max: number[];
+    };
+    encoding?: {
+        /**
+         * Bundle-wide field precision. `'fp16'` means pos/scale/rot/opacity and
+         * the weights chunk's per-splat weights are stored as IEEE 754 half-floats
+         * (read 2 bytes / value, expanded to Float32 on parse). `'fp32'` or
+         * missing = legacy raw float32 (the v1 layout). RGB stays uint8 and bone
+         * indices stay uint16 either way. Bumps the file size by ~42%; expanding
+         * to Float32 here means GPU memory is unchanged.
+         */
+        precision?: 'fp16' | 'fp32';
+        weights?: {
+            topK: number;
+            indexType: string;
+            weightType: string;
+            stride: number;
+        };
+        color?: {
+            format: string;
+            levels: number;
+        };
+    };
+    chunks: {
+        splats: BundleChunk;
+        weights?: BundleChunk;
+        joints?: BundleChunk;
+        animation?: BundleChunk;
+    };
+    animation?: {
+        format: string;
+        numFrames: number;
+        numBones: number;
+        shape: number[];
+        stride: number;
+    };
+    joints?: {
+        count: number;
+        format: string;
+        stride: number;
+    };
+}
+declare function parseBinaryGsplat(bundleBuffer: ArrayBuffer): {
+    result: {
+        header: AssetHeader;
+        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<ArrayBufferLike> | null;
+        animNumFrames: number;
+        animNumBones: number;
+        jointsArray: Float32Array<ArrayBufferLike> | null;
+    };
+    transferables: ArrayBuffer[];
+};
+export { parseBinaryGsplat, CHARACTER_BUNDLE_MAGIC };