@driftengine/core 4.8.4 → 4.8.6

package/src/render/lightmap.ts

@@ -0,0 +1,202 @@
+/**
+ * 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';
+import { toHalfFloats } from './halfFloat.ts';
+
+/** One page as a consumer decoded it. */
+export interface LightmapPage {
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Linear irradiance, three floats a texel, 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.
+   */
+  readonly irradiance: Float32Array;
+  /**
+   * 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 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 const WHOLE_PAGE: LightmapRegion = [1, 1, 0, 0];
+
+/** A page as both backends upload it: `layers` images of half-float RGBA, row-major from the top. */
+export interface LightmapTexels {
+  readonly kind: 'lightmap-texels';
+  readonly width: number;
+  readonly height: number;
+  readonly layers: number;
+  readonly texels: Uint16Array;
+}
+
+/** Whether a surface texture's source is a page's texels rather than an image or blocks. */
+export function isLightmapTexels(source: unknown): source is LightmapTexels {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { kind?: unknown }).kind === 'lightmap-texels'
+  );
+}
+
+/**
+ * A page as both backends upload it: two layers of half-float RGBA, the irradiance with an alpha of
+ * one and the direction as the fractions its bytes are. Refuses a page whose arrays are not its
+ * size, naming the one that is short.
+ */
+export function lightmapTexels(page: LightmapPage): LightmapTexels {
+  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;
+  if (page.irradiance.length !== texels * 3) {
+    throw new Error(
+      `createLightmap: ${page.irradiance.length} irradiance floats for a ${width} by ${height} ` +
+        `page, which wants ${texels * 3}: 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`,
+    );
+  }
+  const floats = new Float32Array(texels * 4 * LIGHTMAP_LAYERS);
+  for (let t = 0; t < texels; t++) {
+    floats[t * 4] = page.irradiance[t * 3] as number;
+    floats[t * 4 + 1] = page.irradiance[t * 3 + 1] as number;
+    floats[t * 4 + 2] = page.irradiance[t * 3 + 2] as number;
+    floats[t * 4 + 3] = 1;
+    const at = (texels + t) * 4;
+    for (let c = 0; c < 4; c++) floats[at + c] = (page.direction[t * 4 + c] as number) / 255;
+  }
+  return {
+    kind: 'lightmap-texels',
+    width,
+    height,
+    layers: LIGHTMAP_LAYERS,
+    texels: toHalfFloats(floats),
+  };
+}
+
+/**
+ * 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: MeshData): MeshData {
+  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] as number);
+    relief[v] = -1 - (uvs[v * 2 + 1] as number);
+  }
+  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: LightmapRegion | undefined): LightmapRegion {
+  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: { readonly kind: string } | null | undefined,
+  map: unknown,
+): void {
+  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: { readonly kind: string } | null | undefined,
+  regions: Float32Array | undefined,
+): void {
+  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/src/render/mesh.ts

@@ -400,7 +400,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/src/render/particleBatch.ts

@@ -3,6 +3,27 @@ import { particleShaders, type ParticleMaterial } from './particleMaterial.ts';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.ts';
 import type { ParticleInstances } from './particlePool.ts';
 import { blendCovering, blendKeeping } from './sceneCoverage.ts';
+import type { SurfaceTexture } from './surfaceTexture.ts';
+import { PARTICLE_SPRITE_UNIT } from './lightBudget.ts';
+import { createParticleSort, sortBackToFront, type ParticleSort } from './particleSort.ts';
+
+/** The vertex stage's `uCameraFacing` for a facing: the cross 0, the camera 1, the travel 2. */
+export function facingCode(facing: ParticleFacing): number {
+  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: ParticleInstances, count: number, out: Float32Array): void {
+  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;
+  }
+}
 
 /**
  * One draw call for a live particle pool: one camera-facing quad per particle, or a
@@ -26,9 +47,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 {
   /**
@@ -78,6 +101,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.
    *
@@ -118,6 +176,17 @@ export class ParticleBatch {
   private readonly ageBuffer: WebGLBuffer;
   private readonly seedBuffer: WebGLBuffer;
   private readonly velocityBuffer: WebGLBuffer;
+  private readonly spriteBuffer: WebGLBuffer;
+  private readonly spriteStaging: Float32Array;
+  /** Room to draw farthest first, where the batch asked. See `ParticleBatchOptions.sort`. */
+  private readonly order: ParticleSort | null;
+  /** 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: ParticleBlend;
   private readonly stretchSec: number;
   private readonly erosion: number;
@@ -152,6 +221,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);
@@ -189,6 +269,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`);
@@ -204,9 +285,12 @@ 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: WebGL2RenderingContext, data: ParticleInstances): void {
+  upload(gl: WebGL2RenderingContext, given: ParticleInstances, eye: ArrayLike<number>): void {
+    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);
@@ -221,7 +305,14 @@ export class ParticleBatch {
   bindMaterial(gl: WebGL2RenderingContext): void {
     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/src/render/particleMaterial.ts

@@ -2,6 +2,7 @@ import {
   PARTICLE_MOTE_FRAG,
   PARTICLE_SMOKE_FRAG,
   PARTICLE_SPARK_FRAG,
+  PARTICLE_SPRITE_FRAG,
   PARTICLE_VERT,
 } from './shaders/particle.ts';
 import {
@@ -9,6 +10,7 @@ import {
   PARTICLE_MOTE_FRAG_WGSL,
   PARTICLE_SMOKE_FRAG_WGSL,
   PARTICLE_SPARK_FRAG_WGSL,
+  PARTICLE_SPRITE_FRAG_WGSL,
   PARTICLE_VERT_WGSL,
 } from './shaders/generated/particle.wgsl.ts';
 
@@ -27,7 +29,7 @@ import {
  * 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 {
@@ -66,6 +68,14 @@ const MATERIALS: Readonly<Record<ParticleMaterial, ParticleShaders>> = {
     vertexWgsl: PARTICLE_VERT_WGSL,
     fragmentWgsl: PARTICLE_MOTE_FRAG_WGSL,
   },
+  /* An image a consumer supplies, not a shape this engine draws: see `PARTICLE_SPRITE_FRAG`. */
+  sprite: {
+    label: 'particle:sprite',
+    vertexSource: PARTICLE_VERT,
+    fragmentSource: PARTICLE_SPRITE_FRAG,
+    vertexWgsl: PARTICLE_VERT_WGSL,
+    fragmentWgsl: PARTICLE_SPRITE_FRAG_WGSL,
+  },
 };
 
 /** What the generator recorded about the shared vertex stage. */

