@driftengine/core 3.61.0

package/dist/render/plumeGeometry.d.ts

@@ -0,0 +1,25 @@
+import type { PlumePlacement } from './plumeRenderer.ts';
+/**
+ * The crossed quads a plume batch is drawn from, built once for both backends.
+ *
+ * **Two blades rather than a billboard, and two rather than three.** A single card turned to
+ * face the viewer has no three-dimensional structure to see — orbiting a fire showed the same
+ * silhouette from every angle — while a fixed cross has the parallax a volume has and never
+ * goes edge-on, because its partner is square-on at that exact moment. The third blade costs
+ * 50% more geometry for a difference the eye does not separate at these sizes.
+ *
+ * Here rather than in `plumeRenderer.ts` because a second copy of a mesh generator is a plume
+ * whose triangles differ per backend, which is the 2026-08-13 rule in `AGENTS.md`.
+ */
+export declare const PLUME_BLADES = 2;
+export declare const PLUME_VERTS: number;
+/** The five attribute streams and the index list. */
+export interface PlumeGeometryData {
+    readonly centers: Float32Array;
+    readonly corners: Float32Array;
+    readonly sizes: Float32Array;
+    readonly seeds: Float32Array;
+    readonly blades: Float32Array;
+    readonly indices: Uint32Array;
+}
+export declare function buildPlumeGeometry(plumes: readonly PlumePlacement[]): PlumeGeometryData;

package/dist/render/plumeGeometry.js

@@ -0,0 +1,61 @@
+/**
+ * The crossed quads a plume batch is drawn from, built once for both backends.
+ *
+ * **Two blades rather than a billboard, and two rather than three.** A single card turned to
+ * face the viewer has no three-dimensional structure to see — orbiting a fire showed the same
+ * silhouette from every angle — while a fixed cross has the parallax a volume has and never
+ * goes edge-on, because its partner is square-on at that exact moment. The third blade costs
+ * 50% more geometry for a difference the eye does not separate at these sizes.
+ *
+ * Here rather than in `plumeRenderer.ts` because a second copy of a mesh generator is a plume
+ * whose triangles differ per backend, which is the 2026-08-13 rule in `AGENTS.md`.
+ */
+export const PLUME_BLADES = 2;
+export const PLUME_VERTS = PLUME_BLADES * 4;
+/** Corners of one blade, as a quad. */
+const CORNERS = [
+    [-1, -1],
+    [1, -1],
+    [1, 1],
+    [-1, 1],
+];
+export function buildPlumeGeometry(plumes) {
+    const count = plumes.length;
+    const centers = new Float32Array(count * PLUME_VERTS * 3);
+    const corners = new Float32Array(count * PLUME_VERTS * 2);
+    const sizes = new Float32Array(count * PLUME_VERTS * 2);
+    const seeds = new Float32Array(count * PLUME_VERTS);
+    const blades = new Float32Array(count * PLUME_VERTS);
+    const indices = new Uint32Array(count * 6 * PLUME_BLADES);
+    for (let f = 0; f < count; f++) {
+        const plume = plumes[f];
+        if (plume === undefined)
+            continue;
+        for (let b = 0; b < PLUME_BLADES; b++) {
+            for (let c = 0; c < 4; c++) {
+                const v = f * PLUME_VERTS + b * 4 + c;
+                const corner = CORNERS[c] ?? [0, 0];
+                centers[v * 3] = plume.x;
+                centers[v * 3 + 1] = plume.y;
+                centers[v * 3 + 2] = plume.z;
+                corners[v * 2] = corner[0];
+                corners[v * 2 + 1] = corner[1];
+                sizes[v * 2] = plume.width;
+                sizes[v * 2 + 1] = plume.height;
+                // Golden-ratio phase offset: neighbours never animate in step.
+                seeds[v] = f * 0.618;
+                // Which blade of the cross this vertex belongs to.
+                blades[v] = b;
+            }
+            const base = f * PLUME_VERTS + b * 4;
+            const i = (f * PLUME_BLADES + b) * 6;
+            indices[i] = base;
+            indices[i + 1] = base + 1;
+            indices[i + 2] = base + 2;
+            indices[i + 3] = base;
+            indices[i + 4] = base + 2;
+            indices[i + 5] = base + 3;
+        }
+    }
+    return { centers, corners, sizes, seeds, blades, indices };
+}

