@driftengine/drft 4.5.0 → 4.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 The `.drft` container: read and write a baked scene. Declares no runtime dependency.
 
-**Cost: 9.7 KB gzipped.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 14.0 KB gzipped.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/assemble.d.ts

@@ -0,0 +1,7 @@
+import type { DrftAssembly } from './drftAssembly.ts';
+import type { MeshData } from './meshData.ts';
+/** Finds a kit piece by mesh ordinal. */
+export type PieceLookup = (ordinal: number) => MeshData;
+export declare function expandAssembly(assembly: DrftAssembly, piece: PieceLookup): MeshData;
+/** Min xyz then max xyz of every copy: its piece's box through its matrix, corner by corner. */
+export declare function assemblyBounds(assembly: DrftAssembly, piece: PieceLookup, out?: Float32Array): Float32Array;

package/dist/assemble.js

@@ -0,0 +1,242 @@
+/**
+ * An assembly expanded into the mesh it describes: every copy's piece through its matrix, painted
+ * by its surface, its texture coordinates stretched as the copy says.
+ *
+ * **Positions by the matrix, normals by its inverse transpose**, so a slope stretched along one
+ * axis stays perpendicular to itself rather than leaning with the stretch. **A copy that mirrors
+ * — a negative determinant — winds its triangles back** and flips its tangent's handedness, so its
+ * faces still wind counter-clockwise seen from outside and a mirrored texture still lights the
+ * right way up. Tangents follow the matrix, since a tangent is a direction along the surface.
+ *
+ * **A coordinate is stretched along the piece's own tangent**: u by `|uStretch ⊙ t|` for the
+ * piece's unit tangent t, v the same along its bitangent, then offset. That is what lets one unit
+ * box serve every box in a city: its face coordinates run 0..1, and a copy 13 m by 4 m carrying
+ * stretches of size over tile repeats its facade in metres on every face. What it gives up is a
+ * stretch that varies across one face — a cone's side, where the circumference shrinks up the
+ * slope — which comes out as the stretch at each vertex's own tangent, and exact only where the
+ * piece's coordinates are linear in its surface.
+ *
+ * One allocation per output array, sized by a first pass over the copies.
+ */
+import { COPY_MATRIX_FLOATS, COPY_UV_FLOATS, SURFACE, SURFACE_FLOATS, determinant, } from './drftAssembly.js';
+import { ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_LAYERS, ATTR_RELIEF, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_TANGENT, ATTR_UVS, ATTR_CHANNEL, DrftError, } from './drftFormat.js';
+function pieceOf(piece, assembly, c) {
+    const mesh = piece(assembly.pieces[c]);
+    const textured = (assembly.attributes & ATTR_UVS) !== 0;
+    if (textured && (mesh.uvs === undefined || mesh.tangents === undefined)) {
+        throw new DrftError(`piece ${assembly.pieces[c]} has no ${mesh.uvs === undefined ? 'texture coordinates' : 'tangents'}, and a textured assembly copies it`);
+    }
+    if ((assembly.attributes & ATTR_TANGENT) !== 0 && mesh.tangents === undefined) {
+        throw new DrftError(`piece ${assembly.pieces[c]} has no tangents, and the assembly carries them`);
+    }
+    if ((assembly.attributes & ATTR_CHANNEL) !== 0 && mesh.channel === undefined) {
+        throw new DrftError(`piece ${assembly.pieces[c]} has no channel, and the assembly sways`);
+    }
+    return mesh;
+}
+export function expandAssembly(assembly, piece) {
+    const { attributes, surfaces, surfaceOf, transforms, uv } = assembly;
+    const copies = assembly.pieces.length;
+    let vertices = 0;
+    let indexCount = 0;
+    for (let c = 0; c < copies; c++) {
+        const mesh = pieceOf(piece, assembly, c);
+        vertices += mesh.positions.length / 3;
+        indexCount += mesh.indices.length;
+    }
+    const has = (bit) => (attributes & bit) !== 0;
+    const out = {
+        positions: new Float32Array(vertices * 3),
+        normals: new Float32Array(vertices * 3),
+        colors: new Float32Array(vertices * 3),
+        emissive: new Float32Array(vertices),
+        indices: new Uint32Array(indexCount),
+    };
+    if (has(ATTR_SPECULAR))
+        out.specular = new Float32Array(vertices);
+    if (has(ATTR_UVS))
+        out.uvs = new Float32Array(vertices * 2);
+    if (has(ATTR_EMISSIVE_COLOR))
+        out.emissiveColor = new Float32Array(vertices * 3);
+    if (has(ATTR_ROUGHNESS))
+        out.roughness = new Float32Array(vertices);
+    if (has(ATTR_GRAIN))
+        out.grain = new Float32Array(vertices);
+    if (has(ATTR_RELIEF))
+        out.relief = new Float32Array(vertices);
+    if (has(ATTR_TANGENT))
+        out.tangents = new Float32Array(vertices * 4);
+    if (has(ATTR_LAYERS))
+        out.layers = new Float32Array(vertices);
+    if (has(ATTR_CHANNEL))
+        out.channel = new Float32Array(vertices * 4);
+    let v0 = 0;
+    let i0 = 0;
+    for (let c = 0; c < copies; c++) {
+        const mesh = pieceOf(piece, assembly, c);
+        const m = c * COPY_MATRIX_FLOATS;
+        const t = transforms;
+        const [a, b, cc, d, e, f, g, h, k] = [
+            t[m],
+            t[m + 1],
+            t[m + 2],
+            t[m + 3],
+            t[m + 4],
+            t[m + 5],
+            t[m + 6],
+            t[m + 7],
+            t[m + 8],
+        ];
+        const [tx, ty, tz] = [t[m + 9], t[m + 10], t[m + 11]];
+        const det = determinant(t, m);
+        /* The inverse transpose is the cofactor matrix over the determinant. With columns (a b cc),
+           (d e f), (g h k) the matrix's rows are (a d g), (b e h), (cc f k), and nRC is the cofactor of
+           row R, column C — not of C, R, which would be the plain inverse. */
+        const n00 = (e * k - f * h) / det;
+        const n01 = (cc * h - b * k) / det;
+        const n02 = (b * f - cc * e) / det;
+        const n10 = (f * g - d * k) / det;
+        const n11 = (a * k - cc * g) / det;
+        const n12 = (cc * d - a * f) / det;
+        const n20 = (d * h - e * g) / det;
+        const n21 = (b * g - a * h) / det;
+        const n22 = (a * e - b * d) / det;
+        const hand = det < 0 ? -1 : 1;
+        const s = surfaceOf[c] * SURFACE_FLOATS;
+        const u = c * COPY_UV_FLOATS;
+        const count = mesh.positions.length / 3;
+        const p = mesh.positions;
+        const n = mesh.normals;
+        const tan = mesh.tangents;
+        const tex = mesh.uvs;
+        for (let i = 0; i < count; i++) {
+            const o = v0 + i;
+            const px = p[i * 3];
+            const py = p[i * 3 + 1];
+            const pz = p[i * 3 + 2];
+            out.positions[o * 3] = a * px + d * py + g * pz + tx;
+            out.positions[o * 3 + 1] = b * px + e * py + h * pz + ty;
+            out.positions[o * 3 + 2] = cc * px + f * py + k * pz + tz;
+            const nx = n[i * 3];
+            const ny = n[i * 3 + 1];
+            const nz = n[i * 3 + 2];
+            let wx = n00 * nx + n01 * ny + n02 * nz;
+            let wy = n10 * nx + n11 * ny + n12 * nz;
+            let wz = n20 * nx + n21 * ny + n22 * nz;
+            const nl = Math.hypot(wx, wy, wz) || 1;
+            wx /= nl;
+            wy /= nl;
+            wz /= nl;
+            out.normals[o * 3] = wx;
+            out.normals[o * 3 + 1] = wy;
+            out.normals[o * 3 + 2] = wz;
+            out.colors[o * 3] = surfaces[s + SURFACE.color];
+            out.colors[o * 3 + 1] = surfaces[s + SURFACE.color + 1];
+            out.colors[o * 3 + 2] = surfaces[s + SURFACE.color + 2];
+            out.emissive[o] = surfaces[s + SURFACE.emissive];
+            if (out.specular)
+                out.specular[o] = surfaces[s + SURFACE.specular];
+            if (out.emissiveColor) {
+                out.emissiveColor[o * 3] = surfaces[s + SURFACE.emissiveColor];
+                out.emissiveColor[o * 3 + 1] = surfaces[s + SURFACE.emissiveColor + 1];
+                out.emissiveColor[o * 3 + 2] = surfaces[s + SURFACE.emissiveColor + 2];
+            }
+            if (out.roughness)
+                out.roughness[o] = surfaces[s + SURFACE.roughness];
+            if (out.grain)
+                out.grain[o] = surfaces[s + SURFACE.grain];
+            if (out.relief)
+                out.relief[o] = surfaces[s + SURFACE.relief];
+            if (out.layers)
+                out.layers[o] = surfaces[s + SURFACE.layer];
+            /* Sway, sky and opacity are the piece's own: shape, not paint. */
+            if (out.channel && mesh.channel !== undefined) {
+                for (let lane = 0; lane < 4; lane++) {
+                    out.channel[o * 4 + lane] = mesh.channel[i * 4 + lane];
+                }
+            }
+            if (tan !== undefined && (out.tangents !== undefined || out.uvs !== undefined)) {
+                const qx = tan[i * 4];
+                const qy = tan[i * 4 + 1];
+                const qz = tan[i * 4 + 2];
+                const qw = tan[i * 4 + 3];
+                if (out.tangents) {
+                    let rx = a * qx + d * qy + g * qz;
+                    let ry = b * qx + e * qy + h * qz;
+                    let rz = cc * qx + f * qy + k * qz;
+                    const rl = Math.hypot(rx, ry, rz) || 1;
+                    rx /= rl;
+                    ry /= rl;
+                    rz /= rl;
+                    out.tangents[o * 4] = rx;
+                    out.tangents[o * 4 + 1] = ry;
+                    out.tangents[o * 4 + 2] = rz;
+                    out.tangents[o * 4 + 3] = qw * hand;
+                }
+                if (out.uvs && tex !== undefined) {
+                    /* The piece's own directions for u and v: its tangent, and the bitangent n × t · w. */
+                    const ql = Math.hypot(qx, qy, qz) || 1;
+                    const bx = (ny * qz - nz * qy) * qw;
+                    const by = (nz * qx - nx * qz) * qw;
+                    const bz = (nx * qy - ny * qx) * qw;
+                    const bl = Math.hypot(bx, by, bz) || 1;
+                    const su = Math.hypot((uv[u] * qx) / ql, (uv[u + 1] * qy) / ql, (uv[u + 2] * qz) / ql);
+                    const sv = Math.hypot((uv[u + 3] * bx) / bl, (uv[u + 4] * by) / bl, (uv[u + 5] * bz) / bl);
+                    out.uvs[o * 2] = tex[i * 2] * su + uv[u + 6];
+                    out.uvs[o * 2 + 1] = tex[i * 2 + 1] * sv + uv[u + 7];
+                }
+            }
+        }
+        const idx = mesh.indices;
+        for (let j = 0; j + 2 < idx.length; j += 3) {
+            out.indices[i0 + j] = v0 + idx[j];
+            /* A mirrored copy winds back, or its faces turn inside out. */
+            out.indices[i0 + j + 1] = v0 + idx[hand < 0 ? j + 2 : j + 1];
+            out.indices[i0 + j + 2] = v0 + idx[hand < 0 ? j + 1 : j + 2];
+        }
+        v0 += count;
+        i0 += idx.length;
+    }
+    return out;
+}
+/** Min xyz then max xyz of every copy: its piece's box through its matrix, corner by corner. */
+export function assemblyBounds(assembly, piece, out = new Float32Array(6)) {
+    out.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+    for (let c = 0; c < assembly.pieces.length; c++) {
+        const p = piece(assembly.pieces[c]).positions;
+        let lx = Infinity;
+        let ly = Infinity;
+        let lz = Infinity;
+        let hx = -Infinity;
+        let hy = -Infinity;
+        let hz = -Infinity;
+        for (let i = 0; i + 2 < p.length; i += 3) {
+            lx = Math.min(lx, p[i]);
+            ly = Math.min(ly, p[i + 1]);
+            lz = Math.min(lz, p[i + 2]);
+            hx = Math.max(hx, p[i]);
+            hy = Math.max(hy, p[i + 1]);
+            hz = Math.max(hz, p[i + 2]);
+        }
+        if (lx > hx)
+            continue;
+        const m = c * COPY_MATRIX_FLOATS;
+        const t = assembly.transforms;
+        for (let corner = 0; corner < 8; corner++) {
+            const x = corner & 1 ? hx : lx;
+            const y = corner & 2 ? hy : ly;
+            const z = corner & 4 ? hz : lz;
+            for (let axis = 0; axis < 3; axis++) {
+                const w = t[m + axis] * x +
+                    t[m + 3 + axis] * y +
+                    t[m + 6 + axis] * z +
+                    t[m + 9 + axis];
+                if (w < out[axis])
+                    out[axis] = w;
+                if (w > out[axis + 3])
+                    out[axis + 3] = w;
+            }
+        }
+    }
+    return out;
+}

