@driftengine/core 4.8.5 → 4.8.7

package/dist/render/lightBudget.d.ts

@@ -1,4 +1,3 @@
-/** Fixed point-light budget shared by CPU selection and the flat shader. */
 import type { AreaLightBuffer } from './areaLights.ts';
 import type { ResolvedAreaShadows } from './areaShadowSet.ts';
 /**
@@ -229,12 +228,21 @@ export declare const CLOTH_REST_TEXTURE_UNIT: number;
  */
 export declare const MODEL_MAP_TEXTURE_UNIT: number;
 /**
- * The two units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
+ * The units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
  * every unit a lit program binds, so spreading skin in the middle of a frame unbinds nothing the
  * draws after it sample. WebGL2 guarantees thirty-two.
  */
 export declare const SKIN_BLUR_TEXTURE_UNIT: number;
 export declare const SKIN_BLUR_DEPTH_UNIT: number;
+/** And the skin's colour, which the blur's second axis multiplies the spread light by. */
+export declare const SKIN_BLUR_ALBEDO_UNIT: number;
+/**
+ * A sprite particle's image and the frame's depth copy its soft edge reads, on WebGL2: past every
+ * unit a lit program binds, for the skin blur's reason — a particle is drawn in the middle of a
+ * frame, and the draws after it must find their textures where they left them.
+ */
+export declare const PARTICLE_SPRITE_UNIT: number;
+export declare const PARTICLE_DEPTH_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *
@@ -349,6 +357,22 @@ export interface PointLightSet {
      * drawn for one spot works in another with a different angle.
      */
     readonly lightCookies?: Float32Array;
+    /**
+     * One per light: the lighting channels it lights, as a bitmask in a float — 1, 2, 3 … 255.
+     * **Absent, or a short array, is channel 1 for every light**, which is every surface's default
+     * too, so a scene that never names a channel lights everything with everything as it did.
+     *
+     * A light shades a surface only where its mask and the surface's `SurfaceMaterial.lightChannels`
+     * share a bit. What it is for: a rig of lights that belongs to some draws and not others — a
+     * character's own key and rim lights, which the floor around the character must not take.
+     */
+    readonly lightChannels?: Float32Array;
+    /**
+     * One per light: its own falloff exponent, `(1 - (d/R)^2)^n` with no distance term, or 0 for the
+     * frame's falloff. **Absent, or a short array, is 0 for every light**, so a scene that names none
+     * falls off as it did. See `PointLightSource.falloffExponent`.
+     */
+    readonly lightFalloffExponents?: Float32Array;
 }
 /**
  * A cone that admits every direction, for every light.
@@ -416,6 +440,18 @@ export interface ResolvedPointLights {
     iesProfiles: Float32Array;
     iesAxes: Float32Array;
     cookies: Float32Array;
+    /**
+     * Owned, four a light: the photometric azimuth in xyz and the light's channels in w, which is how
+     * `uLightIesAxis` carries them — the channels in a lane the axis left, rather than in a uniform
+     * array of their own, which would cost a row a light of a budget that has none to give.
+     */
+    readonly axesAndChannels: Float32Array;
+    /**
+     * Owned, four a light: the cone's two cosines, then the light's own falloff exponent, as
+     * `uLightCone` carries them — a `vec2` array costs a whole row a light on WebGL2 anyway, so the
+     * exponent rides the half it left rather than a row of its own.
+     */
+    readonly conesAndFalloffs: Float32Array;
     /**
      * Owned, `MAX_POINT_LIGHTS` long: the emitter sizes and weights as the froxel record carries
      * them, at half precision. `sourceRadii` and `weights` point here once a light set resolves, so

package/dist/render/lightBudget.js

@@ -1,4 +1,6 @@
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lampSourceRadius, lampWeight, } from './clusteredLights.js';
+/** Fixed point-light budget shared by CPU selection and the flat shader. */
+import { MAX_AREA_LIGHTS, packAreaSizesAndDoors } from './areaLights.js';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lampSourceRadius, lampWeight, lightChannelsOf, lightFalloffExponentOf, } from './clusteredLights.js';
 /**
  * How many point lights the shading pass shades against at once.
  *
@@ -227,12 +229,21 @@ export const CLOTH_REST_TEXTURE_UNIT = CLOTH_PARTICLES_TEXTURE_UNIT + 1;
  */
 export const MODEL_MAP_TEXTURE_UNIT = CLOTH_REST_TEXTURE_UNIT + 1;
 /**
- * The two units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
+ * The units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
  * every unit a lit program binds, so spreading skin in the middle of a frame unbinds nothing the
  * draws after it sample. WebGL2 guarantees thirty-two.
  */
 export const SKIN_BLUR_TEXTURE_UNIT = MODEL_MAP_TEXTURE_UNIT + 1;
 export const SKIN_BLUR_DEPTH_UNIT = SKIN_BLUR_TEXTURE_UNIT + 1;
