@driftengine/core 3.63.0 → 4.1.0

package/dist/render/gpudriven/pipeline.js

@@ -0,0 +1,237 @@
+/**
+ * The GPU-driven frame, as an order and a set of dependencies.
+ *
+ * **Every stage of Wave 2A exists on its own and this is what says how they fit together.** The
+ * frame's colour is cleared, the directional map is drawn, the meshes wholly outside the view are
+ * flagged, the cut through the cluster graph is chosen without them and phase one culls what was
+ * visible last frame, phase one draws, the depth pyramid is reduced from that, phase two culls the
+ * rest against it and draws, the visibility is copied where a dispatch can read it, binned by
+ * material, and each bin is shaded. Twelve stages, and the edges between them are what stop a
+ * scheduler reordering the ones that must not move — see `twoPhase.ts` for the one that matters
+ * most.
+ *
+ * **The pipeline is opt-in and WebGPU only.** `gpuDrivenSupported` is `indirectSupport`, which is
+ * false on WebGL2 and not a thing a fallback can paper over: without an indirect draw the counts
+ * this frame produces would have to come back to the processor, and a readback is slower than the
+ * draw it would replace. Selecting it on a backend that cannot run it **fails at creation** rather
+ * than falling back, because a silent fallback means a consumer ships believing they have a
+ * pipeline they do not.
+ *
+ * **This is what `GpuDrivenPass` is scheduled by**, since 2026-09-17: the pass records these stages
+ * into a `Deps` table each frame, `scheduleGraph` decides which of them run, and the pass encodes
+ * the ones it kept in the order it kept them. Until then this was a description beside an encoder
+ * with its own fixed order — and the description had drifted, naming a separate instance cull the
+ * encoder never had and a colour both draws wrote when neither does. The instance cull is a stage
+ * of the encoder now, 2026-09-17, which is `wave2a`'s fifth task finally reaching the frame. Binding real buffers and
+ * issuing real dispatches stays the backend's; what moved here is the decision about what runs.
+ */
+import { indirectSupport } from '../backend/api.js';
+import { recordDeps } from '../frame/deps.js';
+/** Whether a backend can run this pipeline at all. */
+export function gpuDrivenSupported(backend) {
+    return indirectSupport(backend);
+}
+/**
+ * Why a backend cannot, in the words a consumer sees.
+ *
+ * A sentence rather than a code, because the one thing the reader needs is that this is a property
+ * of the backend and not of their scene — and `''` where it can.
+ */
+export function gpuDrivenRefusal(backend) {
+    if (gpuDrivenSupported(backend))
+        return '';
+    return (`the gpu-driven pipeline needs indirect draws and dispatches, which ${backend} does not have. ` +
+        'Emulating them through a readback is slower than the draw it would replace, so this fails ' +
+        'rather than falling back: a silent fallback ships a consumer a pipeline they do not have.');
+}
+/** The identifiers one frame uses. A frame is its own graph, so they start at zero. */
+export const GPU_DRIVEN_RESOURCES = {
+    clusters: 0,
+    history: 1,
+    shadowMap: 2,
+    cut: 3,
+    keep: 4,
+    listOne: 5,
+    listTwo: 6,
+    drawn: 7,
+    depth: 8,
+    visibility: 9,
+    visibilityCopy: 10,
+    hzb: 11,
+    binCounts: 12,
+    binOffsets: 13,
+    binCursors: 14,
+    binPixels: 15,
+    colour: 16,
+    instances: 17,
+    blendList: 18,
+    oitAccum: 19,
+    oitReveal: 20,
+};
+/**
+ * What each stage is called, in the order they are recorded — one render or compute pass each, or
+ * one copy between them.
+ */
+export const GPU_DRIVEN_PASSES = [
+    'clearColour',
+    'shadow',
+    'instanceCull',
+    'cut',
+    'phaseOneDraw',
+    'pyramid',
+    'phaseTwoCull',
+    'phaseTwoDraw',
+    'blendCull',
+    'blendDraw',
+    'visibilityCopy',
+    'bin',
+    'cursorCopy',
+    'shade',
+    'blendResolve',
+];
+/**
+ * **Every stage is ordered, so none merges with a neighbour.** Two adjacent compute stages could
+ * share a pass as far as their results go; they do not, because each is bracketed by its own pair
+ * of timestamps and a pair brackets a pass. What the schedule decides here is which stages run,
+ * and it checks the order the names give against the edges the stages declare.
+ */
+export const GPU_DRIVEN_ORDERED = new Uint8Array(GPU_DRIVEN_PASSES.length).fill(1);
+/**
+ * The frame's edges, stage by stage. The claim is here, and five parts of it are load-bearing
+ * enough to name:
+ *
+ * - `cut` reads the flags `instanceCull` wrote, so a mesh wholly outside the view has its clusters
+ *   left out of the cut before the cluster cull or the compaction reads one of them.
+ * - `pyramid` reads the depth `phaseOneDraw` wrote, and `phaseTwoCull` reads the pyramid. Together
+ *   those are "the occlusion is tested against depth from this frame", which is the whole reason
+ *   the frame has two halves — and `cut` reads no pyramid at all, which is the other half of it.
+ * - `cut` and `phaseTwoCull` both read the history and both write the next one: the history
+ *   decides which half judges a cluster, never whether one does.
+ * - `cursorCopy` reads the offsets `bin` wrote and `shade` reads the cursors. The scatter cannot
+ *   start before the sum has, and neither ordering is a comment anybody has to obey.
+ * - `shade` reads the map only where the frame is shadowed — `unshadowedShade` — so an unshadowed
+ *   frame's map is something nothing reads, and `scheduleGraph` culls the stage that draws it.
+ */
+function edgesFor(res) {
+    const table = {
+        clearColour: [[], [res.colour]],
+        shadow: [[res.clusters], [res.shadowMap]],
+        instanceCull: [[res.clusters], [res.instances]],
+        cut: [
+            [res.clusters, res.history, res.instances],
+            [res.cut, res.keep, res.listOne, res.drawn],
+        ],
+        phaseOneDraw: [
+            [res.listOne, res.clusters],
+            [res.depth, res.visibility],
+        ],
+        pyramid: [[res.depth], [res.hzb]],
+        phaseTwoCull: [
+            [res.hzb, res.cut, res.clusters, res.history],
+            [res.keep, res.listTwo, res.drawn],
+        ],
+        phaseTwoDraw: [
+            [res.listTwo, res.clusters, res.depth, res.visibility],
+            [res.depth, res.visibility],
+        ],
+        /*
+         * **The cut's second run, over the other half of the scene.** It reads what the first run read
+         * and writes the same working buffers, which is safe because it runs after both draws have
+         * taken what they needed from them — and it writes a list of its own, which is what the blended
+         * draw reads. It reads the pyramid too: a pane wholly behind a wall is occluded exactly as an
+         * opaque cluster there would be.
+         */
+        blendCull: [
+            [res.clusters, res.instances, res.hzb],
+            [res.cut, res.keep, res.blendList],
+        ],
+        /*
+         * **It reads the depth the opaque half wrote and does not write it.** A pane behind a wall is
+         * rejected at the wall; nothing here writes depth, so two panes do not hide each other and
+         * there is something left to blend.
+         */
+        blendDraw: [
+            [res.blendList, res.clusters, res.depth],
+            [res.oitAccum, res.oitReveal],
+        ],
+        visibilityCopy: [[res.visibility], [res.visibilityCopy]],
+        bin: [[res.visibilityCopy], [res.binCounts, res.binOffsets]],
+        cursorCopy: [[res.binOffsets], [res.binCursors]],
+        shade: [
+            [res.visibilityCopy, res.binOffsets, res.binCursors, res.clusters, res.colour, res.shadowMap],
+            [res.binPixels, res.colour],
+        ],
+        /*
+         * **After the shading, because it composites over what the shading wrote.** The opaque picture
+         * is the background a transparent layer is blended against, so this is the last thing the
+         * frame does to its own colour target.
+         */
+        blendResolve: [[res.oitAccum, res.oitReveal, res.colour], [res.colour]],
+    };
+    return {
+        stages: GPU_DRIVEN_PASSES.map((name) => table[name]),
+        unshadowedShade: table.shade[0].filter((id) => id !== res.shadowMap),
+    };
+}
+/* Built once a resource table, so a frame records without constructing an edge list. */
+const EDGES = new WeakMap();
+const SHADE = GPU_DRIVEN_PASSES.indexOf('shade');
+/**
+ * The three stages a frame with nothing transparent does not record at all.
+ *
+ * **Culled by giving them no edges rather than by filtering a read**, which is how the shadow map
+ * is culled one line above and does not work here: `blendResolve` writes the colour, the colour is
+ * what the frame is kept alive for, so a stage that writes it survives any amount of filtering. A
+ * stage with no writes is read by nothing and the scheduler drops it, which is the same answer
+ * reached the only way that is true for this one.
+ */
+const BLEND_STAGES = [
+    GPU_DRIVEN_PASSES.indexOf('blendCull'),
+    GPU_DRIVEN_PASSES.indexOf('blendDraw'),
+    GPU_DRIVEN_PASSES.indexOf('blendResolve'),
+];
+const NOTHING = [];
+/**
+ * Record the whole frame, in order, and answer the index its first stage landed at.
+ *
+ * Allocates nothing once a resource table has been seen, which is what lets `GpuDrivenPass` call it
+ * every frame. Stage `i` of `GPU_DRIVEN_PASSES` is node `first + i`.
+ */
+export function recordGpuDrivenStages(deps, res, shape) {
+    let edges = EDGES.get(res);
+    if (edges === undefined) {
+        edges = edgesFor(res);
+        EDGES.set(res, edges);
+    }
+    const first = deps.count;
+    for (let stage = 0; stage < edges.stages.length; stage += 1) {
+        if (!shape.blended && BLEND_STAGES.includes(stage)) {
+            recordDeps(deps, NOTHING, NOTHING);
+            continue;
+        }
+        const [reads, writes] = edges.stages[stage];
+        recordDeps(deps, stage === SHADE && !shape.shadowed ? edges.unshadowedShade : reads, writes);
+    }
+    return first;
+}
+/** Record the whole frame and answer where each pass went, by name. For a reader, not a frame. */
+export function recordGpuDrivenFrame(deps, res, shape) {
+    const first = recordGpuDrivenStages(deps, res, shape);
+    return Object.fromEntries(GPU_DRIVEN_PASSES.map((name, index) => [name, first + index]));
+}
+/**
+ * What a frame leaves behind, which is what `scheduleGraph` is asked to keep alive.
+ *
+ * The colour, which the blit presents, and the history, which next frame's phase one reads. The
+ * depth, the pyramid, the visibility buffer and every bin are this frame's working set and nothing
+ * outside reads them. Naming more than is needed keeps resources alive that could have been
+ * aliased — which is `alias.ts`'s whole subject — and naming fewer culls a pass that was doing
+ * something.
+ */
+export function gpuDrivenLive(res) {
+    return [res.colour, res.drawn];
+}
+/** What a frame reads without having written: the scene, and last frame's history. */
+export function gpuDrivenImports(res) {
+    return [res.clusters, res.history];
+}