package/dist/drftAssembly.d.ts

@@ -0,0 +1,62 @@
+import type { MeshData } from './meshData.ts';
+/** Where each value sits in a surface, whichever of them the mesh carries. */
+export declare const SURFACE: {
+    readonly color: 0;
+    readonly emissive: 3;
+    readonly specular: 4;
+    readonly emissiveColor: 5;
+    readonly roughness: 8;
+    readonly grain: 9;
+    readonly relief: 10;
+    readonly layer: 11;
+};
+export declare const SURFACE_FLOATS = 12;
+/** A copy's matrix: three columns of the linear part, then the translation. */
+export declare const COPY_MATRIX_FLOATS = 12;
+/** A copy's texture stretch: u along each piece axis, v along each, then the offset. */
+export declare const COPY_UV_FLOATS = 8;
+/** The optional arrays an assembled mesh may carry. Skinning is a piece of a character, not a kit. */
+export declare const ASSEMBLY_ATTRIBUTES: number;
+export interface DrftAssembly {
+    /** Which optional arrays the expanded mesh carries, as a `MESH`'s attribute bits. */
+    readonly attributes: number;
+    /** `SURFACE_FLOATS` a surface, laid out as `SURFACE` says. */
+    readonly surfaces: Float32Array;
+    /** One kit piece a copy, by mesh ordinal. */
+    readonly pieces: Uint32Array;
+    /** One surface a copy. */
+    readonly surfaceOf: Uint32Array;
+    /** `COPY_MATRIX_FLOATS` a copy, taking the piece to where the copy stands. */
+    readonly transforms: Float32Array;
+    /**
+     * `COPY_UV_FLOATS` a copy. A coordinate is multiplied by how far the copy stretches the piece's
+     * own direction for it — `|stretch ⊙ t|` for the unit tangent `t`, the bitangent for v — so a
+     * unit box copied at 13 × 4 m with stretches of size over tile repeats its texture in metres,
+     * face by face. `(1, 1, 1)` twice and no offset leave a piece's coordinates as they are.
+     */
+    readonly uv: Float32Array;
+}
+/** Whether a mesh slot holds an assembly rather than vertices. */
+export declare function isAssembly(mesh: object): mesh is DrftAssembly;
+export declare function buildKit(ordinals: readonly number[]): Uint8Array;
+/** The kit's pieces, ascending and each a mesh the file carries. */
+export declare function readKit(buffer: ArrayBufferLike, offset: number, byteLength: number, meshCount: number): number[];
+export declare function checkKit(ordinals: readonly number[], meshCount: number): void;
+export declare function buildAssembly(assembly: DrftAssembly): Uint8Array;
+/** One `MSHC` payload, checked on its own; its pieces are the caller's to check. */
+export declare function readAssembly(buffer: ArrayBufferLike, offset: number, byteLength: number): DrftAssembly;
+/**
+ * What an assembly must be on its own: known bits, whole records, surfaces it names, finite
+ * numbers, whole layers, and no copy flattened to nothing — whose normals would be a division by
+ * zero rather than a direction.
+ */
+export declare function checkAssembly(assembly: DrftAssembly, name: string): void;
+/** The determinant of the linear part of the copy matrix at `m`. */
+export declare function determinant(t: ArrayLike<number>, m: number): number;
+/**
+ * What an assembly must be to the kit around it: every copy a declared piece that comes before it
+ * in the file — so a streaming reader holds the piece when the copy lands — and every piece
+ * carrying what the assembly asks of it. Shared by the writer and both readers, so a file one
+ * refuses the others refuse too.
+ */
+export declare function checkCopies(assembly: DrftAssembly, ordinal: number, kit: ReadonlySet<number>, piece: (ordinal: number) => MeshData | undefined): void;

