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

package/dist/types/skeletal/bone-mask.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bone-mask utilities for layered animation. A {@link BoneMask} selects a
+ * subset of an armature's bones by index; the {@link Armature} layer system
+ * uses it to gate an overlay animation to (e.g.) just the upper body while a
+ * base full-body clip drives the rest.
+ *
+ * Built-in regions ({@link UPPER_BODY_BONE_NAMES} / {@link LOWER_BODY_BONE_NAMES})
+ * follow the canonical 86-bone rig naming. The split bone is the pelvis:
+ *   - UPPER covers everything from `spine_01` up (spine 01-05, neck, head,
+ *     clavicles, arms, hands, all fingers) so the overlay fully replaces
+ *     the torso without leak from the base's spine rotation.
+ *   - LOWER covers `pelvis` plus the leg chain (thighs, calves, calf
+ *     twists, feet, ball, all toes). Including pelvis means an overlay's
+ *     pelvis Y motion drives the rig and routes through `rootMotionMode`,
+ *     so the lower-body overlay owns root motion when active.
+ *
+ * @group Characters & Animation
+ */
+export declare const UPPER_BODY_BONE_NAMES: readonly ["spine_01", "spine_02", "spine_03", "spine_04", "spine_05", "neck_01", "neck_02", "head", "clavicle_l", "clavicle_r", "upperarm_l", "upperarm_r", "lowerarm_l", "lowerarm_r", "hand_l", "hand_r", "thumb_01_l", "thumb_02_l", "thumb_03_l", "index_metacarpal_l", "index_01_l", "index_02_l", "index_03_l", "middle_metacarpal_l", "middle_01_l", "middle_02_l", "middle_03_l", "ring_metacarpal_l", "ring_01_l", "ring_02_l", "ring_03_l", "pinky_metacarpal_l", "pinky_01_l", "pinky_02_l", "pinky_03_l", "thumb_01_r", "thumb_02_r", "thumb_03_r", "index_metacarpal_r", "index_01_r", "index_02_r", "index_03_r", "middle_metacarpal_r", "middle_01_r", "middle_02_r", "middle_03_r", "ring_metacarpal_r", "ring_01_r", "ring_02_r", "ring_03_r", "pinky_metacarpal_r", "pinky_01_r", "pinky_02_r", "pinky_03_r"];
+export declare const LOWER_BODY_BONE_NAMES: readonly ["pelvis", "thigh_l", "thigh_r", "calf_l", "calf_r", "calf_twist_01_l", "calf_twist_01_r", "foot_l", "foot_r", "ball_l", "ball_r", "bigtoe_01_l", "bigtoe_02_l", "indextoe_01_l", "indextoe_02_l", "middletoe_01_l", "middletoe_02_l", "ringtoe_01_l", "ringtoe_02_l", "littletoe_01_l", "littletoe_02_l", "bigtoe_01_r", "bigtoe_02_r", "indextoe_01_r", "indextoe_02_r", "middletoe_01_r", "middletoe_02_r", "ringtoe_01_r", "ringtoe_02_r", "littletoe_01_r", "littletoe_02_r"];
+export interface BoneMask {
+    name: string;
+    boneIndices: Int32Array;
+}
+export declare function resolveBoneIndices(allBoneNames: readonly string[], maskNames: readonly string[]): Int32Array;
+export type BodyRegion = 'upperBody' | 'lowerBody';
+export declare function makeRegionMask(region: BodyRegion, allBoneNames: readonly string[]): BoneMask;

package/dist/types/skeletal/bone-stretch.d.ts