package/dist/render/gpudriven/rangeAlloc.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A free list over one axis of units, and nothing else.
+ *
+ * **Four of these make a streaming scene** — vertices, indices, clusters and meshes — and none of
+ * them needs to know what a cluster is. Keeping it that way is what lets "a returned range is
+ * reusable" be a test that does not build a mesh.
+ *
+ * **Best fit rather than first fit**, because the workload that motivated this remeshes a chunk
+ * into a slightly different size on every block a player breaks. First fit hands the front of the
+ * largest hole to whatever asks next, so the large holes disappear first and the request that
+ * needed one is refused while the total says there is room.
+ *
+ * **Refusal is `-1` rather than an exception**, because a streaming consumer calls `claim` from a
+ * frame loop: an exception there is a crashed demo where a refusal is a chunk that arrives a frame
+ * later.
+ */
+export declare class RangeAlloc {
+    /**
+     * The free runs, kept sorted by `at` and never touching.
+     *
+     * **Sorted and coalesced is an invariant rather than a convenience**: it is what makes the
+     * layout independent of the order ranges were released in, which a capture would otherwise
+     * expose as an image that differs between runs with nothing failing.
+     */
+    private holes;
+    private readonly total;
+    private usedUnits;
+    private high;
+    constructor(capacity: number);
+    get capacity(): number;
+    get used(): number;
+    /** The most units ever live at once. `scripts/stream-fragmentation.mjs` reads this. */
+    get highWater(): number;
+    /**
+     * The first unit of a run of `units`, or -1 where no single run is long enough.
+     *
+     * A request for nothing succeeds at 0 and occupies nothing: a mesh with no clusters is legal,
+     * and `buildGpuDrivenScene`'s header says what dropping one would do to every mesh after it.
+     */
+    claim(units: number): number;
+    /**
+     * Give a run back, merging it with whatever it now touches.
+     *
+     * **Merged on the way in rather than swept later**, which is what keeps the invariant true at
+     * every moment a caller could look and makes the order releases arrived in stop mattering.
+     */
+    release(at: number, units: number): void;
+    /** Back to one free run, keeping the high-water mark, which is a record of the run so far. */
+    reset(): void;
+}