+/** And the skin's colour, which the blur's second axis multiplies the spread light by. */
+export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
+/**
+ * A sprite particle's image and the frame's depth copy its soft edge reads, on WebGL2: past every
+ * unit a lit program binds, for the skin blur's reason — a particle is drawn in the middle of a
+ * frame, and the draws after it must find their textures where they left them.
+ */
+export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
+export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
 /**
  * A cookie's tile, in texels a side.
  *
@@ -293,6 +304,8 @@ export const SDF_TEXT_TEXTURE_UNIT = SURFACE_TEXTURE_UNIT;
 export const POINT_SHADOW_POOL = MAX_POINT_LIGHTS + 4;
 /** Weights are optional per consumer; a short array means every light is fully present. */
 const FULLY_PRESENT = new Float32Array(MAX_POINT_LIGHTS).fill(1);
+/** The fixed arm's rectangles as `uAreaLightSize` holds them; refilled per bind, allocated once. */
+const AREA_SIZES_AND_DOORS = new Float32Array(MAX_AREA_LIGHTS * 4);
 /** No size at all, which is the behaviour every scene had before a light could have one. */
 const POINT_SOURCES = new Float32Array(MAX_POINT_LIGHTS);
 /**
@@ -385,9 +398,11 @@ export function bindPointLights(gl, uniforms, lights, falloff) {
      * every lamp switched off.
      */
     gl.uniform3fv(uniforms['uLightDir[0]'] ?? null, r.directions);
-    gl.uniform2fv(uniforms['uLightCone[0]'] ?? null, r.coneCos);
+    /* The cone and, in z, the light's own falloff exponent. See `conesAndFalloffs`. */
+    gl.uniform4fv(uniforms['uLightCone[0]'] ?? null, r.conesAndFalloffs);
     gl.uniform1fv(uniforms['uLightIesProfile[0]'] ?? null, r.iesProfiles);
-    gl.uniform3fv(uniforms['uLightIesAxis[0]'] ?? null, r.iesAxes);
+    /* The azimuth and, in w, the channels. See `axesAndChannels`. */
+    gl.uniform4fv(uniforms['uLightIesAxis[0]'] ?? null, r.axesAndChannels);
     gl.uniform1fv(uniforms['uLightCookie[0]'] ?? null, r.cookies);
 }
 /**
@@ -411,7 +426,9 @@ export function bindAreaLights(gl, uniforms, lights) {
     gl.uniform3fv(uniforms['uAreaLightColor[0]'] ?? null, lights.colors);
     gl.uniform3fv(uniforms['uAreaLightRight[0]'] ?? null, lights.right);
     gl.uniform3fv(uniforms['uAreaLightUp[0]'] ?? null, lights.up);
-    gl.uniform2fv(uniforms['uAreaLightSize[0]'] ?? null, lights.sizes);
+    /* The half extents and, in zw, the barn doors. See `packAreaSizesAndDoors`. */
+    packAreaSizesAndDoors(lights, AREA_SIZES_AND_DOORS);
+    gl.uniform4fv(uniforms['uAreaLightSize[0]'] ?? null, AREA_SIZES_AND_DOORS);
     gl.uniform1fv(uniforms['uAreaLightTwoSided[0]'] ?? null, lights.twoSided);
 }
 /**
@@ -452,6 +469,8 @@ const glLights = {
     iesProfiles: NO_PROFILES,
     iesAxes: NO_IES_AXES,
     cookies: NO_COOKIES,
+    axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+    conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
     heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
     heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
@@ -481,6 +500,8 @@ export function resolvePointLights(lights, falloff, out) {
         out.iesProfiles = NO_PROFILES;
         out.iesAxes = NO_IES_AXES;
         out.cookies = NO_COOKIES;
+        packAxesAndChannels(NO_IES_AXES, undefined, out.axesAndChannels);
+        packConesAndFalloffs(OPEN_CONES, undefined, out.conesAndFalloffs);
         return out;
     }
     /*
@@ -561,5 +582,27 @@ export function resolvePointLights(lights, falloff, out) {
     out.iesProfiles = iesProfiles;
     out.iesAxes = iesAxes;
     out.cookies = cookies;
+    packAxesAndChannels(iesAxes, lights.lightChannels, out.axesAndChannels);
+    packConesAndFalloffs(coneCos, lights.lightFalloffExponents, out.conesAndFalloffs);
     return out;
 }
+/** The cone and the falloff exponent, four a light, as `uLightCone` holds them. */
+function packConesAndFalloffs(cones, exponents, out) {
+    const named = (exponents?.length ?? 0) >= MAX_POINT_LIGHTS ? exponents : undefined;
+    for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+        out[light * 4] = cones[light * 2] ?? POINT_LIGHT_COS_INNER;
+        out[light * 4 + 1] = cones[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+        out[light * 4 + 2] = lightFalloffExponentOf(named?.[light]);
+        out[light * 4 + 3] = 0;
+    }
+}
+/** The azimuth and the channels, four a light, as `uLightIesAxis` holds them. */
+function packAxesAndChannels(axes, channels, out) {
+    const named = (channels?.length ?? 0) >= MAX_POINT_LIGHTS ? channels : undefined;
+    for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+        out[light * 4] = axes[light * 3] ?? 0;
+        out[light * 4 + 1] = axes[light * 3 + 1] ?? 0;
+        out[light * 4 + 2] = axes[light * 3 + 2] ?? 0;
+        out[light * 4 + 3] = lightChannelsOf(named?.[light]);
+    }
+}

