@viggle/splat-engine-three 0.1.0 → 0.1.1

package/dist/chunks/{chunk-MM6DJU6S.js → chunk-WN5WBKM4.js}

@@ -1,5 +1,5 @@
 // src/three/splat-character.ts
-import { Color, Matrix4 as Matrix42, Object3D, SRGBColorSpace, Vector3 as Vector35 } from "three";
+import { Color, Matrix3, Matrix4 as Matrix42, Object3D, SRGBColorSpace, Vector3 as Vector35 } from "three";
 
 // src/character.ts
 import { Euler, MathUtils, Vector3 as Vector34 } from "three";
@@ -2341,6 +2341,14 @@ function buildSourceBoneRemap(splat, numBones, skeletonLibrary) {
   const sourceCount = splat.sourceBoneCount;
   if (!sourceCount || sourceCount === numBones) return null;
   if (!skeletonLibrary) return null;
+  if (sourceCount === 119 && numBones === 86) {
+    const head = skeletonLibrary.boneNames?.indexOf("head") ?? -1;
+    if (head < 0) return null;
+    const remap2 = new Int32Array(sourceCount);
+    for (let i = 0; i < 86; i++) remap2[i] = i;
+    remap2.fill(head, 86);
+    return remap2;
+  }
   let targetNames;
   if (skeletonLibrary.boneNames?.length === numBones) targetNames = skeletonLibrary.boneNames;
   else if (skeletonLibrary.boneNames441?.length === numBones) targetNames = skeletonLibrary.boneNames441;
@@ -2404,15 +2412,20 @@ function initializeSplatBoneMapping(splat, numBones, skeletonLibrary) {
       }
     }
   }
+  splat.syncMappedCpuInfluences(firstIdx);
   splat.markBoneTexturesDirty();
   return firstIdx;
 }