package/dist/drftAssembly.js

@@ -0,0 +1,267 @@
+/**
+ * `KITS` and `MSHC`: a mesh carried as painted copies of a few pieces, rather than as its vertices.
+ *
+ * **What it is for is a world built from a kit.** A city of boxes, columns and cornices is a few
+ * thousand distinct shapes placed half a million times, each at its own size and in its own paint.
+ * Merged, its vertices are most of a gigabyte even quantised; as placements of the kit they are a
+ * few tens of megabytes. So a mesh may arrive as `MSHC` — a table of surfaces and, per copy, which
+ * piece, which surface, a 3×4 matrix and how its texture stretches — and is expanded by arithmetic
+ * into exactly the `MeshData` a `MESH` would have carried (`assemble.ts`). It stands in place of a
+ * `MESH` and counts as one in every ordinal, as `MSHQ` does, so materials and regions name it
+ * like any other.
+ *
+ * **`KITS` names the pieces, and is written ahead of the geometry.** A piece is an ordinary mesh
+ * that is drawn only inside the meshes assembled from it; without the declaration a streaming
+ * reader would upload every piece as a part and draw the whole kit at the origin. Both chunks are
+ * **required**, for the `INST` reason: a reader that skipped `KITS` would draw that kit, and one
+ * that skipped `MSHC` would draw nothing where a district stands. A refusal naming them is the
+ * honest answer, and what it gives up is opening such a file in a reader before 1.23.
+ *
+ * **A piece is shape; a copy is shape placed and painted.** A piece's colours, emissive and every
+ * other per-vertex constant are ignored — the copy's surface supplies them. A piece carries
+ * positions, normals, and texture coordinates with tangents where the mesh is textured, since the
+ * tangent is what says which way a coordinate runs, and so how a copy's stretch applies to it.
+ * **Its sway is shape too**: where the assembly carries `channel`, each copy takes its piece's, as
+ * a tree's rises from its root to its leaves however it is placed.
+ *
+ * Layout, little-endian:
+ * - `KITS`: u32 count, then that many u32 mesh ordinals, ascending;
+ * - `MSHC`: u32 attribute bits (a `MESH`'s, less skinning), u32 surface count, then
+ *   `SURFACE_FLOATS` f32 a surface; u32 copy count, then per copy u32 piece ordinal, u32 surface,
+ *   12 f32 of matrix (three columns, then the translation), 3 f32 of u stretch, 3 f32 of v stretch
+ *   and 2 f32 of offset: 88 bytes a copy.
+ */
+import { ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_LAYERS, ATTR_RELIEF, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_TANGENT, ATTR_UVS, ATTR_CHANNEL, DrftError, align, } from './drftFormat.js';
+/** Where each value sits in a surface, whichever of them the mesh carries. */
+export const SURFACE = {
+    color: 0,
+    emissive: 3,
+    specular: 4,
+    emissiveColor: 5,
+    roughness: 8,
+    grain: 9,
+    relief: 10,
+    layer: 11,
+};
+export const SURFACE_FLOATS = 12;
+/** A copy's matrix: three columns of the linear part, then the translation. */
+export const COPY_MATRIX_FLOATS = 12;
+/** A copy's texture stretch: u along each piece axis, v along each, then the offset. */
+export const COPY_UV_FLOATS = 8;
+const COPY_BYTES = 8 + (COPY_MATRIX_FLOATS + COPY_UV_FLOATS) * 4;
+/** The optional arrays an assembled mesh may carry. Skinning is a piece of a character, not a kit. */
+export const ASSEMBLY_ATTRIBUTES = ATTR_SPECULAR |
+    ATTR_UVS |
+    ATTR_EMISSIVE_COLOR |
+    ATTR_ROUGHNESS |
+    ATTR_GRAIN |
+    ATTR_RELIEF |
+    ATTR_TANGENT |
+    ATTR_LAYERS |
+    ATTR_CHANNEL;
+/** Whether a mesh slot holds an assembly rather than vertices. */
+export function isAssembly(mesh) {
+    return 'pieces' in mesh && 'surfaceOf' in mesh;
+}
+export function buildKit(ordinals) {
+    const out = new Uint8Array(align(4 + ordinals.length * 4));
+    const view = new DataView(out.buffer);
+    view.setUint32(0, ordinals.length, true);
+    ordinals.forEach((o, i) => view.setUint32(4 + i * 4, o, true));
+    return out;
+}
+/** The kit's pieces, ascending and each a mesh the file carries. */
+export function readKit(buffer, offset, byteLength, meshCount) {
+    const view = new DataView(buffer, offset, byteLength);
+    if (byteLength < 4)
+        throw new DrftError('KITS ends inside its count');
+    const count = view.getUint32(0, true);
+    if (4 + count * 4 > byteLength)
+        throw new DrftError('KITS ends inside its pieces');
+    const out = [];
+    for (let i = 0; i < count; i++)
+        out.push(view.getUint32(4 + i * 4, true));
+    checkKit(out, meshCount);
+    return out;
+}
+export function checkKit(ordinals, meshCount) {
+    let previous = -1;
+    for (const o of ordinals) {
+        if (o >= meshCount)
+            throw new DrftError(`KITS names mesh ${o}, and the file carries ${meshCount}`);
+        if (o <= previous)
+            throw new DrftError('KITS names its pieces out of order or twice');
+        previous = o;
+    }
+}
+export function buildAssembly(assembly) {
+    const copies = assembly.pieces.length;
+    const bytes = 12 + assembly.surfaces.length * 4 + copies * COPY_BYTES;
+    const out = new Uint8Array(align(bytes));
+    const view = new DataView(out.buffer);
+    let at = 0;
+    const u32 = (v) => {
+        view.setUint32(at, v, true);
+        at += 4;
+    };
+    const f32 = (v) => {
+        view.setFloat32(at, v, true);
+        at += 4;
+    };
+    u32(assembly.attributes);
+    u32(assembly.surfaces.length / SURFACE_FLOATS);
+    for (let i = 0; i < assembly.surfaces.length; i++)
+        f32(assembly.surfaces[i]);
+    u32(copies);
+    for (let c = 0; c < copies; c++) {
+        u32(assembly.pieces[c]);
+        u32(assembly.surfaceOf[c]);
+        for (let i = 0; i < COPY_MATRIX_FLOATS; i++)
+            f32(assembly.transforms[c * COPY_MATRIX_FLOATS + i]);
+        for (let i = 0; i < COPY_UV_FLOATS; i++)
+            f32(assembly.uv[c * COPY_UV_FLOATS + i]);
+    }
+    if (at !== bytes)
+        throw new DrftError(`internal: MSHC wrote ${at} of ${bytes} bytes`);
+    return out;
+}
+/** One `MSHC` payload, checked on its own; its pieces are the caller's to check. */
+export function readAssembly(buffer, offset, byteLength) {
+    const view = new DataView(buffer, offset, byteLength);
+    let at = 0;
+    const need = (bytes, what) => {
+        if (at + bytes > byteLength)
+            throw new DrftError(`MSHC ends inside ${what}`);
+    };
+    need(8, 'its header');
+    const attributes = view.getUint32(0, true);
+    const surfaceCount = view.getUint32(4, true);
+    at = 8;
+    need(surfaceCount * SURFACE_FLOATS * 4 + 4, 'its surfaces');
+    const surfaces = new Float32Array(surfaceCount * SURFACE_FLOATS);
+    for (let i = 0; i < surfaces.length; i++)
+        surfaces[i] = view.getFloat32(at + i * 4, true);
+    at += surfaces.length * 4;
+    const copies = view.getUint32(at, true);
+    at += 4;
+    need(copies * COPY_BYTES, 'its copies');
+    const pieces = new Uint32Array(copies);
+    const surfaceOf = new Uint32Array(copies);
+    const transforms = new Float32Array(copies * COPY_MATRIX_FLOATS);
+    const uv = new Float32Array(copies * COPY_UV_FLOATS);
+    for (let c = 0; c < copies; c++) {
+        pieces[c] = view.getUint32(at, true);
+        surfaceOf[c] = view.getUint32(at + 4, true);
+        at += 8;
+        for (let i = 0; i < COPY_MATRIX_FLOATS; i++, at += 4)
+            transforms[c * COPY_MATRIX_FLOATS + i] = view.getFloat32(at, true);
+        for (let i = 0; i < COPY_UV_FLOATS; i++, at += 4)
+            uv[c * COPY_UV_FLOATS + i] = view.getFloat32(at, true);
+    }
+    const assembly = { attributes, surfaces, pieces, surfaceOf, transforms, uv };
+    checkAssembly(assembly, 'MSHC');
+    return assembly;
+}
+/**
+ * What an assembly must be on its own: known bits, whole records, surfaces it names, finite
+ * numbers, whole layers, and no copy flattened to nothing — whose normals would be a division by
+ * zero rather than a direction.
+ */
+export function checkAssembly(assembly, name) {
+    const { attributes, surfaces, pieces, surfaceOf, transforms, uv } = assembly;
+    if ((attributes & ~ASSEMBLY_ATTRIBUTES) !== 0) {
+        throw new DrftError(`${name} carries attribute bits ${attributes} an assembly cannot`);
+    }
+    if ((attributes & ATTR_LAYERS) !== 0 && (attributes & ATTR_UVS) === 0) {
+        throw new DrftError(`${name} names layers without texture coordinates for them to ride with`);
+    }
+    if ((attributes & ATTR_UVS) !== 0 && (attributes & ATTR_TANGENT) === 0) {
+        throw new DrftError(`${name} is textured without tangents; a copy's stretch follows the piece's tangent`);
+    }
+    const copies = pieces.length;
+    if (surfaces.length % SURFACE_FLOATS !== 0 ||
+        surfaceOf.length !== copies ||
+        transforms.length !== copies * COPY_MATRIX_FLOATS ||
+        uv.length !== copies * COPY_UV_FLOATS) {
+        throw new DrftError(`${name}'s surfaces and copies are not whole records`);
+    }
+    const surfaceCount = surfaces.length / SURFACE_FLOATS;
+    for (let s = 0; s < surfaceCount; s++) {
+        for (let i = 0; i < SURFACE_FLOATS; i++) {
+            if (!Number.isFinite(surfaces[s * SURFACE_FLOATS + i])) {
+                throw new DrftError(`${name}'s surface ${s} is not finite`);
+            }
+        }
+        const layer = surfaces[s * SURFACE_FLOATS + SURFACE.layer];
+        if (!(layer >= 0) || Math.floor(layer) !== layer) {
+            throw new DrftError(`${name}'s surface ${s} names layer ${layer}, not a whole number`);
+        }
+    }
+    for (let c = 0; c < copies; c++) {
+        if (surfaceOf[c] >= surfaceCount) {
+            throw new DrftError(`${name}'s copy ${c} wears surface ${surfaceOf[c]} of ${surfaceCount}`);
+        }
+        const m = c * COPY_MATRIX_FLOATS;
+        for (let i = 0; i < COPY_MATRIX_FLOATS; i++) {
+            if (!Number.isFinite(transforms[m + i])) {
+                throw new DrftError(`${name}'s copy ${c} has a matrix that is not finite`);
+            }
+        }
+        for (let i = 0; i < COPY_UV_FLOATS; i++) {
+            if (!Number.isFinite(uv[c * COPY_UV_FLOATS + i])) {
+                throw new DrftError(`${name}'s copy ${c} has a texture stretch that is not finite`);
+            }
+        }
+        if (Math.abs(determinant(transforms, m)) < 1e-12) {
+            throw new DrftError(`${name}'s copy ${c} is flattened to nothing by its matrix`);
+        }
+    }
+}
+/** The determinant of the linear part of the copy matrix at `m`. */
+export function determinant(t, m) {
+    const a = t[m];
+    const b = t[m + 1];
+    const c = t[m + 2];
+    const d = t[m + 3];
+    const e = t[m + 4];
+    const f = t[m + 5];
+    const g = t[m + 6];
+    const h = t[m + 7];
+    const i = t[m + 8];
+    return a * (e * i - f * h) - d * (b * i - c * h) + g * (b * f - c * e);
+}
+/**
+ * What an assembly must be to the kit around it: every copy a declared piece that comes before it
+ * in the file — so a streaming reader holds the piece when the copy lands — and every piece
+ * carrying what the assembly asks of it. Shared by the writer and both readers, so a file one
+ * refuses the others refuse too.
+ */
+export function checkCopies(assembly, ordinal, kit, piece) {
+    const textured = (assembly.attributes & ATTR_UVS) !== 0;
+    const tangents = textured || (assembly.attributes & ATTR_TANGENT) !== 0;
+    const seen = new Set();
+    for (let c = 0; c < assembly.pieces.length; c++) {
+        const o = assembly.pieces[c];
+        if (seen.has(o))
+            continue;
+        seen.add(o);
+        if (!kit.has(o)) {
+            throw new DrftError(`mesh ${ordinal} copies mesh ${o}, which KITS does not name a piece`);
+        }
+        if (o >= ordinal) {
+            throw new DrftError(`mesh ${ordinal} copies piece ${o}, which comes after it; a piece is written before the meshes assembled from it`);
+        }
+        const mesh = piece(o);
+        if (mesh === undefined)
+            throw new DrftError(`mesh ${ordinal} copies piece ${o}, which has not arrived`);
+        if (textured && mesh.uvs === undefined) {
+            throw new DrftError(`mesh ${ordinal} is textured and piece ${o} has no texture coordinates`);
+        }
+        if (tangents && mesh.tangents === undefined) {
+            throw new DrftError(`mesh ${ordinal} needs tangents and piece ${o} has none`);
+        }
+        if ((assembly.attributes & ATTR_CHANNEL) !== 0 && mesh.channel === undefined) {
+            throw new DrftError(`mesh ${ordinal} sways and piece ${o} carries no channel to sway by`);
+        }
+    }
+}

