@driftengine/assets 3.61.0

package/dist/coarseLevel.js

@@ -0,0 +1,606 @@
+/**
+ * One coarse mesh standing in for a whole asset, so a load can start with an outline.
+ *
+ * docs/FORMAT.md §4.6 argues for this and states the two things that make it worth building:
+ * a coarse whole model has to *exist as geometry* before it can be drawn, so it is baked
+ * rather than derived at load; and **level 0 for the whole asset is worth more than level 0
+ * for each of 187 parts**, because a single decimated body reads as a car while 187 coarse
+ * fragments read as a mess. So this takes every mesh and returns exactly one.
+ *
+ * **The surface of an occupancy grid, not a cluster of vertices.** The first version of this
+ * clustered vertices onto a grid and connected three clusters wherever a source triangle
+ * spanned three cells, which is the classic Rossignac-Borrel decimation and was wrong for
+ * this job in a way that only showed on screen: nothing stops the three clusters of a
+ * triangle from lying on *different surfaces* of the model, so a car whose seats and engine
+ * bay share cells with its shell grew triangles straight through the bodywork. It was
+ * reported, correctly, as white cliffs.
+ *
+ * This marks every cell any surface passes through, then emits the boundary between the
+ * occupied cells and the empty ones. That boundary is **closed by construction** and cannot
+ * contain a triangle joining two sides of the model, because it is the outside of a solid
+ * rather than a decimation of a surface. Interior geometry disappears into cells that are
+ * already occupied, which is exactly what should happen to it in an outline.
+ *
+ * The blocky result is then pulled onto the model: each corner of the boundary sits at the
+ * average of the real surface inside the cells around it. So a cube grid becomes a shape
+ * that follows the car, at the resolution the caller asked for.
+ *
+ * Offline work in the baker, so it may allocate freely. Nothing here runs per frame.
+ */
+/**
+ * The grid this uses when nobody names a resolution, exported because two other places used
+ * to carry their own copy of the number and disagreed with it.
+ *
+ * The baker printed 32 and the browser's converter passed nothing, so one path wrote an
+ * outline at 32 cells and the other at 40, and the same model taken through the two arrived
+ * differently for no stated reason. A default that callers restate is a default in name only.
+ */
+export const DEFAULT_COARSE_CELLS = 40;
+const DEFAULT_CELLS = DEFAULT_COARSE_CELLS;
+const MIN_CELLS = 4;
+const MAX_CELLS = 192;
+const DEFAULT_INSET = 0.3;
+/**
+ * How finely a triangle bigger than a cell is sampled when marking cells it passes through.
+ *
+ * Marking only the three corners is right for the overwhelming majority of a real model,
+ * whose triangles are centimetres across against a cell of twelve. It is wrong for the few
+ * that are not: a backdrop plane or a wall is two triangles the size of the asset, and a hull
+ * built from their corners alone would have a hole the shape of the wall. So a triangle is
+ * walked at a spacing below one cell, which costs nothing on the small ones because a spacing
+ * below one cell is one step.
+ */
+const MAX_SAMPLE_STEPS = 96;
+/**
+ * How much the cells around a node must agree about which way the surface faces before the node
+ * is moved at all. See where it is used: it is what keeps a thin feature from sliding off itself.
+ */
+const DIRECTED = 0.5;
+/**
+ * How closely a surface must face the direction of travel before its plane is honoured.
+ *
+ * A surface at more than about seventy degrees to it is one the node moves *along* rather than
+ * toward, and the arithmetic divides by that alignment, so at ninety degrees it asks for an
+ * infinite push to get behind something it can never get behind by moving this way.
+ */
+const MIN_ALIGN = 0.35;
+function clamp(value, low, high) {
+    return value < low ? low : value > high ? high : value;
+}
+/**
+ * What one cell of the grid knows about the surface inside it, as one flat accumulator.
+ *
+ * Position, normal, colour, emissive, then how many samples went in: `0..2`, `3..5`, `6..8`,
+ * `9`, `10`. One array rather than several because the cells are addressed by a slot and a
+ * second array indexed by the same slot is a second thing to keep in step.
+ */
+const CELL_STRIDE = 11;
+const AT_POSITION = 0;
+const AT_NORMAL = 3;
+const AT_COLOUR = 6;
+const AT_EMISSIVE = 9;
+const AT_COUNT = 10;
+/**
+ * Build the coarse level, or `null` when there is nothing to build one from.
+ *
+ * `null` rather than an empty mesh: an asset with no extent, or one whose geometry all falls
+ * inside a single cell, has no outline worth a chunk in the file, and every caller would
+ * otherwise have to check the vertex count to find that out.
+ *
+ * Whether the result is *worth writing* is a separate question with a separate answer:
+ * `isOutlineWorthWriting`.
+ */
+export function buildCoarseLevel(meshes, options = {}) {
+    const cells = clamp(Math.round(options.cells ?? DEFAULT_CELLS), MIN_CELLS, MAX_CELLS);
+    const inset = Math.max(0, options.inset ?? DEFAULT_INSET);
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (const mesh of meshes) {
+        for (let at = 0; at + 2 < mesh.positions.length; at += 3) {
+            const x = mesh.positions[at];
+            const y = mesh.positions[at + 1];
+            const z = mesh.positions[at + 2];
+            if (x < minX)
+                minX = x;
+            if (y < minY)
+                minY = y;
+            if (z < minZ)
+                minZ = z;
+            if (x > maxX)
+                maxX = x;
+            if (y > maxY)
+                maxY = y;
+            if (z > maxZ)
+                maxZ = z;
+        }
+    }
+    if (!Number.isFinite(minX))
+        return null;
+    const cell = Math.max(maxX - minX, maxY - minY, maxZ - minZ) / cells;
+    if (!(cell > 0))
+        return null;
+    /* At least one cell on every axis, so a flat asset has a grid rather than none. */
+    const nx = Math.max(1, Math.ceil((maxX - minX) / cell));
+    const ny = Math.max(1, Math.ceil((maxY - minY) / cell));
+    const nz = Math.max(1, Math.ceil((maxZ - minZ) / cell));
+    /**
+     * Which cells hold surface, and what that surface is: summed position, normal, colour and
+     * emissive, then the sample count, so a cell can report the average of what passed through it.
+     */
+    const occupied = new Map();
+    const cellSums = [];
+    const ixOf = (x) => clamp(Math.floor((x - minX) / cell), 0, nx - 1);
+    const iyOf = (y) => clamp(Math.floor((y - minY) / cell), 0, ny - 1);
+    const izOf = (z) => clamp(Math.floor((z - minZ) / cell), 0, nz - 1);
+    const cellId = (ix, iy, iz) => (iz * ny + iy) * nx + ix;
+    /** Mark the cell a point falls in, and fold the surface there into it. */
+    const mark = (x, y, z, nxs, nys, nzs, r, g, b, emissive) => {
+        const id = cellId(ixOf(x), iyOf(y), izOf(z));
+        let slot = occupied.get(id);
+        if (slot === undefined) {
+            slot = cellSums.length;
+            occupied.set(id, slot);
+            for (let i = 0; i < CELL_STRIDE; i++)
+                cellSums.push(0);
+        }
+        cellSums[slot + AT_POSITION] = cellSums[slot + AT_POSITION] + x;
+        cellSums[slot + AT_POSITION + 1] = cellSums[slot + AT_POSITION + 1] + y;
+        cellSums[slot + AT_POSITION + 2] = cellSums[slot + AT_POSITION + 2] + z;
+        cellSums[slot + AT_NORMAL] = cellSums[slot + AT_NORMAL] + nxs;
+        cellSums[slot + AT_NORMAL + 1] = cellSums[slot + AT_NORMAL + 1] + nys;
+        cellSums[slot + AT_NORMAL + 2] = cellSums[slot + AT_NORMAL + 2] + nzs;
+        cellSums[slot + AT_COLOUR] = cellSums[slot + AT_COLOUR] + r;
+        cellSums[slot + AT_COLOUR + 1] = cellSums[slot + AT_COLOUR + 1] + g;
+        cellSums[slot + AT_COLOUR + 2] = cellSums[slot + AT_COLOUR + 2] + b;
+        cellSums[slot + AT_EMISSIVE] = cellSums[slot + AT_EMISSIVE] + emissive;
+        cellSums[slot + AT_COUNT] = cellSums[slot + AT_COUNT] + 1;
+    };
+    for (const mesh of meshes) {
+        const p = mesh.positions;
+        const n = mesh.normals;
+        const c = mesh.colors;
+        const e = mesh.emissive;
+        for (let at = 0; at + 2 < mesh.indices.length; at += 3) {
+            const i0 = mesh.indices[at];
+            const i1 = mesh.indices[at + 1];
+            const i2 = mesh.indices[at + 2];
+            const ax = p[i0 * 3], ay = p[i0 * 3 + 1], az = p[i0 * 3 + 2];
+            const bx = p[i1 * 3], by = p[i1 * 3 + 1], bz = p[i1 * 3 + 2];
+            const cx = p[i2 * 3], cy = p[i2 * 3 + 1], cz = p[i2 * 3 + 2];
+            /* One step for anything smaller than a cell, which is nearly everything. */
+            const longest = Math.max(Math.hypot(bx - ax, by - ay, bz - az), Math.hypot(cx - bx, cy - by, cz - bz), Math.hypot(ax - cx, ay - cy, az - cz));
+            const steps = clamp(Math.ceil(longest / cell), 1, MAX_SAMPLE_STEPS);
+            for (let i = 0; i <= steps; i++) {
+                for (let j = 0; i + j <= steps; j++) {
+                    const u = i / steps;
+                    const v = j / steps;
+                    const w = 1 - u - v;
+                    mark(ax * w + bx * u + cx * v, ay * w + by * u + cy * v, az * w + bz * u + cz * v, n[i0 * 3] * w + n[i1 * 3] * u + n[i2 * 3] * v, n[i0 * 3 + 1] * w +
+                        n[i1 * 3 + 1] * u +
+                        n[i2 * 3 + 1] * v, n[i0 * 3 + 2] * w +
+                        n[i1 * 3 + 2] * u +
+                        n[i2 * 3 + 2] * v, c[i0 * 3] * w + c[i1 * 3] * u + c[i2 * 3] * v, c[i0 * 3 + 1] * w +
+                        c[i1 * 3 + 1] * u +
+                        c[i2 * 3 + 1] * v, c[i0 * 3 + 2] * w +
+                        c[i1 * 3 + 2] * u +
+                        c[i2 * 3 + 2] * v, e[i0] * w + e[i1] * u + e[i2] * v);
+                }
+            }
+        }
+    }
+    if (occupied.size === 0)
+        return null;
+    return buildBoundary({ occupied, cellSums, nx, ny, nz, cell, minX, minY, minZ, inset });
+}
+/**
+ * Whether a built level is worth writing into a file as an outline.
+ *
+ * **A level of detail that is bigger than the model is not one.** The grid is a fixed number of
+ * cells across whatever it is given, so its cost follows the *shape* rather than the detail: four
+ * hand-written triangles come back as a 9,840-triangle shell, which is 308 KB of outline arriving
+ * ahead of a model measured in bytes. Everything an outline is for, being on screen before the
+ * geometry at a fraction of the download, is inverted.
+ *
+ * Found the day the default flipped from off to on, by a fixture. While an outline was asked for
+ * per asset by somebody who had looked, the case could not arise. A default has to hold for the
+ * assets nobody looks at, which is what makes it a default.
+ *
+ * **Separate from `buildCoarseLevel`, which stays a geometry function.** This is a budget, and a
+ * caller that wants the hull of a small mesh for some other purpose is entitled to it. It lives
+ * here rather than in the two callers because the baker and the browser's converter have to agree
+ * about what a file carries, and a rule stated twice is a rule until somebody edits one copy.
+ *
+ * Half rather than merely smaller: an outline that saves a few per cent is a chunk, an upload and
+ * a swap for no visible gain.
+ */
+export function isOutlineWorthWriting(level, meshes) {
+    let sourceTriangles = 0;
+    for (const mesh of meshes)
+        sourceTriangles += mesh.indices.length / 3;
+    return level.indices.length / 3 <= sourceTriangles / 2;
+}
+/**
+ * The surface between the occupied cells and the empty ones, pulled onto the model.
+ *
+ * Every quad is a face an occupied cell shares with a cell that holds nothing, wound so it
+ * faces out of the solid. Its four corners are grid nodes shared with the neighbouring faces,
+ * so the result is one welded, closed shell rather than a pile of squares — and because the
+ * corners then move to the average of the real surface around them, the shell follows the
+ * model instead of stepping around it.
+ */
+function buildBoundary(grid) {
+    const { occupied, cellSums, nx, ny, nz, cell, minX, minY, minZ, inset } = grid;
+    const cellId = (ix, iy, iz) => (iz * ny + iy) * nx + ix;
+    const holds = (ix, iy, iz) => ix >= 0 &&
+        iy >= 0 &&
+        iz >= 0 &&
+        ix < nx &&
+        iy < ny &&
+        iz < nz &&
+        occupied.has(cellId(ix, iy, iz));
+    /**
+     * Whether a point in space falls in a cell that holds surface.
+     *
+     * Unclamped, deliberately: clamping a point that is outside the grid into the nearest cell
+     * would report the asset as occupying places it does not, which is the opposite of what this
+     * is asked for.
+     */
+    const holdsPoint = (x, y, z) => holds(Math.floor((x - minX) / cell), Math.floor((y - minY) / cell), Math.floor((z - minZ) / cell));
+    /** Node ids run over the grid's corners, one more than the cells on every axis. */
+    const nodeId = (ix, iy, iz) => (iz * (ny + 1) + iy) * (nx + 1) + ix;
+    const nodes = new Map();
+    const nodeAt = [];
+    const vertexOf = (ix, iy, iz) => {
+        const id = nodeId(ix, iy, iz);
+        let found = nodes.get(id);
+        if (found === undefined) {
+            found = nodeAt.length / 3;
+            nodes.set(id, found);
+            nodeAt.push(ix, iy, iz);
+        }
+        return found;
+    };
+    /**
+     * The six faces, each as the four corner offsets in the order that faces outward.
+     *
+     * Written out rather than derived, because a face wound the wrong way is invisible in the
+     * source and shows up as a hole in the hull from one side only.
+     */
+    const FACES = [
+        [
+            1,
+            0,
+            0,
+            [
+                [1, 0, 0],
+                [1, 1, 0],
+                [1, 1, 1],
+                [1, 0, 1],
+            ],
+        ],
+        [
+            -1,
+            0,
+            0,
+            [
+                [0, 0, 0],
+                [0, 0, 1],
+                [0, 1, 1],
+                [0, 1, 0],
+            ],
+        ],
+        [
+            0,
+            1,
+            0,
+            [
+                [0, 1, 0],
+                [0, 1, 1],
+                [1, 1, 1],
+                [1, 1, 0],
+            ],
+        ],
+        [
+            0,
+            -1,
+            0,
+            [
+                [0, 0, 0],
+                [1, 0, 0],
+                [1, 0, 1],
+                [0, 0, 1],
+            ],
+        ],
+        [
+            0,
+            0,
+            1,
+            [
+                [0, 0, 1],
+                [1, 0, 1],
+                [1, 1, 1],
+                [0, 1, 1],
+            ],
+        ],
+        [
+            0,
+            0,
+            -1,
+            [
+                [0, 0, 0],
+                [0, 1, 0],
+                [1, 1, 0],
+                [1, 0, 0],
+            ],
+        ],
+    ];
+    /**
+     * Which empty cells can be reached from outside the asset, found by flooding inward.
+     *
+     * **This is what keeps the outline to the outside of the model, and it halves it.** A car body
+     * is a shell, so the cells it occupies have empty space on both sides, and a boundary drawn
+     * against every empty neighbour produces two shells: the one a viewer sees and a second one
+     * lining the cabin. The inner one is invisible, doubles the triangle count, and where the
+     * shell is a single cell thick both sheets snap to the same surface and fight over the depth
+     * buffer, which reads as dark speckle across the model.
+     *
+     * A cavity is exactly an empty region the flood cannot reach, so this is the whole test.
+     */
+    const outside = new Uint8Array(nx * ny * nz);
+    const queue = [];
+    for (let iz = 0; iz < nz; iz++) {
+        for (let iy = 0; iy < ny; iy++) {
+            for (let ix = 0; ix < nx; ix++) {
+                const onRim = ix === 0 || iy === 0 || iz === 0 || ix === nx - 1 || iy === ny - 1 || iz === nz - 1;
+                if (!onRim)
+                    continue;
+                const id = cellId(ix, iy, iz);
+                if (occupied.has(id) || outside[id] === 1)
+                    continue;
+                outside[id] = 1;
+                queue.push(ix, iy, iz);
+            }
+        }
+    }
+    const STEPS = [
+        [1, 0, 0],
+        [-1, 0, 0],
+        [0, 1, 0],
+        [0, -1, 0],
+        [0, 0, 1],
+        [0, 0, -1],
+    ];
+    /* Breadth first over an explicit list rather than by recursion: a grid of a hundred thousand
+       cells would be a hundred thousand frames deep in the worst case. */
+    for (let head = 0; head + 2 < queue.length; head += 3) {
+        const ix = queue[head];
+        const iy = queue[head + 1];
+        const iz = queue[head + 2];
+        for (const [dx, dy, dz] of STEPS) {
+            const jx = ix + dx;
+            const jy = iy + dy;
+            const jz = iz + dz;
+            if (jx < 0 || jy < 0 || jz < 0 || jx >= nx || jy >= ny || jz >= nz)
+                continue;
+            const id = cellId(jx, jy, jz);
+            if (occupied.has(id) || outside[id] === 1)
+                continue;
+            outside[id] = 1;
+            queue.push(jx, jy, jz);
+        }
+    }
+    /** Whether this neighbour is open air a viewer could be standing in. */
+    const open = (ix, iy, iz) => {
+        if (ix < 0 || iy < 0 || iz < 0 || ix >= nx || iy >= ny || iz >= nz)
+            return true;
+        const id = cellId(ix, iy, iz);
+        return !occupied.has(id) && outside[id] === 1;
+    };
+    const triangles = [];
+    for (const id of occupied.keys()) {
+        const ix = id % nx;
+        const iy = Math.floor(id / nx) % ny;
+        const iz = Math.floor(id / (nx * ny));
+        for (const [dx, dy, dz, corners] of FACES) {
+            if (!open(ix + dx, iy + dy, iz + dz))
+                continue;
+            const a = vertexOf(ix + corners[0]?.[0], iy + corners[0]?.[1], iz + corners[0]?.[2]);
+            const b = vertexOf(ix + corners[1]?.[0], iy + corners[1]?.[1], iz + corners[1]?.[2]);
+            const c = vertexOf(ix + corners[2]?.[0], iy + corners[2]?.[1], iz + corners[2]?.[2]);
+            const d = vertexOf(ix + corners[3]?.[0], iy + corners[3]?.[1], iz + corners[3]?.[2]);
+            triangles.push(a, b, c, a, c, d);
+        }
+    }
+    const count = nodeAt.length / 3;
+    if (count < 3 || triangles.length === 0)
+        return null;
+    const positions = new Float32Array(count * 3);
+    const normals = new Float32Array(count * 3);
+    const colors = new Float32Array(count * 3);
+    const emissive = new Float32Array(count);
+    for (let at = 0; at < count; at++) {
+        const ix = nodeAt[at * 3];
+        const iy = nodeAt[at * 3 + 1];
+        const iz = nodeAt[at * 3 + 2];
+        /*
+         * The average of the real surface in the cells touching this node, which is what turns a
+         * staircase of cubes into the shape of the thing. Up to eight cells meet at a node and only
+         * the occupied ones have anything to say.
+         */
+        let px = 0, py = 0, pz = 0;
+        let nxs = 0, nys = 0, nzs = 0;
+        let r = 0, g = 0, b = 0, glow = 0;
+        let found = 0;
+        /** The planes this node has to end up behind: one per occupied cell around it. */
+        const planes = [];
+        for (let ox = -1; ox <= 0; ox++) {
+            for (let oy = -1; oy <= 0; oy++) {
+                for (let oz = -1; oz <= 0; oz++) {
+                    const cx = ix + ox;
+                    const cy = iy + oy;
+                    const cz = iz + oz;
+                    if (cx < 0 || cy < 0 || cz < 0 || cx >= nx || cy >= ny || cz >= nz)
+                        continue;
+                    const slot = occupied.get(cellId(cx, cy, cz));
+                    if (slot === undefined)
+                        continue;
+                    const samples = cellSums[slot + AT_COUNT];
+                    if (samples <= 0)
+                        continue;
+                    const qx = cellSums[slot + AT_POSITION] / samples;
+                    const qy = cellSums[slot + AT_POSITION + 1] / samples;
+                    const qz = cellSums[slot + AT_POSITION + 2] / samples;
+                    px += qx;
+                    py += qy;
+                    pz += qz;
+                    /*
+                     * Each cell's facing, as a unit vector, so the node's own facing is an average of
+                     * directions rather than of magnitudes. A cell whose samples cancel has no facing to
+                     * offer and is left out of both the average and the planes: it is a fold or a doubled
+                     * face, and it has no side for anything to be behind.
+                     */
+                    let mx = cellSums[slot + AT_NORMAL];
+                    let my = cellSums[slot + AT_NORMAL + 1];
+                    let mz = cellSums[slot + AT_NORMAL + 2];
+                    const facing = Math.hypot(mx, my, mz);
+                    if (facing > 1e-6) {
+                        mx /= facing;
+                        my /= facing;
+                        mz /= facing;
+                        nxs += mx;
+                        nys += my;
+                        nzs += mz;
+                        planes.push(qx, qy, qz, mx, my, mz);
+                    }
+                    r += cellSums[slot + AT_COLOUR] / samples;
+                    g += cellSums[slot + AT_COLOUR + 1] / samples;
+                    b += cellSums[slot + AT_COLOUR + 2] / samples;
+                    glow += cellSums[slot + AT_EMISSIVE] / samples;
+                    found++;
+                }
+            }
+        }
+        if (found === 0) {
+            /* Cannot happen for a node of a boundary face, and if it ever does, the node's own grid
+               position is the honest answer rather than a division by zero. */
+            positions[at * 3] = minX + ix * cell;
+            positions[at * 3 + 1] = minY + iy * cell;
+            positions[at * 3 + 2] = minZ + iz * cell;
+            normals[at * 3 + 1] = 1;
+            continue;
+        }
+        px /= found;
+        py /= found;
+        pz /= found;
+        /*
+         * How much the cells around this node agree about which way the surface faces, which is the
+         * sum of unit facings over their count: one when they all agree, zero when they cancel.
+         *
+         * **A node that has no agreed facing is left exactly where it is**, and that is what keeps a
+         * thin feature intact. A wing mirror or a spoiler thinner than a cell has both of its faces
+         * inside the same cells, so there is no side to be behind, and pushing along whichever
+         * direction the arithmetic happened to produce would slide the outline off the part it
+         * stands for.
+         */
+        const agreement = Math.hypot(nxs, nys, nzs) / found;
+        const length = Math.hypot(nxs, nys, nzs);
+        if (length > 1e-6) {
+            nxs /= length;
+            nys /= length;
+            nzs /= length;
+        }
+        else {
+            nxs = 0;
+            nys = 1;
+            nzs = 0;
+        }
+        /*
+         * **How far back this node has to sit, measured against the surfaces around it.**
+         *
+         * The outline stays on screen while the real parts land on top of it, so anywhere it ends up
+         * in *front* of the surface it stands for, it shows through the finished model. A constant
+         * cannot do this job: a smooth panel needs almost nothing and a concave crease needs most of
+         * a cell, because a node there averages two surfaces and lands in the air between them.
+         *
+         * So each surrounding cell states a plane and the node has to end up behind all of them. For
+         * a plane at `q` facing `m`, a node at `c - t·n` is behind it while
+         * `dot(c - q, m) <= t·dot(n, m)`, so the cell demands `t >= dot(c - q, m) / dot(n, m)` and
+         * the node takes the largest demand made of it. A cell facing nearly across the direction of
+         * travel is skipped rather than honoured: dividing by an alignment approaching zero asks for
+         * an unbounded push to clear a surface this node is sliding along rather than facing.
+         */
+        let behind = 0;
+        if (agreement >= DIRECTED) {
+            for (let plane = 0; plane + 5 < planes.length; plane += 6) {
+                const mx = planes[plane + 3];
+                const my = planes[plane + 4];
+                const mz = planes[plane + 5];
+                const align = nxs * mx + nys * my + nzs * mz;
+                if (align < MIN_ALIGN)
+                    continue;
+                const overshoot = (px - planes[plane]) * mx +
+                    (py - planes[plane + 1]) * my +
+                    (pz - planes[plane + 2]) * mz;
+                if (overshoot <= 0)
+                    continue;
+                const need = overshoot / align;
+                if (need > behind)
+                    behind = need;
+            }
+            /* Capped at a cell: a larger demand comes from a fold narrower than the grid, where no
+               position clears every surface at once, and honouring it would tear the hull. */
+            behind = Math.min(behind, cell);
+            /*
+             * **And bounded by the cells the asset actually occupies, which is the half that had to be
+             * measured to be found.** A demand comes from whichever surfaces happen to sit in the cells
+             * around a node, and a cell whose only surface is an interior lining facing downward
+             * demands a push *upward* — so the outline ended up standing 0.14 m above the roof of a car
+             * 1.49 m tall, which is 0.92 of a cell and was visible as a shape floating over the model.
+             *
+             * A push that leaves the occupied region is not a push behind anything, so it is halved
+             * until it lands inside or given up. The margin below is applied regardless, because at 0.3
+             * of a cell it is small enough to be worth the certainty of never coinciding with the
+             * surface it hides under.
+             */
+            for (let tries = 0; tries < 4 && behind > 0; tries++) {
+                if (holdsPoint(px - nxs * behind, py - nys * behind, pz - nzs * behind))
+                    break;
+                behind = tries === 3 ? 0 : behind / 2;
+            }
+            /*
+             * The **demand** is bounded by occupancy and the margin is not, which is a deliberate split
+             * and the only one that serves both shapes this has to handle. A car is a shell inside a
+             * volume of parts, where a large push that leaves the occupied cells is going the wrong way.
+             * A bare floor meeting a bare wall is a shell and nothing else, where the push that clears
+             * both surfaces *has* to leave the two cells holding them — there is no solid to stay in.
+             * Bounding the demand fixes the first and bounding the margin as well would break the
+             * second, so the margin stays free at 0.3 of a cell.
+             */
+            behind += inset * cell;
+        }
+        positions[at * 3] = px - nxs * behind;
+        positions[at * 3 + 1] = py - nys * behind;
+        positions[at * 3 + 2] = pz - nzs * behind;
+        normals[at * 3] = nxs;
+        normals[at * 3 + 1] = nys;
+        normals[at * 3 + 2] = nzs;
+        colors[at * 3] = r / found;
+        colors[at * 3 + 1] = g / found;
+        colors[at * 3 + 2] = b / found;
+        emissive[at] = glow / found;
+    }
+    /*
+     * The four mandatory attributes and nothing else, deliberately.
+     *
+     * Colour is carried because a grey outline of a painted model is a worse first frame than no
+     * outline at all, and emissive because a lamp that glows in the model should glow in its
+     * outline. Everything optional is left absent, so the engine's own constants apply and the
+     * chunk stays small: a level of detail is a *silhouette*, and spending bytes on the roughness
+     * of a surface nobody will look at for half a second is the opposite of the point.
+     */
+    return { positions, normals, colors, emissive, indices: new Uint32Array(triangles) };
+}

