@driftengine/core 3.61.0

package/dist/render/backend/webgl2/skinPaletteTexture.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The joint palette as a one-row `RGBA32F` texture, on WebGL2.
+ *
+ * Its own module rather than more lines in a 5,000-line renderer, and because the decision it
+ * implements — width, cap, unit — lives in `skinPalette.ts` where both backends read it, per the
+ * 2026-08-13 rule. This is only the binding half.
+ *
+ * **One storage level and `NEAREST` both filters, so there is no mip to select.** That is what
+ * makes `texelFetch` in the vertex stage honest: an integer coordinate, no level inferred, and
+ * nothing for the 2026-08-07 derivative rule to govern — the same property `pointShadowMap.ts`
+ * records for its own allocation.
+ *
+ * `RGBA32F` is a sized internal format WebGL2 core accepts for `texStorage2D`. It is not
+ * texture-filterable without an extension, which costs nothing here because nothing filters it.
+ */
+export declare class SkinPaletteTexture {
+    private texture;
+    private joints;
+    /**
+     * Upload a palette, reallocating only when the joint count changes.
+     *
+     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
+     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
+     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     */
+    update(gl: WebGL2RenderingContext, palette: Float32Array): void;
+    /** Bind to a **vertex-stage** unit. See `SKIN_PALETTE_TEXTURE_UNIT` for why that is free. */
+    bind(gl: WebGL2RenderingContext, unit: number): void;
+    /** Whether anything has been uploaded, which is what decides the skinned draw path. */
+    get ready(): boolean;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/backend/webgl2/skinPaletteTexture.js

@@ -0,0 +1,68 @@
+import { paletteTextureWidth, validateSkinPalette } from '../../skinPalette.js';
+/**
+ * The joint palette as a one-row `RGBA32F` texture, on WebGL2.
+ *
+ * Its own module rather than more lines in a 5,000-line renderer, and because the decision it
+ * implements — width, cap, unit — lives in `skinPalette.ts` where both backends read it, per the
+ * 2026-08-13 rule. This is only the binding half.
+ *
+ * **One storage level and `NEAREST` both filters, so there is no mip to select.** That is what
+ * makes `texelFetch` in the vertex stage honest: an integer coordinate, no level inferred, and
+ * nothing for the 2026-08-07 derivative rule to govern — the same property `pointShadowMap.ts`
+ * records for its own allocation.
+ *
+ * `RGBA32F` is a sized internal format WebGL2 core accepts for `texStorage2D`. It is not
+ * texture-filterable without an extension, which costs nothing here because nothing filters it.
+ */
+export class SkinPaletteTexture {
+    texture = null;
+    joints = 0;
+    /**
+     * Upload a palette, reallocating only when the joint count changes.
+     *
+     * A rig's joint count is fixed for its life, so the reallocation path runs once per skeleton and
+     * the steady state is one `texSubImage2D`. Reallocating per frame would be a GPU allocation in
+     * the frame loop, which is the same class of mistake as allocating on the CPU there.
+     */
+    update(gl, palette) {
+        validateSkinPalette(palette);
+        const joints = palette.length / 16;
+        const width = paletteTextureWidth(joints);
+        if (this.texture === null || this.joints !== joints) {
+            if (this.texture !== null)
+                gl.deleteTexture(this.texture);
+            const created = gl.createTexture();
+            if (created === null)
+                throw new Error('skin palette: failed to create the palette texture');
+            this.texture = created;
+            this.joints = joints;
+            gl.bindTexture(gl.TEXTURE_2D, created);
+            gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA32F, width, 1);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        }
+        else {
+            gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        }
+        gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, width, 1, gl.RGBA, gl.FLOAT, palette);
+    }
+    /** Bind to a **vertex-stage** unit. See `SKIN_PALETTE_TEXTURE_UNIT` for why that is free. */
+    bind(gl, unit) {
+        if (this.texture === null)
+            return;
+        gl.activeTexture(gl.TEXTURE0 + unit);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    }
+    /** Whether anything has been uploaded, which is what decides the skinned draw path. */
+    get ready() {
+        return this.texture !== null;
+    }
+    dispose(gl) {
+        if (this.texture !== null)
+            gl.deleteTexture(this.texture);
+        this.texture = null;
+        this.joints = 0;
+    }
+}

package/dist/render/backend/webgpu/boltPass.d.ts