-function buildSplatBoneIndexList(splat, numBones) {
+function buildSplatBoneIndexList(splat, numBones, firstPaletteIdx) {
   const weights = splat.splatWeights;
   if (!weights) return new Int32Array(0);
   const used = new Uint8Array(numBones);
+  const indices = splat.boneIndicesData;
+  const mappedWeights = splat.boneWeightsData;
+  if (!indices || !mappedWeights) return new Int32Array(0);
   for (let i = 0; i < weights.indices.length; i++) {
-    const idx2 = weights.indices[i] | 0;
+    if (mappedWeights[i] <= 1e-3) continue;
+    const idx2 = indices[i] - firstPaletteIdx | 0;
     if (idx2 >= 0 && idx2 < numBones) used[idx2] = 1;
   }
   let count = 0;
@@ -2561,7 +2574,7 @@ var SplatSkinning = class {
       }
       let boneIndexList = this._boneIndexLists.get(splat);
       if (!boneIndexList) {
-        boneIndexList = buildSplatBoneIndexList(splat, numBones);
+        boneIndexList = buildSplatBoneIndexList(splat, numBones, firstPaletteIdx);
         this._boneIndexLists.set(splat, boneIndexList);
       }
       const palette = splat.transformPalette;
@@ -3741,6 +3754,490 @@ function packSplats(numSplats, s) {
   };
 }
 
+// src/splat/importance.ts
+import { DataUtils as DataUtils2 } from "three";
+function bucketByCell(cellKey, n) {
+  const id = /* @__PURE__ */ new Map();
+  const dense = new Uint32Array(n);
+  let cells = 0;
+  for (let i = 0; i < n; i++) {
+    const key = cellKey[i];
+    let d = id.get(key);
+    if (d === void 0) {
+      d = cells++;
+      id.set(key, d);
+    }
+    dense[i] = d;
+  }
+  const start = new Uint32Array(cells + 1);
+  for (let i = 0; i < n; i++) start[dense[i] + 1]++;
+  for (let c = 0; c < cells; c++) start[c + 1] += start[c];
+  const order = new Uint32Array(n);
+  const cursor = new Uint32Array(cells);
+  for (let i = 0; i < n; i++) {
+    const d = dense[i];
+    order[start[d] + cursor[d]++] = i;
+  }
+  return { order, start, cells };
+}
+var CELL_STRIDE = 1024;
+function cellKeyOf(x, y, z, minX, minY, minZ, invVoxel) {
+  const cx = Math.floor((x - minX) * invVoxel);
+  const cy = Math.floor((y - minY) * invVoxel);
+  const cz = Math.floor((z - minZ) * invVoxel);
+  return (cx * CELL_STRIDE + cy) * CELL_STRIDE + cz;
+}
+function cellKeysFor(centers, count, voxelSize) {
+  let minX = Infinity, minY = Infinity, minZ = Infinity;
+  for (let i = 0, c = 0; i < count; i++, c += 3) {
+    if (centers[c] < minX) minX = centers[c];
+    if (centers[c + 1] < minY) minY = centers[c + 1];
+    if (centers[c + 2] < minZ) minZ = centers[c + 2];
+  }
+  const inv = 1 / voxelSize;
+  const keys = new Float64Array(count);
+  for (let i = 0, c = 0; i < count; i++, c += 3) {
+    keys[i] = cellKeyOf(centers[c], centers[c + 1], centers[c + 2], minX, minY, minZ, inv);
+  }
+  return keys;
+}
+function buildImportanceOrder(packed, voxelSize) {
+  const n = packed.numSplats;
+  const out = new Uint32Array(n);
+  if (n === 0) return out;
+  const { color, transformB, centers } = packed;
+  const half = DataUtils2.fromHalfFloat;
+  const score = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const o = i * 4;
+    const alpha = half(color[o + 3]);
+    const s0 = half(transformB[o]);
+    const s1 = half(transformB[o + 1]);
+    const s2 = half(transformB[o + 2]);
+    const mx = s0 > s1 ? s0 > s2 ? s0 : s2 : s1 > s2 ? s1 : s2;
+    const mn = s0 < s1 ? s0 < s2 ? s0 : s2 : s1 < s2 ? s1 : s2;
+    score[i] = alpha * mx * (s0 + s1 + s2 - mx - mn);
+  }
+  const { order, start, cells } = bucketByCell(cellKeysFor(centers, n, voxelSize), n);
+  let widest = 0;
+  const scratch = [];
+  for (let c = 0; c < cells; c++) {
+    const lo = start[c];
+    const hi = start[c + 1];
+    const size = hi - lo;
+    if (size > widest) widest = size;
+    if (size < 2) continue;
+    scratch.length = 0;
+    for (let k = lo; k < hi; k++) scratch.push(order[k]);
+    scratch.sort((a, b) => score[b] - score[a]);
+    for (let k = 0; k < size; k++) order[lo + k] = scratch[k];
+  }
+  let w = 0;
+  for (let rank = 0; rank < widest; rank++) {
+    for (let c = 0; c < cells; c++) {
+      const at = start[c] + rank;
+      if (at < start[c + 1]) out[w++] = order[at];
+    }
+  }
+  return out;
+}
+
+// src/splat/quality.ts
+var MAX_MIN_OPACITY = 0.1;
+var _quadAlphaCutoff = 8 / 255;
+var _screenSizeCull = 0;
+var _minOpacity = 0.05;
+var _pruneRatio = 0;
+var _pruneVoxelSize = 0.04;
+var clamp = (v, lo, hi) => v < lo ? lo : v > hi ? hi : v;
+var warnedAboutCap = false;
+var SplatQuality = {
+  /**
+   * Alpha at which a splat's quad is allowed to end, so each one is sized to
+   * the radius its own opacity actually reaches instead of to the worst case.
+   * **The first knob to reach for on a weak GPU.**
+   *
+   * The fragment stage multiplies a gaussian falloff by the splat's opacity
+   * and discards anything below 1/255, so a quad drawn out to where that
+   * product is already below the cutoff spends fragments on a ring that
+   * cannot put ink on the screen. Raising the cutoff shrinks every quad. What
+   * it costs is a harder edge on each splat, which shows first on soft things
+   * - hair, fabric, anything semi-transparent.
+   *
+   * Takes effect on the next frame; nothing is reloaded and nothing is lost,
+   * so it is safe to drive from a frame-rate governor.
+   *
+   * | Value | What it is for |
+   * |---|---|
+   * | `1 / 255` | Exactly the behaviour before this knob existed. Changes nothing at all: below it a fragment is discarded anyway, so the quad it trims was drawing nothing. |
+   * | `8 / 255` | What the Unity build ships. The conservative end. |
+   * | `12 / 255` | **The default here.** |
+   * | `16 / 255` | **Low-end phones, and the floor.** Still 43.7 dB overall and 34.8 dB on the face, which the Unity build calls invisible at arm's length. |
+   * | above `16 / 255` | Not on this project. The Unity build measures a further -7% at 24/255, but the edges are visibly harder by then; a device that needs more should spend it on {@link SplatQuality.pruneRatio}, the renderer's pixel ratio, or a distance LOD, none of which harden every silhouette in the frame. |
+   *
+   * Measured on a Mali-G57 with three characters, against 8/255: 12/255 -7%,
+   * 16/255 -12%, 24/255 -19%. Measured here on an Apple GPU where fragments
+   * are the bottleneck, against 1/255: 8/255 -29%, 16/255 -42%, 24/255 -50%.
+   * Where the main thread is the bottleneck instead - the WebGL backend with
+   * animated characters - it is free but buys nothing; see the README's
+   * Tuning section for which case a scene is in.
+   */
+  get quadAlphaCutoff() {
+    return _quadAlphaCutoff;
+  },
+  set quadAlphaCutoff(value) {
+    _quadAlphaCutoff = clamp(value, 0, 1);
+  },
+  /**
+   * Drop splats whose projected size falls below this radius in pixels, for
+   * every splat at once. `0` (the default) draws everything.
+   *
+   * The same test as the per-splat {@link Splat.minPixelSize}; the larger of
+   * the two wins, so a global floor cannot un-cull a splat an application
+   * already asked to cull. Removes distant crowd splats that cannot contribute
+   * more than a fraction of a pixel.
+   */
+  get screenSizeCull() {
+    return _screenSizeCull;
+  },
+  set screenSizeCull(value) {
+    _screenSizeCull = Math.max(0, value);
+  },
+  /**
+   * Peak opacity a splat must reach to be kept when a character or scene is
+   * loaded. `0` keeps everything.
+   *
+   * A splat's alpha at its centre IS its opacity - the gaussian only falls
+   * off from there - so the faintest splats in a bundle are ones that paint
+   * almost nothing from any camera while still costing memory, a skinning
+   * pass, a sort slot and a quad. This removes them outright, which is what
+   * separates it from {@link SplatQuality.quadAlphaCutoff}: the cutoff
+   * shrinks a splat's quad and saves rasterisation alone, this saves
+   * everything, but it cannot half-remove one.
+   *
+   * **Applied during the decode of a CHARACTER bundle**, so it only affects
+   * what is loaded afterwards - set it before the first `load()`, and changing
+   * it later does nothing to characters already in the scene. It does not
+   * touch `.ply` scenes, matching the Unity build, which applies it in the
+   * skinned renderer and nowhere else: a scene's opacity distribution is a
+   * different thing, and 0.05 measured as 8.7% of a character against 41.8%
+   * of a 1M-splat room. {@link pruneSplats} is exported for an application
+   * that wants to make the trade on a scene of its own. It also changes
+   * {@link Splat.numSplats}, so an application that hands back a per-splat
+   * array ({@link Splat.setSplatGroups}) must size that array from
+   * `numSplats` after loading rather than from the file.
+   *
+   * | Value | What it is for |
+   * |---|---|
+   * | `0` | Keep every splat. The behaviour before this knob existed. |
+   * | `1 / 255` | Free in the strict sense: provably pixel-identical, because a splat under the fragment shader's own discard cannot produce a pixel. Worth about 2% of a character. |
+   * | `0.05` | **The default here, and what the Unity build ships.** Removes ~13% of a typical character for a difference of at most 11/255 on 1.3% of it - 58-62 dB, which does not read as a quality loss. |
+   * | above `0.05` | Untested. Prefer {@link SplatQuality.pruneRatio} to go further: it is measured, and it thins every region by the same share instead of taking the faintest splats wherever they happen to be - which is disproportionately the face. |
+   */
+  get minOpacity() {
+    return _minOpacity;
+  },
+  set minOpacity(value) {
+    if (value > MAX_MIN_OPACITY && !warnedAboutCap) {
+      warnedAboutCap = true;
+      console.warn(
+        `[splat-engine-three] SplatQuality.minOpacity is capped at ${MAX_MIN_OPACITY}; ${value} was requested and ${MAX_MIN_OPACITY} applied. Past the cap a character loses the faint splats its soft edges are made of. To go further, use pruneRatio, the renderer's pixel ratio, or a distance LOD.`
+      );
+    }
+    _minOpacity = clamp(value, 0, MAX_MIN_OPACITY);
+  },
+  /**
+   * Fraction of splats removed at load by voxel-local importance, on top of
+   * {@link SplatQuality.minOpacity}. `0` (the default) keeps everything, `0.5`
+   * drops the least-important half of every cell.
+   *
+   * Importance is opacity times a splat's two largest axes - the area it
+   * actually paints - ranked separately inside each spatial cell so a dense
+   * region loses the same share as a sparse one rather than being deleted
+   * wholesale. That per-cell quota is what keeps the face: a global ranking
+   * puts the many faint facial splats at the bottom and smears it. Measured on
+   * the Unity build's reference character at 0.5: 25,826 of 50,267 splats
+   * remain, the frame falls 24.5% on a Mali-G57, and the face holds 43.5 dB
+   * where a global rank gives 37.6.
+   *
+   * Applied during the decode of a character bundle, like
+   * {@link SplatQuality.minOpacity}, with the same scope and the same reason
+   * for being off by default.
+   */
+  get pruneRatio() {
+    return _pruneRatio;
+  },
+  set pruneRatio(value) {
+    _pruneRatio = clamp(value, 0, 1);
+  },
+  /**
+   * Cell size, in metres, for {@link SplatQuality.pruneRatio}'s per-voxel
+   * quota.
+   *
+   * 4 cm gives ~19 splats per occupied cell on the Unity build's reference
+   * character - small enough that the face and the jacket are ranked apart,
+   * large enough that a cell has a population to rank. A tuning constant
+   * rather than a per-title knob, exposed because a character authored at a
+   * different scale needs a different one.
+   */
+  get pruneVoxelSize() {
+    return _pruneVoxelSize;
+  },
+  set pruneVoxelSize(value) {
+    _pruneVoxelSize = Math.max(1e-4, value);
+  },
+  /**
+   * Test each splat against the depth buffer, so opaque geometry hides the
+   * splats behind it. On by default.
+   *
+   * Unlike the Unity build, where turning this off was the single largest
+   * mobile saving, this is a correctness switch here and not a performance
+   * one: that build renders splats into an offscreen target and pays for the
+   * test by sampling a depth texture per fragment, where this package draws
+   * straight into the camera's target and gets the hardware depth test for
+   * free. Turning it off makes characters draw through walls and saves
+   * nothing. It is here because the behaviour is occasionally what an
+   * application wants - a character deliberately drawn over the scene.
+   */
+  depthOcclusion: true,
+  /**
+   * Collect {@link SplatQuality.timings}. Off by default.
+   *
+   * The CPU stages are timed with `performance.now()`, which is cheap but not
+   * free at a few calls per splat per frame, and a shipping application that
+   * never reads the numbers should not pay for them.
+   */
+  passTimings: false,
+  /**
+   * Per-stage cost of the last frame in which {@link SplatQuality.passTimings}
+   * was on, in milliseconds, summed over every splat that ran that stage.
+   *
+   * These are main-thread times, which is the measurement that matters for
+   * this package: under `WebGLRenderer` the per-character CPU cost - skinning
+   * every centre to feed the sort, then the sort - is what limits how many
+   * characters a scene can carry, and neither stage exists on the GPU
+   * timeline. `skin` and `sort` are zero under `WebGPURenderer`, where both
+   * happen in compute; `splatsDrawn` and `splatsTotal` are meaningful on both,
+   * and differ when {@link SplatQuality.screenSizeCull} or a count LOD is
+   * reducing what is submitted.
+   *
+   * These describe the most recent pass in which any splat drew, so read them
+   * after your render call. A pass that drew no splats leaves the previous
+   * numbers in place rather than zeroing them - a zero and "nothing happened"
+   * would otherwise read the same, which is the mistake the Unity build's
+   * equivalent made and spent a long time chasing.
+   */
+  timings: {
+    /** CPU skinning of splat centres, i.e. `Splat.ensureCenters`. */
+    skin: 0,
+    /** The depth sort, where it runs on the main thread. */
+    sort: 0,
+    /** Uniform and buffer updates in `beforeRender`, excluding skin and sort. */
+    prepare: 0,
+    /** Splat instances submitted to the GPU this frame. */
+    splatsDrawn: 0,
+    /** Splat instances those draws could have covered at full detail. */
+    splatsTotal: 0
+  },
+  /** Restore every knob to its default. Call when tearing the engine down. */
+  resetStatics() {
+    SplatQuality.quadAlphaCutoff = 8 / 255;
+    SplatQuality.screenSizeCull = 0;
+    SplatQuality.minOpacity = 0.05;
+    SplatQuality.pruneRatio = 0;
+    SplatQuality.pruneVoxelSize = 0.04;
+    SplatQuality.depthOcclusion = true;
+    SplatQuality.passTimings = false;
+    resetTimings();
+  }
+};
+function effectiveMinPixelSize(splatMinPixelSize) {
+  const global = SplatQuality.screenSizeCull;
+  return global > splatMinPixelSize ? global : splatMinPixelSize;
+}
+var pendingSkin = 0;
+var contributors = /* @__PURE__ */ new Set();
+function addSkinTime(ms) {
+  pendingSkin += ms;
+}
+function resetTimings() {
+  const t = SplatQuality.timings;
+  t.skin = pendingSkin;
+  pendingSkin = 0;
+  t.sort = 0;
+  t.prepare = 0;
+  t.splatsDrawn = 0;
+  t.splatsTotal = 0;
+}
+function beginFrameTimings(source) {
+  if (contributors.has(source)) {
+    contributors.clear();
+    resetTimings();
+  }
+  contributors.add(source);
+}
+
+// src/splat/prune.ts
+var COLUMNS = [
+  "x",
+  "y",
+  "z",
+  "scale_0",
+  "scale_1",
+  "scale_2",
+  "rot_0",
+  "rot_1",
+  "rot_2",
+  "rot_3",
+  "f_dc_0",
+  "f_dc_1",
+  "f_dc_2",
+  "opacity"
+];
+function pruneSplats(numSplats, attributes, weights, opts) {
+  const minOpacity = opts?.minOpacity ?? SplatQuality.minOpacity;
+  const pruneRatio = opts?.pruneRatio ?? SplatQuality.pruneRatio;
+  const voxelSize = opts?.voxelSize ?? SplatQuality.pruneVoxelSize;
+  const report = {
+    numSplatsIn: numSplats,
+    numSplatsOut: numSplats,
+    droppedByOpacity: 0,
+    droppedByImportance: 0,
+    weights
+  };
+  if (numSplats === 0) return report;
+  const k = influencesPerSplat(numSplats, weights);
+  let count = numSplats;
+  if (minOpacity > 0) {
+    const kept = cullByOpacity(count, attributes, weights, k, minOpacity);
+    report.droppedByOpacity = count - kept;
+    count = kept;
+  }
+  if (pruneRatio > 0 && voxelSize > 0) {
+    const kept = pruneByImportance(count, attributes, weights, k, Math.min(pruneRatio, 1), voxelSize);
+    report.droppedByImportance = count - kept;
+    count = kept;
+  }
+  report.numSplatsOut = count;
+  if (weights && count !== numSplats) {
+    report.weights = {
+      indices: weights.indices.subarray(0, count * k),
+      weights: weights.weights.subarray(0, count * k)
+    };
+  }
+  return report;
+}
+function influencesPerSplat(numSplats, weights) {
+  if (!weights || numSplats === 0) return 0;
+  return Math.max(1, Math.floor(weights.indices.length / numSplats));
+}
+function cullByOpacity(numSplats, attributes, weights, influences, minOpacity) {
+  if (minOpacity >= 1) return 0;
+  const threshold = Math.log(minOpacity / (1 - minOpacity));
+  const opacity = attributes.opacity;
+  const keep = new Uint8Array(numSplats);
+  let kept = 0;
+  for (let i = 0; i < numSplats; i++) {
+    if (opacity[i] >= threshold) {
+      keep[i] = 1;
+      kept++;
+    }
+  }
+  if (kept === numSplats) return kept;
+  compact(numSplats, keep, attributes, weights, influences);
+  return kept;
+}
+function pruneByImportance(numSplats, attributes, weights, influences, ratio, voxelSize) {
+  const { x, y, z, scale_0, scale_1, scale_2, opacity } = attributes;
+  let minX = Infinity, minY = Infinity, minZ = Infinity;
+  for (let i = 0; i < numSplats; i++) {
+    if (x[i] < minX) minX = x[i];
+    if (y[i] < minY) minY = y[i];
+    if (z[i] < minZ) minZ = z[i];
+  }
+  const invVoxel = 1 / voxelSize;
+  const score = new Float32Array(numSplats);
+  const cellKey = new Float64Array(numSplats);
+  for (let i = 0; i < numSplats; i++) {
+    const s0 = Math.exp(scale_0[i]);
+    const s1 = Math.exp(scale_1[i]);
+    const s2 = Math.exp(scale_2[i]);
+    const mx = s0 > s1 ? s0 > s2 ? s0 : s2 : s1 > s2 ? s1 : s2;
+    const mn = s0 < s1 ? s0 < s2 ? s0 : s2 : s1 < s2 ? s1 : s2;
+    const md = s0 + s1 + s2 - mx - mn;
+    const alpha = 1 / (1 + Math.exp(-opacity[i]));
+    score[i] = alpha * mx * md;
+    cellKey[i] = cellKeyOf(x[i], y[i], z[i], minX, minY, minZ, invVoxel);
+  }
+  const { order, start, cells } = bucketByCell(cellKey, numSplats);
+  const keep = new Uint8Array(numSplats).fill(1);
+  let dropped = 0;
+  for (let c = 0; c < cells; c++) {
+    const lo = start[c];
+    const hi = start[c + 1];
+    const size = hi - lo;
+    const dropN = Math.floor(size * ratio);
+    if (dropN <= 0) continue;
+    if (dropN >= size) {
+      for (let k = lo; k < hi; k++) keep[order[k]] = 0;
+      dropped += size;
+      continue;
+    }
+    selectWeakest(order, score, lo, hi, dropN);
+    for (let k = 0; k < dropN; k++) keep[order[lo + k]] = 0;
+    dropped += dropN;
+  }
+  if (dropped === 0) return numSplats;
+  compact(numSplats, keep, attributes, weights, influences);
+  return numSplats - dropped;
+}
+function selectWeakest(order, score, lo, hi, k) {
+  while (hi - lo > 1) {
+    const mid = lo + (hi - lo >> 1);
+    const a = score[order[lo]];
+    const b = score[order[mid]];
+    const c = score[order[hi - 1]];
+    const pivot = a < b ? b < c ? b : a < c ? c : a : a < c ? a : b < c ? c : b;
+    let i = lo;
+    let j = hi - 1;
+    while (i <= j) {
+      while (score[order[i]] < pivot) i++;
+      while (score[order[j]] > pivot) j--;
+      if (i <= j) {
+        const t = order[i];
+        order[i] = order[j];
+        order[j] = t;
+        i++;
+        j--;
+      }
+    }
+    if (lo + k <= i && lo + k > j + 1) return;
+    if (lo + k <= j + 1) hi = j + 1;
+    else {
+      k -= i - lo;
+      lo = i;
+    }
+  }
+}
+function compact(numSplats, keep, attributes, weights, k) {
+  const indices = weights?.indices;
+  const values = weights?.weights;
+  let w = 0;
+  for (let r = 0; r < numSplats; r++) {
+    if (!keep[r]) continue;
+    if (w !== r) {
+      for (const column of COLUMNS) attributes[column][w] = attributes[column][r];
+      if (indices && values) {
+        for (let j = 0; j < k; j++) {
+          indices[w * k + j] = indices[r * k + j];
+          values[w * k + j] = values[r * k + j];
+        }
+      }
+    }
+    w++;
+  }
+}
+
 // src/loader/character/types.ts
 var CharacterBundleError = class extends Error {
   category;
@@ -4854,10 +5351,16 @@ async function decodeCharacterBundle(file) {
     };
   }
   const header = result.header;
