@driftengine/drft 4.5.0 → 4.6.0

package/dist/drftFormat.js

@@ -20,7 +20,7 @@ export 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 const DRFT_VERSION_MINOR = 19;
+export const DRFT_VERSION_MINOR = 23;
 /** Bytes before the chunk table. */
 export const HEADER_BYTES = 32;
 /** Bytes per chunk table entry. */
@@ -242,6 +242,32 @@ export const CHUNK_INST = fourCC('INST');
  * See `drftQuantised.ts`. Added in 1.18.
  */
 export const CHUNK_MSHQ = fourCC('MSHQ');
+/**
+ * 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 const CHUNK_REGN = fourCC('REGN');
+/**
+ * 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 const CHUNK_LVOL = fourCC('LVOL');
+/**
+ * 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 const CHUNK_KITS = fourCC('KITS');
+/**
+ * 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 const CHUNK_MSHC = fourCC('MSHC');
+/** Whether a chunk is a mesh in the ordinal sequence: plain, quantised or assembled. */
+export function isMeshChunk(code) {
+    return code === CHUNK_MESH || code === CHUNK_MSHQ || code === CHUNK_MSHC;
+}
 /** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
 export const SPLAT_BLOCK_PREFIX = 40;
 /**
@@ -275,6 +301,10 @@ export const KNOWN_CHUNKS = new Set([
     CHUNK_ENTS,
     CHUNK_INST,
     CHUNK_MSHQ,
+    CHUNK_REGN,
+    CHUNK_LVOL,
+    CHUNK_KITS,
+    CHUNK_MSHC,
 ]);
 /** Chunk flags. */
 export const CHUNK_REQUIRED = 1 << 0;
@@ -358,6 +388,24 @@ export const ATTR_TANGENT = 1 << 6;
 export const ATTR_JOINTS = 1 << 7;
 /** How much each of `ATTR_JOINTS`' four influences moves the vertex. See it for the whole story. */
 export const ATTR_WEIGHTS = 1 << 8;
+/**
+ * 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 const ATTR_LAYERS = 1 << 9;
+/**
+ * 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 const ATTR_CHANNEL = 1 << 10;
 /** Everything this version defines, so a reader can spot bits from a later writer. */
 export const ATTR_KNOWN = ATTR_SPECULAR |
     ATTR_UVS |
@@ -367,7 +415,9 @@ export const ATTR_KNOWN = ATTR_SPECULAR |
     ATTR_RELIEF |
     ATTR_TANGENT |
     ATTR_JOINTS |
-    ATTR_WEIGHTS;
+    ATTR_WEIGHTS |
+    ATTR_LAYERS |
+    ATTR_CHANNEL;
 /**
  * How a `TEXS` payload is encoded.
  *

package/dist/drftLightVolume.d.ts

@@ -0,0 +1,12 @@
+/** The same shape as core's `DenseLightVolume`, so a read volume goes straight to the renderer. */
+export interface DrftLightVolume {
+    readonly origin: readonly [number, number, number];
+    readonly spacing: number;
+    readonly dims: readonly [number, number, number];
+    /** Four floats a sample, x fastest: the colour, then 1 for a sample and 0 inside solid. */
+    readonly light: Float32Array;
+    /** Four floats a sample: the direction light arrives from, then 0. */
+    readonly direction: Float32Array;
+}
+export declare function buildLightVolume(volume: DrftLightVolume): Uint8Array;
+export declare function readLightVolume(buffer: ArrayBufferLike, offset: number, byteLength: number): DrftLightVolume;

package/dist/drftLightVolume.js