package/dist/render/plumeMaterial.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which plume material a caller wants, by name rather than by source.
+ *
+ * **`PlumeOptions` used to take GLSL strings, and that could not cross to a second backend.**
+ * WebGPU has no runtime GLSL compiler and this package must never ship one — the toolchain is
+ * dev-only, for the licensing and size reasons the WGSL toolchain design
+ * records — so a caller-supplied `vertexSource` was a capability that existed on exactly one
+ * backend and could never exist on the other.
+ *
+ * Naming the material instead makes it universal by construction: each backend resolves the
+ * name to the shader it can actually compile, and neither can be handed something it cannot
+ * use. **The cost is real and was accepted deliberately**: a caller can no longer supply its
+ * own plume shader at all. That capability was documented — `uCameraRight` is set
+ * unconditionally precisely so a caller's own vertex shader could billboard against it — and
+ * it is gone. A world that needs a plume this engine does not ship now needs the engine to
+ * ship it.
+ */
+export type PlumeMaterial = 'fire' | 'smoke' | 'arcane';
+/** The two source pairs one material resolves to, one per backend. */
+export interface PlumeShaders {
+    readonly label: string;
+    readonly vertexSource: string;
+    readonly fragmentSource: string;
+    readonly vertexWgsl: string;
+    readonly fragmentWgsl: string;
+    /** What the generator recorded about the fragment stage's uniform block. */
+    readonly fragmentBindings: unknown;
+    readonly vertexBindings: unknown;
+}
+/** Resolve a material name, or say which names exist. */
+export declare function plumeShaders(material: PlumeMaterial): PlumeShaders;

package/dist/render/plumeMaterial.js

@@ -0,0 +1,64 @@
+import { ARCANE_FRAG } from './shaders/arcane.js';
+import { FIRE_FRAG, PLUME_VERT } from './shaders/fire.js';
+import { SMOKE_FRAG } from './shaders/smoke.js';
+import { ARCANE_FRAG_WGSL, ARCANE_BINDINGS } from './shaders/generated/arcane.wgsl.js';
+import { FIRE_FRAG_WGSL, PLUME_VERT_WGSL, FIRE_BINDINGS } from './shaders/generated/fire.wgsl.js';
+import { SMOKE_FRAG_WGSL, SMOKE_BINDINGS } from './shaders/generated/smoke.wgsl.js';
+/**
+ * Every plume this engine ships, with both compilations of each.
+ *
+ * One table rather than a lookup per backend: a material present in one and absent from the
+ * other is precisely the drift the 2026-08-13 rule in `AGENTS.md` exists to prevent, and here
+ * it would be a plume that draws on WebGL2 and throws on WebGPU.
+ */
+const MATERIALS = {
+    fire: {
+        label: 'plume:fire',
+        vertexSource: PLUME_VERT,
+        fragmentSource: FIRE_FRAG,
+        vertexWgsl: PLUME_VERT_WGSL,
+        fragmentWgsl: FIRE_FRAG_WGSL,
+        vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+        fragmentBindings: FIRE_BINDINGS.FIRE_FRAG,
+    },
+    smoke: {
+        label: 'plume:smoke',
+        vertexSource: PLUME_VERT,
+        fragmentSource: SMOKE_FRAG,
+        vertexWgsl: PLUME_VERT_WGSL,
+        fragmentWgsl: SMOKE_FRAG_WGSL,
+        /* Smoke shares the plume vertex stage; its own file records only the fragment one. */
+        vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+        fragmentBindings: SMOKE_BINDINGS.SMOKE_FRAG,
+    },
+    /*
+     * A radial counter-rotating swirl rather than a rising column, so it reads as a spell
+     * containing a thing rather than as a fire underneath it.
+     *
+     * **Added because a consumer already drew with it.** The shader has existed here since
+     * before the second backend and a consumer passed it as `ARCANE_FRAG`, which the move to
+     * named materials took away with nothing to replace it — the one effect in either consumer
+     * that the material table did not already cover. It is the only material that reads
+     * `uTint`, and that is why: an aura takes the day's glow colour, so relics shift with the
+     * palette exactly as the lamps do.
+     */
+    arcane: {
+        label: 'plume:arcane',
+        vertexSource: PLUME_VERT,
+        fragmentSource: ARCANE_FRAG,
+        vertexWgsl: PLUME_VERT_WGSL,
+        fragmentWgsl: ARCANE_FRAG_WGSL,
+        /* Arcane shares the plume vertex stage; its own file records only the fragment one. */
+        vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+        fragmentBindings: ARCANE_BINDINGS.ARCANE_FRAG,
+    },
+};
+/** Resolve a material name, or say which names exist. */
+export function plumeShaders(material) {
+    const found = MATERIALS[material];
+    if (found === undefined) {
+        throw new Error(`createPlumes: unknown plume material "${String(material)}". ` +
+            `Known materials: ${Object.keys(MATERIALS).join(', ')}.`);
+    }
+    return found;
+}

