@driftengine/drft 4.4.2 → 4.6.0

package/dist/drftRegions.d.ts

@@ -0,0 +1,58 @@
+import type { DrftInstanceGroup } from './drftInstances.ts';
+export interface DrftRegionLevel {
+    /** How far, in metres, this level's surface may stand from the real one. 0 for exact. */
+    readonly error: number;
+    /** The ordinals of the meshes this level draws. */
+    readonly meshes: readonly number[];
+}
+export interface DrftRegionCollision {
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+}
+export interface DrftRegion {
+    readonly id: number;
+    /** Everything the region holds, min xyz then max xyz. */
+    readonly bounds: ArrayLike<number>;
+    /** Finest first; at least one. */
+    readonly levels: readonly DrftRegionLevel[];
+    /** Its props, drawn at its finest level. */
+    readonly instances: readonly DrftInstanceGroup[];
+    /** Boxes that hide what stands behind them, six floats each. */
+    readonly occluders: Float32Array;
+    /** One triangle mesh the region collides as, or null. */
+    readonly collision: DrftRegionCollision | null;
+}
+/** The most levels a region may carry; the runtime keeps one value of a byte for "none". */
+export declare const REGION_MAX_LEVELS = 254;
+export declare function buildRegion(region: DrftRegion): Uint8Array;
+/** One `REGN` payload, checked on its own against the file's mesh count. */
+export declare function readRegion(buffer: ArrayBufferLike, offset: number, byteLength: number, meshCount: number): DrftRegion;
+/**
+ * What regions must be to each other: an id once, a level mesh in one region's one level, and a
+ * group's prototype never also a level mesh. Kept across chunks by the writer, the whole-file reader
+ * and the stream alike, so a file one of them refuses the others refuse too.
+ */
+export declare class RegionLedger {
+    private readonly ids;
+    private readonly levelMeshes;
+    private readonly prototypes;
+    admit(region: DrftRegion): void;
+    /** Whether a mesh is any region's, as a level or a prop. */
+    names(mesh: number): boolean;
+}
+/**
+ * Where each region's chunk goes among the meshes: `before[m]` is the regions written just ahead of
+ * mesh `m`, and `before[meshCount]` those after the last. A streaming reader then always has a
+ * region before the meshes it introduces.
+ *
+ * The meshes no region introduces come first, then each region's new meshes, in the order the
+ * regions are given and ascending. **A region introduces the kit pieces its assemblies copy, where
+ * no earlier region did** (`piecesOf` names them), so a piece travels with the first region that
+ * needs it rather than at the head of the file: a world's kit is most of its bytes, and a walker's
+ * first regions need a sliver of it. A piece ahead of the first mesh any region names is the
+ * file's own, as every piece was before a region could carry one, so either layout is valid. That
+ * a piece comes ahead of every assembly copying it is the kit's own rule (`checkCopies`). Anything
+ * else is refused by name rather than reordered, because the ordinals are what the regions and the
+ * materials already point at.
+ */
+export declare function planRegions(regions: readonly DrftRegion[], meshCount: number, piecesOf?: (mesh: number) => ArrayLike<number> | undefined): DrftRegion[][];

package/dist/drftRegions.js

