@driftengine/drft 4.2.1 → 4.4.0

package/dist/drftQuantised.js

@@ -0,0 +1,362 @@
+/**
+ * `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.js';
+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;
+/** The frozen order `MESH` uses, with each optional array's bit: `FORMAT.md` §4.3. */
+const ORDER = [
+    { 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 {
+    data = new Uint8Array(1024);
+    view = new DataView(this.data.buffer);
+    length = 0;
+    room(n) {
+        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) {
+        this.room(1);
+        this.view.setUint8(this.length, v);
+        this.length += 1;
+    }
+    u16(v) {
+        this.room(2);
+        this.view.setUint16(this.length, v, true);
+        this.length += 2;
+    }
+    i16(v) {
+        this.room(2);
+        this.view.setInt16(this.length, v, true);
+        this.length += 2;
+    }
+    u32(v) {
+        this.room(4);
+        this.view.setUint32(this.length, v, true);
+        this.length += 4;
+    }
+    f32(v) {
+        this.room(4);
+        this.view.setFloat32(this.length, v, true);
+        this.length += 4;
+    }
+    pad() {
+        while (this.length % 4 !== 0)
+            this.u8(0);
+    }
+    finish() {
+        this.pad();
+        return this.data.slice(0, align(this.length));
+    }
+}
+export function encodeQuantisedMesh(mesh) {
+    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];
+        if (narrow)
+            out.u16(index);
+        else
+            out.u32(index);
+    }
+    return out.finish();
+}
+function writeAttribute(out, values, vertices, width, kind) {
+    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]);
+        return;
+    }
+    if (encoding === RAW) {
+        for (let i = 0; i < vertices * width; i++)
+            out.f32(values[i]);
+        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];
+                if (x < lo[c])
+                    lo[c] = x;
+                if (x > hi[c])
+                    hi[c] = x;
+            }
+        }
+        for (let c = 0; c < width; c++)
+            out.f32(lo[c]);
+        for (let c = 0; c < width; c++)
+            out.f32(hi[c]);
+        /* 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] - flo[c];
+                const x = values[v * width + c];
+                out.u16(span > 0 ? Math.round(((x - flo[c]) / 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], values[v * width + 1], values[v * width + 2]);
+        out.i16(u);
+        out.i16(w);
+    }
+    if (encoding === OCTAHEDRAL_SIGNED) {
+        for (let v = 0; v < vertices; v++)
+            out.u8(values[v * 4 + 3] < 0 ? 1 : 0);
+        out.pad();
+    }
+}
+function choose(values, vertices, width, kind) {
+    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];
+            const y = values[v * width + 1];
+            const z = values[v * width + 2];
+            if (Math.abs(Math.hypot(x, y, z) - 1) > 1e-3)
+                return RAW;
+            if (width === 4 && Math.abs(values[v * 4 + 3]) !== 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, y, z) {
+    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 = [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] * x +
+                OCT_SCRATCH[1] * y +
+                OCT_SCRATCH[2] * 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, qw, out, at) {
+    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, offset, byteLength) {
+    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, what) => {
+        if (at + n > byteLength)
+            throw new DrftError(`MSHQ ends inside ${what}`);
+    };
+    const out = {};
+    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] + (q / 65535) * (hi[c] - lo[c]);
+                }
+            }
+            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;
+}

package/dist/drftRead.d.ts

@@ -24,6 +24,8 @@ import { type EntsScene } from './ents.ts';
 import { type NavPolyMesh } from './navm.ts';
 import { type DrftNetwork } from './nnet.ts';
 import { type DrftGraph } from './ngrf.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import type { DrftLight } from './drftLights.ts';
 /** An embedded image, still compressed. Decoding is the consumer's, through `createImageBitmap`. */
 export interface DrftTexture {
     /** What the source called this image. Empty for a file written before names existed. */
@@ -96,6 +98,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. */

package/dist/drftRead.js

@@ -16,7 +16,7 @@
  */
 import { readClip, readMorph, readNodes, readSkin } from './drftSkin.js';
 import { validateMeshData } from './meshData.js';
-import { ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_JOINTS, ATTR_RELIEF, ATTR_TANGENT, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_UVS, ATTR_WEIGHTS, CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_LODM, CHUNK_LODF, CHUNK_DTEX, CHUNK_ENTS, CHUNK_NAVM, CHUNK_SPLT, SPLAT_BLOCK_PREFIX, CHUNK_MESH, CHUNK_REQUIRED, DRFT_MAGIC, DRFT_VERSION_MAJOR, DrftError, HEADER_BYTES, CHUNK_MATL, CHUNK_TEXS, KNOWN_CHUNKS, MATERIAL_ENTRY_BYTES, align, fourCCName, CHUNK_ANIM, CHUNK_NODE, CHUNK_SKIN, CHUNK_MORP, CHUNK_NNET, CHUNK_NGRF, CHUNK_SDFV, CHUNK_SUBS, CHUNK_COLL, } from './drftFormat.js';
+import { ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_JOINTS, ATTR_RELIEF, ATTR_TANGENT, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_UVS, ATTR_WEIGHTS, CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_LODM, CHUNK_LODF, CHUNK_DTEX, CHUNK_ENTS, CHUNK_NAVM, CHUNK_SPLT, SPLAT_BLOCK_PREFIX, CHUNK_MESH, CHUNK_REQUIRED, DRFT_MAGIC, DRFT_VERSION_MAJOR, DrftError, HEADER_BYTES, CHUNK_MATL, CHUNK_TEXS, KNOWN_CHUNKS, MATERIAL_ENTRY_BYTES, align, fourCCName, CHUNK_ANIM, CHUNK_NODE, CHUNK_INST, CHUNK_LITE, CHUNK_MSHQ, CHUNK_SKIN, CHUNK_MORP, CHUNK_NNET, CHUNK_NGRF, CHUNK_SDFV, CHUNK_SUBS, CHUNK_COLL, } from './drftFormat.js';
 import { readSubs } from './drftSubs.js';
 import { readSdfv } from './sdfv.js';
 import { readDtex } from './dtex.js';
@@ -25,6 +25,9 @@ import { readNavm } from './navm.js';
 import { readNnet } from './nnet.js';
 import { readNgrf } from './ngrf.js';
 import { readColliders } from './drftColliders.js';
+import { readInstances } from './drftInstances.js';
+import { readLights } from './drftLights.js';
+import { decodeQuantisedMesh } from './drftQuantised.js';
 const decoder = new TextDecoder();
 function readString(view, buffer, at, limit) {
     if (at + 4 > limit)
@@ -171,6 +174,9 @@ export function readDrft(buffer) {
     let nnet = null;
     let graphs = [];
     let colliders = [];
+    /* Read once every mesh is counted, because a group is checked against the mesh count. */
+    let instanceChunk = null;
+    let lights = [];
     const skipped = [];
     let head = null;
     for (let i = 0; i < chunkCount; i++) {
@@ -206,6 +212,9 @@ export function readDrft(buffer) {
             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) });
@@ -227,6 +236,10 @@ export function readDrft(buffer) {
             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)
@@ -315,6 +328,10 @@ export function readDrft(buffer) {
         lods,
         levels: discreteLevels,
         nodes,
+        instances: instanceChunk === null
+            ? []
+            : readInstances(buffer, instanceChunk.offset, instanceChunk.byteLength, meshes.length),
+        lights,
         skins,
         clips,
         materials,
@@ -515,6 +532,10 @@ export function readMaterials(buffer, chunk) {
             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/dist/drftStream.d.ts

@@ -5,6 +5,9 @@ import type { DrftTexture } from './drftRead.ts';
 import type { AnimationClip, DrftSkin } from './animationData.ts';
 import type { DrftNode } from './drftSkin.ts';
 import type { DrftMorph } from './drftSkin.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import type { DrftSdfvEntry } from './sdfv.ts';
+import type { DrftLight } from './drftLights.ts';
 /**
  * What the file says is coming, known from the first few kilobytes.
  *
@@ -76,6 +79,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. */
@@ -160,6 +175,33 @@ export declare class DrftStream {
     /** Report every chunk whose last byte has now landed, in file order. */
     private settleChunks;
 }
+/**
+ * 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 declare 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>;
+}
 /**
  * Read a `.drft` from a fetch response as it arrives.
  *
@@ -167,4 +209,4 @@ export declare class DrftStream {
  * and the model improves as the bytes land. A response with no body — an error page, a
  * cache miss served as a redirect — throws rather than resolving to an empty asset.
  */
-export declare function streamDrft(response: Response, handlers?: DrftStreamHandlers): Promise<void>;
+export declare function streamDrft(response: Response, handlers?: DrftStreamHandlers, pacing?: DrftStreamPacing): Promise<void>;

package/dist/drftStream.js

@@ -1,7 +1,11 @@
 /** Reading a `.drft` while it is still arriving, chunk by chunk. */
-import { CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_LODM, CHUNK_SPLT, CHUNK_MATL, CHUNK_MESH, CHUNK_REQUIRED, CHUNK_TEXS, DRFT_MAGIC, DRFT_VERSION_MAJOR, DrftError, HEADER_BYTES, KNOWN_CHUNKS, fourCCName, CHUNK_ANIM, CHUNK_NODE, CHUNK_SKIN, CHUNK_MORP, } from './drftFormat.js';
+import { CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_LODM, CHUNK_SPLT, CHUNK_MATL, CHUNK_MESH, CHUNK_REQUIRED, CHUNK_TEXS, DRFT_MAGIC, DRFT_VERSION_MAJOR, DrftError, HEADER_BYTES, KNOWN_CHUNKS, fourCCName, CHUNK_ANIM, CHUNK_NODE, CHUNK_INST, CHUNK_LITE, CHUNK_SDFV, CHUNK_MSHQ, CHUNK_SKIN, CHUNK_MORP, } from './drftFormat.js';
 import { readHead, readMaterials, readMesh, readSplatBlock, readTexture } from './drftRead.js';
 import { readClip, readMorph, readNodes, readSkin } from './drftSkin.js';
+import { readInstances } from './drftInstances.js';
+import { readLights } from './drftLights.js';
+import { readSdfv } from './sdfv.js';
+import { decodeQuantisedMesh } from './drftQuantised.js';
 /**
  * An incremental `.drft` reader: feed it bytes, it reports each chunk as that chunk completes.
  *
@@ -196,8 +200,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)
+            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
@@ -216,7 +221,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,
@@ -242,8 +247,10 @@ export class DrftStream {
                 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++);
             }
@@ -265,6 +272,16 @@ export class DrftStream {
             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);
             }
@@ -288,6 +305,16 @@ 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;
+const monotonicNow = () => performance.now();
+/* A timer rather than a microtask: a microtask would rejoin the task it is trying to leave. */
+const nextTask = () => new Promise((resolve) => {
+    setTimeout(resolve, 0);
+});
 /**
  * Read a `.drft` from a fetch response as it arrives.
  *
@@ -295,21 +322,29 @@ export class DrftStream {
  * and the model improves as the bytes land. A response with no body — an error page, a
  * cache miss served as a redirect — throws rather than resolving to an empty asset.
  */
-export async function streamDrft(response, handlers = {}) {
+export async function streamDrft(response, handlers = {}, pacing = {}) {
     if (!response.ok) {
         throw new DrftError(`fetching the asset returned ${response.status} ${response.statusText}`);
     }
     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();
 }

package/dist/drftWrite.d.ts

@@ -19,6 +19,8 @@ import { type DtexEntry } from './dtex.ts';
 import { type EntsScene } from './ents.ts';
 import { type NavPolyMesh } from './navm.ts';
 import { type DrftGraph } from './ngrf.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import type { DrftLight } from './drftLights.ts';
 /** An image to embed, already compressed, with what its own header said about it. */
 export interface DrftTextureSource {
     /**
@@ -106,6 +108,19 @@ export interface DrftSource {
      * the meshes exactly as it always did, which is why this is additive.
      */
     readonly nodes?: readonly DrftNode[];
+    /**
+     * Meshes drawn many times: one `INST` chunk, written ahead of the geometry and required. The mesh
+     * a group names holds one copy; see `drftInstances.ts`.
+     */
+    readonly instances?: readonly DrftInstanceGroup[];
+    /** The lights the scene was authored with: one `LITE` chunk, optional. See `drftLights.ts`. */
+    readonly lights?: readonly DrftLight[];
+    /**
+     * Write each mesh as `MSHQ` rather than `MESH`: constants, 16-bit ranges and octahedral
+     * directions, about a third of the bytes, within the bounds `drftQuantised.ts` states. Off unless
+     * asked, so a caller writing a file gets the bytes it always got; the baker asks by default.
+     */
+    readonly quantise?: boolean;
     /** Skins, one `SKIN` chunk each, or absent for an asset that deforms nothing. */
     readonly skins?: readonly DrftSkin[];
     /** Clips, one `ANIM` chunk each, or absent for an asset that animates nothing. */