@@ -0,0 +1,42 @@
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The bolt pass: a pool of electrical arcs, four vertices a segment.
+ *
+ * **The only pass here whose vertex buffers change every frame.** Plumes, scatter, water and the
+ * flock upload once and animate in the shader; an arc's endpoints are the simulation's output
+ * and arrive per frame, so three of the four streams are written on each draw. The staging
+ * arrays are allocated with the batch, which is what keeps the frame loop allocation-free.
+ */
+export declare const BOLT_VERT_FIELDS: UniformFields;
+export declare const BOLT_VERT_SIZE: 96;
+export declare const BOLT_FRAG_FIELDS: UniformFields;
+export declare const BOLT_FRAG_SIZE: 128;
+/** A batch of arcs on the device, behind the surface's opaque handle. */
+export interface GpuBolts {
+    readonly fromBuffer: GPUBuffer;
+    readonly toBuffer: GPUBuffer;
+    readonly corners: GPUBuffer;
+    readonly arcBuffer: GPUBuffer;
+    readonly indices: GPUBuffer;
+    readonly capacity: number;
+    /** Staging, expanded from the pool's per-segment arrays to per-vertex ones. */
+    readonly from: Float32Array;
+    readonly to: Float32Array;
+    readonly arc: Float32Array;
+    dispose(): void;
+}
+export declare function createGpuBolts(device: GPUDevice, capacity: number, label: string): GpuBolts;
+/** `aFrom`, `aTo`, `aCorner`, `aArc` — one buffer each, at the locations `bolt.ts` declares. */
+export declare function boltVertexLayouts(): GPUVertexBufferLayout[];
+export declare function createBoltBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createBoltBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * **Additive, depth tested, depth not written, nothing culled** — the same shape every emissive
+ * effect here takes, and for the same reason `plumePass` gives: an arc adds light to what is
+ * behind it, so a one-minus-alpha destination factor would make a bright filament darken the
+ * wall behind it, and writing depth would let it occlude whatever is drawn next.
+ */
+export declare function boltPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

package/dist/render/backend/webgpu/boltPass.js