package/dist/render/gpudriven/rangeAlloc.js

@@ -0,0 +1,112 @@
+/**
+ * A free list over one axis of units, and nothing else.
+ *
+ * **Four of these make a streaming scene** — vertices, indices, clusters and meshes — and none of
+ * them needs to know what a cluster is. Keeping it that way is what lets "a returned range is
+ * reusable" be a test that does not build a mesh.
+ *
+ * **Best fit rather than first fit**, because the workload that motivated this remeshes a chunk
+ * into a slightly different size on every block a player breaks. First fit hands the front of the
+ * largest hole to whatever asks next, so the large holes disappear first and the request that
+ * needed one is refused while the total says there is room.
+ *
+ * **Refusal is `-1` rather than an exception**, because a streaming consumer calls `claim` from a
+ * frame loop: an exception there is a crashed demo where a refusal is a chunk that arrives a frame
+ * later.
+ */
+export class RangeAlloc {
+    /**
+     * The free runs, kept sorted by `at` and never touching.
+     *
+     * **Sorted and coalesced is an invariant rather than a convenience**: it is what makes the
+     * layout independent of the order ranges were released in, which a capture would otherwise
+     * expose as an image that differs between runs with nothing failing.
+     */
+    holes;
+    total;
+    usedUnits = 0;
+    high = 0;
+    constructor(capacity) {
+        const units = Math.max(0, Math.floor(capacity));
+        this.total = units;
+        this.holes = units > 0 ? [{ at: 0, units }] : [];
+    }
+    get capacity() {
+        return this.total;
+    }
+    get used() {
+        return this.usedUnits;
+    }
+    /** The most units ever live at once. `scripts/stream-fragmentation.mjs` reads this. */
+    get highWater() {
+        return this.high;
+    }
+    /**
+     * The first unit of a run of `units`, or -1 where no single run is long enough.
+     *
+     * A request for nothing succeeds at 0 and occupies nothing: a mesh with no clusters is legal,
+     * and `buildGpuDrivenScene`'s header says what dropping one would do to every mesh after it.
+     */
+    claim(units) {
+        const want = Math.max(0, Math.floor(units));
+        if (want === 0)
+            return 0;
+        let best = -1;
+        for (let i = 0; i < this.holes.length; i += 1) {
+            const hole = this.holes[i];
+            if (hole.units < want)
+                continue;
+            if (best < 0 || hole.units < this.holes[best].units)
+                best = i;
+        }
+        if (best < 0)
+            return -1;
+        const hole = this.holes[best];
+        const at = hole.at;
+        if (hole.units === want)
+            this.holes.splice(best, 1);
+        else {
+            hole.at += want;
+            hole.units -= want;
+        }
+        this.usedUnits += want;
+        if (this.usedUnits > this.high)
+            this.high = this.usedUnits;
+        return at;
+    }
+    /**
+     * Give a run back, merging it with whatever it now touches.
+     *
+     * **Merged on the way in rather than swept later**, which is what keeps the invariant true at
+     * every moment a caller could look and makes the order releases arrived in stop mattering.
+     */
+    release(at, units) {
+        const count = Math.max(0, Math.floor(units));
+        if (count === 0)
+            return;
+        const start = Math.max(0, Math.floor(at));
+        let index = 0;
+        while (index < this.holes.length && this.holes[index].at < start)
+            index += 1;
+        this.holes.splice(index, 0, { at: start, units: count });
+        this.usedUnits = Math.max(0, this.usedUnits - count);
+        /* Merge with the one before and the one after, in that order, so three runs become one. */
+        const previous = index > 0 ? this.holes[index - 1] : null;
+        if (previous !== null && previous.at + previous.units === start) {
+            previous.units += count;
+            this.holes.splice(index, 1);
+            index -= 1;
+        }
+        const merged = this.holes[index];
+        const next = index + 1 < this.holes.length ? this.holes[index + 1] : null;
+        if (next !== null && merged.at + merged.units === next.at) {
+            merged.units += next.units;
+            this.holes.splice(index + 1, 1);
+        }
+    }
+    /** Back to one free run, keeping the high-water mark, which is a record of the run so far. */
+    reset() {
+        this.holes = this.total > 0 ? [{ at: 0, units: this.total }] : [];
+        this.usedUnits = 0;
+    }
+}