+  const decodedWeights = result.boneIndices && result.boneWeights ? { indices: result.boneIndices, weights: result.boneWeights } : void 0;
+  const { numSplatsOut, weights: splatWeights } = pruneSplats(
+    result.numSplats,
+    result.splats,
+    decodedWeights
+  );
   return {
     source: {
-      packed: packSplats(result.numSplats, result.splats),
-      splatWeights: result.boneIndices && result.boneWeights ? { indices: result.boneIndices, weights: result.boneWeights } : void 0,
+      packed: packSplats(numSplatsOut, result.splats),
+      splatWeights,
       sourceBoneCount: header?.numBones ?? armatureData?.numBones
     },
     armatureData,
@@ -5019,7 +5522,7 @@ import {
 } from "three";
 
 // src/splat/depth-sort.ts
-function countingSortByDepth(centers, count, dx, dy, dz, depthMin, depthMax, order, scratch) {
+function countingSortByDepth(centers, count, dx, dy, dz, depthMin, depthMax, order, scratch, subset) {
   if (count === 0) return;
   const bits = Math.max(10, Math.min(20, Math.round(Math.log2(count / 4))));
   const bucketCount = 1 << bits;
@@ -5031,17 +5534,31 @@ function countingSortByDepth(centers, count, dx, dy, dz, depthMin, depthMax, ord
   const range = depthMax - depthMin;
   const scale = range > 1e-12 ? (bucketCount - 1) / range : 0;
   const last = bucketCount - 1;
-  for (let i = 0, c = 0; i < count; i++, c += 3) {
-    const depth = centers[c] * dx + centers[c + 1] * dy + centers[c + 2] * dz;
-    let key = (depthMax - depth) * scale | 0;
-    if (key < 0) key = 0;
-    else if (key > last) key = last;
-    keys[i] = key;
-    counts[key]++;
+  if (subset) {
+    for (let i = 0; i < count; i++) {
+      const c = subset[i] * 3;
+      const depth = centers[c] * dx + centers[c + 1] * dy + centers[c + 2] * dz;
+      let key = (depthMax - depth) * scale | 0;
+      if (key < 0) key = 0;
+      else if (key > last) key = last;
+      keys[i] = key;
+      counts[key]++;
+    }
+  } else {
+    for (let i = 0, c = 0; i < count; i++, c += 3) {
+      const depth = centers[c] * dx + centers[c + 1] * dy + centers[c + 2] * dz;
+      let key = (depthMax - depth) * scale | 0;
+      if (key < 0) key = 0;
+      else if (key > last) key = last;
+      keys[i] = key;
+      counts[key]++;
+    }
   }
   for (let i = 1; i < bucketCount; i++) counts[i] += counts[i - 1];
-  for (let i = count - 1; i >= 0; i--) {
-    order[--counts[keys[i]]] = i;
+  if (subset) {
+    for (let i = count - 1; i >= 0; i--) order[--counts[keys[i]]] = subset[i];
+  } else {
+    for (let i = count - 1; i >= 0; i--) order[--counts[keys[i]]] = i;
   }
 }
 function projectBoundsOnDirection(min, max, dx, dy, dz) {
@@ -5051,8 +5568,14 @@ function projectBoundsOnDirection(min, max, dx, dy, dz) {
 }
 var DepthSorter = class {
   _scratch = { keys: null, counts: null };
-  sort(centers, count, dx, dy, dz, depthMin, depthMax, order) {
-    countingSortByDepth(centers, count, dx, dy, dz, depthMin, depthMax, order, this._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, count, dx, dy, dz, depthMin, depthMax, order, subset) {
+    countingSortByDepth(centers, count, dx, dy, dz, depthMin, depthMax, order, this._scratch, subset);
   }
 };
 var AsyncDepthSorter = class {
@@ -5062,22 +5585,26 @@ var AsyncDepthSorter = class {
   _order;
   /**
    * @param centers - Flat `[x,y,z] * count`. Copied into the worker once.
-   * @param onSorted - Called with each finished order. 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.
+   * @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, count, onSorted) {
     this._order = new Uint32Array(count);
     const source = `
       const sortByDepth = (${countingSortByDepth.toString()});
       let centers = null;
+      let subset = null;
       const scratch = { keys: null, counts: null };
       self.onmessage = (e) => {
         const m = e.data;
         if (m.centers) { centers = m.centers; return; }
+        if (m.subset) { subset = m.subset; return; }
         const order = m.order;
-        sortByDepth(centers, order.length, m.dx, m.dy, m.dz, m.depthMin, m.depthMax, order, scratch);
-        self.postMessage({ order }, [order.buffer]);
+        const count = m.count === undefined ? order.length : m.count;
+        sortByDepth(centers, count, m.dx, m.dy, m.dz, m.depthMin, m.depthMax, order, scratch, subset);
+        self.postMessage({ order, count }, [order.buffer]);
       };
     `;
     const url = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
@@ -5085,7 +5612,7 @@ var AsyncDepthSorter = class {
     URL.revokeObjectURL(url);
     this._worker.onmessage = (e) => {
       this._order = e.data.order;
-      onSorted(this._order);
+      onSorted(this._order, e.data.count);
       if (this._pending) {
         const next = this._pending;
         this._pending = null;
@@ -5095,6 +5622,16 @@ var AsyncDepthSorter = class {
     const copy = centers.slice(0, count * 3);
     this._worker.postMessage({ centers: copy }, [copy.buffer]);
   }
+  /**
+   * 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) {
+    if (!this._worker) return;
+    const copy = subset.slice();
+    this._worker.postMessage({ subset: copy }, [copy.buffer]);
+  }
   /** True while a sort is running in the worker. */
   get busy() {
     return this._order === null;
@@ -5382,6 +5919,11 @@ uniform int uTexWidth;
 // Drawing-buffer size in pixels.
 uniform vec2 uViewport;
 uniform float uMinPixelSize;
+// 1 / the alpha a splat's quad is allowed to end at. Carried as the reciprocal
+// so the historic 1/255 cutoff arrives as exactly 255.0 and the two
+// expressions below reduce, bit for bit, to what they were before the cutoff
+// was a setting at all. See SplatQuality.quadAlphaCutoff.
+uniform float uAlphaCutoffScale;
 // World rotation (xyzw) and scale of the splat object.
 uniform vec4 uModelRotation;
 uniform vec3 uModelScale;
@@ -5572,14 +6114,19 @@ void main(void) {
         clr.rgb = clamp(clr.rgb, 0.0, 1.0);
     }
 
-    if (255.0 * clr.a <= 1.0) {
+    // A splat whose peak alpha is already under the cutoff cannot put a
+    // fragment on screen: its own quad would be empty.
+    float alphaOverCutoff = clr.a * uAlphaCutoffScale;
+    if (alphaOverCutoff <= 1.0) {
         gl_Position = discardVec;
         return;
     }
 
-    // Shrink the quad to where the gaussian is still above 1/255: fewer
-    // fragments, identical pixels.
-    float clip = min(1.0, sqrt(log(255.0 * clr.a)) * 0.5);
+    // Shrink the quad to where the gaussian is still above the cutoff: fewer
+    // fragments. At a cutoff of 1/255 the pixels are identical, since below
+    // that frag() discards anyway; above it, this is the trade the setting
+    // exists to make.
+    float clip = min(1.0, sqrt(log(alphaOverCutoff)) * 0.5);
     offset *= clip;
 
     gl_Position = centerProj + vec4(offset, 0.0, 0.0);
@@ -5645,6 +6192,8 @@ var WebGLSplatImpl = class {
   _lastDx = NaN;
   _lastDy = NaN;
   _lastDz = NaN;
+  /** The importance ordering the worker already holds, if any. */
+  _sentSubset = null;
   /**
    * @param asyncSort - Sort in a worker and keep drawing the previous order
    * meanwhile. Right for large static splats; wrong for skinned ones, whose
@@ -5674,6 +6223,7 @@ var WebGLSplatImpl = class {
         uTexWidth: { value: splat.packed.width },
         uViewport: { value: new Vector2(1, 1) },
         uMinPixelSize: { value: 0 },
+        uAlphaCutoffScale: { value: 255 },
         uModelRotation: { value: new Vector4(0, 0, 0, 1) },
         uModelScale: { value: new Vector32(1, 1, 1) },
         uTint: { value: splat.tint },
@@ -5712,10 +6262,10 @@ var WebGLSplatImpl = class {
     if (asyncSort) {
       this._syncSorter = null;
       geometry.instanceCount = 0;
-      this._asyncSorter = new AsyncDepthSorter(splat.centers, splat.numSplats, (sorted) => {
+      this._asyncSorter = new AsyncDepthSorter(splat.centers, splat.numSplats, (sorted, count) => {
         order.array.set(sorted);
         order.needsUpdate = true;
-        geometry.instanceCount = splat.numSplats;
+        geometry.instanceCount = count;
       });
     } else {
       this._asyncSorter = null;
@@ -5759,6 +6309,7 @@ var WebGLSplatImpl = class {
     box.getBoundingSphere(this.geometry.boundingSphere);
   }
   beforeRender(renderer, camera) {
+    const tEntered = SplatQuality.passTimings ? performance.now() : 0;
     const gl = renderer;
     const splat = this._splat;
     const u = this.material.uniforms;
@@ -5770,16 +6321,31 @@ var WebGLSplatImpl = class {
     this._host.matrixWorld.decompose(_position, _quaternion, _scale);
     u.uModelRotation.value.set(_quaternion.x, _quaternion.y, _quaternion.z, _quaternion.w);
     u.uModelScale.value.copy(_scale);
-    u.uMinPixelSize.value = splat.minPixelSize;
+    u.uMinPixelSize.value = effectiveMinPixelSize(splat.minPixelSize);
+    u.uAlphaCutoffScale.value = 1 / Math.max(1 / 65535, SplatQuality.quadAlphaCutoff);
     u.transformPalette.value = splat.transformPalette.texture;
     u.splatGroupIds.value = splat.groupIdsTexture ?? null;
     u.splatVariantMask.value = splat.variantMaskTexture ?? null;
+    if (this.material.depthTest !== SplatQuality.depthOcclusion) {
+      this.material.depthTest = SplatQuality.depthOcclusion;
+    }
     this._engine.syncLighting();
+    if (!SplatQuality.passTimings) {
+      this._sortFor(camera);
+      return;
+    }
+    beginFrameTimings(this);
+    const t = SplatQuality.timings;
+    const tPrepared = performance.now();
+    t.prepare += tPrepared - tEntered;
     this._sortFor(camera);
+    t.sort += performance.now() - tPrepared;
+    t.splatsDrawn += this.geometry.instanceCount;
+    t.splatsTotal += splat.numSplats;
   }
   _sortFor(camera) {
     const splat = this._splat;
-    const count = splat.numSplats;
+    const count = splat.activeSplatCount;
     if (count === 0) return;
     splat.ensureCenters();
     const ce = camera.matrixWorld.elements;
@@ -5804,11 +6370,27 @@ var WebGLSplatImpl = class {
       dy,
       dz
     );
+    const subset = splat.countLodActive ? splat.importanceOrder : null;
     if (this._asyncSorter) {
-      this._asyncSorter.request({ dx, dy, dz, depthMin, depthMax });
+      if (subset && subset !== this._sentSubset) {
+        this._sentSubset = subset;
+        this._asyncSorter.setSubset(subset);
+      }
+      this._asyncSorter.request({ dx, dy, dz, depthMin, depthMax, count });
     } else {
-      this._syncSorter.sort(splat.centers, count, dx, dy, dz, depthMin, depthMax, this._order.array);
+      this._syncSorter.sort(
+        splat.centers,
+        count,
+        dx,
+        dy,
+        dz,
+        depthMin,
+        depthMax,
+        this._order.array,
+        subset
+      );
       this._order.needsUpdate = true;
+      this.geometry.instanceCount = count;
     }
   }
   dispose() {
@@ -6026,6 +6608,10 @@ var Splat = class _Splat {
   localBounds = new Box3();
   /** Discard splats smaller than this many pixels on screen. `0` draws everything. */
   minPixelSize = 0;
+  _activeSplatCount;
+  _importanceOrder = null;
+  /** `_importanceOrder` inverted: each splat's place in it. @internal */
+  _importanceRank = null;
   _mesh;
   _cpuInfluences = null;
   _pendingBoneTransforms = null;
@@ -6069,6 +6655,7 @@ var Splat = class _Splat {
       const size = this.localBounds.getSize(_size);
       this.localBounds.expandByScalar(0.5 * Math.max(size.x, size.y, size.z));
     }
+    this._activeSplatCount = this.numSplats;
     const asyncSort = opts?.asyncSort ?? !this.splatWeights;
     this._mesh = new SplatMesh(this, engine, asyncSort);
     this.object3D = this._mesh;
@@ -6103,10 +6690,101 @@ var Splat = class _Splat {
     }
     return { indices, weights };
   }
+  /**
+   * How many splats are skinned, sorted and drawn this frame: the whole set,
+   * or the first `n` of {@link Splat.importanceOrder} after
+   * {@link Splat.setCountLod}.
+   */
+  get activeSplatCount() {
+    return this._activeSplatCount;
+  }
+  /** Whether a count LOD is currently reducing this splat. */
+  get countLodActive() {
+    return this._activeSplatCount < this.numSplats;
+  }
+  /**
+   * Process only the `n` most important splats this frame, or the whole set
+   * with `null`.
+   *
+   * The dynamic counterpart of {@link SplatQuality.pruneRatio}: the prune
+   * decides once, at load, that some splats are not worth carrying at all,
+   * while this decides per frame how many of them are worth the work right
+   * now - which is the trade a character makes as it walks away from the
+   * camera. Nothing is freed, so it reverses the moment `n` goes back up.
+   *
+   * Which splats the first `n` are is {@link Splat.importanceOrder}'s answer:
+   * the strongest splat of every 4 cm cell, then the second of every cell, and
+   * so on, so the character thins evenly rather than losing a region.
+   *
+   * `WebGLRenderer` only, where it is worth the most: that backend skins every
+   * splat centre on the CPU each frame to feed its sort, and this cuts that
+   * pass, the sort and the draw together. Under `WebGPURenderer` all of that
+   * already happens in compute, and the call is accepted and ignored rather
+   * than silently changing which splats a GPU sort can see.
+   *
+   * {@link Character.setSplatCountLod} drives this from camera distance; call
+   * it directly for a policy of your own.
+   */
+  setCountLod(n) {
+    const next = n === null ? this.numSplats : Math.max(1, Math.min(this.numSplats, Math.floor(n)));
+    if (next === this._activeSplatCount) return;
+    if (next < this.numSplats) this.prepareCountLod();
+    this._activeSplatCount = next;
+    this.centersVersion++;
+    this._mesh.requestSort();
+  }
+  /**
+   * Build {@link Splat.importanceOrder} now, if it does not exist yet.
+   *
+   * One pass over the splats plus a small sort inside each 4 cm cell - single
+   * digit milliseconds for a character, but milliseconds that would otherwise
+   * land on the frame where the LOD first engages, which is a frame where the
+   * camera is already moving. {@link Character.setSplatCountLod} calls this
+   * when the LOD is configured, so the cost lands there instead.
+   */
+  prepareCountLod() {
+    if (this._importanceRank) return;
+    const order = this._importanceOrder ??= buildImportanceOrder(this.packed, SplatQuality.pruneVoxelSize);
+    const rank = new Uint32Array(order.length);
+    for (let i = 0; i < order.length; i++) rank[order[i]] = i;
+    this._importanceRank = rank;
+  }
+  /**
+   * Each splat's place in {@link Splat.importanceOrder}, which is how the
+   * per-frame passes test membership of the active prefix. `null` until
+   * {@link Splat.prepareCountLod}.
+   * @internal
+   */
+  get importanceRank() {
+    return this._importanceRank;
+  }
+  /**
+   * Splat indices ordered by importance for {@link Splat.setCountLod}. `null`
+   * until {@link Splat.prepareCountLod} or a count LOD has asked for one.
+   */
+  get importanceOrder() {
+    return this._importanceOrder;
+  }
   /** Re-upload the bone index/weight textures after editing their data arrays. */
   markBoneTexturesDirty() {
     this._mesh.syncBoneData();
   }
+  /** Keep CPU-skinned centres (sorting and ground probes) on the same bone
+   * mapping as the GPU shader. Called once when an armature binds this splat. */
+  syncMappedCpuInfluences(firstPaletteIdx) {
+    const packed = this._cpuInfluences;
+    const indices = this.boneIndicesData;
+    const weights = this.boneWeightsData;
+    if (!packed || !indices || !weights) return;
+    for (let s = 0; s < this.numSplats; s++) {
+      const base = s * 11;
+      const src = s * 4;
+      for (let j = 0; j < 4; j++) {
+        packed[base + 3 + j * 2] = weights[src + j];
+        packed[base + 4 + j * 2] = indices[src + j] - firstPaletteIdx;
+      }
+    }
+  }
   get variantMaskEnabled() {
     return this._variantMaskEnabled;
   }
@@ -6152,11 +6830,16 @@ var Splat = class _Splat {
   /**
    * Assign each splat to a group and enable per-group visibility. All groups
    * start visible; toggle them with {@link Splat.setVariantMask}.
+   *
+   * `groupIds` is indexed by splat, so it has to be built against
+   * {@link Splat.numSplats} as loaded - which {@link SplatQuality.minOpacity}
+   * makes smaller than the count in the file. An array authored offline
+   * against the file cannot simply be shortened: see the error this throws.
    */
   setSplatGroups(groupIds, numGroups) {
     if (groupIds.length !== this.numSplats) {
       throw new Error(
-        `Splat.setSplatGroups: groupIds length ${groupIds.length} != numSplats ${this.numSplats}`
+        `Splat.setSplatGroups: groupIds has ${groupIds.length} entries but this splat has ${this.numSplats}. One id per loaded splat is required. If the array was authored against the source file, do not truncate it - its indices no longer line up, because SplatQuality.minOpacity drops splats during the decode. Build it from the loaded splats, or set SplatQuality.minOpacity = 0 before loading this character.`
       );
     }
     if (numGroups < 1) throw new Error("Splat.setSplatGroups: numGroups must be \u22651");
@@ -6217,21 +6900,22 @@ var Splat = class _Splat {
     if (n === 0 || !this.splatWeights) return this.getWorldMinY();
     this.ensureCenters();
     const centers = this.centers;
+    this.object3D.updateWorldMatrix(true, false);
+    const m = this.object3D.matrixWorld.elements;
+    const worldY = (i) => m[1] * centers[i * 3] + m[5] * centers[i * 3 + 1] + m[9] * centers[i * 3 + 2] + m[13];
     let lo = Infinity, hi = -Infinity;
     for (let i = 0; i < n; i++) {
-      const y = centers[i * 3 + 1];
+      const y = worldY(i);
       if (y < lo) lo = y;
       if (y > hi) hi = y;
     }
-    this.object3D.updateWorldMatrix(true, false);
-    const worldOffsetY = this.object3D.matrixWorld.elements[13];
-    if (!(hi > lo)) return lo + worldOffsetY;
+    if (!(hi > lo)) return lo;
     const BUCKETS = 256;
     const counts = this._groundHist;
     counts.fill(0);
     const scale = BUCKETS / (hi - lo);
     for (let i = 0; i < n; i++) {
-      const y = centers[i * 3 + 1];
+      const y = worldY(i);
       let b = (y - lo) * scale | 0;
       if (b >= BUCKETS) b = BUCKETS - 1;
       if (b < 0) b = 0;
@@ -6247,7 +6931,7 @@ var Splat = class _Splat {
         break;
       }
     }
-    return boundary + worldOffsetY;
+    return boundary;
   }
   /**
    * Flatten rest centres and influences into one interleaved buffer for the
@@ -6286,7 +6970,13 @@ var Splat = class _Splat {
     const boneTransforms = this._pendingBoneTransforms;
     if (!boneTransforms) return;
     this._pendingBoneTransforms = null;
+    if (!SplatQuality.passTimings) {
+      this._skinCenters(boneTransforms);
+      return;
+    }
+    const t0 = performance.now();
     this._skinCenters(boneTransforms);
+    addSkinTime(performance.now() - t0);
   }
   /**
    * Skin the splat centres on the CPU with the same matrices the GPU uses.
@@ -6318,9 +7008,12 @@ var Splat = class _Splat {
     }
     const centers = this.centers;
     const count = this.numSplats;
+    const active = this._activeSplatCount;
+    const rank = active < count ? this._importanceRank : null;
     let minX = Infinity, minY = Infinity, minZ = Infinity;
     let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
     for (let i = 0, base = 0, ci = 0; i < count; i++, base += 11, ci += 3) {
+      if (rank !== null && rank[i] >= active) continue;
       const rx = packed[base];
       const ry = packed[base + 1];
       const rz = packed[base + 2];
@@ -6428,6 +7121,12 @@ var Character = class _Character {
   get splat() {
     return this.splats[this._activeLevel];
   }
+  // Splat-count LOD configuration (see setSplatCountLod). Off by default.
+  _countLodEnabled = false;
+  _countLodNearDist = 0;
+  _countLodFarDist = Infinity;
+  _countLodNearFraction = 1;
+  _countLodFarFraction = 0.3;
   // Render LOD configuration.
   _renderLodEnabled = false;
   _renderLodNearDist = Infinity;
@@ -6653,7 +7352,9 @@ var Character = class _Character {
     const boneNames = use441 ? library.boneNames441 : library.boneNames;
     const restSource = opts?.restSource ?? "auto";
     const wantsBundled = restSource === "auto" ? primary.armatureData?.corrected === true : restSource === "bundled";
-    const canBundle = wantsBundled && bundledJoints instanceof Float32Array && bundledJoints.length === builtinRest.length;
+    const bodyRestCount = builtinRest.length;
+    const expressionOnBody = binBoneCount === 119 && !use441 && bodyRestCount === 86 * 3;
+    const canBundle = wantsBundled && bundledJoints instanceof Float32Array && (bundledJoints.length === bodyRestCount || expressionOnBody && bundledJoints.length === 119 * 3);
     let restTranslations = builtinRest;
     if (canBundle) {
       const joints = bundledJoints;
@@ -6709,6 +7410,7 @@ var Character = class _Character {
           this._activeLevel = next;
         }
       }
+      if (this._countLodEnabled) this._applyCountLod();
       this.armature.update(dt);
     };
     this._engine.addUpdater(this._updateHandler);
@@ -6774,6 +7476,60 @@ var Character = class _Character {
     this.splats[clamped].setRenderingEnabled(true);
     this._activeLevel = clamped;
   }
+  /**
+   * Thin the character with distance by processing fewer of its splats, rather
+   * than by switching to a different file.
+   *
+   * At `nearDist` and closer, `nearFraction` of the splats are skinned, sorted
+   * and drawn; at `farDist` and beyond, `farFraction` of them; in between, the
+   * fraction is interpolated. Which splats those are is decided by importance
+   * inside each 4 cm cell (see {@link Splat.setCountLod}), so the character
+   * thins evenly instead of losing a region.
+   *
+   * The dynamic counterpart of {@link SplatQuality.pruneRatio}, and the one to
+   * reach for when the splats are still wanted close up. It composes with
+   * everything else: {@link Character.setRenderLod} switches between loaded
+   * files, {@link Armature.setAnimationLod} and {@link Armature.setSortLod}
+   * drop frames of pose and sort work, and this one changes how much of the
+   * character each of those frames covers.
+   *
+   * `WebGLRenderer` only - see {@link Splat.setCountLod} for why.
+   *
+   * ```ts
+   * character.setSplatCountLod({ nearDist: 4, farDist: 16, farFraction: 0.25 });
+   * ```
+   */
+  setSplatCountLod(opts) {
+    this._countLodNearDist = Math.max(0, opts.nearDist);
+    this._countLodFarDist = Math.max(this._countLodNearDist + 1e-6, opts.farDist);
+    this._countLodNearFraction = Math.min(1, Math.max(0.01, opts.nearFraction ?? 1));
+    this._countLodFarFraction = Math.min(1, Math.max(0.01, opts.farFraction ?? 0.3));
+    this._countLodEnabled = true;
+    for (const splat of this.splats) splat.prepareCountLod();
+  }
+  /** Stop thinning: every splat is processed again, on every level. */
+  disableSplatCountLod() {
+    if (!this._countLodEnabled) return;
+    this._countLodEnabled = false;
+    for (const splat of this.splats) splat.setCountLod(null);
+  }
+  /** Pick this frame's splat fraction from camera distance and apply it. */
+  _applyCountLod() {
+    const distSq = this.armature.cameraDistanceSq();
+    if (distSq === null) return;
+    const near = this._countLodNearDist;
+    const far = this._countLodFarDist;
+    const nearF = this._countLodNearFraction;
+    const farF = this._countLodFarFraction;
+    const dist = Math.sqrt(distSq);
+    let fraction;
+    if (dist <= near) fraction = nearF;
+    else if (dist >= far) fraction = farF;
+    else fraction = nearF + (farF - nearF) * (dist - near) / (far - near);
+    const steps = Math.max(1, Math.round(fraction * 64));
+    const splat = this.splat;
+    splat.setCountLod(Math.round(steps / 64 * splat.numSplats));
+  }
   /** Number of LOD levels loaded for this character (>=1). */
   get renderLodLevels() {
     return this.splats.length;
@@ -7172,6 +7928,8 @@ var _euler = new Euler();
 // src/three/splat-character.ts
 var _color = new Color();
 var _rgb = { r: 0, g: 0, b: 0 };
+var _groundDelta = new Vector35();
+var _parentInverseLinear = new Matrix3();
 var _clipSerial = 0;
 var SplatCharacter = class _SplatCharacter extends Object3D {
   /** Type flag, in the three.js manner. */
@@ -7189,6 +7947,10 @@ var SplatCharacter = class _SplatCharacter extends Object3D {
   _loop = true;
   _finishedSent = false;
   _rootMotion = "off";
+  /** Optional world-space floor height. When set, the lowest visible splats
+   * are aligned to it after each pose. Useful for dances with no airborne
+   * phase; leave null for clips with intentional jumps or flight. */
+  groundLockY = null;
   _disposed = false;
   /**
    * @param bundles - Decoded character bundles, finest level of detail first.
@@ -7226,6 +7988,18 @@ var SplatCharacter = class _SplatCharacter extends Object3D {
     const armature = this.character.armature;
     const before = armature.animationTime;
     this.character.update(delta);
+    if (this.groundLockY !== null) {
+      const low = this.character.getLowestWorldY();
+      if (low !== null && Number.isFinite(low)) {
+        _groundDelta.set(0, this.groundLockY - low, 0);
+        if (this.parent) {
+          this.parent.updateWorldMatrix(true, false);
+          _parentInverseLinear.setFromMatrix4(this.parent.matrixWorld).invert();
+          _groundDelta.applyMatrix3(_parentInverseLinear);
+        }
+        this.position.add(_groundDelta);
+      }
+    }
     const clip = this._clip;
     if (!clip || !armature.isPlaying) return;
     if (this._loop) {
@@ -7358,6 +8132,32 @@ var SplatCharacter = class _SplatCharacter extends Object3D {
     for (const splat of this.character.splats) splat.setGrade(contrast, saturation);
     return this;
   }
+  // ── Performance ──────────────────────────────────────────────────────────
+  /**
+   * Draw fewer of this character's splats as it gets further away.
+   *
+   * `nearFraction` of them at `nearDist` and closer, `farFraction` at
+   * `farDist` and beyond, interpolated in between. Which splats those are is
+   * decided by importance within each 4 cm cell, so the character thins evenly
+   * rather than losing a region of itself. See {@link Character.setSplatCountLod}.
+   *
+   * Needs a camera on the engine to measure distance from - the same one the
+   * other distance throttles use:
+   *
+   * ```ts
+   * SplatEngine.shared.camera = camera;
+   * character.setSplatCountLod({ nearDist: 4, farDist: 16, farFraction: 0.25 });
+   * ```
+   */
+  setSplatCountLod(opts) {
+    this.character.setSplatCountLod(opts);
+    return this;
+  }
+  /** Stop thinning: every splat is drawn again, at any distance. */
+  disableSplatCountLod() {
+    this.character.disableSplatCountLod();
+    return this;
+  }
   // ── Rig ──────────────────────────────────────────────────────────────────
   /** Bone names, in rig order. */
   get boneNames() {
@@ -7391,6 +8191,7 @@ var SplatCharacter = class _SplatCharacter extends Object3D {
     copy.layers.mask = this.layers.mask;
     copy.userData = { ...this.userData };
     copy.rootMotion = this._rootMotion;
+    copy.groundLockY = this.groundLockY;
     return copy;
   }
   /**
@@ -7778,6 +8579,10 @@ export {
   SplatEngine,
   EngineDisposedError,
   packSplats,
+  SplatQuality,
+  effectiveMinPixelSize,
+  beginFrameTimings,
+  pruneSplats,
   CharacterBundleError,
   decodeCharacterBundle,
   loadCharacterBundle,
@@ -7798,4 +8603,4 @@ export {
   SkyLight,
   PointLight
 };
-//# sourceMappingURL=chunk-MM6DJU6S.js.map
+//# sourceMappingURL=chunk-WN5WBKM4.js.map