@@ -0,0 +1,65 @@
+import { Mat4 } from '../math';
+import type { Skeleton } from './skeleton';
+/**
+ * Per-axis scale for a single bone, in a frame aligned to the bone:
+ *  - `along`     - scale down the bone's own axis (lengthen / shorten),
+ *  - `width` / `thickness` - scale across the bone (the two cross-section axes;
+ *    their world orientation is bone-dependent, so treat them as "the two
+ *    perpendicular directions" rather than a fixed front/side).
+ *
+ * Each defaults to `1`. A bare `number` is shorthand for a uniform scale on all
+ * three axes.
+ *
+ * @group Characters & Animation
+ */
+export interface BoneScale {
+    along: number;
+    width: number;
+    thickness: number;
+}
+/** A bone scale, or a number meaning uniform scale on all three axes. */
+export type BoneScaleInput = Partial<BoneScale> | number;
+/**
+ * Per-bone data that realizes a set of bone scales. Produced by
+ * {@link computeBoneStretch}, consumed by {@link Skeleton} (lengthening) and
+ * {@link SplatSkinning} (flesh/covariance stretch).
+ *
+ * @group Characters & Animation
+ */
+export interface BoneStretch {
+    /**
+     * Per-bone multiplier on the local rest translation. A bone's local
+     * translation is its offset from its parent (the parent segment's vector),
+     * so scaling it lengthens that segment by the parent's `along` factor.
+     * Translation-only → never inflates covariance, never compounds down a
+     * chain. Indexed by bone; `1` = unchanged.
+     */
+    lengthScale: Float32Array;
+    /**
+     * Per-bone local stretch matrix (`F·diag(along,width,thickness)·Fᵀ` in the
+     * bone-aligned frame `F`), folded into the skinning palette so the bone's
+     * Gaussians scale on all three axes and their covariances follow. Identity
+     * for unscaled bones. Indexed by bone.
+     */
+    covStretch: Mat4[];
+    /** True when at least one bone is actually scaled. */
+    any: boolean;
+}
+/**
+ * Translate a map of per-bone scales into the {@link BoneStretch} arrays.
+ * `factors[boneName]` scales that bone's flesh + segment (e.g.
+ * `{ thigh_l: { along: 1.3 }, calf_l: { along: 1.3 } }` → a 1.3× longer left
+ * leg; `{ upperarm_l: { width: 1.4, thickness: 1.4 } }` → a beefier arm).
+ * Bones not listed stay at `1`.
+ *
+ * Correct for arbitrary bone sets (limbs, spine, …) with no boundary
+ * compensation: lengthening lives in per-segment translations (no cumulative
+ * scale), and the flesh scale is per-bone in the palette (non-propagating).
+ * Each bone scales in ITS OWN frame, so bones at any orientation scale
+ * correctly.
+ *
+ * @param skeleton  Rig to read the rest pose / hierarchy from.
+ * @param boneNames Bone names in index order (from the armature).
+ * @param factors   Per-bone scales keyed by bone name.
+ */
+export declare function computeBoneStretch(skeleton: Skeleton, boneNames: readonly string[], factors: Record<string, BoneScaleInput>): BoneStretch;

package/dist/types/skeletal/pose.d.ts

@@ -0,0 +1,27 @@
+import { Quat, Vec3 } from '../math';
+/**
+ * Per-bone local TRS for a whole rig. The seam between
+ * {@link AnimationPlayer} (which writes pose values) and
+ * {@link Skeleton} (which composes them into world transforms).
+ *
+ * Three parallel arrays of length `numBones`. Values live in armature-local
+ * bone space - absolute, not rest-relative. Allocation happens once;
+ * AnimationPlayer mutates entries in place each frame.
+ *
+ * @group Characters & Animation
+ */
+export declare class Pose {
+    readonly positions: Vec3[];
+    readonly rotations: Quat[];
+    readonly scales: Vec3[];
+    constructor(numBones: number);
+    get numBones(): number;
+    /** Copy every bone from `other` into this pose. */
+    copyFrom(other: Pose): void;
+    /**
+     * Reset every bone to the bind-pose values held in `bindT` (flat
+     * `[x,y,z]*numBones`) and `bindR` (flat `[x,y,z,w]*numBones`). Scales reset
+     * to unit.
+     */
+    setToBind(bindT: Float32Array, bindR: Float32Array): void;
+}

package/dist/types/skeletal/skeleton.d.ts