package/src/render/particlePool.ts

@@ -38,6 +38,17 @@ export interface ParticleInstances {
   seeds: Float32Array;
   /** Current velocity, three floats each: what a streak is stretched along. */
   velocities: Float32Array;
+  /**
+   * A sprite's flipbook frame, one float each: its whole part names a cell of the image, counted
+   * across then down from the top-left, and its fraction is how far toward the next a batch that
+   * blends cells has come. Read by the `'sprite'` material alone. Absent is frame 0.
+   */
+  frames?: Float32Array;
+  /**
+   * A sprite's half-height in metres, one float each, beside `sizes`' half-width — a sprite need
+   * not be square. Read by the `'sprite'` material alone; absent or 0 is as tall as it is wide.
+   */
+  heights?: Float32Array;
   count: number;
   capacity: number;
 }
@@ -52,6 +63,8 @@ function createParticleInstances(capacity: number): ParticleInstances {
     ages: new Float32Array(capacity),
     seeds: new Float32Array(capacity),
     velocities: new Float32Array(capacity * 3),
+    frames: new Float32Array(capacity),
+    heights: new Float32Array(capacity),
     count: 0,
     capacity,
   };

package/src/render/particleSort.ts

@@ -0,0 +1,133 @@
+/**
+ * A pool's particles, farthest from the eye first, for a blended batch that asks to be sorted.
+ *
+ * **Why a blended batch wants it.** An alpha blend is order-dependent: a near puff drawn before a
+ * far one is covered by it, and a cloud of them drawn in the order they were born flickers as
+ * that order and the camera disagree. Back to front is the order the blend assumes. Additive
+ * blending is a sum and needs none of it, which is why sorting is the batch's choice.
+ *
+ * **Backend-neutral, as a copy**: the sorted particles are written into a second set of streams the
+ * batch owns, and each backend uploads that set exactly as it uploads an unsorted one — so the
+ * order is one decision, not two, by the 2026-08-13 rule. A merge sort into preallocated scratch,
+ * so nothing is allocated per frame however many particles there are; stable, so two particles at
+ * one distance keep their order and do not trade places from frame to frame.
+ *
+ * **What it gives up** is order between batches and within one particle: two sorted batches still
+ * draw one after the other, and two crossing cards cut through each other. **What would make it
+ * wrong** is a field of particles large enough that sorting it on the CPU costs a frame; the GPU
+ * sorts it then.
+ */
+import type { ParticleInstances } from './particlePool.ts';
+
+/** What sorting a batch keeps between frames: the order, its keys and the sorted copy. */
+export interface ParticleSort {
+  readonly order: Uint32Array;
+  readonly scratch: Uint32Array;
+  readonly keys: Float32Array;
+  readonly sorted: ParticleInstances;
+}
+
+/** Room to sort `capacity` particles, allocated once with the batch. */
+export function createParticleSort(capacity: number): ParticleSort {
+  return {
+    order: new Uint32Array(capacity),
+    scratch: new Uint32Array(capacity),
+    keys: new Float32Array(capacity),
+    sorted: {
+      positions: new Float32Array(capacity * 3),
+      sizes: new Float32Array(capacity),
+      spins: new Float32Array(capacity),
+      colors: new Float32Array(capacity * 3),
+      alphas: new Float32Array(capacity),
+      ages: new Float32Array(capacity),
+      seeds: new Float32Array(capacity),
+      velocities: new Float32Array(capacity * 3),
+      frames: new Float32Array(capacity),
+      heights: new Float32Array(capacity),
+      count: 0,
+      capacity,
+    },
+  };
+}
+
+/**
+ * `data`'s live particles into `sort.sorted`, farthest from `eye` first, and that copy returned.
+ * At most the sort's capacity are kept.
+ */
+export function sortBackToFront(
+  data: ParticleInstances,
+  eye: ArrayLike<number>,
+  sort: ParticleSort,
+): ParticleInstances {
+  const count = Math.min(data.count, sort.order.length);
+  const { order, keys } = sort;
+  const ex = eye[0] ?? 0;
+  const ey = eye[1] ?? 0;
+  const ez = eye[2] ?? 0;
+  for (let i = 0; i < count; i++) {
+    const dx = (data.positions[i * 3] as number) - ex;
+    const dy = (data.positions[i * 3 + 1] as number) - ey;
+    const dz = (data.positions[i * 3 + 2] as number) - ez;
+    keys[i] = dx * dx + dy * dy + dz * dz;
+    order[i] = i;
+  }
+  mergeSortFarFirst(order, sort.scratch, keys, count);
+
+  const out = sort.sorted;
+  for (let k = 0; k < count; k++) {
+    const i = order[k] as number;
+    copy3(data.positions, i, out.positions, k);
+    copy3(data.colors, i, out.colors, k);
+    copy3(data.velocities, i, out.velocities, k);
+    out.sizes[k] = data.sizes[i] as number;
+    out.spins[k] = data.spins[i] as number;
+    out.alphas[k] = data.alphas[i] as number;
+    out.ages[k] = data.ages[i] as number;
+    out.seeds[k] = data.seeds[i] as number;
+    (out.frames as Float32Array)[k] = data.frames?.[i] ?? 0;
+    (out.heights as Float32Array)[k] = data.heights?.[i] ?? 0;
+  }
+  out.count = count;
+  return out;
+}
+
+function copy3(from: Float32Array, i: number, to: Float32Array, k: number): void {
+  to[k * 3] = from[i * 3] as number;
+  to[k * 3 + 1] = from[i * 3 + 1] as number;
+  to[k * 3 + 2] = from[i * 3 + 2] as number;
+}
+
+/** A bottom-up merge sort of `order` by `keys`, largest first, stable, through `scratch`. */
+function mergeSortFarFirst(
+  order: Uint32Array,
+  scratch: Uint32Array,
+  keys: Float32Array,
+  count: number,
+): void {
+  let from = order;
+  let to = scratch;
+  for (let width = 1; width < count; width *= 2) {
+    for (let start = 0; start < count; start += 2 * width) {
+      const middle = Math.min(start + width, count);
+      const end = Math.min(start + 2 * width, count);
+      let a = start;
+      let b = middle;
+      let at = start;
+      while (a < middle && b < end) {
+        /* `>=` keeps the left run's particle first on a tie, which is what makes this stable. */
+        if ((keys[from[a] as number] as number) >= (keys[from[b] as number] as number)) {
+          to[at++] = from[a++] as number;
+        } else {
+          to[at++] = from[b++] as number;
+        }
+      }
+      while (a < middle) to[at++] = from[a++] as number;
+      while (b < end) to[at++] = from[b++] as number;
+    }
+    const swap = from;
+    from = to;
+    to = swap;
+  }
+  /* Copied by hand: a subarray would be a view allocated every frame. */
+  if (from !== order) for (let i = 0; i < count; i++) order[i] = from[i] as number;
+}