package/dist/render/lightmap.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A baked lightmap: what a consumer hands over, how both backends lay it out, and what a surface
+ * reads from it — the backend-neutral half of `createLightmap` and `lightmapModel`, by the
+ * 2026-08-13 rule.
+ *
+ * **What it is for.** A stage built in another engine carries its static light baked: the bounce
+ * off its walls, the soft occlusion in its corners, most of the colour a reference render shows.
+ * The dynamic lights alone leave everything they do not reach flat. A consumer decodes the bake
+ * into pages — one irradiance image and one direction image each — and every lightmapped surface
+ * reads its own region of its page, at its second texture coordinates scaled and offset into it.
+ *
+ * **What a surface adds**, for its shading normal `n` (the normal map's, where it has one):
+ *
+ *     d     = direction * 2 - 1
+ *     light = irradiance(uv) * max(0, dot(d.xyz, n) + d.w)
+ *     diffuse += albedo * (1 - metal) * light
+ *
+ * Unreal's high-quality lightmap read, `GetLightMapColorHQ`, once its own vectors have decoded the
+ * page — the first-order spherical harmonic its direction carries, in this engine's axes. **Added
+ * to what the dynamic lights give**, and to the ambient: a consumer whose bake already holds the
+ * sky's light zeroes the ambient for those draws itself, with `setAmbientSH` and nine zeros.
+ *
+ * **A shading model, because everything it would otherwise take is spent.** The page binds where a
+ * model's map does and the region is the model's numbers (`lightmapModel`), so a lightmapped
+ * material is a pipeline constant of its own and nothing else pays for it; the surface is otherwise
+ * the standard model, unchanged. The second coordinates ride the grain and relief attributes
+ * (`MeshData.lightmapUvs`, stored below zero by `withLightmapUvs`), and an instance's region rides
+ * its tint and opacity (`MeshInstances.lightmapRegions`). **What it gives up**: a lightmapped
+ * surface has no procedural grain or relief, no other shading model, and an instanced batch with
+ * regions no tint. **What it does not do**: the GPU-driven pipeline and splats read no page.
+ */
+import type { MeshData } from '@driftengine/drft';
+/** One page as a consumer decoded it. */
+export interface LightmapPage {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Linear irradiance, row-major from the top, in the same units every other light here is in — a
+     * bake from another engine scaled by that engine's exposure, as its lights are. Either three
+     * floats a texel, or one word a texel already packed as rgb9e5 (`rgb9e5.ts`), which is how such a
+     * bake usually arrives and which uploads with no conversion at all.
+     */
+    readonly irradiance: Float32Array | Uint32Array;
+    /**
+     * The direction the light arrives from, four bytes a texel: a first-order spherical harmonic in
+     * this engine's world axes, each value stored as `v * 0.5 + 0.5` — xyz the axis, w the constant.
+     */
+    readonly direction: Uint8Array;
+}
+/** Layers a page is uploaded as: the irradiance, then the direction. */
+export declare const LIGHTMAP_LAYERS = 2;
+/**
+ * Where a surface's region of its page is: `lightmapUv = uv2 * scale + bias`, as
+ * `[scaleU, scaleV, biasU, biasV]`. The whole page is the identity.
+ */
+export type LightmapRegion = readonly [number, number, number, number];
+/** The whole page. */
+export declare const WHOLE_PAGE: LightmapRegion;
+/**
+ * A page as both backends upload it: two layers of four bytes a texel, row-major from the top. The
+ * first is the irradiance's rgb9e5 word, byte by byte from its lowest; the second is the direction.
+ *
+ * **Eight bytes a texel, and the shader filters it.** Half floats were sixteen: a stage of 49 pages
+ * and 21.8 million texels held 348 MB, where this holds 174. The price is that the irradiance cannot
+ * be filtered as it is stored — a bilinear blend of two words with different exponents is not the
+ * blend of the colours they hold — so the lit stage fetches a texel's four neighbours, decodes each
+ * and blends the colours (`modelBaked` in `shaders/flat/models.ts`): four fetches a layer where one
+ * filtered sample was, on lightmapped surfaces alone. **What would make it wrong** is every device
+ * a page reaches sampling `rgb9e5ufloat`, which WebGL2 does as `RGB9_E5` too; it would then be a
+ * texture of its own, filtered by the device, and a binding the lit stage has no room for.
+ */
+export interface LightmapTexels {
+    readonly kind: 'lightmap-texels';
+    readonly width: number;
+    readonly height: number;
+    /** Each layer's bytes, in layer order: the irradiance, then the direction. */
+    readonly layers: readonly Uint8Array[];
+}
+/** Whether a surface texture's source is a page's texels rather than an image or blocks. */
+export declare function isLightmapTexels(source: unknown): source is LightmapTexels;
+/**
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
+ */
+export declare function lightmapTexels(page: LightmapPage): LightmapTexels;
+/**
+ * A mesh with its second coordinates moved onto the grain and relief streams they ride, or the
+ * mesh itself where it has none. Called by both backends' `createMesh`, before anything records
+ * which streams the mesh has.
+ *
+ * **Stored as `-1 - uv`, below zero, and that is what keeps the lanes safe to share.** Grain takes
+ * effect only above zero and relief is read through `max(relief, 0)`, so the same mesh drawn by a
+ * material that is not lightmapped is a mesh with no grain and no relief — rather than one mottled
+ * and bumped by its own coordinates, which is what storing them as they are drew. **What it gives
+ * up** is coordinates at or below −1, which read as nothing; a page's coordinates are from 0 to 1.
+ */
+export declare function withLightmapUvs(data: MeshData): MeshData;
+/** A material's region, checked: four finite numbers, the whole page where none was named. */
+export declare function lightmapRegionOf(region: LightmapRegion | undefined): LightmapRegion;
+/**
+ * Says once that a lightmapped material was set with no page. The lit stage adds nothing for one,
+ * which is the defined state; this is what keeps it from also being a silent one.
+ */
+export declare function warnUnpagedLightmap(model: {
+    readonly kind: string;
+} | null | undefined, map: unknown): void;
+/**
+ * Says once that an instanced batch and its material disagree about lightmap regions: a batch with
+ * regions drawn by a material that is not lightmapped, or a lightmapped one drawn without them. The
+ * regions ride the lane a tint and an opacity do (`MeshInstances.lightmapRegions`), so either draw
+ * reads one as the other: drawn, and wrong, which is why it is said rather than left.
+ */
+export declare function warnRegionsWithoutPage(model: {
+    readonly kind: string;
+} | null | undefined, regions: Float32Array | undefined): void;

package/dist/render/lightmap.js

@@ -0,0 +1,140 @@
+import { packRgb9e5 } from './rgb9e5.js';
+/** Layers a page is uploaded as: the irradiance, then the direction. */
+export const LIGHTMAP_LAYERS = 2;
+/** The whole page. */
+export const WHOLE_PAGE = [1, 1, 0, 0];
+/** Whether a surface texture's source is a page's texels rather than an image or blocks. */
+export function isLightmapTexels(source) {
+    return (typeof source === 'object' &&
+        source !== null &&
+        source.kind === 'lightmap-texels');
+}
+/**
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
+ */
+export function lightmapTexels(page) {
+    const { width, height } = page;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+        throw new Error(`createLightmap: a ${width} by ${height} page has nothing in it`);
+    }
+    const texels = width * height;
+    const irradiance = page.irradiance;
+    const packed = irradiance instanceof Uint32Array;
+    const wanted = packed ? texels : texels * 3;
+    if (irradiance.length !== wanted) {
+        throw new Error(`createLightmap: ${irradiance.length} irradiance ${packed ? 'words' : 'floats'} for a ` +
+            `${width} by ${height} page, which wants ${wanted}: ` +
+            (packed ? 'one rgb9e5 word a texel' : 'three a texel'));
+    }
+    if (page.direction.length !== texels * 4) {
+        throw new Error(`createLightmap: ${page.direction.length} direction bytes for a ${width} by ${height} ` +
+            `page, which wants ${texels * 4}: four a texel`);
+    }
+    let words;
+    if (packed) {
+        words = irradiance;
+    }
+    else {
+        words = new Uint32Array(texels);
+        for (let t = 0; t < texels; t++) {
+            words[t] = packRgb9e5(irradiance[t * 3], irradiance[t * 3 + 1], irradiance[t * 3 + 2]);
+        }
+    }
+    return {
+        kind: 'lightmap-texels',
+        width,
+        height,
+        layers: [littleEndianBytes(words), page.direction],
+    };
+}
+/** Whether this platform lays a word out lowest byte first, which the shader's decode assumes. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+/**
+ * A page's words as bytes, lowest first: a view of the same memory on every little-endian platform,
+ * which is every one a browser runs on, and a reordered copy anywhere else.
+ */
+function littleEndianBytes(words) {
+    const bytes = new Uint8Array(words.buffer, words.byteOffset, words.length * 4);
+    if (LITTLE_ENDIAN)
+        return bytes;
+    const swapped = new Uint8Array(bytes.length);
+    for (let i = 0; i < bytes.length; i += 4) {
+        swapped[i] = bytes[i + 3];
+        swapped[i + 1] = bytes[i + 2];
+        swapped[i + 2] = bytes[i + 1];
+        swapped[i + 3] = bytes[i];
+    }
+    return swapped;
+}
+/**
+ * A mesh with its second coordinates moved onto the grain and relief streams they ride, or the
+ * mesh itself where it has none. Called by both backends' `createMesh`, before anything records
+ * which streams the mesh has.
+ *
+ * **Stored as `-1 - uv`, below zero, and that is what keeps the lanes safe to share.** Grain takes
+ * effect only above zero and relief is read through `max(relief, 0)`, so the same mesh drawn by a
+ * material that is not lightmapped is a mesh with no grain and no relief — rather than one mottled
+ * and bumped by its own coordinates, which is what storing them as they are drew. **What it gives
+ * up** is coordinates at or below −1, which read as nothing; a page's coordinates are from 0 to 1.
+ */
+export function withLightmapUvs(data) {
+    const uvs = data.lightmapUvs;
+    if (uvs === undefined)
+        return data;
+    const vertices = uvs.length / 2;
+    const grain = new Float32Array(vertices);
+    const relief = new Float32Array(vertices);
+    for (let v = 0; v < vertices; v++) {
+        grain[v] = -1 - uvs[v * 2];
+        relief[v] = -1 - uvs[v * 2 + 1];
+    }
+    return { ...data, grain, relief, lightmapUvs: undefined };
+}
+/** A material's region, checked: four finite numbers, the whole page where none was named. */
+export function lightmapRegionOf(region) {
+    if (region === undefined)
+        return WHOLE_PAGE;
+    let finite = region.length === 4;
+    for (let i = 0; i < region.length; i++)
+        finite &&= Number.isFinite(region[i]);
+    if (!finite) {
+        throw new Error('lightmapModel: a region is four numbers, [scaleU, scaleV, biasU, biasV], ' +
+            `and was given ${String(region)}`);
+    }
+    return region;
+}
+let warnedUnpaged = false;
+/**
+ * Says once that a lightmapped material was set with no page. The lit stage adds nothing for one,
+ * which is the defined state; this is what keeps it from also being a silent one.
+ */
+export function warnUnpagedLightmap(model, map) {
+    if (warnedUnpaged || model?.kind !== 'lightmap' || (map !== null && map !== undefined))
+        return;
+    warnedUnpaged = true;
+    console.warn('setMaterial: a lightmapModel material with no modelMap reads no page and adds no light. ' +
+        'Pass the page createLightmap returned as its modelMap.');
+}
+let warnedRegions = false;
+/**
+ * Says once that an instanced batch and its material disagree about lightmap regions: a batch with
+ * regions drawn by a material that is not lightmapped, or a lightmapped one drawn without them. The
+ * regions ride the lane a tint and an opacity do (`MeshInstances.lightmapRegions`), so either draw
+ * reads one as the other: drawn, and wrong, which is why it is said rather than left.
+ */
+export function warnRegionsWithoutPage(model, regions) {
+    if (warnedRegions)
+        return;
+    const lightmapped = model?.kind === 'lightmap';
+    if (lightmapped === (regions !== undefined))
+        return;
+    warnedRegions = true;
+    console.warn(lightmapped
+        ? 'drawInstanced: a lightmapModel material drawing a batch with no lightmapRegions reads ' +
+            'its tints as regions. Give each instance its region of the page.'
+        : 'drawInstanced: a batch with lightmapRegions drawn by a material that is not a ' +
+            'lightmapModel reads its regions as its tints and opacities. Draw it with its page, or ' +
+            'without regions.');
+}

