@driftengine/drft 4.3.0 → 4.4.0

package/src/drftQuantised.ts

@@ -0,0 +1,401 @@
+/**
+ * `MSHQ`: a mesh stored in the bytes its data needs, decoded on read into the same `MeshData` a
+ * `MESH` gives. Added in 1.18.
+ *
+ * **Why a second mesh chunk rather than a flag in `MESH`.** `MESH`'s reserved word must be ignored
+ * by readers (§4.4 rule 6), so a flag there would let an older reader read 16-bit numbers as floats
+ * and draw noise without a word. A new FourCC, marked required, makes that reader refuse by name.
+ *
+ * **One encoding per attribute, chosen from what the data allows:**
+ * - constant, when every vertex carries one value: a bought scene's colour and emissive, 16 bytes a
+ *   vertex of nothing;
+ * - 16 bits over the attribute's own range, for positions, UVs, scalars and weights: half a step of
+ *   error, 0.27 mm across 36 m;
+ * - octahedral in two 16-bit numbers, for unit normals, and for unit tangents with the handedness
+ *   in a sign byte: within 5e-5 rad, 0.003°, measured over the sphere;
+ * - raw floats, where exactness is the contract (joints) or where a "direction" is not unit length
+ *   and an octahedral code would bend it into one: data already malformed is carried as it came.
+ *
+ * Indices are 16-bit when the mesh has at most 65,536 vertices.
+ *
+ * What it gives up is exactness: a quantised mesh is within its bound of the source, not equal to it,
+ * and it is no longer a zero-copy view of the file. What would make that wrong is a consumer that
+ * compares vertices bit for bit, or one that cannot afford the decode's copy; `writeDrft`'s
+ * `quantise: false` writes `MESH` as before.
+ */
+import {
+  ATTR_EMISSIVE_COLOR,
+  ATTR_GRAIN,
+  ATTR_JOINTS,
+  ATTR_RELIEF,
+  ATTR_ROUGHNESS,
+  ATTR_SPECULAR,
+  ATTR_TANGENT,
+  ATTR_UVS,
+  ATTR_WEIGHTS,
+  DrftError,
+  align,
+} from './drftFormat.ts';
+import type { MeshData } from './meshData.ts';
+
+const RAW = 0;
+const CONSTANT = 1;
+const RANGE16 = 2;
+const OCTAHEDRAL = 3;
+const OCTAHEDRAL_SIGNED = 4;
+
+/** Header flag: the indices are 16-bit. */
+const INDICES_16 = 1;
+
+type Name =
+  | 'positions'
+  | 'normals'
+  | 'colors'
+  | 'emissive'
+  | 'specular'
+  | 'uvs'
+  | 'emissiveColor'
+  | 'roughness'
+  | 'grain'
+  | 'relief'
+  | 'tangents'
+  | 'joints'
+  | 'weights';
+
+/** The frozen order `MESH` uses, with each optional array's bit: `FORMAT.md` §4.3. */
+const ORDER: readonly {
+  name: Name;
+  width: number;
+  bit: number;
+  kind: 'value' | 'direction' | 'exact';
+}[] = [
+  { name: 'positions', width: 3, bit: 0, kind: 'value' },
+  { name: 'normals', width: 3, bit: 0, kind: 'direction' },
+  { name: 'colors', width: 3, bit: 0, kind: 'value' },
+  { name: 'emissive', width: 1, bit: 0, kind: 'value' },
+  { name: 'specular', width: 1, bit: ATTR_SPECULAR, kind: 'value' },
+  { name: 'uvs', width: 2, bit: ATTR_UVS, kind: 'value' },
+  { name: 'emissiveColor', width: 3, bit: ATTR_EMISSIVE_COLOR, kind: 'value' },
+  { name: 'roughness', width: 1, bit: ATTR_ROUGHNESS, kind: 'value' },
+  { name: 'grain', width: 1, bit: ATTR_GRAIN, kind: 'value' },
+  { name: 'relief', width: 1, bit: ATTR_RELIEF, kind: 'value' },
+  { name: 'tangents', width: 4, bit: ATTR_TANGENT, kind: 'direction' },
+  { name: 'joints', width: 4, bit: ATTR_JOINTS, kind: 'exact' },
+  { name: 'weights', width: 4, bit: ATTR_WEIGHTS, kind: 'value' },
+];
+
+/** A growing little-endian byte list, for the writer: offline, so it may allocate. */
+class Bytes {
+  private data = new Uint8Array(1024);
+  private view = new DataView(this.data.buffer);
+  length = 0;
+  private room(n: number): void {
+    if (this.length + n <= this.data.length) return;
+    let size = this.data.length * 2;
+    while (size < this.length + n) size *= 2;
+    const next = new Uint8Array(size);
+    next.set(this.data.subarray(0, this.length));
+    this.data = next;
+    this.view = new DataView(next.buffer);
+  }
+  u8(v: number): void {
+    this.room(1);
+    this.view.setUint8(this.length, v);
+    this.length += 1;
+  }
+  u16(v: number): void {
+    this.room(2);
+    this.view.setUint16(this.length, v, true);
+    this.length += 2;
+  }
+  i16(v: number): void {
+    this.room(2);
+    this.view.setInt16(this.length, v, true);
+    this.length += 2;
+  }
+  u32(v: number): void {
+    this.room(4);
+    this.view.setUint32(this.length, v, true);
+    this.length += 4;
+  }
+  f32(v: number): void {
+    this.room(4);
+    this.view.setFloat32(this.length, v, true);
+    this.length += 4;
+  }
+  pad(): void {
+    while (this.length % 4 !== 0) this.u8(0);
+  }
+  finish(): Uint8Array {
+    this.pad();
+    return this.data.slice(0, align(this.length));
+  }
+}
+
+export function encodeQuantisedMesh(mesh: MeshData): Uint8Array {
+  const vertices = mesh.positions.length / 3;
+  let attributes = 0;
+  for (const entry of ORDER)
+    if (entry.bit !== 0 && mesh[entry.name] !== undefined) attributes |= entry.bit;
+  if (((attributes & ATTR_JOINTS) !== 0) !== ((attributes & ATTR_WEIGHTS) !== 0)) {
+    throw new DrftError('a mesh carries joints without weights, or weights without joints');
+  }
+  const narrow = vertices <= 65_536;
+  const out = new Bytes();
+  out.u32(vertices);
+  out.u32(mesh.indices.length);
+  out.u32(attributes);
+  out.u32(narrow ? INDICES_16 : 0);
+  for (const entry of ORDER) {
+    const values = mesh[entry.name];
+    if (values === undefined) continue;
+    writeAttribute(out, values, vertices, entry.width, entry.kind);
+  }
+  for (let i = 0; i < mesh.indices.length; i++) {
+    const index = mesh.indices[i] as number;
+    if (narrow) out.u16(index);
+    else out.u32(index);
+  }
+  return out.finish();
+}
+
+function writeAttribute(
+  out: Bytes,
+  values: Float32Array,
+  vertices: number,
+  width: number,
+  kind: 'value' | 'direction' | 'exact',
+): void {
+  const encoding = choose(values, vertices, width, kind);
+  out.u8(encoding);
+  out.u8(width);
+  out.u16(0);
+  if (encoding === CONSTANT) {
+    for (let c = 0; c < width; c++) out.f32(vertices === 0 ? 0 : (values[c] as number));
+    return;
+  }
+  if (encoding === RAW) {
+    for (let i = 0; i < vertices * width; i++) out.f32(values[i] as number);
+    return;
+  }
+  if (encoding === RANGE16) {
+    const lo = new Float64Array(width).fill(Infinity);
+    const hi = new Float64Array(width).fill(-Infinity);
+    for (let v = 0; v < vertices; v++) {
+      for (let c = 0; c < width; c++) {
+        const x = values[v * width + c] as number;
+        if (x < (lo[c] as number)) lo[c] = x;
+        if (x > (hi[c] as number)) hi[c] = x;
+      }
+    }
+    for (let c = 0; c < width; c++) out.f32(lo[c] as number);
+    for (let c = 0; c < width; c++) out.f32(hi[c] as number);
+    /* Quantised against the float32 the reader will see, so the reader's arithmetic is the same. */
+    const flo = Float32Array.from(lo);
+    const fhi = Float32Array.from(hi);
+    for (let v = 0; v < vertices; v++) {
+      for (let c = 0; c < width; c++) {
+        const span = (fhi[c] as number) - (flo[c] as number);
+        const x = values[v * width + c] as number;
+        out.u16(span > 0 ? Math.round(((x - (flo[c] as number)) / span) * 65535) : 0);
+      }
+    }
+    out.pad();
+    return;
+  }
+  /* Octahedral: two snorm16 a direction, and for a tangent a sign byte after them all. */
+  for (let v = 0; v < vertices; v++) {
+    const [u, w] = octEncode(
+      values[v * width] as number,
+      values[v * width + 1] as number,
+      values[v * width + 2] as number,
+    );
+    out.i16(u);
+    out.i16(w);
+  }
+  if (encoding === OCTAHEDRAL_SIGNED) {
+    for (let v = 0; v < vertices; v++) out.u8((values[v * 4 + 3] as number) < 0 ? 1 : 0);
+    out.pad();
+  }
+}
+
+function choose(values: Float32Array, vertices: number, width: number, kind: string): number {
+  if (kind === 'exact') return RAW;
+  let constant = true;
+  for (let v = 1; v < vertices && constant; v++) {
+    for (let c = 0; c < width; c++) {
+      if (values[v * width + c] !== values[c]) {
+        constant = false;
+        break;
+      }
+    }
+  }
+  if (constant) return CONSTANT;
+  if (kind === 'direction') {
+    /* Only unit directions, and for a tangent only a handedness of exactly ±1, take a code. */
+    for (let v = 0; v < vertices; v++) {
+      const x = values[v * width] as number;
+      const y = values[v * width + 1] as number;
+      const z = values[v * width + 2] as number;
+      if (Math.abs(Math.hypot(x, y, z) - 1) > 1e-3) return RAW;
+      if (width === 4 && Math.abs(values[v * 4 + 3] as number) !== 1) return RAW;
+    }
+    return width === 4 ? OCTAHEDRAL_SIGNED : OCTAHEDRAL;
+  }
+  return RANGE16;
+}
+
+const SNORM = 32767;
+
+/**
+ * The octahedral code of a unit direction: the nearest of the four 16-bit neighbours of the exact
+ * projection, measured by decoding each: the "precise" variant, whose worst over 200,000 directions
+ * is 4.3e-5 rad. Rounding each coordinate alone does noticeably worse near the folds.
+ */
+function octEncode(x: number, y: number, z: number): [number, number] {
+  const l1 = Math.abs(x) + Math.abs(y) + Math.abs(z);
+  let u = x / l1;
+  let w = y / l1;
+  if (z < 0) {
+    const pu = u;
+    u = (1 - Math.abs(w)) * (pu >= 0 ? 1 : -1);
+    w = (1 - Math.abs(pu)) * (w >= 0 ? 1 : -1);
+  }
+  const fu = Math.floor(u * SNORM);
+  const fw = Math.floor(w * SNORM);
+  let best: [number, number] = [fu, fw];
+  let bestDot = -2;
+  for (let du = 0; du <= 1; du++) {
+    for (let dw = 0; dw <= 1; dw++) {
+      const qu = Math.max(-SNORM, Math.min(SNORM, fu + du));
+      const qw = Math.max(-SNORM, Math.min(SNORM, fw + dw));
+      octDecode(qu, qw, OCT_SCRATCH, 0);
+      const dot =
+        (OCT_SCRATCH[0] as number) * x +
+        (OCT_SCRATCH[1] as number) * y +
+        (OCT_SCRATCH[2] as number) * z;
+      if (dot > bestDot) {
+        bestDot = dot;
+        best = [qu, qw];
+      }
+    }
+  }
+  return best;
+}
+
+/*
+ * Float64, because the choice is between codes a ten-thousandth of a radian apart and a float32 dot
+ * product near 1 cannot see differences below about 3e-4: its own rounding is that coarse.
+ */
+const OCT_SCRATCH = new Float64Array(3);
+
+function octDecode(qu: number, qw: number, out: Float32Array | Float64Array, at: number): void {
+  let x = Math.max(-1, qu / SNORM);
+  let y = Math.max(-1, qw / SNORM);
+  const z = 1 - Math.abs(x) - Math.abs(y);
+  if (z < 0) {
+    const px = x;
+    x = (1 - Math.abs(y)) * (px >= 0 ? 1 : -1);
+    y = (1 - Math.abs(px)) * (y >= 0 ? 1 : -1);
+  }
+  /*
+   * A square root rather than `Math.hypot`, which guards an overflow that three numbers bounded by
+   * one cannot reach and costs nearly three times as much for it: 0.7 s of a five-pack load was this
+   * function. The float32 a reader keeps agreed with `hypot`'s on every one of 263 million codes
+   * sampled across the whole lattice.
+   */
+  const len = Math.sqrt(x * x + y * y + z * z);
+  out[at] = x / len;
+  out[at + 1] = y / len;
+  out[at + 2] = z / len;
+}
+
+export function decodeQuantisedMesh(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+): MeshData {
+  const view = new DataView(buffer, offset, byteLength);
+  if (byteLength < 16) throw new DrftError('MSHQ is shorter than its header');
+  const vertices = view.getUint32(0, true);
+  const indexCount = view.getUint32(4, true);
+  const attributes = view.getUint32(8, true);
+  const flags = view.getUint32(12, true);
+  let at = 16;
+  const need = (n: number, what: string): void => {
+    if (at + n > byteLength) throw new DrftError(`MSHQ ends inside ${what}`);
+  };
+  const out: Record<string, unknown> = {};
+  for (const entry of ORDER) {
+    if (entry.bit !== 0 && (attributes & entry.bit) === 0) continue;
+    need(4, entry.name);
+    const encoding = view.getUint8(at);
+    const width = view.getUint8(at + 1);
+    at += 4;
+    if (width !== entry.width) {
+      throw new DrftError(
+        `MSHQ ${entry.name} is ${width} wide, and the format says ${entry.width}`,
+      );
+    }
+    const values = new Float32Array(vertices * width);
+    if (encoding === CONSTANT) {
+      need(width * 4, entry.name);
+      for (let c = 0; c < width; c++) {
+        const x = view.getFloat32(at + c * 4, true);
+        for (let v = 0; v < vertices; v++) values[v * width + c] = x;
+      }
+      at += width * 4;
+    } else if (encoding === RAW) {
+      need(vertices * width * 4, entry.name);
+      for (let i = 0; i < vertices * width; i++) values[i] = view.getFloat32(at + i * 4, true);
+      at += vertices * width * 4;
+    } else if (encoding === RANGE16) {
+      need(width * 8 + vertices * width * 2, entry.name);
+      const lo = new Float32Array(width);
+      const hi = new Float32Array(width);
+      for (let c = 0; c < width; c++) lo[c] = view.getFloat32(at + c * 4, true);
+      for (let c = 0; c < width; c++) hi[c] = view.getFloat32(at + width * 4 + c * 4, true);
+      at += width * 8;
+      for (let v = 0; v < vertices; v++) {
+        for (let c = 0; c < width; c++) {
+          const q = view.getUint16(at + (v * width + c) * 2, true);
+          values[v * width + c] =
+            (lo[c] as number) + (q / 65535) * ((hi[c] as number) - (lo[c] as number));
+        }
+      }
+      at = align(at + vertices * width * 2);
+    } else if (encoding === OCTAHEDRAL || encoding === OCTAHEDRAL_SIGNED) {
+      need(vertices * 4, entry.name);
+      for (let v = 0; v < vertices; v++) {
+        octDecode(
+          view.getInt16(at + v * 4, true),
+          view.getInt16(at + v * 4 + 2, true),
+          values,
+          v * width,
+        );
+      }
+      at += vertices * 4;
+      if (encoding === OCTAHEDRAL_SIGNED) {
+        need(vertices, `${entry.name}' handedness`);
+        for (let v = 0; v < vertices; v++) values[v * 4 + 3] = view.getUint8(at + v) === 1 ? -1 : 1;
+        at = align(at + vertices);
+      }
+    } else {
+      throw new DrftError(
+        `MSHQ ${entry.name} has encoding ${encoding}, which this reader does not know`,
+      );
+    }
+    out[entry.name] = values;
+  }
+  const narrow = (flags & INDICES_16) !== 0;
+  need(indexCount * (narrow ? 2 : 4), 'its indices');
+  const indices = new Uint32Array(indexCount);
+  for (let i = 0; i < indexCount; i++) {
+    const index = narrow ? view.getUint16(at + i * 2, true) : view.getUint32(at + i * 4, true);
+    if (index >= vertices)
+      throw new DrftError(`MSHQ index ${i} names vertex ${index} of ${vertices}`);
+    indices[i] = index;
+  }
+  out['indices'] = indices;
+  return out as unknown as MeshData;
+}