@@ -0,0 +1,160 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { BOLT_BINDINGS, BOLT_FRAG_WGSL, BOLT_VERT_WGSL, } from '../../shaders/generated/bolt.wgsl.js';
+import { buildSegmentQuads } from '../../segmentQuads.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The bolt pass: a pool of electrical arcs, four vertices a segment.
+ *
+ * **The only pass here whose vertex buffers change every frame.** Plumes, scatter, water and the
+ * flock upload once and animate in the shader; an arc's endpoints are the simulation's output
+ * and arrive per frame, so three of the four streams are written on each draw. The staging
+ * arrays are allocated with the batch, which is what keeps the frame loop allocation-free.
+ */
+export const BOLT_VERT_FIELDS = BOLT_BINDINGS.BOLT_VERT.fields;
+export const BOLT_VERT_SIZE = BOLT_BINDINGS.BOLT_VERT.uniformSize;
+export const BOLT_FRAG_FIELDS = BOLT_BINDINGS.BOLT_FRAG.fields;
+export const BOLT_FRAG_SIZE = BOLT_BINDINGS.BOLT_FRAG.uniformSize;
+const VERT_BINDING = BOLT_BINDINGS.BOLT_VERT.uniforms;
+const FRAG_BINDING = BOLT_BINDINGS.BOLT_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+export function createGpuBolts(device, capacity, label) {
+    const verts = capacity * 4;
+    const geometry = buildSegmentQuads(capacity);
+    const dynamic = (floats, name) => device.createBuffer({
+        label: `${label}.${name}`,
+        size: Math.max(4, floats * 4),
+        usage: USAGE_VERTEX,
+    });
+    const fromBuffer = dynamic(verts * 3, 'from');
+    const toBuffer = dynamic(verts * 3, 'to');
+    const arcBuffer = dynamic(verts * 4, 'arc');
+    const corners = device.createBuffer({
+        label: `${label}.corners`,
+        size: Math.max(4, geometry.corners.byteLength),
+        usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(corners, 0, geometry.corners);
+    const indices = device.createBuffer({
+        label: `${label}.indices`,
+        size: Math.max(4, geometry.indices.byteLength),
+        usage: USAGE_INDEX,
+    });
+    device.queue.writeBuffer(indices, 0, geometry.indices);
+    return {
+        fromBuffer,
+        toBuffer,
+        corners,
+        arcBuffer,
+        indices,
+        capacity,
+        from: new Float32Array(verts * 3),
+        to: new Float32Array(verts * 3),
+        arc: new Float32Array(verts * 4),
+        dispose() {
+            fromBuffer.destroy();
+            toBuffer.destroy();
+            corners.destroy();
+            arcBuffer.destroy();
+            indices.destroy();
+        },
+    };
+}
+/** `aFrom`, `aTo`, `aCorner`, `aArc` — one buffer each, at the locations `bolt.ts` declares. */
+export function boltVertexLayouts() {
+    return [
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' }],
+        },
+        {
+            arrayStride: 16,
+            attributes: [{ shaderLocation: 3, offset: 0, format: 'float32x4' }],
+        },
+    ];
+}
+export function createBoltBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'bolt.layout',
+        entries: [
+            /*
+             * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+             *
+             * With one buffer rewritten between draws, every batch reads whatever was written last:
+             * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+             * every one of them. The picture is each batch wearing the last one's colour, width, time
+             * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+             * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+             * nothing drew two, which is exactly how water kept it for eight releases.
+             *
+             * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+             */
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: BOLT_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: BOLT_FRAG_SIZE },
+            },
+        ],
+    });
+}
+export function createBoltBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'bolt.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: BOLT_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: BOLT_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Additive, depth tested, depth not written, nothing culled** — the same shape every emissive
+ * effect here takes, and for the same reason `plumePass` gives: an arc adds light to what is
+ * behind it, so a one-minus-alpha destination factor would make a bright filament darken the
+ * wall behind it, and writing depth would let it occlude whatever is drawn next.
+ */
+export function boltPipeline(cache, device, layout) {
+    return cache.get('bolt', () => ({
+        label: 'bolt',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'bolt.vert', code: BOLT_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: boltVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'bolt.frag', code: BOLT_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: {
+                        color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                        alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

package/dist/render/backend/webgpu/buffers.d.ts

@@ -0,0 +1,159 @@
+import type { Bounds } from '../../../math/bounds.ts';
+import { MorphTexture } from './morphTexture.ts';
+import type { MeshData } from '../../mesh.ts';
+/** One attribute of the flat vertex format, in the order and at the locations the shaders use. */
+export interface VertexAttribute {
+    readonly name: keyof MeshData | 'positions';
+    readonly shaderLocation: number;
+    readonly format: GPUVertexFormat;
+    /** Floats per vertex. */
+    readonly components: number;
+    /** Whether a mesh may omit it, in which case a constant stands in. */
+    readonly optional: boolean;
+}
+/**
+ * Locations 0–9, matching `ATTR_POSITION` … `ATTR_RELIEF` in `mesh.ts`.
+ *
+ * **All ten, not the four that a simple mesh supplies.** WebGL2 lets the pipeline ignore an
+ * attribute the shader declares but the mesh omits; WebGPU validates the whole vertex state
+ * against the shader module and rejects the pipeline outright:
+ *
+ *     Vertex attribute slot 9 used in [flat.vert] is not present in the VertexState
+ *
+ * Six were listed here first, because six is what `Mesh` names in the obvious place. The
+ * shader declares ten, and the four extra are exactly the ones added late enough to be easy
+ * to miss: emissive colour, roughness, grain and relief.
+ */
+export declare const VERTEX_LAYOUT: readonly VertexAttribute[];
+/** Geometry on the device, with the buffers bound in layout order. */
+export interface GpuMesh {
+    /** One buffer per attribute, indexed by position in `VERTEX_LAYOUT`. */
+    readonly vertexBuffers: readonly GPUBuffer[];
+    readonly indexBuffer: GPUBuffer;
+    readonly indexCount: number;
+    /**
+     * How big this mesh is, in its own space.
+     *
+     * Measured here because the positions are already in hand: an upload walks them anyway, so a
+     * caller gets bounds for nothing and no `MeshData` producer has to supply them. Everything
+     * that wants to know whether this is on screen starts from this object.
+     */
+    readonly bounds: Bounds;
+    /**
+     * Whether all of this mesh's geometry has reached the device.
+     *
+     * False only between the steps of an incremental upload; a mesh made by `createGpuMesh` is
+     * complete before the call returns. **`submitMesh` refuses to draw an incomplete one**, and
+     * that refusal is the contract: the alternative — drawing what has landed — is a mesh whose
+     * triangle count grows over several frames, which is a worse artefact than a square that is
+     * briefly not there. A consumer that never drives the iterator therefore sees nothing rather
+     * than a fan of triangles through the origin.
+     *
+     * It is also how an abandoned upload is told from a finished one: a lost device ends the
+     * iterator, and a mesh that is done but not complete is one whose geometry never arrived.
+     */
+    readonly complete: boolean;
+    /**
+     * Whether this mesh carries a tangent frame.
+     *
+     * WebGPU has no disabled attribute, so location 10 is always backed — by the caller's data or by
+     * the constant buffer. That makes the binding indistinguishable from a real frame, exactly as it
+     * is on WebGL2, so the fact travels beside the mesh rather than being read off the GPU.
+     */
+    readonly hasTangents: boolean;
+    /**
+     * Whether this mesh carries a rig, which decides the vertex variant a draw takes.
+     *
+     * The twin of `Mesh.isSkinned` on the other backend. Recorded at upload rather than derived at
+     * draw time from the `present` map, because the draw needs it to build its pipeline *key* — and
+     * the key is built before the present map is consulted.
+     */
+    readonly isSkinned: boolean;
+    /**
+     * Whether this mesh carries the per-vertex channel, which an instanced draw cannot.
+     *
+     * The twin of `MeshData.channel !== undefined` on the other backend, where `InstancedMesh`
+     * refuses it at construction. Recorded rather than derived at draw time for the same reason
+     * `isSkinned` is: the refusal happens at `createInstanced`, which holds the mesh and not the
+     * data it was built from.
+     */
+    readonly hasChannel: boolean;
+    /**
+     * This mesh's morph deltas, or null for geometry that does not deform.
+     *
+     * Owned by the mesh for the reason the WebGL2 twin gives: deltas are geometry and never change,
+     * where a palette belongs to a pose. Only the weights are per-draw state.
+     */
+    readonly morph: MorphTexture | null;
+    /**
+     * Rewrite this mesh's positions, and its normals where the caller has them.
+     *
+     * Absent unless the mesh was created `dynamic`. **This backend interleaves every attribute into
+     * one buffer**, so a position is not contiguous with the next one — writing them individually
+     * would be one `writeBuffer` per vertex. So a dynamic mesh keeps the interleaved array it was
+     * built from, patches the two fields that move, and uploads the lot in one call. The cost is
+     * one CPU-side copy of the vertex data per dynamic mesh, which is why the flag exists rather
+     * than every mesh paying it.
+     */
+    readonly update: ((device: GPUDevice, positions: Float32Array, normals?: Float32Array) => void) | null;
+    dispose(): void;
+}
+/** A mesh on its way to the device, and the iterator that gets it there. */
+export interface IncrementalGpuMesh {
+    /**
+     * Usable at once — it can be held, measured and disposed — but not drawable until the upload
+     * finishes. See `GpuMesh.complete`.
+     */
+    readonly mesh: GpuMesh;
+    /**
+     * Advance the upload by one bounded step. Done when it returns `done`.
+     *
+     * The call that returns `done` is the one that does the last step's work, not an empty call
+     * after it, so a mesh of *n* chunks takes exactly *n* calls and a caller counting stops counts
+     * the right number.
+     */
+    readonly upload: Iterator<void, void>;
+}
+/**
+ * Upload a mesh, all of it, now.
+ *
+ * The whole of `createGpuMeshIncremental` driven to the end in one call — deliberately, so the
+ * two paths cannot write different bytes. The one that spreads the work is the one with the
+ * interesting decisions in it; read that.
+ */
+export declare function createGpuMesh(device: GPUDevice, data: MeshData, dynamic?: boolean): GpuMesh;
+/**
+ * Upload a mesh over as many frames as the caller gives it.
+ *
+ * **The absent-attribute trick is the interesting part.** WebGL2 lets an attribute be
+ * *disabled* and read a constant the driver supplies, which is why `mesh.ts` can leave
+ * `specular` and `uvs` off entirely and a world with no shiny or textured geometry uploads
+ * nothing for them. WebGPU has no disabled attribute: every location in a vertex layout must
+ * be backed by a buffer.
+ *
+ * `arrayStride: 0` is the equivalent and it is exact. A stride of zero means every vertex
+ * reads element zero, so a one-element buffer of zeroes serves a mesh of any size. Eight
+ * bytes, allocated per mesh that omits the attribute, and **no shader variant** — which is
+ * what keeps both backends drawing from one generated set of WGSL instead of two.
+ *
+ * **Why the work is divisible here and not on the other backend.** This one interleaves every
+ * vertex on the CPU into a new array before it writes anything, where `mesh.ts` skips the
+ * interleave in favour of three tight buffers and says so in its first line. So the cost is
+ * WebGPU's alone and proportional to geometry, which is why a consumer measured the same drive
+ * as smooth on WebGL2 and hitching here.
+ *
+ * **What is paid at creation and not spread:** validation, the bounds, the allocation of the
+ * interleave array, the three buffers, and the constants. The bounds are the deliberate one — a
+ * streamer places and culls a region from them before a byte of it has landed, so a handle whose
+ * bounds were not yet known would not be usable at once, which is the whole promise here.
+ */
+export declare function createGpuMeshIncremental(device: GPUDevice, data: MeshData, dynamic?: boolean): IncrementalGpuMesh;
+export declare function vertexBufferLayouts(present: Readonly<Record<string, boolean>>, 
+/**
+ * Whether a third buffer carries one placement and colour per instance.
+ *
+ * Appended rather than woven in, at `stepMode: 'instance'`, so an instanced pipeline binds the
+ * mesh's own two buffers unchanged and its batch's third. The flat pipeline binds two of a
+ * limit of eight, so there is room, and a mesh needs no second upload to be instanced.
+ */
+instanced?: boolean): GPUVertexBufferLayout[];