package/dist/render/gpudriven/sceneUpload.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A scene's meshes packed into the one set of buffers a GPU-driven frame reads.
+ *
+ * **`clusterUpload.ts` packs the clusters and this packs everything they point at.** That split is
+ * not arbitrary: the cluster packing is about identifiers and spans and has no idea a vertex
+ * exists, and it rebases each mesh's index *offsets* by the indices already written while leaving
+ * the index *values* alone. Which is right — a mesh's indices address that mesh's vertices — and
+ * is exactly wrong the moment two meshes share one buffer, which is the whole point of the
+ * pipeline. Every mesh after the first would address vertex zero of the *scene*, a real vertex
+ * belonging to the first mesh, drawn in the wrong place with nothing reporting anything.
+ *
+ * So the rebasing happens here, where the vertex base is known, and the packer is handed sources
+ * whose indices are already scene-global.
+ *
+ * **Three parallel arrays rather than one interleaved vertex.** The raster shader reads
+ * `positions[index * 3]` and the shading pass reads normals and colours the same way; an
+ * interleaved stride would put the layout in three shaders instead of one place, and the memory
+ * this saves is not the memory the pipeline is short of.
+ *
+ * **Colour is a vertex attribute, because that is what this engine's geometry carries.**
+ * `MeshData` has `colors` and most of it is untextured, so the shading pass interpolates them the
+ * way the forward path does rather than inventing a material system to sit beside the one that
+ * exists. What a *material* then selects is the shading each bin gets — see `materialBin.ts` — and
+ * a mesh names one.
+ */
+import { type ClusterBuffers, type ClusterSource } from './clusterUpload.ts';
+/**
+ * Floats a vertex in the buffer the GPU-driven pass uploads: position, normal, colour, uv, glow.
+ *
+ * **One number read by four consumers** — the upload, the raster, the blended raster and the
+ * shading pass — and `vertexLayout.test.ts` holds all four to it. It was nine until UVs arrived on
+ * 2026-09-17, and eleven until the voxel sandbox's block light needed a glow a vertex on 2026-09-18.
+ */
+export declare const GPU_DRIVEN_VERTEX_FLOATS = 12;
+/** One mesh of a GPU-driven scene: its vertices, its clusters, and which material shades it. */
+export interface GpuDrivenMesh {
+    /** Three floats a vertex. */
+    readonly positions: Float32Array;
+    /** Three floats a vertex. */
+    readonly normals: Float32Array;
+    /** Three floats a vertex. */
+    readonly colours: Float32Array;
+    /**
+     * Two floats a vertex. Optional: a mesh without them uploads zeros, and a textured material on
+     * it reads one texel everywhere and turns no normal — a statement about the mesh, and what the
+     * forward path does with an absent attribute.
+     */
+    readonly uvs?: Float32Array;
+    /**
+     * One float a vertex, added to the material's own emissive. Optional: a mesh without it glows as
+     * its material says and nothing more, which is every mesh before 2026-09-18.
+     *
+     * **For light a colour cannot carry.** The voxel sandbox folds occlusion and sky light into the
+     * vertex colour and keeps block light here, because it has to survive the sun going down and a
+     * colour is multiplied by the sun. The forward path reads the same attribute from `MeshData`.
+     */
+    readonly emissive?: Float32Array;
+    /** This mesh's clusters, with indices addressing *this mesh's* vertices. */
+    readonly clusters: ClusterSource;
+    /** Which material bin every cluster of this mesh shades in. */
+    readonly material: number;
+}
+export interface GpuDrivenScene {
+    /** Every mesh's positions, concatenated in the order they were given. */
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly colours: Float32Array;
+    /** Two floats a vertex, zeros where a mesh carried none. */
+    readonly uvs: Float32Array;
+    /** One float a vertex, zeros where a mesh carried none. */
+    readonly emissive: Float32Array;
+    /** The clusters, with indices addressing `positions` rather than any one mesh. */
+    readonly clusters: ClusterBuffers;
+    /** One material a cluster, from the mesh it came from. */
+    readonly materialOf: Uint32Array;
+    /** Where each mesh's vertices begin. One entry a mesh, including meshes with no clusters. */
+    readonly vertexBase: Uint32Array;
+    readonly vertexCount: number;
+}
+/**
+ * A mesh's per-vertex glow, refused by name when it is not one float a vertex.
+ *
+ * Shared by both packers, because a glow of the wrong length read one float a vertex is somebody
+ * else's torchlight on the next mesh along — or `NaN` past the end, which lights nothing and says
+ * nothing about why.
+ */
+export declare function glowOf(mesh: GpuDrivenMesh, at: number | string): Float32Array | undefined;
+/**
+ * Pack a scene.
+ *
+ * **A mesh with no clusters still takes its slot**, in `vertexBase` and in the mesh numbering the
+ * clusters carry. `meshOf` indexes the caller's transform array, so dropping an empty mesh shifts
+ * every mesh after it and each of their clusters draws with somebody else's matrix — the same
+ * reasoning `packClusters` already gives, one level up.
+ */
+export declare function buildGpuDrivenScene(meshes: readonly GpuDrivenMesh[]): GpuDrivenScene;

