@driftengine/drft 4.5.0 → 4.6.0

package/src/drftStream.ts

@@ -19,9 +19,17 @@ import {
   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.ts';
@@ -39,6 +47,17 @@ import { readSdfv } from './sdfv.ts';
 import type { DrftSdfvEntry } from './sdfv.ts';
 import type { DrftLight } from './drftLights.ts';
 import { decodeQuantisedMesh } from './drftQuantised.ts';
+import { readColliders } from './drftColliders.ts';
+import { expandAssembly } from './assemble.ts';
+import type { PieceLookup } from './assemble.ts';
+import { checkCopies, readAssembly, readKit } from './drftAssembly.ts';
+import type { DrftAssembly } from './drftAssembly.ts';
+import { RegionLedger, readRegion } from './drftRegions.ts';
+import { readLightVolume } from './drftLightVolume.ts';
+import type { DrftLightVolume } from './drftLightVolume.ts';
+import type { DrftRegion } from './drftRegions.ts';
+import { type NavPolyMesh, readNavm } from './navm.ts';
+import { type EntsScene, readEnts } from './ents.ts';
 
 /**
  * What the file says is coming, known from the first few kilobytes.
@@ -93,8 +112,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.
    *
@@ -117,6 +153,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;
   /**
@@ -136,6 +179,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;
 }
@@ -171,10 +226,20 @@ export class DrftStream {
   private preludeBytes = 0;
   private received = 0;
   private chunks: DrftChunk[] = [];
+  /** What the regions so far claim, so a second claim on a mesh is refused as `readDrft` refuses it. */
+  private readonly regions = new RegionLedger();
   /** How many table entries have been reported complete, in table order. */
   private settled = 0;
   private meshOrdinal = 0;
   private textureOrdinal = 0;
+  /** The kit's pieces once `KITS` lands, and each piece as it arrives. */
+  private kit: Set<number> | null = null;
+  private readonly pieces = new Map<number, MeshData>();
+  private readonly pieceAt: PieceLookup = (o) => {
+    const piece = this.pieces.get(o);
+    if (piece === undefined) throw new DrftError(`kit piece ${o} has not arrived`);
+    return piece;
+  };
   private head: DrftHead | null = null;
   private meshCount = 0;
   private materialCount = 0;
@@ -350,7 +415,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) textureBytes += chunk.byteLength;
@@ -371,7 +436,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,
@@ -400,7 +465,36 @@ 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
            arrived — which for a sequential fetch is the same order, and for a range-fetching