@@ -0,0 +1,313 @@
+/**
+ * `REGN`: one region of a streamed world — its geometry at every level of detail, its prop
+ * batches, its occluders and its collision — as one chunk, written just ahead of its meshes.
+ *
+ * **Required, because a reader that skipped it would draw every level of every region at once.**
+ * A region's levels are ordinary meshes, so an old reader would open a city as each district drawn
+ * three times over itself, and every prop it places as one copy at the origin — the `INST`
+ * argument. A refusal naming `REGN` is the honest answer. What that gives up is opening such a file
+ * at all in a reader before 1.21.
+ *
+ * **Levels are meshes named by ordinal, finest first, each with a geometric error**: how far, in
+ * metres, that level's surface may stand from the real one. The runtime turns an error into a
+ * switch distance against its own screen, which a file cannot know. A mesh belongs to at most one
+ * region's levels. An instance group's prototype may be shared by any number of regions — a lamp
+ * post is one mesh however many districts stand it — but is never also a level mesh.
+ *
+ * Layout, little-endian:
+ * - u32 id, then f32 × 6 bounds (min xyz, max xyz);
+ * - u32 level count, then per level: f32 error, u32 mesh count, that many u32 mesh ordinals;
+ * - u32 group count, then per group: u32 mesh ordinal, u32 copies, that many 16-float matrices;
+ * - u32 occluder count, then f32 × 6 a box (min xyz, max xyz);
+ * - u32 vertex count, u32 index count, f32 × 3 a vertex, u32 an index: the region's collision.
+ */
+import { DrftError, align } from './drftFormat.js';
+/** The most levels a region may carry; the runtime keeps one value of a byte for "none". */
+export const REGION_MAX_LEVELS = 254;
+export function buildRegion(region) {
+    checkRegion(region, Number.POSITIVE_INFINITY);
+    let bytes = 4 + 24 + 4 + 4 + 4 + 8;
+    for (const level of region.levels)
+        bytes += 8 + level.meshes.length * 4;
+    for (const group of region.instances)
+        bytes += 8 + group.transforms.length * 4;
+    bytes += region.occluders.length * 4;
+    const vertices = region.collision?.positions.length ?? 0;
+    const indices = region.collision?.indices.length ?? 0;
+    bytes += vertices * 4 + indices * 4;
+    const out = new Uint8Array(align(bytes));
+    const view = new DataView(out.buffer);
+    let at = 0;
+    const u32 = (value) => {
+        view.setUint32(at, value, true);
+        at += 4;
+    };
+    const f32 = (value) => {
+        view.setFloat32(at, value, true);
+        at += 4;
+    };
+    u32(region.id);
+    for (let i = 0; i < 6; i++)
+        f32(region.bounds[i]);
+    u32(region.levels.length);
+    for (const level of region.levels) {
+        f32(level.error);
+        u32(level.meshes.length);
+        for (const mesh of level.meshes)
+            u32(mesh);
+    }
+    u32(region.instances.length);
+    for (const group of region.instances) {
+        u32(group.mesh);
+        u32(group.transforms.length / 16);
+        for (let i = 0; i < group.transforms.length; i++)
+            f32(group.transforms[i]);
+    }
+    u32(region.occluders.length / 6);
+    for (let i = 0; i < region.occluders.length; i++)
+        f32(region.occluders[i]);
+    u32(vertices / 3);
+    u32(indices);
+    for (let i = 0; i < vertices; i++)
+        f32(region.collision?.positions[i]);
+    for (let i = 0; i < indices; i++)
+        u32(region.collision?.indices[i]);
+    /* The one check the builder owns: it wrote exactly what it measured. */
+    if (at !== bytes)
+        throw new DrftError(`internal: REGN wrote ${at} of ${bytes} bytes`);
+    return out;
+}
+/** One `REGN` payload, checked on its own against the file's mesh count. */
+export function readRegion(buffer, offset, byteLength, meshCount) {
+    const view = new DataView(buffer, offset, byteLength);
+    let at = 0;
+    const need = (bytes, what) => {
+        if (at + bytes > byteLength)
+            throw new DrftError(`REGN ends inside ${what}`);
+    };
+    const u32 = () => {
+        const value = view.getUint32(at, true);
+        at += 4;
+        return value;
+    };
+    const floats = (count) => {
+        const out = new Float32Array(count);
+        for (let i = 0; i < count; i++)
+            out[i] = view.getFloat32(at + i * 4, true);
+        at += count * 4;
+        return out;
+    };
+    need(32, 'its header');
+    const id = u32();
+    const bounds = floats(6);
+    const levelCount = u32();
+    const levels = [];
+    for (let l = 0; l < levelCount; l++) {
+        need(8, `region ${id}'s level ${l}`);
+        const error = view.getFloat32(at, true);
+        at += 4;
+        const count = u32();
+        need(count * 4, `region ${id}'s level ${l}`);
+        const meshes = [];
+        for (let m = 0; m < count; m++)
+            meshes.push(u32());
+        levels.push({ error, meshes });
+    }
+    need(4, `region ${id}'s groups`);
+    const groupCount = u32();
+    const instances = [];
+    for (let g = 0; g < groupCount; g++) {
+        need(8, `region ${id}'s group ${g}`);
+        const mesh = u32();
+        const copies = u32();
+        need(copies * 64, `region ${id}'s group ${g}`);
+        instances.push({ mesh, transforms: floats(copies * 16) });
+    }
+    need(4, `region ${id}'s occluders`);
+    const occluderCount = u32();
+    need(occluderCount * 24, `region ${id}'s occluders`);
+    const occluders = floats(occluderCount * 6);
+    need(8, `region ${id}'s collision`);
+    const vertices = u32();
+    const indexCount = u32();
+    need(vertices * 12 + indexCount * 4, `region ${id}'s collision`);
+    const positions = floats(vertices * 3);
+    const indices = new Uint32Array(indexCount);
+    for (let i = 0; i < indexCount; i++)
+        indices[i] = u32();
+    const region = {
+        id,
+        bounds,
+        levels,
+        instances,
+        occluders,
+        collision: vertices === 0 && indexCount === 0 ? null : { positions, indices },
+    };
+    checkRegion(region, meshCount);
+    return region;
+}
+/** What one region must be on its own, whoever is asking. */
+function checkRegion(region, meshCount) {
+    const name = `region ${region.id}`;
+    const b = region.bounds;
+    for (let axis = 0; axis < 3; axis++) {
+        if (!(b[axis] <= b[axis + 3])) {
+            throw new DrftError(`${name}'s bounds are inside out on axis ${axis}`);
+        }
+    }
+    if (region.levels.length < 1 || region.levels.length > REGION_MAX_LEVELS) {
+        throw new DrftError(`${name} has ${region.levels.length} levels; 1 to ${REGION_MAX_LEVELS} are allowed`);
+    }
+    let previous = 0;
+    for (let l = 0; l < region.levels.length; l++) {
+        const level = region.levels[l];
+        if (!(level.error >= previous) || !Number.isFinite(level.error)) {
+            throw new DrftError(`${name}'s level ${l} has error ${level.error}, finer than the one before`);
+        }
+        previous = level.error;
+        for (const mesh of level.meshes) {
+            if (mesh >= meshCount) {
+                throw new DrftError(`${name} draws mesh ${mesh}, and the file carries ${meshCount}`);
+            }
+        }
+    }
+    const grouped = new Set();
+    for (const group of region.instances) {
+        if (group.mesh >= meshCount) {
+            throw new DrftError(`${name} places mesh ${group.mesh}, and the file carries ${meshCount}`);
+        }
+        if (group.transforms.length === 0 || group.transforms.length % 16 !== 0) {
+            throw new DrftError(`${name}'s group for mesh ${group.mesh} is not whole matrices`);
+        }
+        if (grouped.has(group.mesh))
+            throw new DrftError(`${name} groups mesh ${group.mesh} twice`);
+        grouped.add(group.mesh);
+    }
+    if (region.occluders.length % 6 !== 0) {
+        throw new DrftError(`${name}'s occluders are not whole boxes`);
+    }
+    const collision = region.collision;
+    if (collision !== null) {
+        const vertices = collision.positions.length / 3;
+        if (collision.positions.length % 3 !== 0 || collision.indices.length % 3 !== 0) {
+            throw new DrftError(`${name}'s collision is not whole vertices and triangles`);
+        }
+        for (let i = 0; i < collision.indices.length; i++) {
+            if (collision.indices[i] >= vertices) {
+                throw new DrftError(`${name}'s collision names vertex ${collision.indices[i]} of ${vertices}`);
+            }
+        }
+    }
+}
+/**
+ * What regions must be to each other: an id once, a level mesh in one region's one level, and a
+ * group's prototype never also a level mesh. Kept across chunks by the writer, the whole-file reader
+ * and the stream alike, so a file one of them refuses the others refuse too.
+ */
+export class RegionLedger {
+    ids = new Set();
+    levelMeshes = new Set();
+    prototypes = new Set();
+    admit(region) {
+        if (this.ids.has(region.id))
+            throw new DrftError(`region ${region.id} appears twice`);
+        this.ids.add(region.id);
+        for (const level of region.levels) {
+            for (const mesh of level.meshes) {
+                if (this.levelMeshes.has(mesh) || this.prototypes.has(mesh)) {
+                    throw new DrftError(`mesh ${mesh} is region ${region.id}'s and something else's; a level mesh belongs to one region's one level`);
+                }
+                this.levelMeshes.add(mesh);
+            }
+        }
+        for (const group of region.instances) {
+            if (this.levelMeshes.has(group.mesh)) {
+                throw new DrftError(`mesh ${group.mesh} is both a level mesh and a prop region ${region.id} places`);
+            }
+            this.prototypes.add(group.mesh);
+        }
+    }
+    /** Whether a mesh is any region's, as a level or a prop. */
+    names(mesh) {
+        return this.levelMeshes.has(mesh) || this.prototypes.has(mesh);
+    }
+}
+/**
+ * Where each region's chunk goes among the meshes: `before[m]` is the regions written just ahead of
+ * mesh `m`, and `before[meshCount]` those after the last. A streaming reader then always has a
+ * region before the meshes it introduces.
+ *
+ * The meshes no region introduces come first, then each region's new meshes, in the order the
+ * regions are given and ascending. **A region introduces the kit pieces its assemblies copy, where
+ * no earlier region did** (`piecesOf` names them), so a piece travels with the first region that
+ * needs it rather than at the head of the file: a world's kit is most of its bytes, and a walker's
+ * first regions need a sliver of it. A piece ahead of the first mesh any region names is the
+ * file's own, as every piece was before a region could carry one, so either layout is valid. That
+ * a piece comes ahead of every assembly copying it is the kit's own rule (`checkCopies`). Anything
+ * else is refused by name rather than reordered, because the ordinals are what the regions and the
+ * materials already point at.
+ */
+export function planRegions(regions, meshCount, piecesOf = () => undefined) {
+    const ledger = new RegionLedger();
+    for (const region of regions) {
+        checkRegion(region, meshCount);
+        ledger.admit(region);
+    }
+    /* What each region introduces: its levels' meshes and its props, then the pieces its level
+       meshes copy that nobody introduced before it — those past the first mesh any region names;
+       a piece ahead of it is the file's own, written first as every piece once was. */
+    let firstNamed = meshCount;
+    for (let m = 0; m < meshCount; m++) {
+        if (ledger.names(m)) {
+            firstNamed = m;
+            break;
+        }
+    }
+    const introduced = new Set();
+    const fresh = regions.map((region) => {
+        const out = [];
+        const take = (mesh) => {
+            if (introduced.has(mesh))
+                return;
+            introduced.add(mesh);
+            out.push(mesh);
+        };
+        for (const level of region.levels)
+            for (const mesh of level.meshes)
+                take(mesh);
+        for (const group of region.instances)
+            take(group.mesh);
+        for (const level of region.levels) {
+            for (const mesh of level.meshes) {
+                const pieces = piecesOf(mesh);
+                for (let i = 0; i < (pieces?.length ?? 0); i++) {
+                    const piece = pieces?.[i];
+                    if (piece > firstNamed && !ledger.names(piece))
+                        take(piece);
+                }
+            }
+        }
+        return out.sort((a, b) => a - b);
+    });
+    let next = meshCount - introduced.size;
+    for (let m = 0; m < next; m++) {
+        if (introduced.has(m)) {
+            throw new DrftError(`mesh ${m} is a region's and comes before mesh ${next - 1}, which no region names; ` +
+                'a file with regions writes the meshes no region names first');
+        }
+    }
+    const before = [];
+    for (let m = 0; m <= meshCount; m++)
+        before.push([]);
+    regions.forEach((region, r) => {
+        before[next].push(region);
+        for (const mesh of fresh[r]) {
+            if (mesh !== next) {
+                throw new DrftError(`region ${region.id} introduces mesh ${mesh} where mesh ${next} is next; ` +
+                    "write each region's new meshes in the order the regions are written");
+            }
+            next++;
+        }
+    });
+    return before;
+}