package/src/drftRead.ts

@@ -54,6 +54,9 @@ import {
   fourCCName,
   CHUNK_ANIM,
   CHUNK_NODE,
+  CHUNK_INST,
+  CHUNK_LITE,
+  CHUNK_MSHQ,
   CHUNK_SKIN,
   CHUNK_MORP,
   CHUNK_NNET,
@@ -71,6 +74,11 @@ import { type NavPolyMesh, readNavm } from './navm.ts';
 import { type DrftNetwork, type DrftNnet, readNnet } from './nnet.ts';
 import { type DrftGraph, readNgrf } from './ngrf.ts';
 import { readColliders } from './drftColliders.ts';
+import { readInstances } from './drftInstances.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import { readLights } from './drftLights.ts';
+import type { DrftLight } from './drftLights.ts';
+import { decodeQuantisedMesh } from './drftQuantised.ts';
 
 /** An embedded image, still compressed. Decoding is the consumer's, through `createImageBitmap`. */
 export interface DrftTexture {
@@ -145,6 +153,13 @@ export interface DrftAsset {
    * behaves identically against a file with a hierarchy it ignores.
    */
   readonly nodes: readonly DrftNode[];
+  /**
+   * Meshes drawn many times, each group naming the mesh that holds one copy and a matrix a copy.
+   * Empty for a file that instances nothing, which is every file before 1.18.
+   */
+  readonly instances: readonly DrftInstanceGroup[];
+  /** The lights the scene was authored with, or empty. `LITE`, defined at 1.18. */
+  readonly lights: readonly DrftLight[];
   /** Skins, in the order their chunks appear. Empty for a file that deforms nothing. */
   readonly skins: readonly DrftSkin[];
   /** Clips, in the order their chunks appear. Empty for a file that animates nothing. */
@@ -365,6 +380,9 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
   let nnet: DrftNnet | null = null;
   let graphs: DrftGraph[] = [];
   let colliders: readonly Float32Array[] = [];
+  /* Read once every mesh is counted, because a group is checked against the mesh count. */
+  let instanceChunk: { offset: number; byteLength: number } | null = null;
+  let lights: DrftLight[] = [];
   const skipped: string[] = [];
   let head: DrftHead | null = null;
 
@@ -406,6 +424,9 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
 
     if (chunk.code === CHUNK_HEAD) head = readHead(buffer, chunk);
     else if (chunk.code === CHUNK_MESH) meshes.push(readMesh(buffer, chunk));
+    /* A mesh like any other, in the same ordinal sequence: see `drftQuantised.ts`. */
+    else if (chunk.code === CHUNK_MSHQ)
+      meshes.push(decodeQuantisedMesh(buffer, chunk.offset, chunk.byteLength));
     /* A level of detail is a mesh payload under another code, so it takes the same reader. */
     else if (chunk.code === CHUNK_LODM)
       levels.push({ level: chunk.index, mesh: readMesh(buffer, chunk) });
@@ -421,6 +442,8 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
       navigation = readNavm(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_ENTS) entities = readEnts(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_NODE) nodes = readNodes(buffer, chunk.offset, chunk.byteLength);
+    else if (chunk.code === CHUNK_INST) instanceChunk = chunk;
+    else if (chunk.code === CHUNK_LITE) lights = readLights(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_SKIN)
       skins.push(readSkin(buffer, chunk.offset, chunk.byteLength));
     else if (chunk.code === CHUNK_ANIM)
@@ -517,6 +540,11 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
     lods,
     levels: discreteLevels,
     nodes,
+    instances:
+      instanceChunk === null
+        ? []
+        : readInstances(buffer, instanceChunk.offset, instanceChunk.byteLength, meshes.length),
+    lights,
     skins,
     clips,
     materials,
@@ -726,6 +754,10 @@ export function readMaterials(buffer: ArrayBuffer, chunk: DrftChunk): DrftMateri
       occlusionStrength: has(68, 4) ? view.getFloat32(at + 68, true) : 0,
       /* Discard nothing, which is exactly what a file written before this field meant. */
       cutout: has(72, 4) ? view.getFloat32(at + 72, true) : 0,
+      /* Opaque unless its opacity says otherwise, which is what a file before 1.18 meant. */
+      blend: has(76, 4) ? (view.getUint32(at + 76, true) & 1) !== 0 : false,
+      /* One-sided unless it says otherwise, which is how every file before the bit was drawn. */
+      doubleSided: has(76, 4) ? (view.getUint32(at + 76, true) & 2) !== 0 : false,
     });
   }
   return out;