package/dist/drftFormat.d.ts

@@ -20,7 +20,7 @@ export declare const DRFT_VERSION_MAJOR = 1;
  * Additive revisions within a generation: new optional chunks, new attribute bits, new
  * enum values with a defined fallback. Never a changed meaning.
  */
-export declare const DRFT_VERSION_MINOR = 19;
+export declare const DRFT_VERSION_MINOR = 23;
 /** Bytes before the chunk table. */
 export declare const HEADER_BYTES = 32;
 /** Bytes per chunk table entry. */
@@ -231,6 +231,30 @@ export declare const CHUNK_INST: number;
  * See `drftQuantised.ts`. Added in 1.18.
  */
 export declare const CHUNK_MSHQ: number;
+/**
+ * One region of a streamed world: its levels of detail as mesh ordinals, its prop groups, its
+ * occluders and its collision. **Required**, one chunk per region, written just ahead of the meshes
+ * it introduces; see `drftRegions.ts`. Added in 1.21.
+ */
+export declare const CHUNK_REGN: number;
+/**
+ * A world's fixed lights summed offline into one dense volume. Optional: a reader that skips it
+ * loses the glow of every light past the ones it shades exactly. See `drftLightVolume.ts`. Added in
+ * 1.22.
+ */
+export declare const CHUNK_LVOL: number;
+/**
+ * The meshes that are pieces of a kit, drawn only as copies inside assembled meshes. **Required**,
+ * and written ahead of the geometry; see `drftAssembly.ts`. Added in 1.23.
+ */
+export declare const CHUNK_KITS: number;
+/**
+ * A mesh carried as painted copies of kit pieces, expanded on read into the `MeshData` a `MESH`
+ * gives. **Required**, and counted as a mesh in every ordinal. See `drftAssembly.ts`. Added in 1.23.
+ */
+export declare const CHUNK_MSHC: number;
+/** Whether a chunk is a mesh in the ordinal sequence: plain, quantised or assembled. */
+export declare function isMeshChunk(code: number): boolean;
 /** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
 export declare const SPLAT_BLOCK_PREFIX = 40;
 /**
@@ -323,6 +347,24 @@ export declare const ATTR_TANGENT: number;
 export declare const ATTR_JOINTS: number;
 /** How much each of `ATTR_JOINTS`' four influences moves the vertex. See it for the whole story. */
 export declare const ATTR_WEIGHTS: number;
+/**
+ * Added in 1.20: which image of a texture array each vertex's face wears. See `MeshData.layers`.
+ *
+ * Next free bit, appended last, for the reason `grain` gives at length: a 1.19 reader meets the
+ * arrays it knows where it expects them, stops before this one, and draws every face at layer 0 —
+ * the first image of the array, which is what a reader that has never heard of layers should
+ * produce.
+ */
+export declare const ATTR_LAYERS: number;
+/**
+ * Added in 1.23: `MeshData.channel`, four floats a vertex — sway, sky, opacity, and a spare lane.
+ *
+ * **The writer dropped it without a word until then**, which is the silent kind of missing: a tree
+ * baked with its sway came back still, and nothing said the lane had not been written. Next free
+ * bit, appended last, so a 1.22 reader meets every array it knows where it expects them, stops
+ * before this one, and draws the mesh planted, sunlit and opaque — the absent lane's own meaning.
+ */
+export declare const ATTR_CHANNEL: number;
 /** Everything this version defines, so a reader can spot bits from a later writer. */
 export declare const ATTR_KNOWN: number;
 /**