@@ -0,0 +1,172 @@
+/**
+ * `LVOL`: a world's fixed lights summed into one dense volume offline, as the renderer reads it.
+ *
+ * **Optional, because the file is whole without it.** A reader that skips it draws the world lit by
+ * the lights it shades exactly and loses the glow of every light past them — less, not wrong.
+ *
+ * **Runs, because most of a city's volume is dark.** Lamps reach thirty metres and the volume stands
+ * a hundred and more, so the samples above the light are nothing, and a sample inside a building is
+ * nothing of another kind: it is not a sample at all, which the shader's filtering must be told.
+ * So samples are written in order as runs of three kinds — dark air, solid, and literal — and only a
+ * literal run carries values, eight half floats a sample: the colour and whether it is a sample,
+ * then the direction light arrives from.
+ *
+ * Layout, little-endian:
+ * - f32 × 3 origin, f32 spacing, u32 × 3 samples on each axis;
+ * - runs until every sample is covered, each a u32 whose top two bits are the kind (0 dark air,
+ *   1 solid, 2 literal) and whose low thirty are the count, a literal followed by its halves.
+ */
+import { DrftError, align } from './drftFormat.js';
+const DARK = 0;
+const SOLID = 1;
+const LITERAL = 2;
+const COUNT_MASK = 0x3fffffff;
+function kindOf(volume, sample) {
+    const at = sample * 4;
+    const light = volume.light;
+    const lit = light[at] !== 0 ||
+        light[at + 1] !== 0 ||
+        light[at + 2] !== 0 ||
+        volume.direction[at] !== 0 ||
+        volume.direction[at + 1] !== 0 ||
+        volume.direction[at + 2] !== 0;
+    if (lit)
+        return LITERAL;
+    if (light[at + 3] === 1)
+        return DARK;
+    if (light[at + 3] === 0)
+        return SOLID;
+    return LITERAL;
+}
+export function buildLightVolume(volume) {
+    const count = volume.dims[0] * volume.dims[1] * volume.dims[2];
+    if (volume.light.length !== count * 4 || volume.direction.length !== count * 4) {
+        throw new DrftError(`a light volume of ${count} samples needs ${count * 4} floats a channel`);
+    }
+    if (!(volume.spacing > 0))
+        throw new DrftError(`a light volume's spacing is ${volume.spacing}`);
+    /* Measured first, so the payload is allocated once. */
+    let bytes = 28;
+    for (let sample = 0; sample < count;) {
+        const kind = kindOf(volume, sample);
+        let end = sample + 1;
+        while (end < count && end - sample < COUNT_MASK && kindOf(volume, end) === kind)
+            end++;
+        bytes += 4 + (kind === LITERAL ? (end - sample) * 16 : 0);
+        sample = end;
+    }
+    const out = new Uint8Array(align(bytes));
+    const view = new DataView(out.buffer);
+    for (let i = 0; i < 3; i++)
+        view.setFloat32(i * 4, volume.origin[i], true);
+    view.setFloat32(12, volume.spacing, true);
+    for (let i = 0; i < 3; i++)
+        view.setUint32(16 + i * 4, volume.dims[i], true);
+    let at = 28;
+    for (let sample = 0; sample < count;) {
+        const kind = kindOf(volume, sample);
+        let end = sample + 1;
+        while (end < count && end - sample < COUNT_MASK && kindOf(volume, end) === kind)
+            end++;
+        view.setUint32(at, ((kind << 30) | (end - sample)) >>> 0, true);
+        at += 4;
+        if (kind === LITERAL) {
+            for (let s = sample; s < end; s++) {
+                for (let c = 0; c < 4; c++) {
+                    view.setUint16(at, halfOf(volume.light[s * 4 + c]), true);
+                    view.setUint16(at + 8, halfOf(volume.direction[s * 4 + c]), true);
+                    at += 2;
+                }
+                at += 8;
+            }
+        }
+        sample = end;
+    }
+    return out;
+}
+export function readLightVolume(buffer, offset, byteLength) {
+    if (byteLength < 28)
+        throw new DrftError('LVOL ends inside its header');
+    const view = new DataView(buffer, offset, byteLength);
+    const origin = [
+        view.getFloat32(0, true),
+        view.getFloat32(4, true),
+        view.getFloat32(8, true),
+    ];
+    const spacing = view.getFloat32(12, true);
+    const dims = [
+        view.getUint32(16, true),
+        view.getUint32(20, true),
+        view.getUint32(24, true),
+    ];
+    const count = dims[0] * dims[1] * dims[2];
+    if (!(spacing > 0) || count === 0) {
+        throw new DrftError(`LVOL has spacing ${spacing} and ${dims.join(' x ')} samples`);
+    }
+    const light = new Float32Array(count * 4);
+    const direction = new Float32Array(count * 4);
+    let at = 28;
+    let sample = 0;
+    while (sample < count) {
+        if (at + 4 > byteLength)
+            throw new DrftError(`LVOL ends at sample ${sample} of ${count}`);
+        const word = view.getUint32(at, true);
+        at += 4;
+        const kind = word >>> 30;
+        const run = word & COUNT_MASK;
+        if (run === 0 || sample + run > count || kind > LITERAL) {
+            throw new DrftError(`LVOL has a run of ${run} of kind ${kind} at sample ${sample}`);
+        }
+        if (kind === DARK) {
+            for (let s = sample; s < sample + run; s++)
+                light[s * 4 + 3] = 1;
+        }
+        else if (kind === LITERAL) {
+            if (at + run * 16 > byteLength)
+                throw new DrftError(`LVOL ends inside sample ${sample}`);
+            for (let s = sample; s < sample + run; s++) {
+                for (let c = 0; c < 4; c++) {
+                    light[s * 4 + c] = floatOf(view.getUint16(at, true));
+                    direction[s * 4 + c] = floatOf(view.getUint16(at + 8, true));
+                    at += 2;
+                }
+                at += 8;
+            }
+        }
+        sample += run;
+    }
+    return { origin, spacing, dims, light, direction };
+}
+const scratchFloat = new Float32Array(1);
+const scratchWord = new Uint32Array(scratchFloat.buffer);
+/** A float as IEEE half-precision bits, rounded to nearest, overflow to infinity. */
+function halfOf(value) {
+    scratchFloat[0] = value;
+    const word = scratchWord[0];
+    const sign = (word >>> 16) & 0x8000;
+    const exponent = ((word >>> 23) & 0xff) - 127 + 15;
+    const mantissa = word & 0x7fffff;
+    if (exponent >= 31)
+        return sign | 0x7c00 | (((word >>> 23) & 0xff) === 0xff && mantissa ? 0x200 : 0);
+    if (exponent <= 0) {
+        if (exponent < -10)
+            return sign;
+        const full = mantissa | 0x800000;
+        const shift = 14 - exponent;
+        const rounded = (full + (1 << (shift - 1))) >> shift;
+        return sign | rounded;
+    }
+    const rounded = (exponent << 10) + ((mantissa + 0x1000) >> 13);
+    return sign | Math.min(rounded, 0x7c00);
+}
+/** IEEE half-precision bits as a float. */
+function floatOf(bits) {
+    const sign = bits & 0x8000 ? -1 : 1;
+    const exponent = (bits >> 10) & 0x1f;
+    const mantissa = bits & 0x3ff;
+    if (exponent === 0)
+        return sign * mantissa * 2 ** -24;
+    if (exponent === 31)
+        return mantissa ? Number.NaN : sign * Number.POSITIVE_INFINITY;
+    return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}