@@ -0,0 +1,57 @@
+import { Mat4 } from '../math';
+import type { RestPose } from '../anim/rest-relative';
+import type { ArmatureData } from '../types';
+import type { Pose } from './pose';
+/**
+ * Rig data and skeletal math for one character. Owns the bone hierarchy, the
+ * rest pose, and the (lazy) inverse-bind pose. Composes per-bone local
+ * transforms into world-space matrices.
+ *
+ * Pure data + math - no three.js object, no `SplatEngine`, no `Splat`. Safe to
+ * construct in tests with a fixture rig.
+ *
+ * @group Characters & Animation
+ */
+export declare class Skeleton {
+    readonly numBones: number;
+    /** Parent bone index per bone. `-1` for root bones. */
+    readonly parents: Int32Array;
+    /** Flat bind-pose translations: `[x,y,z]*numBones`. */
+    readonly bindT: Float32Array;
+    /** Flat bind-pose rotations (quaternions): `[x,y,z,w]*numBones`. */
+    readonly bindR: Float32Array;
+    /** Rest pose as parallel `Vec3`/`Quat` arrays. */
+    readonly restPose: RestPose;
+    /**
+     * Optional per-bone multiplier on the local rest translation, applied during
+     * FK. A bone's local translation is its offset from its parent, so scaling
+     * it lengthens that segment - this is the lengthening half of bone-length
+     * scaling (see {@link computeBoneStretch}). It deliberately affects only the
+     * translation, not the bone's orientation/scale, so it never inflates
+     * Gaussian covariance and never compounds down a chain. `null` = unscaled
+     * (the normal path). The bind/inverse-bind are intentionally NOT rescaled,
+     * so the palette carries the standard→stretched delta.
+     */
+    lengthScale: Float32Array | null;
+    private readonly _children;
+    private readonly _rootBones;
+    private _inverseBindPose;
+    private readonly _tmpLocalMat;
+    private readonly _tmpPos;
+    private readonly _kfStack;
+    constructor(armatureData: ArmatureData);
+    /**
+     * World-space inverse-bind pose, one matrix per bone. Lazy - bind pose is
+     * only needed once splat skinning starts pushing transforms.
+     */
+    get inverseBindPose(): Mat4[];
+    /**
+     * Compose local-space `pose` into world-space matrices, prefixed by
+     * `entityWorldTransform`. Walks the hierarchy parent-first so child world
+     * transforms read the freshly-written parent.
+     *
+     * `out` is reused - entries are created lazily if missing, but the caller
+     * owns the buffer (no per-frame allocation).
+     */
+    applyLocal(pose: Pose, entityWorldTransform: Mat4, out: Mat4[]): void;
+}

package/dist/types/skeletal/splat-skinning.d.ts

@@ -0,0 +1,69 @@
+import type { Frustum } from 'three';
+import { Mat4 } from '../math';
+import type { Splat } from '../splat/splat';
+import type { SkeletonLibrary } from '../types';
+import type { Skeleton } from './skeleton';
+/**
+ * Per-character splat skinning coordinator. Owns the set of {@link Splat}s
+ * driven by an armature, their palette-slot maps, and the GPU push that
+ * uploads bone matrices each frame.
+ *
+ * Also owns the frustum-visibility gate: the armature can skip the expensive
+ * pose-eval + skinning path when no linked splat is on-screen.
+ *
+ * @group Characters & Animation
+ */
+export declare class SplatSkinning {
+    /** Splats currently driven by this skinning unit. */
+    readonly linkedSplats: Set<Splat>;
+    /**
+     * Optional per-bone local stretch matrices (the covariance half of
+     * bone-length scaling - see {@link computeBoneStretch}). When set, each
+     * bone's palette entry gets this stretch folded in, the per-bone scale is
+     * NOT normalized out of the palette, and linked splats render with the
+     * `USE_NONRIGID_COV` shader path so Gaussian covariances follow the stretch.
+     * `null` = rigid skinning (the normal path). Set via {@link setCovStretch}.
+     */
+    covStretch: Mat4[] | null;
+    private readonly _skeleton;
+    private readonly _skeletonLibrary;
+    private readonly _bonePaletteFirstIdx;
+    private readonly _boneIndexLists;
+    private readonly _finalBoneTransforms;
+    private readonly _armatureWorldToLocal;
+    constructor(skeleton: Skeleton, skeletonLibrary: SkeletonLibrary | undefined);
+    link(splat: Splat): void;
+    unlink(splat: Splat): void;
+    /**
+     * Set (or clear with `null`) the per-bone covariance-stretch matrices for
+     * bone-length scaling. Also flips the `USE_NONRIGID_COV` shader path on every
+     * linked splat so covariances follow the stretch. Pass `null` to return to
+     * rigid skinning.
+     */
+    setCovStretch(mats: Mat4[] | null): void;
+    /**
+     * Returns `true` when at least one linked splat's bounding sphere intersects
+     * the camera frustum. Used by the armature to short-circuit the per-frame
+     * skinning math for off-screen characters.
+     *
+     * When `frustum` is missing (e.g. before the first `engine.update()`) returns `true` -
+     * the conservative choice is to do the extra work rather than freeze a
+     * character's pose.
+     */
+    anyVisible(frustum: Frustum | undefined): boolean;
+    /**
+     * Compose `worldTransforms` (one per bone) with the pivot's inverse world
+     * transform and the inverse-bind pose, then upload the resulting palette to
+     * every linked splat. `worldTransforms[i]` is the i-th bone's matrix in
+     * world space, as produced by {@link Skeleton.applyLocal}.
+     *
+     * Strips scale from the per-bone linear part before composing with the
+     * inverse bind. Without this, any net scale (from `splat.object3D` world scale
+     * or animated bone scale) inflates Gaussian sigmas on the GPU via the
+     * palette's column lengths - visible as radial streaks on hands/fists, and
+     * desyncs CPU-computed centers from GPU-rendered positions.
+     */
+    pushTransforms(worldTransforms: Mat4[], entityWorldTransform: Mat4, skipPositions?: boolean): void;
+    /** Request a re-sort on every linked splat (e.g. after a transform change). */
+    requestSortAll(): void;
+}

