@driftengine/core 4.5.0 → 4.6.0

package/src/geometry/csg.ts

@@ -0,0 +1,384 @@
+/**
+ * Boolean operations on closed solids — union, subtraction, intersection — by binary space
+ * partitioning.
+ *
+ * The algorithm is the one Evan Wallace's csg.js made well known, implemented afresh here — named
+ * at the point it is used, as `CREDITS.md` asks of a published method: each operand becomes a BSP tree of its own polygons, each tree clips the
+ * other's polygons to the region it keeps, and the survivors are rebuilt into one tree. Polygons
+ * carry position, normal and texture coordinates, interpolated where a plane splits them, so a cut
+ * face keeps the texture of the face it was cut from.
+ *
+ * **Only what the other operand reaches is split.** Each tree is used for its planes alone: an
+ * operand's own polygons are clipped as they arrived, never as its tree's construction cut them,
+ * and a polygon whose bounds clear the other operand's is passed through whole — kept or dropped
+ * as the operation says of everything outside that operand. The result is the two clipped lists
+ * side by side, where the published method rebuilds one tree from them and splits the second list
+ * along every plane of the first on the way. Neither changes the surface; together they are what
+ * kept a wall cut five times with its end faces at two triangles each instead of eight, and a
+ * city's worth of cut towers out of the millions.
+ *
+ * **What it gives up.** A polygon the other operand does reach is still split along every plane of
+ * its tree that crosses it, and nothing is re-merged, so a heavily cut solid grows, and the pieces
+ * meet with T-junctions: closed as a surface — its volume exact — but not edge for edge. Welding
+ * and simplification are the caller's afterwards. The tree is built iteratively, so a large
+ * operand cannot overflow the stack; clipping recurses to the tree's depth, which a solid of a few
+ * thousand faces keeps shallow.
+ *
+ * **Empty operands are answered before any tree is built**, because clipping against an empty tree
+ * keeps everything — which is the right answer for a union and the wrong one for an intersection.
+ */
+import type { Solid } from './solid.ts';
+import { emptySolid } from './solid.ts';
+import { SolidWriter } from './solidWriter.ts';
+
+/** Distance within which a point counts as on a plane. */
+const EPSILON = 1e-5;
+
+interface Vertex {
+  x: number;
+  y: number;
+  z: number;
+  nx: number;
+  ny: number;
+  nz: number;
+  u: number;
+  v: number;
+}
+
+interface Plane {
+  nx: number;
+  ny: number;
+  nz: number;
+  w: number;
+}
+
+interface Polygon {
+  vertices: Vertex[];
+  plane: Plane;
+}
+
+const COPLANAR = 0;
+const FRONT = 1;
+const BACK = 2;
+const SPANNING = 3;
+
+function planeFrom(a: Vertex, b: Vertex, c: Vertex): Plane | null {
+  const ux = b.x - a.x;
+  const uy = b.y - a.y;
+  const uz = b.z - a.z;
+  const vx = c.x - a.x;
+  const vy = c.y - a.y;
+  const vz = c.z - a.z;
+  let nx = uy * vz - uz * vy;
+  let ny = uz * vx - ux * vz;
+  let nz = ux * vy - uy * vx;
+  const len = Math.hypot(nx, ny, nz);
+  if (len < 1e-12) return null;
+  nx /= len;
+  ny /= len;
+  nz /= len;
+  return { nx, ny, nz, w: nx * a.x + ny * a.y + nz * a.z };
+}
+
+function flipPolygon(p: Polygon): Polygon {
+  const vertices = p.vertices
+    .slice()
+    .reverse()
+    .map((v) => ({ ...v, nx: -v.nx, ny: -v.ny, nz: -v.nz }));
+  return { vertices, plane: { nx: -p.plane.nx, ny: -p.plane.ny, nz: -p.plane.nz, w: -p.plane.w } };
+}
+
+function lerp(a: Vertex, b: Vertex, t: number): Vertex {
+  let nx = a.nx + (b.nx - a.nx) * t;
+  let ny = a.ny + (b.ny - a.ny) * t;
+  let nz = a.nz + (b.nz - a.nz) * t;
+  const len = Math.hypot(nx, ny, nz) || 1;
+  nx /= len;
+  ny /= len;
+  nz /= len;
+  return {
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    z: a.z + (b.z - a.z) * t,
+    nx,
+    ny,
+    nz,
+    u: a.u + (b.u - a.u) * t,
+    v: a.v + (b.v - a.v) * t,
+  };
+}
+
+/**
+ * Sort `polygon` against `plane` into the four lists, splitting it where it spans. A coplanar
+ * polygon goes to the front list when it faces the same way as the plane, the back one otherwise.
+ */
+function split(
+  plane: Plane,
+  polygon: Polygon,
+  coplanarFront: Polygon[],
+  coplanarBack: Polygon[],
+  front: Polygon[],
+  back: Polygon[],
+): void {
+  let kind = 0;
+  const types: number[] = [];
+  for (const v of polygon.vertices) {
+    const t = plane.nx * v.x + plane.ny * v.y + plane.nz * v.z - plane.w;
+    const type = t < -EPSILON ? BACK : t > EPSILON ? FRONT : COPLANAR;
+    kind |= type;
+    types.push(type);
+  }
+  if (kind === COPLANAR) {
+    const facing =
+      plane.nx * polygon.plane.nx + plane.ny * polygon.plane.ny + plane.nz * polygon.plane.nz;
+    (facing > 0 ? coplanarFront : coplanarBack).push(polygon);
+  } else if (kind === FRONT) {
+    front.push(polygon);
+  } else if (kind === BACK) {
+    back.push(polygon);
+  } else if (kind === SPANNING) {
+    const f: Vertex[] = [];
+    const b: Vertex[] = [];
+    const n = polygon.vertices.length;
+    for (let i = 0; i < n; i++) {
+      const j = (i + 1) % n;
+      const ti = types[i] ?? COPLANAR;
+      const tj = types[j] ?? COPLANAR;
+      const vi = polygon.vertices[i];
+      const vj = polygon.vertices[j];
+      if (!vi || !vj) continue;
+      if (ti !== BACK) f.push(vi);
+      if (ti !== FRONT) b.push(vi);
+      if ((ti | tj) === SPANNING) {
+        const di = plane.nx * vi.x + plane.ny * vi.y + plane.nz * vi.z;
+        const dj = plane.nx * vj.x + plane.ny * vj.y + plane.nz * vj.z;
+        const t = (plane.w - di) / (dj - di);
+        const mid = lerp(vi, vj, t);
+        f.push(mid);
+        b.push({ ...mid });
+      }
+    }
+    if (f.length >= 3) front.push({ vertices: f, plane: polygon.plane });
+    if (b.length >= 3) back.push({ vertices: b, plane: polygon.plane });
+  }
+}
+
+/** A BSP tree of an operand's planes. Its polygons only choose the planes and are not kept. */
+class Node {
+  plane: Plane | null = null;
+  front: Node | null = null;
+  back: Node | null = null;
+
+  /** Add `polygons`' planes to the tree, splitting down it, without recursion. */
+  build(polygons: Polygon[]): void {
+    const work: [Node, Polygon[]][] = [[this, polygons]];
+    const coplanar: Polygon[] = [];
+    while (work.length > 0) {
+      const item = work.pop();
+      if (!item) break;
+      const [node, list] = item;
+      if (list.length === 0) continue;
+      const first = list[0];
+      if (!node.plane && first) node.plane = { ...first.plane };
+      const plane = node.plane;
+      if (!plane) continue;
+      const f: Polygon[] = [];
+      const b: Polygon[] = [];
+      for (const p of list) split(plane, p, coplanar, coplanar, f, b);
+      coplanar.length = 0;
+      if (f.length > 0) {
+        node.front ??= new Node();
+        work.push([node.front, f]);
+      }
+      if (b.length > 0) {
+        node.back ??= new Node();
+        work.push([node.back, b]);
+      }
+    }
+  }
+
+  /** Turn the tree inside out: every plane reversed, front and back swapped. */
+  invert(): Node {
+    const stack: Node[] = [this];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (!node) break;
+      if (node.plane) {
+        node.plane = {
+          nx: -node.plane.nx,
+          ny: -node.plane.ny,
+          nz: -node.plane.nz,
+          w: -node.plane.w,
+        };
+      }
+      const f = node.front;
+      node.front = node.back;
+      node.back = f;
+      if (node.front) stack.push(node.front);
+      if (node.back) stack.push(node.back);
+    }
+    return this;
+  }
+
+  /** The parts of `polygons` outside this tree's solid. */
+  clipPolygons(polygons: Polygon[]): Polygon[] {
+    if (!this.plane) return polygons.slice();
+    let f: Polygon[] = [];
+    let b: Polygon[] = [];
+    for (const p of polygons) split(this.plane, p, f, b, f, b);
+    if (this.front) f = this.front.clipPolygons(f);
+    b = this.back ? this.back.clipPolygons(b) : [];
+    return f.concat(b);
+  }
+}
+
+interface Bounds {
+  min: [number, number, number];
+  max: [number, number, number];
+}
+
+function boundsOf(polygons: readonly Polygon[]): Bounds {
+  const min: [number, number, number] = [Infinity, Infinity, Infinity];
+  const max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  for (const p of polygons) {
+    for (const v of p.vertices) {
+      if (v.x < min[0]) min[0] = v.x;
+      if (v.y < min[1]) min[1] = v.y;
+      if (v.z < min[2]) min[2] = v.z;
+      if (v.x > max[0]) max[0] = v.x;
+      if (v.y > max[1]) max[1] = v.y;
+      if (v.z > max[2]) max[2] = v.z;
+    }
+  }
+  return { min, max };
+}
+
+/**
+ * `polygons` split into those that may meet `bounds` and those clear of it by more than the plane
+ * tolerance on some axis — which are outside the solid `bounds` encloses, with no tree to ask.
+ */
+function partition(polygons: readonly Polygon[], bounds: Bounds): [Polygon[], Polygon[]] {
+  const near: Polygon[] = [];
+  const clear: Polygon[] = [];
+  const { min, max } = bounds;
+  for (const p of polygons) {
+    let lx = Infinity;
+    let ly = Infinity;
+    let lz = Infinity;
+    let hx = -Infinity;
+    let hy = -Infinity;
+    let hz = -Infinity;
+    for (const v of p.vertices) {
+      lx = Math.min(lx, v.x);
+      ly = Math.min(ly, v.y);
+      lz = Math.min(lz, v.z);
+      hx = Math.max(hx, v.x);
+      hy = Math.max(hy, v.y);
+      hz = Math.max(hz, v.z);
+    }
+    const apart =
+      hx < min[0] - EPSILON ||
+      hy < min[1] - EPSILON ||
+      hz < min[2] - EPSILON ||
+      lx > max[0] + EPSILON ||
+      ly > max[1] + EPSILON ||
+      lz > max[2] + EPSILON;
+    (apart ? clear : near).push(p);
+  }
+  return [near, clear];
+}
+
+const flipAll = (polygons: readonly Polygon[]): Polygon[] => polygons.map(flipPolygon);
+
+function toPolygons(solid: Solid): Polygon[] {
+  const out: Polygon[] = [];
+  const p = solid.positions;
+  const n = solid.normals;
+  const uv = solid.uvs;
+  const vertex = (i: number): Vertex => ({
+    x: p[i * 3] ?? 0,
+    y: p[i * 3 + 1] ?? 0,
+    z: p[i * 3 + 2] ?? 0,
+    nx: n[i * 3] ?? 0,
+    ny: n[i * 3 + 1] ?? 0,
+    nz: n[i * 3 + 2] ?? 0,
+    u: uv[i * 2] ?? 0,
+    v: uv[i * 2 + 1] ?? 0,
+  });
+  for (let t = 0; t < solid.indices.length; t += 3) {
+    const a = vertex(solid.indices[t] ?? 0);
+    const b = vertex(solid.indices[t + 1] ?? 0);
+    const c = vertex(solid.indices[t + 2] ?? 0);
+    const plane = planeFrom(a, b, c);
+    if (plane) out.push({ vertices: [a, b, c], plane });
+  }
+  return out;
+}
+
+/** Polygons back to a solid, each fanned from its first corner — they are convex. */
+function fromPolygons(polygons: Polygon[]): Solid {
+  const out = new SolidWriter();
+  for (const polygon of polygons) {
+    const base = out.vertexCount;
+    for (const v of polygon.vertices) out.vertex(v.x, v.y, v.z, v.nx, v.ny, v.nz, v.u, v.v);
+    for (let i = 1; i + 1 < polygon.vertices.length; i++)
+      out.triangle(base, base + i, base + i + 1);
+  }
+  return out.finish();
+}
+
+function tree(polygons: Polygon[]): Node {
+  const node = new Node();
+  node.build(polygons);
+  return node;
+}
+
+const isEmpty = (s: Solid): boolean => s.indices.length === 0;
+
+/**
+ * Both operands' polygons, each split by the other's bounds. The three operations below are the
+ * published method's steps written over these lists, with the clear polygons settled by the rule
+ * each operation applies to everything outside the other operand.
+ */
+function operands(a: Solid, b: Solid) {
+  const pa = toPolygons(a);
+  const pb = toPolygons(b);
+  const [aNear, aClear] = partition(pa, boundsOf(pb));
+  const [bNear, bClear] = partition(pb, boundsOf(pa));
+  return { pa, pb, aNear, aClear, bNear, bClear };
+}
+
+/** Everything inside either solid. */
+export function solidUnion(a: Solid, b: Solid): Solid {
+  if (isEmpty(b)) return a;
+  if (isEmpty(a)) return b;
+  const { pa, pb, aNear, aClear, bNear, bClear } = operands(a, b);
+  const ta = tree(pa);
+  const aKept = tree(pb).clipPolygons(aNear);
+  /* B outside A, then without the faces lying on A's facing the same way, which A already has. */
+  const bKept = flipAll(ta.clipPolygons(flipAll(ta.clipPolygons(bNear))));
+  return fromPolygons([...aClear, ...aKept, ...bClear, ...bKept]);
+}
+
+/** Everything inside `a` and outside `b`. */
+export function solidSubtract(a: Solid, b: Solid): Solid {
+  if (isEmpty(a)) return emptySolid();
+  if (isEmpty(b)) return a;
+  const { pa, pb, aNear, aClear, bNear } = operands(a, b);
+  const outside = tree(pa).invert();
+  const aKept = flipAll(tree(pb).clipPolygons(flipAll(aNear)));
+  /* B inside A, turned to face into the cavity it leaves. */
+  const bKept = outside.clipPolygons(flipAll(outside.clipPolygons(bNear)));
+  return fromPolygons([...aClear, ...aKept, ...bKept]);
+}
+
+/** Everything inside both solids. */
+export function solidIntersect(a: Solid, b: Solid): Solid {
+  if (isEmpty(a) || isEmpty(b)) return emptySolid();
+  const { pa, pb, aNear, bNear } = operands(a, b);
+  const outsideA = tree(pa).invert();
+  const outsideB = tree(pb).invert();
+  const aKept = flipAll(outsideB.clipPolygons(flipAll(aNear)));
+  const bKept = flipAll(outsideA.clipPolygons(flipAll(outsideA.clipPolygons(bNear))));
+  return fromPolygons([...aKept, ...bKept]);
+}