package/src/drftStream.ts

@@ -18,6 +18,10 @@ import {
   fourCCName,
   CHUNK_ANIM,
   CHUNK_NODE,
+  CHUNK_INST,
+  CHUNK_LITE,
+  CHUNK_SDFV,
+  CHUNK_MSHQ,
   CHUNK_SKIN,
   CHUNK_MORP,
 } from './drftFormat.ts';
@@ -28,6 +32,13 @@ import type { AnimationClip, DrftSkin } from './animationData.ts';
 import type { DrftNode } from './drftSkin.ts';
 import type { DrftMorph } from './drftSkin.ts';
 import { readClip, readMorph, readNodes, readSkin } from './drftSkin.ts';
+import { readInstances } from './drftInstances.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import { readLights } from './drftLights.ts';
+import { readSdfv } from './sdfv.ts';
+import type { DrftSdfvEntry } from './sdfv.ts';
+import type { DrftLight } from './drftLights.ts';
+import { decodeQuantisedMesh } from './drftQuantised.ts';
 
 /**
  * What the file says is coming, known from the first few kilobytes.
@@ -101,6 +112,18 @@ export interface DrftStreamHandlers {
    * not useful — a child whose parent has not arrived cannot be placed.
    */
   readonly onNodes?: (nodes: readonly DrftNode[]) => void;