package/dist/types/splat/backend.d.ts

@@ -0,0 +1,57 @@
+import type { BufferGeometry, Camera, Material, Mesh } from 'three';
+import type { SplatEngine } from '../engine';
+import type { Splat } from './splat';
+/**
+ * The renderer-specific half of a {@link SplatMesh}: the geometry and material
+ * one kind of three.js renderer needs, plus the per-frame work to keep them
+ * current.
+ *
+ * Everything a splat is - its packed data, weights, palette, tint - lives on
+ * the `Splat`. An implementation only turns that into something one renderer
+ * can draw, and owns whatever that takes (sort state, GPU buffers).
+ *
+ * @internal
+ */
+export interface SplatRenderImpl {
+    readonly geometry: BufferGeometry;
+    readonly material: Material;
+    /**
+     * Whether the splat's centres must be re-skinned on the CPU every frame.
+     * True when the depth sort runs on the CPU; false when the GPU skins for its
+     * own sort, in which case that pass - the dominant per-character CPU cost -
+     * is skipped entirely.
+     */
+    readonly needsCpuCenters: boolean;
+    /** True while the drawn order is stale or absent because a sort is outstanding. */
+    readonly sortPending: boolean;
+    /** Force a re-sort on the next render even if nothing appears to have changed. */
+    requestSort(): void;
+    /** Rebuild the shader variant after a feature toggle on the splat. */
+    syncDefines(): void;
+    /** Refresh culling bounds from the splat's current local bounds. */
+    syncBounds(): void;
+    /** Re-upload bone indices/weights after the splat's arrays were edited. */
+    syncBoneData(): void;
+    /** Re-upload per-splat group ids after {@link Splat.setSplatGroups}. */
+    syncVariantGroups(): void;
+    /** Called from the host mesh's `onBeforeRender`, once per draw. */
+    beforeRender(renderer: unknown, camera: Camera): void;
+    /** Release GPU resources. The splat's own textures are not this object's to free. */
+    dispose(): void;
+}
+/**
+ * Creates {@link SplatRenderImpl}s for one kind of three.js renderer.
+ *
+ * You rarely need to name one: a {@link SplatMesh} picks the backend that
+ * matches whichever renderer first draws it.
+ *
+ * @group Engine
+ */
+export interface SplatBackend {
+    /**
+     * @param host - The mesh in the scene graph the implementation draws through.
+     * @param asyncSort - The splat is static, so a sort that lags the camera by
+     * a frame or two is acceptable. Backends that sort on the GPU ignore this.
+     */
+    createImpl(host: Mesh, splat: Splat, engine: SplatEngine, asyncSort: boolean): SplatRenderImpl;
+}

package/dist/types/splat/bone-binding.d.ts