package/src/geometry/meshBuilder.ts

@@ -128,6 +128,7 @@ export class MeshBuilder {
    * inverse transpose, and nothing here has wanted that yet.
    */
   addMesh(mesh: MeshData, x: number, y: number, z: number, scale = 1): this {
+    refuseLayers(mesh);
     const base = this.vertexCount;
     const count = mesh.positions.length / 3;
     for (let i = 0; i < count; i++) {
@@ -199,6 +200,7 @@ export class MeshBuilder {
     forward: Vec3,
     scale = 1,
   ): this {
+    refuseLayers(mesh);
     assertOrthonormal(right, up, forward);
     const base = this.vertexCount;
     const count = mesh.positions.length / 3;
@@ -1399,3 +1401,16 @@ const CORNERS = [
   [1, 1],
   [-1, 1],
 ] as const;
+
+/**
+ * A builder has no layer channel, so merging a layered mesh would keep its texture coordinates and
+ * silently put every face on layer 0 — the first image of the array, which reads as the wrong
+ * facade everywhere rather than as an error. Refused instead; `concatMeshes` joins layered meshes.
+ */
+function refuseLayers(mesh: MeshData): void {
+  if (mesh.layers === undefined) return;
+  throw new Error(
+    'MeshBuilder: this mesh names texture-array layers, which a builder does not carry — merging ' +
+      'it here would put every face on layer 0. Join layered meshes with concatMeshes instead.',
+  );
+}

package/src/geometry/meshConcat.ts

@@ -28,6 +28,7 @@ const OPTIONAL = [
   ['channel', 4],
   ['joints', 4],
   ['weights', 4],
+  ['layers', 1],
 ] as const;
 
 /**

package/src/geometry/pixelFont.ts

@@ -67,6 +67,8 @@ const GLYPHS: Record<string, readonly number[]> = {
   "'": [0b00100, 0b00100, 0, 0, 0, 0, 0],
   '(': [0b00010, 0b00100, 0b01000, 0b01000, 0b01000, 0b00100, 0b00010],
   ')': [0b01000, 0b00100, 0b00010, 0b00010, 0b00010, 0b00100, 0b01000],
+  '[': [0b01110, 0b01000, 0b01000, 0b01000, 0b01000, 0b01000, 0b01110],
+  ']': [0b01110, 0b00010, 0b00010, 0b00010, 0b00010, 0b00010, 0b01110],
   '%': [0b11001, 0b11010, 0b00010, 0b00100, 0b01000, 0b01011, 0b10011],
   '·': [0, 0, 0, 0b01100, 0b01100, 0, 0],
   '×': [0, 0b10001, 0b01010, 0b00100, 0b01010, 0b10001, 0],

package/src/geometry/solid.ts

@@ -0,0 +1,189 @@
+/**
+ * A solid: an indexed triangle surface with normals and texture coordinates, and the operations
+ * every procedural builder needs on one — place it, join several, measure it, and hand it to the
+ * renderer as a mesh.
+ *
+ * **Why a type of its own rather than `MeshData`.** A mesh carries a dozen per-vertex channels a
+ * renderer reads (colour, emissive, roughness, grain, joints…) and a solid is what exists before any
+ * of them are decided: shape alone. Booleans, smoothing and transforms are defined on shape, and
+ * dragging eleven channels through a boolean would mean deciding how each one interpolates across a
+ * cut. The caller paints a finished solid once, with `solidToMesh` or its own writer.
+ *
+ * **Named `Solid` because `*Shape` is taken**: the physics colliders the core barrel re-exports are
+ * `boxShape`, `cylinderShape` and the rest, and a second meaning for the word would read as the
+ * same thing. Every primitive here is closed except `solidQuad`, a single-sided plane.
+ *
+ * Built at load or bake time, never per frame, so these functions allocate their results.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import type { Vec3 } from '../math/color.ts';
+
+export interface Solid {
+  /** Three floats a vertex. */
+  readonly positions: Float32Array;
+  /** Three floats a vertex, unit length, outward. */
+  readonly normals: Float32Array;
+  /**
+   * Two floats a vertex, parametric: 0..1 across each face of a box, around and along a round
+   * primitive. Tiling in metres is the caller's, who knows the sizes.
+   */
+  readonly uvs: Float32Array;
+  /** Counter-clockwise triangles seen from outside. */
+  readonly indices: Uint32Array;
+}
+
+export function emptySolid(): Solid {
+  return {
+    positions: new Float32Array(0),
+    normals: new Float32Array(0),
+    uvs: new Float32Array(0),
+    indices: new Uint32Array(0),
+  };
+}
+
+/**
+ * `solid` moved by a column-major 4×4 model matrix.
+ *
+ * **Normals go through the inverse transpose of the upper 3×3**, then are renormalised. Rotating
+ * them by the matrix itself is right only for rotations and uniform scales; under a non-uniform one
+ * — a unit cylinder scaled to a post, a sphere to an ellipsoid — it leaves every normal leaning
+ * toward the stretched axis, and the surface is lit as if it faced somewhere else, which reads as a
+ * shading bug rather than a maths one.
+ *
+ * **A mirror reverses the winding**, because a negative determinant turns every triangle inside
+ * out; without the reversal a mirrored solid is culled from outside and its volume goes negative.
+ */
+export function transformSolid(solid: Solid, model: ArrayLike<number>): Solid {
+  const m = (i: number): number => model[i] ?? 0;
+  const a = m(0);
+  const b = m(4);
+  const c = m(8);
+  const d = m(1);
+  const e = m(5);
+  const f = m(9);
+  const g = m(2);
+  const h = m(6);
+  const k = m(10);
+  /* Cofactors of the upper 3×3 in row-major (a b c / d e f / g h k): the inverse transpose up to
+     the determinant's scale, which renormalising removes — except its sign, kept below. */
+  const c00 = e * k - f * h;
+  const c01 = f * g - d * k;
+  const c02 = d * h - e * g;
+  const c10 = c * h - b * k;
+  const c11 = a * k - c * g;
+  const c12 = b * g - a * h;
+  const c20 = b * f - c * e;
+  const c21 = c * d - a * f;
+  const c22 = a * e - b * d;
+  const det = a * c00 + b * c01 + c * c02;
+  const sign = det < 0 ? -1 : 1;
+
+  const count = solid.positions.length / 3;
+  const positions = new Float32Array(count * 3);
+  const normals = new Float32Array(count * 3);
+  for (let v = 0; v < count; v++) {
+    const x = solid.positions[v * 3] ?? 0;
+    const y = solid.positions[v * 3 + 1] ?? 0;
+    const z = solid.positions[v * 3 + 2] ?? 0;
+    positions[v * 3] = a * x + b * y + c * z + m(12);
+    positions[v * 3 + 1] = d * x + e * y + f * z + m(13);
+    positions[v * 3 + 2] = g * x + h * y + k * z + m(14);
+    const nx = solid.normals[v * 3] ?? 0;
+    const ny = solid.normals[v * 3 + 1] ?? 0;
+    const nz = solid.normals[v * 3 + 2] ?? 0;
+    const tx = (c00 * nx + c01 * ny + c02 * nz) * sign;
+    const ty = (c10 * nx + c11 * ny + c12 * nz) * sign;
+    const tz = (c20 * nx + c21 * ny + c22 * nz) * sign;
+    const len = Math.hypot(tx, ty, tz) || 1;
+    normals[v * 3] = tx / len;
+    normals[v * 3 + 1] = ty / len;
+    normals[v * 3 + 2] = tz / len;
+  }
+  let indices = solid.indices;
+  if (det < 0) {
+    indices = new Uint32Array(solid.indices.length);
+    for (let t = 0; t < indices.length; t += 3) {
+      indices[t] = solid.indices[t] ?? 0;
+      indices[t + 1] = solid.indices[t + 2] ?? 0;
+      indices[t + 2] = solid.indices[t + 1] ?? 0;
+    }
+  }
+  return { positions, normals, uvs: solid.uvs, indices };
+}
+
+/** Several solids as one, each one's indices offset past the vertices before it. */
+export function mergeSolids(solids: readonly Solid[]): Solid {
+  if (solids.length === 1 && solids[0] !== undefined) return solids[0];
+  let vertices = 0;
+  let triangles = 0;
+  for (const s of solids) {
+    vertices += s.positions.length / 3;
+    triangles += s.indices.length;
+  }
+  const positions = new Float32Array(vertices * 3);
+  const normals = new Float32Array(vertices * 3);
+  const uvs = new Float32Array(vertices * 2);
+  const indices = new Uint32Array(triangles);
+  let v = 0;
+  let t = 0;
+  for (const s of solids) {
+    positions.set(s.positions, v * 3);
+    normals.set(s.normals, v * 3);
+    uvs.set(s.uvs, v * 2);
+    for (let i = 0; i < s.indices.length; i++) indices[t + i] = (s.indices[i] ?? 0) + v;
+    v += s.positions.length / 3;
+    t += s.indices.length;
+  }
+  return { positions, normals, uvs, indices };
+}
+
+/**
+ * The enclosed volume by the divergence theorem: the sum of each triangle's signed tetrahedron
+ * with the origin. Positive for a closed, outward-wound solid; meaningless for an open one.
+ *
+ * Exact for any closed surface, T-junctions included, which is why the CSG tests can use it on a
+ * boolean's output where an edge-pairing check cannot.
+ */
+export function solidVolume(solid: Solid): number {
+  const p = solid.positions;
+  const idx = solid.indices;
+  let sum = 0;
+  for (let t = 0; t < idx.length; t += 3) {
+    const a = (idx[t] ?? 0) * 3;
+    const b = (idx[t + 1] ?? 0) * 3;
+    const c = (idx[t + 2] ?? 0) * 3;
+    const ax = p[a] ?? 0;
+    const ay = p[a + 1] ?? 0;
+    const az = p[a + 2] ?? 0;
+    const bx = p[b] ?? 0;
+    const by = p[b + 1] ?? 0;
+    const bz = p[b + 2] ?? 0;
+    const cx = p[c] ?? 0;
+    const cy = p[c + 1] ?? 0;
+    const cz = p[c + 2] ?? 0;
+    sum += ax * (by * cz - bz * cy) - ay * (bx * cz - bz * cx) + az * (bx * cy - by * cx);
+  }
+  return sum / 6;
+}
+
+/**
+ * A solid painted one colour, as a mesh the renderer draws. `emissive` is the usual scalar: the
+ * surface's own colour scaled, gated by the environment's night factor like every emissive.
+ */
+export function solidToMesh(solid: Solid, color: Vec3, emissive = 0): MeshData {
+  const count = solid.positions.length / 3;
+  const colors = new Float32Array(count * 3);
+  for (let v = 0; v < count; v++) {
+    colors[v * 3] = color[0];
+    colors[v * 3 + 1] = color[1];
+    colors[v * 3 + 2] = color[2];
+  }
+  return {
+    positions: solid.positions,
+    normals: solid.normals,
+    colors,
+    emissive: new Float32Array(count).fill(emissive),
+    uvs: solid.uvs,
+    indices: solid.indices,
+  };
+}