package/dist/render/mesh.js

@@ -380,7 +380,8 @@ export class Mesh {
             gl.vertexAttribDivisor(location, 1);
         }
         gl.enableVertexAttribArray(15);
-        gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
+        /* The tint and, in w, the opacity: one attribute for both. See `INSTANCE_FLOATS`. */
+        gl.vertexAttribPointer(15, 4, gl.FLOAT, false, stride, 64);
         gl.vertexAttribDivisor(15, 1);
         gl.bindVertexArray(null);
         return vao;

package/dist/render/particleBatch.d.ts

@@ -1,5 +1,13 @@
 import { type ParticleMaterial } from './particleMaterial.ts';
 import type { ParticleInstances } from './particlePool.ts';
+import type { SurfaceTexture } from './surfaceTexture.ts';
+/** The vertex stage's `uCameraFacing` for a facing: the cross 0, the camera 1, the travel 2. */
+export declare function facingCode(facing: ParticleFacing): number;
+/**
+ * A sprite's frame and half-height, two floats a particle, into `out` — the stream the vertex
+ * stage reads at location 10. Shared by both backends, so the two read one layout.
+ */
+export declare function packSpriteStream(data: ParticleInstances, count: number, out: Float32Array): void;
 /**
  * One draw call for a live particle pool: one camera-facing quad per particle, or a
  * crossed pair of world-fixed ones when `facing` asks for them.
@@ -21,9 +29,11 @@ export type ParticleBlend = 'additive' | 'alpha';
  * `'camera'` is one quad facing the viewer, and the default. `'cross'` is the pair of
  * world-fixed blades this batch drew before the option existed — see `uCameraFacing` in
  * `shaders/particle.ts` for the artifact that made the default the other one, and for what
- * the cross still buys a caller who wants it back.
+ * the cross still buys a caller who wants it back. `'velocity'` faces the camera with its up along
+ * the particle's travel across the view — a streak, a spark stretched by its motion — and a
+ * particle at rest faces the camera as `'camera'` does.
  */