@@ -0,0 +1,38 @@
+import type { SkeletonLibrary } from '../types';
+import type { Splat } from './splat';
+/**
+ * Build the source→target bone remap when the splat's `.bin` bundle was
+ * authored against a wider skeleton than the armature uses (e.g. a 1185-bone
+ * source on the 86-bone std-male rig, or a 441-bone full body+facial source
+ * on the 86-bone body rig).
+ *
+ * Returns `null` when no remap is needed (source and target bone counts
+ * match) or when the skeleton library doesn't carry enough naming metadata to
+ * resolve the mapping. Unmapped bones in the result are `-1`, except facial
+ * bones (`FACIAL_*`), which fall back to the `head` bone so the splats track
+ * head motion rather than snapping to root.
+ */
+export declare function buildSourceBoneRemap(splat: Splat, numBones: number, skeletonLibrary: SkeletonLibrary | undefined): Int32Array | null;
+/**
+ * Allocate the splat's slice of the shared transform palette and rewrite its
+ * bone-index texture so each splat's K influences point at the palette slots
+ * the armature will write into.
+ *
+ * Splats with no resolvable target bone (typically facial influences on a
+ * body-only rig that can't fall back to `head`) get weight 0 - they stay at
+ * rest instead of snapping to bone 0.
+ *
+ * Returns the first palette index allocated for this splat's bone block.
+ * Palette slot for bone `i` is always `firstIdx + i`.
+ */
+export declare function initializeSplatBoneMapping(splat: Splat, numBones: number, skeletonLibrary: SkeletonLibrary | undefined): number;
+/**
+ * Walk the splat's per-influence bone-index buffer and return the sorted list
+ * of distinct bone indices it actually references. Used to skip palette writes
+ * for bones no splat influences (e.g. a 441-bone rig where ~half the bones are
+ * facial and the splat has no facial weights).
+ *
+ * Returns an empty `Int32Array` when the splat has no weights data - callers
+ * treat that as "fall back to walking every bone."
+ */
+export declare function buildSplatBoneIndexList(splat: Splat, numBones: number, firstPaletteIdx: number): Int32Array;

package/dist/types/splat/depth-sort.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Back-to-front depth ordering for splats: a counting sort over quantised
+ * distance along the view direction.
+ *
+ * The same routine runs in two places. Skinned characters are small and move
+ * every frame, so they sort synchronously on the main thread and never show a
+ * stale order. Environments are large and only need a new order when the camera
+ * moves, so they sort in a worker ({@link AsyncDepthSorter}) and keep drawing
+ * the previous order until the new one lands.
+ */
+/**
+ * Range of `dot(p, dir)` over an axis-aligned box - the projection of the box
+ * onto the view direction.
+ */
+export declare function projectBoundsOnDirection(min: ArrayLike<number>, max: ArrayLike<number>, dx: number, dy: number, dz: number): {
+    depthMin: number;
+    depthMax: number;
+};
+/** Synchronous sorter with its own scratch buffers. One per splat. */
+export declare class DepthSorter {
+    private readonly _scratch;
+    /**
+     * @param count - How many splats take part. With `subset`, the length of
+     * the prefix of it to use; without, the splats are `[0, count)`.
+     * @param subset - Splat indices to sort, for a count LOD. See
+     * {@link Splat.setCountLod}.
+     */
+    sort(centers: Float32Array, count: number, dx: number, dy: number, dz: number, depthMin: number, depthMax: number, order: Uint32Array, subset?: Uint32Array | null): void;
+}
+export interface SortRequest {
+    dx: number;
+    dy: number;
+    dz: number;
+    depthMin: number;
+    depthMax: number;
+    /**
+     * How many splats to order, for a count LOD. Defaults to all of them; with
+     * a subset set, the length of the prefix of it to use.
+     */
+    count?: number;
+}
+/**
+ * Worker-backed sorter for static splats.
+ *
+ * At most one sort is in flight. A request made while the worker is busy
+ * replaces any earlier pending one, so a fast-moving camera never queues work
+ * it no longer wants. A single order buffer is transferred to the worker and
+ * back, never copied.
+ *
+ * The worker is built from a Blob of this module's own sort routine, so there
+ * is no second file for a bundler to lose.
+ */
+export declare class AsyncDepthSorter {
+    private _worker;
+    private _pending;
+    /** The order buffer, when it is on this side of the worker boundary. */
+    private _order;
+    /**
+     * @param centers - Flat `[x,y,z] * count`. Copied into the worker once.
+     * @param onSorted - Called with each finished order and how many of its
+     * entries are current. The array is only valid for the duration of the call
+     * - it goes back to the worker on the next request - so copy out of it
+     * before returning.
+     */
+    constructor(centers: Float32Array, count: number, onSorted: (order: Uint32Array, count: number) => void);
+    /**
+     * Give the worker the importance ordering a count LOD selects from. Sent
+     * once and kept there, like the centres; after this a request carries only
+     * how many of its entries to use.
+     */
+    setSubset(subset: Uint32Array): void;
+    /** True while a sort is running in the worker. */
+    get busy(): boolean;
+    request(req: SortRequest): void;
+    dispose(): void;
+}