package/dist/drftStream.d.ts

@@ -8,6 +8,12 @@ import type { DrftMorph } from './drftSkin.ts';
 import type { DrftInstanceGroup } from './drftInstances.ts';
 import type { DrftSdfvEntry } from './sdfv.ts';
 import type { DrftLight } from './drftLights.ts';
+import type { PieceLookup } from './assemble.ts';
+import type { DrftAssembly } from './drftAssembly.ts';
+import type { DrftLightVolume } from './drftLightVolume.ts';
+import type { DrftRegion } from './drftRegions.ts';
+import { type NavPolyMesh } from './navm.ts';
+import { type EntsScene } from './ents.ts';
 /**
  * What the file says is coming, known from the first few kilobytes.
  *
@@ -60,8 +66,25 @@ export interface DrftStreamHandlers {
      * stop drawing it in the same frame it starts drawing the model, or the two are both there.
      */
     readonly onLod?: (mesh: MeshData, level: number) => void;
-    /** One mesh, in the order the file lays them out, with its ordinal in that order. */
+    /**
+     * One mesh, in the order the file lays them out, with its ordinal in that order. A kit piece is
+     * not one — it goes to `onPiece` — and an assembly is one only where `onAssembly` is absent, in
+     * which case it arrives here expanded.
+     */
     readonly onMesh?: (mesh: MeshData, ordinal: number) => void;