package/dist/dds.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DDS surfaces to RGBA: BC1, BC2, BC3 and BC5 in either header spelling, and the uncompressed
+ * layouts, by the masks their own header carries.
+ *
+ * **It exists because a third of a shipped vehicle's textures are in it.** The car this was built
+ * against carries 81 textures and 34 of them are DDS — 25 DXT5 and 9 DXT1 — which are its paint,
+ * its interior and most of its normal maps. `imageInfo.ts` identifies PNG, JPEG and WEBP, so
+ * without this the model imports correctly shaped and visibly half-painted.
+ *
+ * **It runs in the baker and never in a frame.** RGBA is larger than the compressed source it came
+ * from, and the bake re-encodes to whatever the texture pipeline wants; nothing ships a block
+ * decoder into a running game. That is what makes the cost acceptable and it is the only reason
+ * decoding to RGBA rather than uploading the blocks directly is the right call here.
+ *
+ * **Only the mips are dropped, deliberately.** A DDS carries a full chain and the container
+ * generates its own, so decoding level 0 and discarding the rest is not a loss — it is declining
+ * to carry two answers to the same question.
+ *
+ * **Both header spellings, as of 3.30.2.** A `DX10` header names the format in a 20-byte extension
+ * rather than in the four characters at byte 84, and the blocks behind it are the same blocks. This
+ * reader took the classic spelling and refused the other, which cost one consumer 20 textures of a
+ * single car — its paint, its wheels, its lamps, its plate and seven interior maps — and cost them
+ * as a *lighting* bug rather than as a missing texture: their baker substitutes a 1x1 white pixel,
+ * and white in an ORM map is roughness 1 **and** metallic 1, which in the flat shader leaves no
+ * diffuse and no sun term at all. The bodywork became a blurred mirror of the field it was parked
+ * in, and the report said so in those words.
+ *
+ * What it refuses, by name: BC7, BC6H, BC4, signed BC5, cube maps, arrays and volumes. A format
+ * identified and declined is worth more than one half-decoded, which is `recognise.ts`'s principle
+ * applied one level down — and the last three of those are refused *because* a classic header has
+ * no way to state them, so accepting one would answer with a picture instead of an error.
+ */
+/** Whether these bytes are a DDS at all. The magic, and nothing inferred from a file name. */
+export declare function isDds(bytes: Uint8Array): boolean;
+/** What a decoded surface is: level 0, RGBA, eight bits a channel. */
+export interface DdsImage {
+    readonly width: number;
+    readonly height: number;
+    readonly rgba: Uint8Array;
+}
+export declare function ddsToRgba(bytes: Uint8Array): DdsImage;