package/dist/drftQuantised.js

@@ -23,7 +23,7 @@
  * 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';
+import { ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_JOINTS, ATTR_RELIEF, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_TANGENT, ATTR_UVS, ATTR_WEIGHTS, ATTR_LAYERS, ATTR_CHANNEL, DrftError, align, } from './drftFormat.js';
 const RAW = 0;
 const CONSTANT = 1;
 const RANGE16 = 2;
@@ -46,6 +46,9 @@ const ORDER = [
     { 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' },
+    /* Whole numbers naming an image, so exact: a layer quantised onto its neighbour is another picture. */
+    { name: 'layers', width: 1, bit: ATTR_LAYERS, kind: 'exact' },
+    { name: 'channel', width: 4, bit: ATTR_CHANNEL, kind: 'value' },
 ];
 /** A growing little-endian byte list, for the writer: offline, so it may allocate. */
 class Bytes {

package/dist/drftRead.d.ts

@@ -24,6 +24,9 @@ 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 { DrftAssembly } from './drftAssembly.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';
 /** An embedded image, still compressed. Decoding is the consumer's, through `createImageBitmap`. */
@@ -156,6 +159,24 @@ export interface DrftAsset {
      * ```
      */
     readonly colliders: readonly Float32Array[];
+    /**
+     * The regions of a streamed world, in the order they were written, or empty. `REGN`, defined at
+     * 1.21: each names the meshes it draws at every level, its props, occluders and collision.
+     */
+    readonly regions: readonly DrftRegion[];
+    /** A world's summed lights, or null for a file carrying no `LVOL`. Defined at 1.22. */
+    readonly lightVolume: DrftLightVolume | null;
+    /**
+     * The meshes that are kit pieces, ascending, or empty. `KITS`, defined at 1.23. A piece is in
+     * `meshes` like any other, and is drawn only as copies inside the assemblies.
+     */
+    readonly kit: readonly number[];
+    /**
+     * Each `MSHC` mesh as the file carried it, by ordinal, or empty. Its slot in `meshes` holds it
+     * expanded — which for a world built from a kit is most of a gigabyte, so a consumer of such a
+     * file streams it (`DrftStream.onAssembly`) rather than reading it whole.
+     */
+    readonly assemblies: ReadonlyMap<number, DrftAssembly>;
     /** Optional chunks this reader did not understand, in file order. Diagnostics only. */
     readonly skipped: readonly string[];
     readonly versionMajor: number;
@@ -163,7 +184,6 @@ export interface DrftAsset {
 }
 export declare function readHead(buffer: ArrayBuffer, chunk: DrftChunk): DrftHead;
 export declare function readMesh(buffer: ArrayBuffer, chunk: DrftChunk): MeshData;
-/** Decode a `.drft` from a buffer. Throws `DrftError` on anything it cannot read. */
 export declare function readDrft(buffer: ArrayBuffer): DrftAsset;
 /**
  * One `SPLT` block, viewed in place.

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_INST, CHUNK_LITE, CHUNK_MSHQ, 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, ATTR_LAYERS, ATTR_CHANNEL, 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_REGN, CHUNK_LVOL, CHUNK_LITE, CHUNK_MSHQ, CHUNK_KITS, CHUNK_MSHC, 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,10 @@ import { readNavm } from './navm.js';
 import { readNnet } from './nnet.js';
 import { readNgrf } from './ngrf.js';
 import { readColliders } from './drftColliders.js';
+import { RegionLedger, readRegion } from './drftRegions.js';
+import { expandAssembly } from './assemble.js';
+import { checkCopies, readAssembly, readKit } from './drftAssembly.js';
+import { readLightVolume } from './drftLightVolume.js';
 import { readInstances } from './drftInstances.js';
 import { readLights } from './drftLights.js';
 import { decodeQuantisedMesh } from './drftQuantised.js';
@@ -96,6 +100,10 @@ export function readMesh(buffer, chunk) {
        writer set only one bit is rejected rather than half-skinned. See ATTR_JOINTS. */
     const joints = (attributes & ATTR_JOINTS) !== 0 ? floats(vertices * 4, 'joints') : undefined;
     const weights = (attributes & ATTR_WEIGHTS) !== 0 ? floats(vertices * 4, 'weights') : undefined;
+    /* Texture-array layers, 1.20, one float a vertex and last. See ATTR_LAYERS. */
+    const layers = (attributes & ATTR_LAYERS) !== 0 ? floats(vertices, 'layers') : undefined;
+    /* Sway, sky and opacity, 1.23, four floats a vertex and last. See ATTR_CHANNEL. */
+    const channel = (attributes & ATTR_CHANNEL) !== 0 ? floats(vertices * 4, 'channel') : undefined;
     const indexBytes = indexCount * 4;
     if (at + indexBytes > limit) {
         throw new DrftError(`indices need ${indexBytes} bytes but only ${limit - at} remain at ${at}`);
@@ -116,6 +124,8 @@ export function readMesh(buffer, chunk) {
         ...(tangents === undefined ? {} : { tangents }),
         ...(joints === undefined ? {} : { joints }),
         ...(weights === undefined ? {} : { weights }),
+        ...(layers === undefined ? {} : { layers }),
+        ...(channel === undefined ? {} : { channel }),
     };
     /*
      * Checked again on the way in, even though the writer checked on the way out. The file
@@ -126,6 +136,14 @@ export function readMesh(buffer, chunk) {
     return mesh;
 }
 /** Decode a `.drft` from a buffer. Throws `DrftError` on anything it cannot read. */
+/** A slot held for an assembly until its pieces are in hand. Never returned. */
+const EMPTY_MESH = {
+    positions: new Float32Array(0),
+    normals: new Float32Array(0),
+    colors: new Float32Array(0),
+    emissive: new Float32Array(0),
+    indices: new Uint32Array(0),
+};
 export function readDrft(buffer) {
     if (buffer.byteLength < HEADER_BYTES) {
         throw new DrftError(`a file is at least ${HEADER_BYTES} bytes, got ${buffer.byteLength}`);
@@ -176,6 +194,10 @@ export function readDrft(buffer) {
     let colliders = [];
     /* Read once every mesh is counted, because a group is checked against the mesh count. */
     let instanceChunk = null;
+    const regionChunks = [];
+    let lightVolume = null;
+    let kitChunk = null;
+    const assemblies = new Map();
     let lights = [];
     const skipped = [];
     let head = null;
@@ -215,6 +237,13 @@ export function readDrft(buffer) {
         /* 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));
+        else if (chunk.code === CHUNK_MSHC) {
+            /* Its slot held, and filled once every piece is in hand. */
+            assemblies.set(meshes.length, readAssembly(buffer, chunk.offset, chunk.byteLength));
+            meshes.push(EMPTY_MESH);
+        }
+        else if (chunk.code === CHUNK_KITS)
+            kitChunk = chunk;
         /* 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) });
@@ -238,6 +267,11 @@ export function readDrft(buffer) {
             nodes = readNodes(buffer, chunk.offset, chunk.byteLength);
         else if (chunk.code === CHUNK_INST)
             instanceChunk = chunk;
+        /* Read once every mesh is counted, since a region names meshes that follow it. */
+        else if (chunk.code === CHUNK_REGN)
+            regionChunks.push(chunk);
+        else if (chunk.code === CHUNK_LVOL)
+            lightVolume = readLightVolume(buffer, chunk.offset, chunk.byteLength);
         else if (chunk.code === CHUNK_LITE)
             lights = readLights(buffer, chunk.offset, chunk.byteLength);
         else if (chunk.code === CHUNK_SKIN)
@@ -319,6 +353,37 @@ export function readDrft(buffer) {
             morphTargetCount: morph.targetCount,
         };
     }
+    const kit = kitChunk === null ? [] : readKit(buffer, kitChunk.offset, kitChunk.byteLength, meshes.length);
+    const pieces = new Set(kit);
+    for (const o of kit) {
+        if (assemblies.has(o))
+            throw new DrftError(`mesh ${o} is a kit piece and an assembly`);
+    }
+    for (const [ordinal, assembly] of assemblies) {
+        checkCopies(assembly, ordinal, pieces, (o) => meshes[o]);
+        meshes[ordinal] = expandAssembly(assembly, (o) => meshes[o]);
+    }
+    const ledger = new RegionLedger();
+    const regions = regionChunks.map((chunk) => {
+        const region = readRegion(buffer, chunk.offset, chunk.byteLength, meshes.length);
+        ledger.admit(region);
+        return region;
+    });
+    const instances = instanceChunk === null
+        ? []
+        : readInstances(buffer, instanceChunk.offset, instanceChunk.byteLength, meshes.length);
+    /* A mesh placed by `INST` across the whole file and also a region's would be drawn twice. */
+    for (const group of instances) {
+        if (ledger.names(group.mesh)) {
+            throw new DrftError(`mesh ${group.mesh} is placed by INST and is also a region's`);
+        }
+        if (pieces.has(group.mesh))
+            throw new DrftError(`mesh ${group.mesh} is a kit piece and is placed by INST`);
+    }
+    for (const o of kit) {
+        if (ledger.names(o))
+            throw new DrftError(`mesh ${o} is a kit piece and a region's`);
+    }
     /* By the ordinal the file gave them rather than by where they sat, coarsest first. */
     levels.sort((a, b) => a.level - b.level);
     const lods = levels.map((entry) => entry.mesh);
@@ -328,9 +393,7 @@ export function readDrft(buffer) {
         lods,
         levels: discreteLevels,
         nodes,
-        instances: instanceChunk === null
-            ? []
-            : readInstances(buffer, instanceChunk.offset, instanceChunk.byteLength, meshes.length),
+        instances,
         lights,
         skins,
         clips,
@@ -341,6 +404,10 @@ export function readDrft(buffer) {
         networks: nnet?.networks ?? [],
         graphs,
         colliders,
+        regions,
+        lightVolume,
+        kit,
+        assemblies,
         dtex,
         navigation,
         entities,

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[][];