package/dist/types/splat/importance.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Ranking splats by how much they contribute, and the spatial bucketing both
+ * users of that ranking share.
+ *
+ * Two features are built on it. {@link pruneSplats} throws the weakest splats
+ * away at load; the count LOD ({@link Splat.setCountLod}) keeps them all and
+ * processes a prefix of the ranking that shrinks with distance. The ranking
+ * has to be the same one in both cases, which is why it lives here rather than
+ * in either of them.
+ */
+import type { PackedSplats } from './packed-splats';
+/**
+ * Group indices by spatial cell without a comparison sort: hash the cells to
+ * dense ids, count, prefix-sum, scatter.
+ *
+ * O(n) with one map probe per splat, against the O(n log n) a sort over a
+ * composite key would cost - which measured 11-16 ms of a ~40 ms character
+ * load in the Unity build this is ported from.
+ */
+export declare function bucketByCell(cellKey: Float64Array, n: number): {
+    order: Uint32Array;
+    start: Uint32Array;
+    cells: number;
+};
+/**
+ * One splat's cell key on a `1 / voxelSize` grid whose origin is `min`.
+ *
+ * The one definition of the grid. Both users of it have to agree - a splat
+ * pruned by one rule and ranked by another would be thinned twice in the same
+ * place - and they walk different layouts, so what they share is this rather
+ * than a loop.
+ */
+export declare function cellKeyOf(x: number, y: number, z: number, minX: number, minY: number, minZ: number, invVoxel: number): number;
+/**
+ * Cell keys for `centers`, with the grid origin at the actual minimum of the
+ * positions rather than at any declared bounds, which can carry a margin the
+ * grid should not inherit.
+ */
+export declare function cellKeysFor(centers: Float32Array, count: number, voxelSize: number): Float64Array;
+/**
+ * Splat indices ordered so that any prefix of the result is a good-looking
+ * subset of the whole: the most important splat of every cell first, then the
+ * second of every cell, and so on.
+ *
+ * Importance within a cell is opacity times the two largest gaussian axes -
+ * the area the splat actually paints, which the Unity build measured as
+ * ranking 0.80 with the ink each splat deposits, at no cost to compute.
+ *
+ * The round-robin across cells is what makes this usable as a prefix, and it
+ * is the same decision the load-time prune makes for the same reason: ranked
+ * globally, a prefix would be every strong splat on the jacket and none of the
+ * many individually-faint ones that make up a face, so the face would be the
+ * first thing to go. Taken a rank at a time across cells, every region thins
+ * by the same proportion at every prefix length, so a character at 30% looks
+ * like a sparser version of itself rather than a damaged one.
+ *
+ * Costs one pass over the splats plus a small sort inside each cell, and is
+ * built once, the first time a count LOD asks for it.
+ */
+export declare function buildImportanceOrder(packed: PackedSplats, voxelSize: number): Uint32Array;

package/dist/types/splat/packed-splats.d.ts