package/dist/render/plumeRenderer.d.ts

@@ -0,0 +1,96 @@
+import type { FrameView } from './frameView.ts';
+import { type PlumeMaterial } from './plumeMaterial.ts';
+import type { Atmosphere } from './atmosphere.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * Batched camera-facing quads for volumetric effects — flames, smoke, steam,
+ * dust. Game-agnostic: it knows positions, sizes and time, and nothing about
+ * what the plume represents.
+ *
+ * One VAO for the whole batch, four vertices per plume, everything animated on
+ * the GPU. The caller supplies the shader pair, so a new effect is a new
+ * fragment shader rather than a new renderer.
+ */
+export interface PlumePlacement {
+    x: number;
+    y: number;
+    z: number;
+    /** Half-width and full height, metres. */
+    width: number;
+    height: number;
+}
+export type PlumeBlend = 'additive' | 'alpha';
+export interface PlumeOptions {
+    /**
+     * Which plume this is, by name.
+     *
+     * **This replaced a pair of GLSL source strings on 2026-08-13, and the replacement is a
+     * breaking change made on purpose.** A caller-supplied shader is a capability that can only
+     * ever exist on WebGL2: WebGPU has no runtime GLSL compiler and this package must not ship
+     * one. Naming the material lets each backend resolve what it can compile. See
+     * `plumeMaterial.ts` for what was given up.
+     */
+    material: PlumeMaterial;
+    /** Emissive effects (fire) add light; dense ones (smoke) occlude it. */
+    blend: PlumeBlend;
+    /**
+     * How much the quads swell and shrink over time, 0 for a fixed size. Purely
+     * visual — anything gameplay depends on must keep its own fixed volume, or
+     * the simulation starts depending on the render clock.
+     */
+    sizePulse?: number;
+    /**
+     * How far this plume leans in a given wind, metres per m/s at its crown.
+     * Smoke is carried; a flame is anchored to its fuel and barely bends.
+     */
+    windResponse?: number;
+    /**
+     * Colour handed to the fragment stage as `uTint`, or white when absent.
+     *
+     * Optional shader contract, the same arrangement `uNoiseOctaves` and
+     * `uCameraRight` already use: the uniform is set unconditionally and
+     * `uniformLocations` hands back null for a shader that ignores it, so `fire`
+     * and `smoke` are untouched by this existing.
+     */
+    tint?: Vec3;
+}
+export declare class PlumeRenderer {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly buffers;
+    private readonly indexCount;
+    /**
+     * The per-vertex size buffer, kept so a caller can turn individual plumes off.
+     *
+     * A batch is uploaded once because a fire does not move — but a *fire that is not always
+     * burning* does need saying. Oil slicks ignite on a cycle, and before this there was no way
+     * to draw one only while it was alight: the launch happened with an empty screen.
+     */
+    private readonly sizeBuffer;
+    private readonly sizes;
+    private readonly baseSizes;
+    private readonly blend;
+    private readonly sizePulse;
+    private readonly windResponse;
+    private readonly noiseOctaves;
+    private readonly tint;
+    constructor(gl: WebGL2RenderingContext, plumes: readonly PlumePlacement[], options: PlumeOptions, noiseOctaves: number);
+    /**
+     * Scale one plume, 0 to hide it.
+     *
+     * Writes only that plume's own vertices — every blade of its cross — so turning a slick's
+     * fire on costs a handful of floats rather than a re-upload of the batch. The caller owns
+     * *when*; the renderer has no idea what a slick is.
+     */
+    setScale(gl: WebGL2RenderingContext, index: number, scale: number): void;
+    /**
+     * Draw the batch. Call after the sky: these blend without writing depth, and
+     * the sky at depth 1.0 under LEQUAL would otherwise overwrite anything drawn
+     * against open background.
+     */
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, atmosphere: Atmosphere, underwaterEnabled: boolean, atmosphereCameraY: number, clipPlane: Float32Array | null, windX?: number, windZ?: number, originX?: number, originY?: number, originZ?: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    /** Uploads one attribute and returns its buffer, for the rare one a caller can change. */
+    private attach;
+}