+    /**
+     * The ordinals of the kit's pieces, once, when `KITS` lands — ahead of the geometry, so a
+     * consumer knows which meshes are drawn only as copies before any of them arrives.
+     */
+    readonly onKit?: (pieces: readonly number[]) => void;
+    /** One kit piece, as it lands. The stream keeps it for the assemblies that copy it. */
+    readonly onPiece?: (mesh: MeshData, ordinal: number) => void;
+    /**
+     * One assembly as the file carried it, with a lookup for its pieces, which have all arrived. A
+     * consumer that pages its world keeps it this small and expands it (`expandAssembly`) when it is
+     * needed; without this handler the stream expands it and calls `onMesh`.
+     */
+    readonly onAssembly?: (assembly: DrftAssembly, ordinal: number, piece: PieceLookup) => void;
     /**
      * One block of a Gaussian splat capture, with its ordinal.
      *
@@ -84,6 +107,13 @@ export interface DrftStreamHandlers {
      * puts it, so a consumer knows a mesh is drawn many times before that mesh arrives.
      */
     readonly onInstances?: (groups: readonly DrftInstanceGroup[]) => void;
+    /**
+     * One region of a streamed world, when its `REGN` lands — ahead of the meshes it introduces, so
+     * a consumer knows a mesh is a region's level or prop before it arrives. See `drftRegions.ts`.
+     */
+    readonly onRegion?: (region: DrftRegion) => void;
+    /** A world's summed lights, once, when `LVOL` lands. See `drftLightVolume.ts`. */
+    readonly onLightVolume?: (volume: DrftLightVolume) => void;
     /** The lights the scene was authored with, once, when `LITE` lands. See `drftLights.ts`. */
     readonly onLights?: (lights: readonly DrftLight[]) => void;
     /**
@@ -103,6 +133,18 @@ export interface DrftStreamHandlers {
      * the geometry so this is usually possible.
      */
     readonly onClip?: (clip: AnimationClip, ordinal: number) => void;