-export type ParticleFacing = 'camera' | 'cross';
+export type ParticleFacing = 'camera' | 'cross' | 'velocity';
 export interface ParticleBatchOptions {
     /**
      * Which particle this is, by name.
@@ -72,6 +82,41 @@ export interface ParticleBatchOptions {
      * shader's own comment on `uCameraFacing` lays out.
      */
     facing?: ParticleFacing;
+    /**
+     * The image a `'sprite'` draws: a surface texture, its first layer. **Required by the sprite** and
+     * ignored by the procedural materials. Colour is the particle's times the image's, unlit.
+     */
+    texture?: SurfaceTexture;
+    /**
+     * A `'sprite'`'s flipbook: the image as `[columns, rows]` cells, numbered across then down from
+     * the top-left, a particle's `frames` naming one. `[1, 1]`, the default, is the whole image.
+     */
+    cells?: readonly [number, number];
+    /**
+     * Whether a `'sprite'` blends from a particle's cell toward the next by the fraction of its
+     * frame, so a slow flipbook moves rather than steps. Off by default: one cell, sampled once.
+     */
+    blendCells?: boolean;
+    /**
+     * Metres over which a `'sprite'` fades where it meets the opaque scene: the hard line a flat card
+     * draws where it cuts a floor or a body, softened. **0, the default, is a hard edge.** It reads a
+     * copy of the frame's depth, which needs `screenEffects`; without one the edge stays hard and
+     * the renderer says so once.
+     */
+    softDepth?: number;
+    /** Metres in front of the eye over which a `'sprite'` fades in. 0, the default, is no fade. */
+    cameraFade?: number;
+    /**
+     * Metres each particle is moved toward the eye before it is drawn, so a sprite born inside a
+     * surface is drawn in front of it. 0 by default. Every material reads it.
+     */
+    cameraOffset?: number;
+    /**
+     * Whether the live particles are drawn farthest first, the order an alpha blend assumes. Off
+     * by default, because sorting costs a pass over the particles on the CPU each frame and an
+     * additive blend is a sum that does not care. See `particleSort.ts`.
+     */
+    sort?: boolean;
     /**
      * Another batch whose compiled program this one should reuse.
      *
@@ -102,6 +147,17 @@ export declare class ParticleBatch {
     private readonly ageBuffer;
     private readonly seedBuffer;
     private readonly velocityBuffer;
+    private readonly spriteBuffer;
+    private readonly spriteStaging;
+    /** Room to draw farthest first, where the batch asked. See `ParticleBatchOptions.sort`. */
+    private readonly order;
+    /** The sprite's own: its image, its flipbook and its fades. See `ParticleBatchOptions`. */
+    readonly texture: SurfaceTexture | null;
+    readonly cells: readonly [number, number];
+    readonly blendCells: boolean;
+    readonly softDepth: number;
+    readonly cameraFade: number;
+    readonly cameraOffset: number;
     private readonly blend;
     private readonly stretchSec;
     private readonly erosion;
@@ -119,7 +175,7 @@ export declare class ParticleBatch {
      * Only the live prefix of each array, which is what the pool's compaction
      * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
      */
-    upload(gl: WebGL2RenderingContext, data: ParticleInstances): void;
+    upload(gl: WebGL2RenderingContext, given: ParticleInstances, eye: ArrayLike<number>): void;
     /** Bind this material's own constants. Called once per draw, before `drawTo`. */
     bindMaterial(gl: WebGL2RenderingContext): void;
     /**

package/dist/render/particleBatch.js

@@ -2,6 +2,24 @@ import { compileProgram, uniformLocations } from './shader.js';
 import { particleShaders } from './particleMaterial.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.js';
 import { blendCovering, blendKeeping } from './sceneCoverage.js';
+import { PARTICLE_SPRITE_UNIT } from './lightBudget.js';
+import { createParticleSort, sortBackToFront } from './particleSort.js';
+/** The vertex stage's `uCameraFacing` for a facing: the cross 0, the camera 1, the travel 2. */
+export function facingCode(facing) {
+    return facing === 'cross' ? 0 : facing === 'velocity' ? 2 : 1;
+}
+/**
+ * A sprite's frame and half-height, two floats a particle, into `out` — the stream the vertex
+ * stage reads at location 10. Shared by both backends, so the two read one layout.
+ */
+export function packSpriteStream(data, count, out) {
+    const frames = data.frames;
+    const heights = data.heights;
+    for (let i = 0; i < count; i++) {
+        out[i * 2] = frames?.[i] ?? 0;
+        out[i * 2 + 1] = heights?.[i] ?? 0;
+    }
+}
 /** Corners of one blade, as a triangle-strip-friendly quad. */
 const CORNERS = [
     [-1, -1],
@@ -22,6 +40,17 @@ export class ParticleBatch {
     ageBuffer;
     seedBuffer;
     velocityBuffer;
+    spriteBuffer;
+    spriteStaging;
+    /** Room to draw farthest first, where the batch asked. See `ParticleBatchOptions.sort`. */
+    order;
+    /** The sprite's own: its image, its flipbook and its fades. See `ParticleBatchOptions`. */
+    texture;
+    cells;
+    blendCells;
+    softDepth;
+    cameraFade;
+    cameraOffset;
     blend;
     stretchSec;
     erosion;
@@ -53,6 +82,17 @@ export class ParticleBatch {
         this.coreGain = options.coreGain ?? 1;
         this.fog = options.fog ?? false;
         this.facing = options.facing ?? 'camera';
+        this.texture = options.texture ?? null;
+        this.cells = options.cells ?? [1, 1];
+        this.blendCells = options.blendCells === true;
+        this.softDepth = Math.max(0, options.softDepth ?? 0);
+        this.cameraFade = Math.max(0, options.cameraFade ?? 0);
+        this.cameraOffset = options.cameraOffset ?? 0;
+        this.order = options.sort === true ? createParticleSort(capacity) : null;
+        this.spriteStaging = new Float32Array(capacity * 2);
+        if (options.material === 'sprite' && this.texture === null) {
+            throw new Error("createParticles: a 'sprite' draws an image, and was given no `texture`");
+        }
         const corners = new Float32Array(PARTICLE_VERTS * 2);
         const blades = new Float32Array(PARTICLE_VERTS);
         const indices = new Uint16Array(PARTICLE_INDICES);
@@ -88,6 +128,7 @@ export class ParticleBatch {
         this.ageBuffer = this.attach(gl, 7, capacity, 1, 1, shaders.label);
         this.seedBuffer = this.attach(gl, 8, capacity, 1, 1, shaders.label);
         this.velocityBuffer = this.attach(gl, 9, capacity * 3, 3, 1, shaders.label);
+        this.spriteBuffer = this.attach(gl, 10, capacity * 2, 2, 1, shaders.label);
         const indexBuffer = gl.createBuffer();
         if (indexBuffer === null)
             throw new Error(`${shaders.label}: createBuffer failed`);
@@ -102,10 +143,13 @@ export class ParticleBatch {
      * Only the live prefix of each array, which is what the pool's compaction
      * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
      */
-    upload(gl, data) {
+    upload(gl, given, eye) {
+        const data = this.order === null ? given : sortBackToFront(given, eye, this.order);
         const n = data.count;
         if (n === 0)
             return;
+        packSpriteStream(data, n, this.spriteStaging);
+        this.send(gl, this.spriteBuffer, this.spriteStaging, n * 2);
         this.send(gl, this.positionBuffer, data.positions, n * 3);
         this.send(gl, this.sizeBuffer, data.sizes, n);
         this.send(gl, this.spinBuffer, data.spins, n);
@@ -119,7 +163,14 @@ export class ParticleBatch {
     bindMaterial(gl) {
         const u = this.uniforms;
         gl.uniform1f(u['uStretchSec'] ?? null, this.stretchSec);
-        gl.uniform1f(u['uCameraFacing'] ?? null, this.facing === 'camera' ? 1 : 0);
+        gl.uniform1f(u['uCameraFacing'] ?? null, facingCode(this.facing));
+        gl.uniform1f(u['uCameraOffset'] ?? null, this.cameraOffset);
+        /* The sprite's flipbook and its image; the fades are the renderer's, which owns the depth. */
+        if (this.texture !== null) {
+            gl.uniform4f(u['uCells'] ?? null, this.cells[0], this.cells[1], this.blendCells ? 1 : 0, 0);
+            this.texture.bind(gl, PARTICLE_SPRITE_UNIT);
+            gl.uniform1i(u['uSprite'] ?? null, PARTICLE_SPRITE_UNIT);
+        }
         gl.uniform1f(u['uErosion'] ?? null, this.erosion);
         gl.uniform1f(u['uCoreGain'] ?? null, this.coreGain);
         /* Only the mote program declares uFogEnabled, so this is a no-op — not a leak into the

package/dist/render/particleMaterial.d.ts

@@ -13,7 +13,7 @@
  * document that. Naming them makes the pairing explicit instead of leaving it to a caller to
  * match a source with the constants that suit it.
  */
-export type ParticleMaterial = 'smoke' | 'spark' | 'mote';
+export type ParticleMaterial = 'smoke' | 'spark' | 'mote' | 'sprite';
 /** Both compilations of one material, and what the generator recorded about each stage. */
 export interface ParticleShaders {
     readonly label: string;
@@ -47,6 +47,11 @@ export declare const PARTICLE_VERT_BINDINGS: {
             readonly size: 4;
             readonly type: "float";
         };
+        readonly uCameraOffset: {
+            readonly offset: 84;
+            readonly size: 4;
+            readonly type: "float";
+        };
     };
     readonly textures: {};
 };