package/dist/render/gpudriven/sceneUpload.js

@@ -0,0 +1,115 @@
+/**
+ * A scene's meshes packed into the one set of buffers a GPU-driven frame reads.
+ *
+ * **`clusterUpload.ts` packs the clusters and this packs everything they point at.** That split is
+ * not arbitrary: the cluster packing is about identifiers and spans and has no idea a vertex
+ * exists, and it rebases each mesh's index *offsets* by the indices already written while leaving
+ * the index *values* alone. Which is right — a mesh's indices address that mesh's vertices — and
+ * is exactly wrong the moment two meshes share one buffer, which is the whole point of the
+ * pipeline. Every mesh after the first would address vertex zero of the *scene*, a real vertex
+ * belonging to the first mesh, drawn in the wrong place with nothing reporting anything.
+ *
+ * So the rebasing happens here, where the vertex base is known, and the packer is handed sources
+ * whose indices are already scene-global.
+ *
+ * **Three parallel arrays rather than one interleaved vertex.** The raster shader reads
+ * `positions[index * 3]` and the shading pass reads normals and colours the same way; an
+ * interleaved stride would put the layout in three shaders instead of one place, and the memory
+ * this saves is not the memory the pipeline is short of.
+ *
+ * **Colour is a vertex attribute, because that is what this engine's geometry carries.**
+ * `MeshData` has `colors` and most of it is untextured, so the shading pass interpolates them the
+ * way the forward path does rather than inventing a material system to sit beside the one that
+ * exists. What a *material* then selects is the shading each bin gets — see `materialBin.ts` — and
+ * a mesh names one.
+ */
+import { packClusters } from './clusterUpload.js';
+/**
+ * Floats a vertex in the buffer the GPU-driven pass uploads: position, normal, colour, uv, glow.
+ *
+ * **One number read by four consumers** — the upload, the raster, the blended raster and the
+ * shading pass — and `vertexLayout.test.ts` holds all four to it. It was nine until UVs arrived on
+ * 2026-09-17, and eleven until the voxel sandbox's block light needed a glow a vertex on 2026-09-18.
+ */
+export const GPU_DRIVEN_VERTEX_FLOATS = 12;
+/**
+ * A mesh's per-vertex glow, refused by name when it is not one float a vertex.
+ *
+ * Shared by both packers, because a glow of the wrong length read one float a vertex is somebody
+ * else's torchlight on the next mesh along — or `NaN` past the end, which lights nothing and says
+ * nothing about why.
+ */
+export function glowOf(mesh, at) {
+    const glow = mesh.emissive;
+    if (glow === undefined)
+        return undefined;
+    const count = mesh.positions.length / 3;
+    if (glow.length !== count) {
+        throw new Error(`[driftengine] mesh ${at} carries ${glow.length} emissive values for ${count} vertices`);
+    }
+    return glow;
+}
+/**
+ * Pack a scene.
+ *
+ * **A mesh with no clusters still takes its slot**, in `vertexBase` and in the mesh numbering the
+ * clusters carry. `meshOf` indexes the caller's transform array, so dropping an empty mesh shifts
+ * every mesh after it and each of their clusters draws with somebody else's matrix — the same
+ * reasoning `packClusters` already gives, one level up.
+ */
+export function buildGpuDrivenScene(meshes) {
+    let vertices = 0;
+    let clusters = 0;
+    const vertexBase = new Uint32Array(meshes.length);
+    for (let at = 0; at < meshes.length; at += 1) {
+        const mesh = meshes[at];
+        vertexBase[at] = vertices;
+        vertices += mesh.positions.length / 3;
+        clusters += mesh.clusters.count;
+    }
+    const positions = new Float32Array(vertices * 3);
+    const normals = new Float32Array(vertices * 3);
+    const colours = new Float32Array(vertices * 3);
+    const uvs = new Float32Array(vertices * 2);
+    const emissive = new Float32Array(vertices);
+    const rebased = [];
+    const materialOf = new Uint32Array(clusters);
+    let cluster = 0;
+    for (let at = 0; at < meshes.length; at += 1) {
+        const mesh = meshes[at];
+        const base = vertexBase[at];
+        positions.set(mesh.positions, base * 3);
+        normals.set(mesh.normals, base * 3);
+        colours.set(mesh.colours, base * 3);
+        if (mesh.uvs !== undefined) {
+            const count = mesh.positions.length / 3;
+            if (mesh.uvs.length !== count * 2) {
+                throw new Error(`[driftengine] mesh ${at} carries ${mesh.uvs.length} uv values for ${count} vertices`);
+            }
+            uvs.set(mesh.uvs, base * 2);
+        }
+        const glow = glowOf(mesh, at);
+        if (glow !== undefined)
+            emissive.set(glow, base);
+        const indices = new Uint32Array(mesh.clusters.indices.length);
+        for (let i = 0; i < indices.length; i += 1) {
+            indices[i] = mesh.clusters.indices[i] + base;
+        }
+        rebased.push({ ...mesh.clusters, indices });
+        for (let c = 0; c < mesh.clusters.count; c += 1) {
+            materialOf[cluster] = mesh.material;
+            cluster += 1;
+        }
+    }
+    return {
+        positions,
+        normals,
+        colours,
+        uvs,
+        emissive,
+        clusters: packClusters(rebased),
+        materialOf,
+        vertexBase,
+        vertexCount: vertices,
+    };
+}