@@ -0,0 +1,36 @@
+import type { SplatAttributes } from '../loader/character/types';
+/**
+ * Splat attributes packed into the three texel streams the shaders read.
+ *
+ * Renderer-agnostic on purpose: these are plain typed arrays laid out as
+ * `width x height` RGBA texels, so the WebGL and WebGPU backends wrap the same
+ * bytes in their own texture objects.
+ *
+ * The layout is 32 bytes per splat:
+ *
+ * - `color`      RGBA16F - `rgb` display-referred colour, `a` opacity (post-sigmoid).
+ * - `transformA` RGBA32UI - `xyz` the centre as raw float32 bits, `w` two packed
+ *                half floats: rotation `x` (low 16) and `y` (high 16).
+ * - `transformB` RGBA16F - `xyz` linear scale, `w` rotation `z`.
+ *
+ * Rotation `w` is not stored: quaternions are normalised and flipped to
+ * `w >= 0` here, so the shader recovers it as `sqrt(1 - |xyz|^2)`.
+ */
+export interface PackedSplats {
+    numSplats: number;
+    width: number;
+    height: number;
+    color: Uint16Array;
+    transformA: Uint32Array;
+    transformB: Uint16Array;
+    /** Rest-pose centres, flat `[x,y,z] * numSplats`. The depth sort reads these. */
+    centers: Float32Array;
+    boundsMin: [number, number, number];
+    boundsMax: [number, number, number];
+}
+/** Texture dimensions for `count` texels: near-square, wide enough to hold every row. */
+export declare function textureSizeFor(count: number): {
+    width: number;
+    height: number;
+};
+export declare function packSplats(numSplats: number, s: SplatAttributes): PackedSplats;

package/dist/types/splat/prune.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Load-time splat removal: the two passes that make a character cheaper by
+ * containing fewer splats, rather than by drawing each one faster.
+ *
+ * Both run on the decoded attribute columns, before {@link packSplats} turns
+ * them into texels, so a removed splat costs nothing anywhere afterwards -
+ * no texel, no CPU skinning slot, no sort slot, no quad. That is what
+ * separates these from {@link SplatQuality.quadAlphaCutoff}, which shrinks
+ * quads and saves rasterisation alone.
+ *
+ * Ported from the Unity build's `SplatCharacterBinData.CullByOpacity` and
+ * `PruneByImportance`, including the two decisions in them that are easy to
+ * get wrong: ranking inside spatial cells rather than globally, and selecting
+ * rather than sorting within a cell.
+ */
+import type { SplatAttributes } from '../loader/character/types';
+import type { SplatWeights } from '../types';
+/** What {@link pruneSplats} did, for a caller that wants to log or report it. */
+export interface PruneReport {
+    /** Splats the decode handed in. */
+    numSplatsIn: number;
+    /** Splats left after both passes. This is what every consumer should read. */
+    numSplatsOut: number;
+    /** Removed by the opacity floor. */
+    droppedByOpacity: number;
+    /** Removed by the per-voxel importance quota, on top of the opacity floor. */
+    droppedByImportance: number;
+    /**
+     * The skinning influences, re-viewed onto the compacted prefix when anything
+     * was removed, or the caller's own object when nothing was. `undefined` for
+     * a splat with no skinning.
+     *
+     * Handed back rather than mutated in place because the arrays' *length* is
+     * what says how many influences each splat has: `Splat` divides it by the
+     * splat count to recover `K`, and leaving a pruned set at its original
+     * length would make that division report a `K` several times too large.
+     */
+    weights?: SplatWeights;
+}
+export interface PruneOptions {
+    /** Defaults to {@link SplatQuality.minOpacity}. */
+    minOpacity?: number;
+    /** Defaults to {@link SplatQuality.pruneRatio}. */
+    pruneRatio?: number;
+    /** Defaults to {@link SplatQuality.pruneVoxelSize}. */
+    voxelSize?: number;
+}
+/**
+ * Remove splats the current quality settings say are not worth carrying,
+ * compacting every column in place.
+ *
+ * `attributes` and `weights` are mutated: their arrays keep their allocated
+ * length and the returned count is what every consumer should read, which is
+ * exactly how {@link packSplats} already uses `numSplats`. Order is preserved,
+ * so whatever spatial coherence the file had survives.
+ *
+ * Returns the input count unchanged, having touched nothing, when both knobs
+ * are off - the default - so this sits on the load path for free.
+ */
+export declare function pruneSplats(numSplats: number, attributes: SplatAttributes, weights?: SplatWeights, opts?: PruneOptions): PruneReport;