package/dist/render/plumeRenderer.js

@@ -0,0 +1,185 @@
+import { PLUME_VERTS } from './plumeGeometry.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { bindAtmosphere } from './atmosphere.js';
+import { plumeShaders } from './plumeMaterial.js';
+import { buildPlumeGeometry } from './plumeGeometry.js';
+/**
+ * Blades in each plume's cross, and the vertices that costs.
+ *
+ * **Two, crossed at 90°, instead of one card turned to face the viewer.** A single
+ * billboard has no three-dimensional structure to see: orbiting a fire showed the
+ * identical silhouette from every angle, because every card shared one camera-derived
+ * axis and the whole plume swivelled as a sheet. Reported twice: the fire did not read
+ * as three-dimensional, it read as something that moved with the camera — and after a
+ * first attempt that only *leaned* edge-on cards toward the viewer, it still did,
+ * correctly, because leaning still rotates whichever cards are edge-on, so the ensemble
+ * still tracks the viewer.
+ *
+ * A cross cannot track anything: both blades are fixed in world space, so turning
+ * around a fire genuinely brings one broadside as the other goes edge-on, which is
+ * the parallax a volume has. It also removes the reason billboarding existed — a
+ * blade going edge-on no longer vanishes, because its partner is square-on at that
+ * exact moment.
+ *
+ * Two rather than three because the plumes blend additively and are drawn in
+ * quantity: the third blade costs 50% more geometry for a difference the eye does not
+ * separate at the sizes these are drawn.
+ */
+const BLADES = 2;
+/* The shared count, so both backends step a plume's vertices the same way. */
+const VERTS_PER_PLUME = PLUME_VERTS;
+const CORNERS = [
+    [-1, -1],
+    [1, -1],
+    [1, 1],
+    [-1, 1],
+];
+export class PlumeRenderer {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    indexCount;
+    /**
+     * The per-vertex size buffer, kept so a caller can turn individual plumes off.
+     *
+     * A batch is uploaded once because a fire does not move — but a *fire that is not always
+     * burning* does need saying. Oil slicks ignite on a cycle, and before this there was no way
+     * to draw one only while it was alight: the launch happened with an empty screen.
+     */
+    sizeBuffer;
+    sizes;
+    baseSizes;
+    blend;
+    sizePulse;
+    windResponse;
+    noiseOctaves;
+    tint;
+    constructor(gl, plumes, options, noiseOctaves) {
+        const shaders = plumeShaders(options.material);
+        this.program = compileProgram(gl, shaders.vertexSource, shaders.fragmentSource, shaders.label);
+        this.uniforms = uniformLocations(gl, this.program, 'plumeRenderer');
+        this.blend = options.blend;
+        this.sizePulse = options.sizePulse ?? 0;
+        this.windResponse = options.windResponse ?? 0;
+        this.noiseOctaves = noiseOctaves;
+        this.tint = options.tint ?? [1, 1, 1];
+        /* Built in `plumeGeometry.ts`, so both backends lay out the same crossed quads. */
+        const { centers, corners, sizes, seeds, blades, indices } = buildPlumeGeometry(plumes);
+        this.indexCount = indices.length;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error(`${shaders.label}: createVertexArray failed`);
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        this.attach(gl, 0, centers, 3, shaders.label);
+        this.attach(gl, 1, corners, 2, shaders.label);
+        this.sizeBuffer = this.attach(gl, 2, sizes, 2, shaders.label);
+        this.attach(gl, 3, seeds, 1, shaders.label);
+        this.attach(gl, 4, blades, 1, shaders.label);
+        this.sizes = sizes;
+        // The authored sizes, so a hidden plume can be restored to exactly what it was.
+        this.baseSizes = new Float32Array(plumes.length * 2);
+        for (let f = 0; f < plumes.length; f++) {
+            const plume = plumes[f];
+            if (plume === undefined)
+                continue;
+            this.baseSizes[f * 2] = plume.width;
+            this.baseSizes[f * 2 + 1] = plume.height;
+        }
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error(`${shaders.label}: createBuffer failed`);
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Scale one plume, 0 to hide it.
+     *
+     * Writes only that plume's own vertices — every blade of its cross — so turning a slick's
+     * fire on costs a handful of floats rather than a re-upload of the batch. The caller owns
+     * *when*; the renderer has no idea what a slick is.
+     */
+    setScale(gl, index, scale) {
+        const span = VERTS_PER_PLUME * 2;
+        const base = index * span;
+        if (base < 0 || base + span > this.sizes.length)
+            return;
+        const width = this.baseSizes[index * 2] ?? 0;
+        const height = this.baseSizes[index * 2 + 1] ?? 0;
+        for (let c = 0; c < VERTS_PER_PLUME; c++) {
+            this.sizes[base + c * 2] = width * scale;
+            this.sizes[base + c * 2 + 1] = height * scale;
+        }
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.sizeBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, base * 4, this.sizes.subarray(base, base + span));
+    }
+    /**
+     * Draw the batch. Call after the sky: these blend without writing depth, and
+     * the sky at depth 1.0 under LEQUAL would otherwise overwrite anything drawn
+     * against open background.
+     */
+    draw(gl, camera, timeSeconds, atmosphere, underwaterEnabled, atmosphereCameraY, clipPlane, windX = 0, windZ = 0, originX = 0, originY = 0, originZ = 0) {
+        if (this.indexCount === 0)
+            return;
+        const u = this.uniforms;
+        gl.useProgram(this.program);
+        gl.uniform2f(u['uWind'] ?? null, windX, windZ);
+        gl.uniform3f(u['uOrigin'] ?? null, originX, originY, originZ);
+        gl.uniform1f(u['uWindResponse'] ?? null, this.windResponse);
+        gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+        const v = camera.view;
+        /*
+         * The camera's own basis, for shader pairs that billboard. The plume shaders
+         * shipped here no longer do — they draw world-fixed crosses, because anything
+         * that rotates with the camera reads as flat (see `BLADES`) — but the uniform is
+         * part of the generic contract a caller may supply its own vertex shader against,
+         * and `uniformLocations` hands back null for a shader that ignores it.
+         */
+        gl.uniform3f(u['uCameraRight'] ?? null, v[0] ?? 1, v[4] ?? 0, v[8] ?? 0);
+        gl.uniform3f(u['uCameraUp'] ?? null, v[1] ?? 0, v[5] ?? 1, v[9] ?? 0);
+        gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+        gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+        gl.uniform1f(u['uSizePulse'] ?? null, this.sizePulse);
+        // Optional shader contract: generic plume shaders may ignore these uniforms.
+        gl.uniform1i(u['uNoiseOctaves'] ?? null, this.noiseOctaves);
+        gl.uniform3f(u['uTint'] ?? null, this.tint[0], this.tint[1], this.tint[2]);
+        gl.uniform1i(u['uClipEnabled'] ?? null, clipPlane === null ? 0 : 1);
+        if (clipPlane !== null)
+            gl.uniform4fv(u['uClipPlane'] ?? null, clipPlane);
+        bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
+        gl.enable(gl.BLEND);
+        if (this.blend === 'additive')
+            gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        else
+            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+    /** Uploads one attribute and returns its buffer, for the rare one a caller can change. */
+    attach(gl, location, data, size, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, data, gl.DYNAMIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        return buffer;
+    }
+}

package/dist/render/pointLightSelection.d.ts

@@ -0,0 +1,175 @@
+/** Allocation-free selection and packing of point lights for a fixed shader budget. */
+export declare const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
+export interface PointLightSource {
+    x: number;
+    y: number;
+    z: number;
+    r: number;
+    g: number;
+    b: number;
+    /** Distance in metres at which illumination falls to zero. */
+    radius: number;
+    /** Colour modulation amplitude; zero keeps a steady source. */
+    flicker: number;
+    /** Shadow cubemap near plane in metres. */
+    shadowNear: number;
+    /** Physical emitter radius in metres, used to derive penumbra width. */
+    sourceRadius: number;
+    /**
+     * Where a spot points, as a world-space direction. Absent makes this a point light.
+     *
+     * Normalised here rather than trusted, because an un-normalised direction scales the cosine the
+     * cone is compared against and shows as a cone of the wrong width — which reads as the angle
+     * having been set wrong rather than as the vector.
+     */
+    dirX?: number;
+    dirY?: number;
+    dirZ?: number;
+    /**
+     * The cone's inner and outer half-angles in degrees. Full brightness inside the inner, nothing
+     * outside the outer, a smooth edge between.
+     *
+     * **A narrow cone is not free**, and the cost is the shadow rather than the shading. A spot's
+     * shadow takes a layer of the same octahedral array a point light's does, and that layer covers
+     * the whole sphere — so a 45 degree cone uses about 15% of it, roughly 0.38 of the linear
+     * resolution, and a 10 degree cone about 0.13. Comfortable for a lamp; visibly coarse for a
+     * stage spotlight, which is the measurement that would justify giving spots a perspective map.
+     */
+    coneInnerDeg?: number;
+    coneOuterDeg?: number;
+    /**
+     * Which photometric profile shapes this light, as a row of the atlas `setIesProfiles` uploaded.
+     *
+     * **Applies to a point light as well as a spot.** A bare bulb has a measured distribution too,
+     * and a fixture's own profile is usually a better description of it than any cone. Absent, or
+     * negative, is a light with no profile.
+     */
+    iesProfile?: number;
+    /**
+     * Whether this light is worth a shadow cubemap. Defaults to true.
+     *
+     * A light whose `radius` is animated invalidates its own map every frame —
+     * `matchesSource` compares the range, because the range *is* the cube's far plane —
+     * so it is perpetually stale and takes bake budget forever. With a fixed budget of a
+     * couple of faces a frame, a handful of those starve every real lamp in the world,
+     * and only the one nearest light ever finishes a bake.
+     *
+     * That is not hypothetical: pulsing floor markers animate a squared fade into
+     * `radius` every frame, and a courtyard full of them left exactly one lamp casting.
+     * They are floor lighting 35 cm off the deck and were never meant to cast at all.
+     */
+    castsShadow?: boolean;
+}
+export interface PointLightBuffer {
+    readonly positions: Float32Array;
+    readonly colors: Float32Array;
+    readonly radii: Float32Array;
+    /**
+     * Each selected light's emitter radius, in metres, packed beside its falloff radius.
+     *
+     * **A light has a size, and a highlight has to know it.** The shading treated every source as
+     * a mathematical point, so its reflection in a polished surface was a point too: smaller than
+     * a fragment, landing in some pixels and not their neighbours. That is the bright speckle a
+     * dark glossy model shows under a close lamp, and it cannot be filtered away afterwards
+     * because the information was never sampled. A real emitter subtends an angle, and a headlight
+     * a few centimetres from a wing subtends a very large one.
+     *
+     * `sourceRadius` already said this and only the shadow pass was listening, which is why the
+     * penumbra was right and the highlight was not.
+     */
+    readonly sourceRadii: Float32Array;
+    /**
+     * How many sources were offered this frame, against the `count` that won a slot.
+     *
+     * **Reported from outside, and it turned an afternoon into a glance.** A scene was submitting
+     * 63 lights against a budget of 10, so the whole budget went to static scenery between 7 and
+     * 23 metres away and the rig that answered the music never got a slot. Nothing flickered and
+     * nothing warned, because the selection did exactly what it documents; the symptom reported by
+     * a person was "the lights are poor", which leads nobody to a light budget. The count had to be
+     * recovered by walking the array in a console.
+     *
+     * Reading it costs nothing and it is the only figure that makes the ratio visible: 63 offered
+     * and 10 bound is a scene to prune, 12 offered and 10 bound is a scene that is fine.
+     */
+    considered: number;
+    count: number;
+    readonly sourceIndex: Int32Array;
+    /**
+     * How present each chosen light is, 0 to 1, against the two boundaries it can be
+     * crossing: the edge of view range, and the budget cut it shares with the nearest
+     * light that missed the set.
+     *
+     * Deliberately not folded into `colors`. Most of the shading is a colour multiply
+     * and would not care, but the emissive term is not — a lit inlay is dimmed by
+     * *whichever* lamp shadows it hardest, regardless of that lamp's colour, so a light
+     * arriving at zero brightness would still switch a shadow onto the start line. The
+     * weight has to reach the shader as itself.
+     */
+    readonly weights: Float32Array;
+    /**
+     * Three per slot: where a spot points, normalised. Zeroes for a point light.
+     *
+     * Filled for every slot rather than only for spots, because a slot keeps whatever the last light
+     * to hold it wrote — and a stale direction on a light that is now a point is a cone pointing
+     * somewhere it was never aimed.
+     */
+    readonly directions: Float32Array;
+    /** Two per slot: the cosine of the inner cone angle, then of the outer. */
+    readonly coneCos: Float32Array;
+    /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
+    readonly iesProfiles: Float32Array;
+    /** Internal insertion-sort storage; exposed only to keep one flat object. */
+    readonly scratchDistance: Float32Array;
+    /**
+     * The nearest `POINT_SHADOW_POOL` lights, nearest first — a superset of the shaded
+     * ones, and the reason a light no longer pops when it enters the sampled set.
+     *
+     * Before the shadow pool every light owned a permanent cubemap, so being chosen for
+     * shading meant the shadow was already correct. Borrowed maps broke that: joining
+     * the set meant evicting somebody and baking six faces at two a frame. The pool has
+     * always had four slots more than the shader can bind; these are the lights they are
+     * for, kept baked *before* they are wanted.
+     */
+    readonly shadowIndex: Int32Array;
+    shadowCount: number;
+}
+/**
+ * A buffer for the selection to fill, sized to what the caller can actually bind.
+ *
+ * **`capacity` exists because clustered lighting can carry far more than the shader's uniform
+ * arrays.** The froxel table takes up to `MAX_CLUSTERED_LIGHTS`, and this helper used to hand it
+ * sixteen whatever a world offered — so the capability was real and unreachable through the one
+ * path every consumer uses. A consumer with `RenderQuality.clusteredLights` on asks for a wider
+ * buffer; everything else takes the default and is unchanged.
+ *
+ * **`scratchDistance` grows with it**, and that is not incidental: the shaded list is kept sorted
+ * in it, so a buffer wider than the array holding its distances writes past the end. It was sized
+ * from `POINT_SHADOW_POOL` because the pool happened to be the larger of the two.
+ */
+export declare function createPointLightBuffer(capacity?: number): PointLightBuffer;
+/**
+ * Select nearest lights whose influence may still be visible and pack them in
+ * shader order. The caller owns `out`; no sort arrays or temporary objects are
+ * created in this per-frame path.
+ *
+ * **Two points, because the two lists answer two questions.** `x, y, z` is where the frame is
+ * being *shaded* from — the camera — and it orders and culls the shaded list. `castX, castY,
+ * castZ` is where whatever might *cast* is standing, and it orders and culls the shadow pool.
+ * `AGENTS.md` had already decided which point the pool belongs to: *"a character's shadow only
+ * has to exist near the light they are standing at"* — they, not the viewer.
+ *
+ * They were one argument until 2026-08-25, and a third-person camera is exactly where that
+ * hurts: it sits behind its subject, so a fire the subject is standing next to got **no map at
+ * all** whenever the camera was further from it than the fire's radius. The scene stayed
+ * perfectly lit, which is why nobody could tell it from a bake that never ran.
+ *
+ * What it gives up: three more numbers on an already-long parameter list, spelled as numbers
+ * rather than a vector to match the point above it. What would make it wrong: a consumer with
+ * several casters far apart, which one point cannot describe — the pool would then want a set of
+ * reference points and a rank over the nearest of them, which is a bigger change than this one
+ * and is not what any consumer here has.
+ *
+ * The default is the shading point, so an existing caller selects bit-identically: `castX = x`
+ * makes the distance the *same arithmetic on the same operands*, not merely a close number.
+ */
+export declare function selectPointLights(sources: readonly PointLightSource[], x: number, y: number, z: number, out: PointLightBuffer, timeSeconds?: number, viewRange?: number, castX?: number, castY?: number, castZ?: number): void;