+    /**
+     * The convex hulls the asset collides as, once, when `COLL` lands. See `drftColliders.ts`.
+     *
+     * These three — collision, the navigation mesh and the entities — were `readDrft`'s alone, so a
+     * scene that streamed its geometry had to fetch the file again, whole, to learn where it could
+     * walk and what stood in it.
+     */
+    readonly onColliders?: (hulls: readonly Float32Array[]) => void;
+    /** The navigation mesh, once, when `NAVM` lands. See `navm.ts`. */
+    readonly onNavigation?: (navigation: NavPolyMesh) => void;
+    /** The serialised entities, once, when `ENTS` lands. See `ents.ts`. */
+    readonly onEntities?: (entities: EntsScene) => void;
     readonly onMaterials?: (materials: readonly DrftMaterial[]) => void;
     readonly onTexture?: (texture: DrftTexture, ordinal: number) => void;
 }
@@ -137,10 +179,16 @@ export declare class DrftStream {
     private preludeBytes;
     private received;
     private chunks;
+    /** What the regions so far claim, so a second claim on a mesh is refused as `readDrft` refuses it. */
+    private readonly regions;
     /** How many table entries have been reported complete, in table order. */
     private settled;
     private meshOrdinal;
     private textureOrdinal;
+    /** The kit's pieces once `KITS` lands, and each piece as it arrives. */
+    private kit;
+    private readonly pieces;
+    private readonly pieceAt;
     private head;
     private meshCount;
     private materialCount;

package/dist/drftStream.js

@@ -1,11 +1,18 @@
 /** 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_INST, CHUNK_LITE, CHUNK_SDFV, CHUNK_MSHQ, 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_REGN, CHUNK_LVOL, CHUNK_LITE, CHUNK_SDFV, CHUNK_COLL, CHUNK_NAVM, CHUNK_ENTS, CHUNK_MSHQ, CHUNK_KITS, CHUNK_MSHC, isMeshChunk, 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';
+import { readColliders } from './drftColliders.js';
+import { expandAssembly } from './assemble.js';
+import { checkCopies, readAssembly, readKit } from './drftAssembly.js';
+import { RegionLedger, readRegion } from './drftRegions.js';
+import { readLightVolume } from './drftLightVolume.js';
+import { readNavm } from './navm.js';
+import { readEnts } from './ents.js';
 /**
  * An incremental `.drft` reader: feed it bytes, it reports each chunk as that chunk completes.
  *
@@ -37,10 +44,21 @@ export class DrftStream {
     preludeBytes = 0;
     received = 0;
     chunks = [];
+    /** What the regions so far claim, so a second claim on a mesh is refused as `readDrft` refuses it. */
+    regions = new RegionLedger();
     /** How many table entries have been reported complete, in table order. */
     settled = 0;
     meshOrdinal = 0;
     textureOrdinal = 0;
+    /** The kit's pieces once `KITS` lands, and each piece as it arrives. */
+    kit = null;
+    pieces = new Map();
+    pieceAt = (o) => {
+        const piece = this.pieces.get(o);
+        if (piece === undefined)
+            throw new DrftError(`kit piece ${o} has not arrived`);
+        return piece;
+    };
     head = null;
     meshCount = 0;
     materialCount = 0;
@@ -200,7 +218,7 @@ 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_MSHQ || chunk.code === CHUNK_LODM) {
+            if (isMeshChunk(chunk.code) || chunk.code === CHUNK_LODM) {
                 meshBytes += chunk.byteLength;
             }
             if (chunk.code === CHUNK_TEXS)
@@ -221,7 +239,7 @@ export class DrftStream {
         this.manifestSent = true;
         this.handlers.onManifest?.({
             totalBytes: this.buffer.byteLength,
-            meshCount: this.chunks.filter((c) => c.code === CHUNK_MESH || c.code === CHUNK_MSHQ).length,
+            meshCount: this.chunks.filter((c) => isMeshChunk(c.code)).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,
@@ -252,7 +270,40 @@ export class DrftStream {
                     ? readMesh(this.buffer, chunk)
                     : decodeQuantisedMesh(this.buffer, chunk.offset, chunk.byteLength);
                 this.meshCount++;
-                this.handlers.onMesh?.(mesh, this.meshOrdinal++);
+                const ordinal = this.meshOrdinal++;
+                if (this.kit?.has(ordinal) === true) {
+                    this.pieces.set(ordinal, mesh);
+                    this.handlers.onPiece?.(mesh, ordinal);
+                }
+                else {
+                    this.handlers.onMesh?.(mesh, ordinal);
+                }
+            }
+            else if (chunk.code === CHUNK_MSHC) {
+                const assembly = readAssembly(this.buffer, chunk.offset, chunk.byteLength);
+                this.meshCount++;
+                const ordinal = this.meshOrdinal++;
+                if (this.kit?.has(ordinal) === true) {
+                    throw new DrftError(`mesh ${ordinal} is a kit piece and an assembly`);
+                }
+                checkCopies(assembly, ordinal, this.kit ?? new Set(), (o) => this.pieces.get(o));
+                if (this.handlers.onAssembly !== undefined) {
+                    this.handlers.onAssembly(assembly, ordinal, this.pieceAt);
+                }
+                else {
+                    this.handlers.onMesh?.(expandAssembly(assembly, this.pieceAt), ordinal);
+                }
+            }
+            else if (chunk.code === CHUNK_KITS) {
+                const meshes = this.chunks.filter((c) => isMeshChunk(c.code)).length;
+                const kit = readKit(this.buffer, chunk.offset, chunk.byteLength, meshes);
+                /* A piece already handed over as a mesh has been drawn; the writer puts the kit first. */
+                const early = kit.find((o) => o < this.meshOrdinal);
+                if (early !== undefined) {
+                    throw new DrftError(`KITS arrives after mesh ${early}, one of its pieces`);
+                }
+                this.kit = new Set(kit);
+                this.handlers.onKit?.(kit);
             }
             else if (chunk.code === CHUNK_SPLT) {
                 /* The ordinal the file gave it, so blocks append in the writer's order however they
@@ -273,9 +324,27 @@ export class DrftStream {
                 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;
+                const meshes = this.chunks.filter((c) => isMeshChunk(c.code)).length;
                 this.handlers.onInstances?.(readInstances(this.buffer, chunk.offset, chunk.byteLength, meshes));
             }
+            else if (chunk.code === CHUNK_REGN) {
+                const meshes = this.chunks.filter((c) => isMeshChunk(c.code)).length;
+                const region = readRegion(this.buffer, chunk.offset, chunk.byteLength, meshes);
+                this.regions.admit(region);
+                this.handlers.onRegion?.(region);
+            }
+            else if (chunk.code === CHUNK_LVOL) {
+                this.handlers.onLightVolume?.(readLightVolume(this.buffer, chunk.offset, chunk.byteLength));
+            }
+            else if (chunk.code === CHUNK_COLL) {
+                this.handlers.onColliders?.(readColliders(this.buffer, chunk.offset, chunk.byteLength));
+            }
+            else if (chunk.code === CHUNK_NAVM) {
+                this.handlers.onNavigation?.(readNavm(this.buffer, chunk.offset, chunk.byteLength));
+            }
+            else if (chunk.code === CHUNK_ENTS) {
+                this.handlers.onEntities?.(readEnts(this.buffer, chunk.offset, chunk.byteLength));
+            }
             else if (chunk.code === CHUNK_LITE) {
                 this.handlers.onLights?.(readLights(this.buffer, chunk.offset, chunk.byteLength));
             }

package/dist/drftWrite.d.ts

@@ -19,8 +19,11 @@ 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 { DrftLightVolume } from './drftLightVolume.ts';
+import type { DrftRegion } from './drftRegions.ts';
 import type { DrftInstanceGroup } from './drftInstances.ts';
 import type { DrftLight } from './drftLights.ts';
+import type { DrftAssembly } from './drftAssembly.ts';
 /** An image to embed, already compressed, with what its own header said about it. */
 export interface DrftTextureSource {
     /**
@@ -39,7 +42,18 @@ export interface DrftTextureSource {
 /** What a caller hands over to be baked. */
 export interface DrftSource {
     readonly head?: Partial<DrftHead>;
-    readonly meshes: readonly MeshData[];
+    /**
+     * The meshes by ordinal. An assembly — painted copies of kit pieces — stands in a slot like any
+     * mesh and is written as one required `MSHC` chunk; see `drftAssembly.ts`.
+     */
+    readonly meshes: readonly (MeshData | DrftAssembly)[];
+    /**
+     * The ordinals of the meshes that are kit pieces, ascending: drawn only as copies inside the
+     * assemblies, never on their own. One required `KITS` chunk, ahead of the geometry. A piece
+     * comes before every assembly that copies it, is never an assembly itself, and is neither placed
+     * by `INST` nor named by a region.
+     */
+    readonly kit?: readonly number[];
     /**
      * One material per mesh, by ordinal, or absent for an asset that names none.
      *
@@ -113,6 +127,19 @@ export interface DrftSource {
      * a group names holds one copy; see `drftInstances.ts`.
      */
     readonly instances?: readonly DrftInstanceGroup[];
+    /**
+     * The regions of a streamed world: one required `REGN` chunk each, written just ahead of the
+     * meshes it introduces. The meshes no region names come first, then each region's new meshes in
+     * region order — the writer refuses any other order rather than renumbering what the regions and
+     * the materials point at. See `drftRegions.ts`.
+     */
+    readonly regions?: readonly DrftRegion[];
+    /**
+     * A world's fixed lights summed offline into one dense volume: one optional `LVOL` chunk, after
+     * the geometry, since the world draws lit by its exact lights until it lands. See
+     * `drftLightVolume.ts`.
+     */
+    readonly lightVolume?: DrftLightVolume;
     /** The lights the scene was authored with: one `LITE` chunk, optional. See `drftLights.ts`. */
     readonly lights?: readonly DrftLight[];
     /**
@@ -156,6 +183,13 @@ export interface DrftSource {
      * carry geometry with no scene at all — which is every baked model this format has ever held.
      */
     readonly entities?: EntsScene;
+    /**
+     * The textures ahead of the geometry rather than after it. A model wants its outline before its
+     * pictures, so a viewer sees a shape early; a world whose every region wears the same texture
+     * arrays wants the pictures before its first region, or that region waits for the file's end.
+     * What it costs a model that asks: its first part arrives later by the size of its pictures.
+     */
+    readonly texturesFirst?: boolean;
 }
 /**
  * Bake a `.drft` into one `ArrayBuffer`.