+  /**
+   * The asset's instance groups, once, when `INST` lands — ahead of the meshes, where the writer
+   * puts it, so a consumer knows a mesh is drawn many times before that mesh arrives.
+   */
+  readonly onInstances?: (groups: readonly DrftInstanceGroup[]) => void;
+  /** The lights the scene was authored with, once, when `LITE` lands. See `drftLights.ts`. */
+  readonly onLights?: (lights: readonly DrftLight[]) => void;
+  /**
+   * The distance fields indirect light is traced against, once, when `SDFV` lands. Each names the
+   * mesh it belongs to, or `SDFV_WHOLE_FILE` for one over all of the file's static geometry.
+   */
+  readonly onFields?: (fields: readonly DrftSdfvEntry[]) => void;
   /** One mesh's morph deltas, naming the mesh ordinal they belong to. */
   readonly onMorph?: (morph: DrftMorph) => void;
   /** One skin, as its `SKIN` chunk lands. Several arrive for an asset with several. */
@@ -327,7 +350,9 @@ export class DrftStream {
        * counted in `meshCount`, which is the number of parts — an outline is not a part, and
        * a readout saying "1 of 188 parts" would be counting the model twice.
        */
-      if (chunk.code === CHUNK_MESH || chunk.code === CHUNK_LODM) meshBytes += chunk.byteLength;
+      if (chunk.code === CHUNK_MESH || chunk.code === CHUNK_MSHQ || chunk.code === CHUNK_LODM) {
+        meshBytes += chunk.byteLength;
+      }
       if (chunk.code === CHUNK_TEXS) textureBytes += chunk.byteLength;
       /* Its own weight rather than geometry's: a capture is not made of parts, so folding it into
          `meshBytes` would make a "parts" readout weigh something that is not one. */
@@ -346,7 +371,7 @@ export class DrftStream {
     this.manifestSent = true;
     this.handlers.onManifest?.({
       totalBytes: this.buffer.byteLength,
-      meshCount: this.chunks.filter((c) => c.code === CHUNK_MESH).length,
+      meshCount: this.chunks.filter((c) => c.code === CHUNK_MESH || c.code === CHUNK_MSHQ).length,
       textureCount: this.chunks.filter((c) => c.code === CHUNK_TEXS).length,
       lodCount: this.chunks.filter((c) => c.code === CHUNK_LODM).length,
       splatBlockCount: this.chunks.filter((c) => c.code === CHUNK_SPLT).length,
@@ -369,8 +394,11 @@ export class DrftStream {
       if (chunk.code === CHUNK_HEAD) {
         this.head = readHead(this.buffer, chunk);
         this.handlers.onHead?.(this.head);
-      } else if (chunk.code === CHUNK_MESH) {
-        const mesh = readMesh(this.buffer, chunk);
+      } else if (chunk.code === CHUNK_MESH || chunk.code === CHUNK_MSHQ) {
+        const mesh =
+          chunk.code === CHUNK_MESH
+            ? readMesh(this.buffer, chunk)
+            : decodeQuantisedMesh(this.buffer, chunk.offset, chunk.byteLength);
         this.meshCount++;
         this.handlers.onMesh?.(mesh, this.meshOrdinal++);
       } else if (chunk.code === CHUNK_SPLT) {
@@ -388,6 +416,17 @@ export class DrftStream {
         this.handlers.onMorph?.(readMorph(this.buffer, chunk.offset, chunk.byteLength));
       } else if (chunk.code === CHUNK_NODE) {
         this.handlers.onNodes?.(readNodes(this.buffer, chunk.offset, chunk.byteLength));
+      } else if (chunk.code === CHUNK_INST) {
+        const meshes = this.chunks.filter(
+          (c) => c.code === CHUNK_MESH || c.code === CHUNK_MSHQ,
+        ).length;
+        this.handlers.onInstances?.(
+          readInstances(this.buffer, chunk.offset, chunk.byteLength, meshes),
+        );
+      } else if (chunk.code === CHUNK_LITE) {
+        this.handlers.onLights?.(readLights(this.buffer, chunk.offset, chunk.byteLength));
+      } else if (chunk.code === CHUNK_SDFV) {
+        this.handlers.onFields?.(readSdfv(this.buffer, chunk.offset, chunk.byteLength).entries);
       } else if (chunk.code === CHUNK_SKIN) {
         this.handlers.onSkin?.(readSkin(this.buffer, chunk.offset, chunk.byteLength), chunk.index);
       } else if (chunk.code === CHUNK_ANIM) {
@@ -408,6 +447,42 @@ export class DrftStream {
   }
 }
 
+/**
+ * How long a stream may work before it gives way for a task, in milliseconds. The loader's own
+ * frame budget is six, and this is the same share of a 60 Hz frame for the same reason.
+ */
+export const DEFAULT_STREAM_SLICE_MS = 6;
+
+/**
+ * When a stream stops to let something else run, and how.
+ *
+ * **Why a stream has to stop at all.** Once a body's bytes are buffered, every `read` resolves as a
+ * microtask, so a loop that pushes what it reads decodes chunk after chunk inside one task and no
+ * frame can draw until the file is done. From a local server a five-file courtyard ran in
+ * stretches of 0.6 to 1.1 s and drew 117 frames in five seconds. From a slow network the reads
+ * wait, the loop yields there by itself, and this costs nothing.
+ *
+ * Both functions are capabilities, for the reason `FetchLike` is: a host with its own clock or its
+ * own scheduler supplies them. What it gives up is throughput when nothing else wants the thread —
+ * a task per slice, which a browser may clamp to four milliseconds once timers nest. What would
+ * make it wrong is a single chunk longer than the slice, which a slice cannot divide.
+ */
+export interface DrftStreamPacing {
+  /** Work this long, then give way. `DEFAULT_STREAM_SLICE_MS` when absent. */
+  readonly sliceMs?: number;
+  /** A monotonic clock in milliseconds. `performance.now` when absent. */
+  readonly now?: () => number;
+  /** Resolve after other tasks have had a turn. A zero-delay timer when absent. */
+  readonly giveWay?: () => Promise<void>;
+}
+
+const monotonicNow = (): number => performance.now();
+/* A timer rather than a microtask: a microtask would rejoin the task it is trying to leave. */
+const nextTask = (): Promise<void> =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, 0);
+  });
+
 /**
  * Read a `.drft` from a fetch response as it arrives.
  *
@@ -418,6 +493,7 @@ export class DrftStream {
 export async function streamDrft(
   response: Response,
   handlers: DrftStreamHandlers = {},
+  pacing: DrftStreamPacing = {},
 ): Promise<void> {
   if (!response.ok) {
     throw new DrftError(`fetching the asset returned ${response.status} ${response.statusText}`);
@@ -425,12 +501,20 @@ export async function streamDrft(
   const body = response.body;
   if (body === null) throw new DrftError('the response carried no body to stream');
 
+  const sliceMs = pacing.sliceMs ?? DEFAULT_STREAM_SLICE_MS;
+  const now = pacing.now ?? monotonicNow;
+  const giveWay = pacing.giveWay ?? nextTask;
   const stream = new DrftStream(handlers);
   const reader = body.getReader();
+  let sliceStarted = now();
   for (;;) {
     const next = await reader.read();
     if (next.done) break;
     if (next.value !== undefined) stream.push(next.value);
+    if (now() - sliceStarted >= sliceMs) {
+      await giveWay();
+      sliceStarted = now();
+    }
   }
   stream.end();
 }