@@ -417,12 +511,23 @@ export class DrftStream {
       } else if (chunk.code === CHUNK_NODE) {
         this.handlers.onNodes?.(readNodes(this.buffer, chunk.offset, chunk.byteLength));
       } else if (chunk.code === CHUNK_INST) {
-        const meshes = this.chunks.filter(
-          (c) => c.code === CHUNK_MESH || c.code === CHUNK_MSHQ,
-        ).length;
+        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));
       } else if (chunk.code === CHUNK_SDFV) {

package/src/drftWrite.ts

@@ -25,6 +25,8 @@ import {
   ATTR_SPECULAR,
   ATTR_UVS,
   ATTR_WEIGHTS,
+  ATTR_LAYERS,
+  ATTR_CHANNEL,
   CHUNK_ENTRY_BYTES,
   CHUNK_HEAD,
   CHUNK_ANIM,
@@ -36,8 +38,12 @@ import {
   CHUNK_MORP,
   CHUNK_NODE,
   CHUNK_INST,
+  CHUNK_REGN,
+  CHUNK_LVOL,
   CHUNK_LITE,
   CHUNK_MSHQ,
+  CHUNK_KITS,
+  CHUNK_MSHC,
   CHUNK_SKIN,
   CHUNK_SPLT,
   SPLAT_BLOCK_PREFIX,
@@ -70,10 +76,32 @@ import { type NavPolyMesh, buildNavm } from './navm.ts';
 import { type DrftGraph, buildNgrf } from './ngrf.ts';
 import { buildColliders } from './drftColliders.ts';
 import { buildInstances } from './drftInstances.ts';
+import { buildRegion, planRegions } from './drftRegions.ts';
+import { buildLightVolume } from './drftLightVolume.ts';
+import type { DrftLightVolume } from './drftLightVolume.ts';
+import type { DrftRegion } from './drftRegions.ts';
+
+/** Whether a region names a mesh, as a level or a prop. */
+function regionNames(region: DrftRegion, mesh: number): boolean {
+  return (
+    region.levels.some((level) => level.meshes.includes(mesh)) ||
+    region.instances.some((group) => group.mesh === mesh)
+  );
+}
 import type { DrftInstanceGroup } from './drftInstances.ts';
 import { buildLights } from './drftLights.ts';
 import type { DrftLight } from './drftLights.ts';
 import { encodeQuantisedMesh } from './drftQuantised.ts';
+import { assemblyBounds } from './assemble.ts';
+import {
+  buildAssembly,
+  buildKit,
+  checkAssembly,
+  checkCopies,
+  checkKit,
+  isAssembly,
+} from './drftAssembly.ts';
+import type { DrftAssembly } from './drftAssembly.ts';
 
 /** An image to embed, already compressed, with what its own header said about it. */
 export interface DrftTextureSource {
@@ -94,7 +122,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.
    *
@@ -168,6 +207,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[];
   /**
@@ -211,6 +263,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;
 }
 
 /**
@@ -315,8 +374,9 @@ function encodeString(value: string): Uint8Array {
 
 function buildHead(
   head: Partial<DrftHead> | undefined,
-  meshes: readonly MeshData[],
+  meshes: readonly (MeshData | DrftAssembly)[],
   instances: readonly DrftInstanceGroup[] = [],
+  kit: ReadonlySet<number> = new Set(),
 ): PendingChunk {
   /*
    * Bounds are computed rather than taken on trust. A caller that gets them wrong would
@@ -331,8 +391,23 @@ function buildHead(
   let maxZ = -Infinity;
   const placed = new Map<number, Float32Array>();
   for (const group of instances) placed.set(group.mesh, group.transforms);
+  const pieceAt = (o: number): MeshData => meshes[o] as MeshData;
   for (let m = 0; m < meshes.length; m++) {
-    const mesh = meshes[m] as MeshData;
+    /* A kit piece is drawn only where it is copied, and its copies are counted with them. */
+    if (kit.has(m)) continue;
+    const slot = meshes[m] as MeshData | DrftAssembly;
+    if (isAssembly(slot)) {
+      const b = assemblyBounds(slot, pieceAt);
+      if (!((b[0] as number) <= (b[3] as number))) continue;
+      minX = Math.min(minX, b[0] as number);
+      minY = Math.min(minY, b[1] as number);
+      minZ = Math.min(minZ, b[2] as number);
+      maxX = Math.max(maxX, b[3] as number);
+      maxY = Math.max(maxY, b[4] as number);
+      maxZ = Math.max(maxZ, b[5] as number);
+      continue;
+    }
+    const mesh = slot;
     const transforms = placed.get(m);
     if (transforms === undefined) {
       for (let at = 0; at + 2 < mesh.positions.length; at += 3) {
@@ -446,6 +521,8 @@ function buildMesh(mesh: MeshData, code = CHUNK_MESH, flags = CHUNK_REQUIRED): P
      these two bits are always set together and the reader may rely on it. */
   if (mesh.joints !== undefined) attributes |= ATTR_JOINTS;
   if (mesh.weights !== undefined) attributes |= ATTR_WEIGHTS;
+  if (mesh.layers !== undefined) attributes |= ATTR_LAYERS;
+  if (mesh.channel !== undefined) attributes |= ATTR_CHANNEL;
 
   /* Order is frozen: mandatory arrays, then optional ones by ascending bit. */
   const arrays: (Float32Array | Uint32Array)[] = [
@@ -465,6 +542,10 @@ function buildMesh(mesh: MeshData, code = CHUNK_MESH, flags = CHUNK_REQUIRED): P
      container validated this pair for four minor versions while writing neither of them. */
   if (mesh.joints !== undefined) arrays.push(mesh.joints);
   if (mesh.weights !== undefined) arrays.push(mesh.weights);
+  /* Newest of all, 1.20, so last. See ATTR_LAYERS. */
+  if (mesh.layers !== undefined) arrays.push(mesh.layers);
+  /* And newer still, 1.23. See ATTR_CHANNEL. */
+  if (mesh.channel !== undefined) arrays.push(mesh.channel);
   arrays.push(mesh.indices);
 
   const PREFIX = 16;
@@ -628,7 +709,30 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
    * same asset less its textures rather than a refusal. Moving it earlier in the file changes
    * nothing about that, because a chunk is found through the table rather than by position.
    */
-  const chunks: PendingChunk[] = [buildHead(source.head, source.meshes, source.instances)];
+  const kit = new Set(source.kit ?? []);
+  checkKit(source.kit ?? [], source.meshes.length);
+  source.meshes.forEach((slot, ordinal) => {
+    if (!isAssembly(slot)) return;
+    checkAssembly(slot, `mesh ${ordinal}`);
+    checkCopies(slot, ordinal, kit, (o) => {
+      const piece = source.meshes[o];
+      return piece === undefined || isAssembly(piece) ? undefined : piece;
+    });
+  });
+  for (const o of kit) {
+    if (isAssembly(source.meshes[o] as MeshData | DrftAssembly)) {
+      throw new DrftError(`mesh ${o} is a kit piece and an assembly; a piece is vertices`);
+    }
+    if ((source.instances ?? []).some((g) => g.mesh === o)) {
+      throw new DrftError(`mesh ${o} is a kit piece and is placed by INST`);
+    }
+    if ((source.regions ?? []).some((r) => regionNames(r, o))) {
+      throw new DrftError(
+        `mesh ${o} is a kit piece and a region's; a piece is drawn only as copies`,
+      );
+    }
+  }
+  const chunks: PendingChunk[] = [buildHead(source.head, source.meshes, source.instances, kit)];
   /*
    * The outline first, ahead of even the paint. It is the one thing that puts a recognisable
    * whole object on screen, it is a few hundred kilobytes against tens of megabytes, and the
@@ -677,6 +781,11 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
       bytes: buildInstances(source.instances as readonly DrftInstanceGroup[]),
     });
   }
+  /* The kit ahead of the geometry, for the placements' reason: a streaming consumer must know a
+     mesh is a piece before it lands, or it has already drawn it at the origin. */
+  if (kit.size > 0) {
+    chunks.push({ code: CHUNK_KITS, flags: CHUNK_REQUIRED, bytes: buildKit(source.kit ?? []) });
+  }
   /* Small, and ahead of the geometry, so a streaming consumer can place its lamps early. */
   if ((source.lights?.length ?? 0) > 0) {
     chunks.push({ code: CHUNK_LITE, flags: 0, bytes: buildLights(source.lights ?? []) });
@@ -707,7 +816,22 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
   if (source.entities !== undefined) {
     chunks.push({ code: CHUNK_ENTS, flags: 0, bytes: buildEnts(source.entities) });
   }
+  if (source.texturesFirst === true) {
+    for (const texture of source.textures ?? []) chunks.push(buildTexture(texture));
+  }
+  const regionsBefore = planRegions(source.regions ?? [], source.meshes.length, (m) => {
+    const mesh = source.meshes[m];
+    return mesh !== undefined && isAssembly(mesh) ? mesh.pieces : undefined;
+  });
+  for (const group of source.instances ?? []) {
+    if ((source.regions ?? []).some((r) => regionNames(r, group.mesh))) {
+      throw new DrftError(`mesh ${group.mesh} is placed by INST and is also a region's`);
+    }
+  }
   source.meshes.forEach((mesh, ordinal) => {
+    for (const region of regionsBefore[ordinal] ?? []) {
+      chunks.push({ code: CHUNK_REGN, flags: CHUNK_REQUIRED, bytes: buildRegion(region) });
+    }
     /*
      * **Its deltas immediately before it, not after.** A streaming consumer uploads a mesh the
      * moment its chunk lands, so deltas arriving afterwards are deltas for geometry already on the
@@ -715,6 +839,10 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
      * them in hand when it builds. The mesh ordinal in the payload still does the pairing, so a
      * reader meeting them in another order is unaffected.
      */
+    if (isAssembly(mesh)) {
+      chunks.push({ code: CHUNK_MSHC, flags: CHUNK_REQUIRED, bytes: buildAssembly(mesh) });
+      return;
+    }
     if (mesh.morphTargets !== undefined && mesh.morphTargetCount !== undefined) {
       chunks.push({
         code: CHUNK_MORP,
@@ -733,7 +861,15 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
       chunks.push(buildMesh(mesh));
     }
   });
-  for (const texture of source.textures ?? []) chunks.push(buildTexture(texture));
+  for (const region of regionsBefore[source.meshes.length] ?? []) {
+    chunks.push({ code: CHUNK_REGN, flags: CHUNK_REQUIRED, bytes: buildRegion(region) });
+  }
+  if (source.lightVolume !== undefined) {
+    chunks.push({ code: CHUNK_LVOL, flags: 0, bytes: buildLightVolume(source.lightVolume) });
+  }
+  if (source.texturesFirst !== true) {
+    for (const texture of source.textures ?? []) chunks.push(buildTexture(texture));
+  }
   /* One `SUBS` for the file, and only where something was labelled — an empty chunk would cost
      sixteen bytes to say nothing, and rule 2 already covers its absence. */
   if ((source.substances?.length ?? 0) > 0) {

package/src/index.ts

@@ -70,6 +70,46 @@ export { buildInstances, readInstances } from './drftInstances.ts';
 export { buildLights, readLights } from './drftLights.ts';
 export type { DrftLight, DrftLightKind } from './drftLights.ts';
 export type { DrftInstanceGroup } from './drftInstances.ts';
+export {
+  REGION_MAX_LEVELS,
+  RegionLedger,
+  buildRegion,
+  planRegions,
+  readRegion,
+} from './drftRegions.ts';
+/* A mesh carried as painted copies of kit pieces, expanded where it is needed. The attribute bits
+   are a MESH's, which is what an assembly declares its optional arrays with. */
+export {
+  ATTR_CHANNEL,
+  ATTR_EMISSIVE_COLOR,
+  ATTR_GRAIN,
+  ATTR_LAYERS,
+  ATTR_RELIEF,
+  ATTR_ROUGHNESS,
+  ATTR_SPECULAR,
+  ATTR_TANGENT,
+  ATTR_UVS,
+} from './drftFormat.ts';
+export {
+  ASSEMBLY_ATTRIBUTES,
+  COPY_MATRIX_FLOATS,
+  COPY_UV_FLOATS,
+  SURFACE,
+  SURFACE_FLOATS,
+  buildAssembly,
+  buildKit,
+  checkAssembly,
+  checkCopies,
+  isAssembly,
+  readAssembly,
+  readKit,
+} from './drftAssembly.ts';
+export type { DrftAssembly } from './drftAssembly.ts';
+export { assemblyBounds, expandAssembly } from './assemble.ts';
+export type { PieceLookup } from './assemble.ts';
+export type { DrftRegion, DrftRegionCollision, DrftRegionLevel } from './drftRegions.ts';
+export { buildLightVolume, readLightVolume } from './drftLightVolume.ts';
+export type { DrftLightVolume } from './drftLightVolume.ts';
 /*
  * **`DTEX`: a material as a decode program over a latent, rather than as pictures.** The chunk
  * carries no semantics — this package is the container and does not know what a channel means —

package/src/meshData.ts

@@ -107,6 +107,25 @@ export interface MeshData {
    * separates asphalt from plaster, and the pass states it: see `Renderer.setSurfaceRelief`.
    */
   relief?: Float32Array;
+  /**
+   * Which image of a texture array each vertex's face wears: one whole number a vertex, 0 the first
+   * layer. Absent means layer 0, which is the only layer a plain texture has.
+   *
+   * **What it is for is a merged mesh wearing many images in one draw.** A block of forty buildings
+   * with forty facades is forty materials — forty draws, forty material changes — when each image
+   * is its own texture; with the facades as the layers of one array and each face naming its layer,
+   * it is one. `Renderer.createSurfaceTextureArray` builds the array, and every map of a material
+   * (albedo, normal, ORM, emissive) is read at the same layer, so an albedo and its emissive twin
+   * share an index.
+   *
+   * **It travels in the texture-coordinate attribute, as its third component**, because all
+   * sixteen of WebGL2's guaranteed vertex locations are spent in the instanced variant. So it needs
+   * `uvs` beside it and is refused without them: a layer with no coordinates addresses nothing.
+   *
+   * Whole numbers, checked, because the shader rounds to the nearest layer and a 1.5 would land on
+   * whichever side rounding favoured on that device.
+   */
+  layers?: Float32Array;
   /**
    * Four floats per vertex, and the only attribute whose lanes mean four different things.
    *
@@ -235,6 +254,25 @@ export function validateMeshData(data: MeshData): void {
   check('grain', data.grain, 1);
   check('relief', data.relief, 1);
   check('channel', data.channel, 4);
+  check('layers', data.layers, 1);
+  if (data.layers !== undefined) {
+    if (data.uvs === undefined) {
+      throw new Error(
+        'Mesh: layers without uvs — a texture-array layer travels as the third texture coordinate, ' +
+          'so a mesh that names layers has to supply the two it rides with',
+      );
+    }
+    const layers = data.layers;
+    for (let v = 0; v < layers.length; v++) {
+      const layer = layers[v] as number;
+      if (!(layer >= 0) || Math.floor(layer) !== layer) {
+        throw new Error(
+          `Mesh: layer ${layer} at vertex ${v} — a texture-array layer is a whole number at or ` +
+            'above zero, and anything else lands on whichever layer the device rounds it to',
+        );
+      }
+    }
+  }
   /*
    * `tangents` was declared optional on 2026-08-22 and was not checked here until 2026-08-25, which
    * made the widest optional attribute in the format the one a short buffer could reach a driver