package/src/render/sceneTarget.ts

@@ -497,6 +497,15 @@ export class SceneTarget {
    * must reject it in the same place or the accumulation and the revealage cover different
    * fragments.
    */
+  /** The frame's size in pixels, as its targets are allocated. */
+  get frameWidth(): number {
+    return this.width;
+  }
+
+  get frameHeight(): number {
+    return this.height;
+  }
+
   /**
    * The depth the frame draws against, for a second framebuffer to share: skin's diffuse half,
    * which tests against it and writes none. The multisampled renderbuffer where the frame is
@@ -783,6 +792,8 @@ export class SceneTarget {
       readonly strength: number;
       /** In scene units, which is why this wants `keepsRange`. See `BloomPass`. */
       readonly threshold: number;
+      /** The ramp and each level's tint, as `resolveBloomResponse` writes them. */
+      readonly response: Float32Array;
     },
     /*
      * Depth of field, between the camera smear and the occlusion in the shader's own order. Like
@@ -966,7 +977,13 @@ export class SceneTarget {
     let bloomTexture: WebGLTexture | null = null;
     if (bloom !== undefined && scene !== null) {
       this.bloom ??= new BloomPass(gl);
-      bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold);
+      bloomTexture = this.bloom.run(
+        scene,
+        this.width,
+        this.height,
+        bloom.threshold,
+        bloom.response,
+      );
     }
 
     /*

package/src/render/shaders/bloom.ts

@@ -27,7 +27,9 @@
  * 3. **Upsample**, additively back up the chain through a tent filter.
  *
  * Deliberately absent, because they were asked against by name: lens dirt, anamorphic streaks
- * and ghosting. One threshold, one radius, one strength.
+ * and ghosting. One threshold, one radius, one strength — and, since 4.8.6, how a colour comes in
+ * past the threshold and a tint for each octave, which is how another engine's stage is matched
+ * rather than how this one looks: see `BloomResponse` in `bloomChain.ts`.
  */
 
 /**
@@ -128,6 +130,11 @@ uniform sampler2D uSource;
 uniform vec2 uTexel;
 /** In scene units. 1.0 is "brighter than white", which is the useful place to start. */
 uniform float uThreshold;
+/**
+ * Scene units over which a colour comes in past the threshold, or 0 to subtract the threshold
+ * instead. See \`BloomResponse.ramp\`.
+ */
+uniform float uRamp;
 
 out vec4 fragColor;
 
@@ -144,6 +151,8 @@ ${BLOOM_BRIGHTNESS}
 vec3 fetch(vec2 uv) {
   vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));
   float bright = brightness(c);
+  /* A ramp keeps a share of the colour, all of it a ramp's width past the line. */
+  if (uRamp > 0.0) return c * clamp((bright - uThreshold) / uRamp, 0.0, 1.0);
   return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));
 }
 
@@ -194,7 +203,9 @@ ${BLOOM_BOXES}
 /**
  * Stage three: a 3x3 tent, added into the level above.
  *
- * **Additive rather than a mix, and each octave counts the same.** A lone bright pixel arrives
+ * **Additive rather than a mix, and each octave counts the same** unless a tint says otherwise:
+ * the level being added onto is multiplied by its own tint as it is, by the blend, and the deepest
+ * by `uScale` on the first draw. White everywhere is exactly the sum. A lone bright pixel arrives
  * at level n divided by four to the n, spread over four to the n pixels, so summing the levels
  * lifts its own pixel by about a third and lays a long shallow tail around it. That falloff is
  * what a real glare looks like; a single gaussian gives a disc with an end to it.
@@ -209,6 +220,12 @@ precision highp float;
 in vec2 vUv;
 
 uniform sampler2D uSource;
+/**
+ * What the level being read is multiplied by: its tint, on the first draw up from the deepest
+ * level, and white on every other — each other level's tint is applied to the level below as it
+ * is added onto, by the blend. See \`BloomResponse.tints\`.
+ */
+uniform vec3 uScale;
 /** How far the tent reaches, in UV. One number for the whole chain. */
 uniform float uRadius;
 
@@ -227,6 +244,6 @@ void main() {
   vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;
 
   vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);
-  fragColor = vec4(sum * 0.0625, 1.0);
+  fragColor = vec4(sum * 0.0625 * uScale, 1.0);
 }
 `;