@driftengine/core 4.8.6 → 4.8.7

package/CHANGELOG.json

@@ -1,4 +1,75 @@
 [
+  {
+    "version": "4.8.7",
+    "date": "2026-10-06",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "A lightmap page is 8 bytes a texel, half what it was: the irradiance is an rgb9e5 word the lit stage decodes and filters, and a bake that arrives packed uploads where it lies.",
+        "text": "`createLightmap` stored a page as two half-float layers, 16 bytes a texel, so a stage of 49 pages and 21.8 million texels took 348 MB on the device. The irradiance is now one rgb9e5 word a texel, three 9-bit mantissas over a shared 5-bit exponent in the layout of `EXT_texture_shared_exponent` and WebGPU's `rgb9e5ufloat`, beside the direction's four bytes, in two `rgba8` layers that the lit stage decodes and filters itself: 8 bytes a texel, 174 MB for the same stage. `LightmapPage.irradiance` takes a `Uint32Array` of packed words as a bake hands them over, uploaded where they lie with no float array in between, as well as floats, which are packed once at upload. What it gives up is precision in a texel's smaller channels, which share the largest one's exponent, and anything past 65,408; light has neither to lose. On `demo/dev/lightmap.html` a page of one value is still 0 pixels from the same ambient raised by `setAmbientSH`, and the room is within one level of 4.8.6's on both backends."
+      },
+      {
+        "kind": "changed",
+        "short": "The BC decode worker is behind its own specifier, so a game importing `@driftengine/assets` no longer has it in its build: name `spawnBcWorker` as `DrftLoader`'s `bcWorker` to decode in it.",
+        "text": "`DrftLoader` decoded a BC texture the device cannot take as blocks in a worker it built with `new Worker(new URL('./bcWorker.ts', import.meta.url))` inside the package's barrel, and a bundler writes that worker out at transform time, before tree-shaking, so every game importing anything from `@driftengine/assets` carried the BC decoder's chunk from 4.8.4 on, whether or not it loaded a BC texture. The gate that asserts no barrel names a worker bundled each barrel against the built packages and skipped one that would not bundle, so it saw this one only when another test's `npm pack` had built them first, which is how it passed three releases. The factory is now `spawnBcWorker` at `@driftengine/assets/src/bcWorkers.ts`, as the physics island pool is, and a loader takes it as `bcWorker`; without it BC textures decode on the main thread and the loader says so once, naming the option. The gate bundles from source now. Every scene and page in this repository that loads a model names the worker."
+      },
+      {
+        "kind": "added",
+        "short": "`PointLightSource.falloffExponent` lights by `(1 - (d/R)^2)^n` with no distance term, Unreal's falloff for a light without inverse square, in both arms and on water, DriftLight and DriftRay.",
+        "text": "A point or spot light may name its own falloff: `(1 - (d/R)^2)^n` with `R` its radius and `n` the exponent, and no inverse square, which is how Unreal lights a light that does not use inverse-square falloff. A rig authored there keeps its shape: a fill meant to light a whole hall across a hundred metres does, where the frame's falloff had it gone a few metres out. 0, or absent, is the frame's falloff as before. The selection carries it in `PointLightBuffer.falloffExponents` and the environment in `lightFalloffExponents`; the fixed arm reads it in the third lane of the cone uniform, which a two-float array already paid a whole row for, so the eight-light build spends no uniform row on it, and the froxel table's record grows to six texels. Water, DriftLight's volume and DriftRay's bounce fall off by it too, so a light lands the same way on every surface it reaches. On `demo/dev/clustered.html` one light drawn by the fixed arm and by the table is 0 pixels apart on both backends, and an exponent of 8 moves 42,123 pixels against none."
+      },
+      {
+        "kind": "added",
+        "short": "`AreaLightSource.barnDoorAngle` and `barnDoorLength` hang barn doors on a rectangle: each fragment is lit by the part the doors leave in view, its highlight included, in both arms.",
+        "text": "A rectangle may carry barn doors, a flap hinged at each edge standing `barnDoorAngle` degrees from its normal and `barnDoorLength` metres long, 20 cm when absent, as Unreal's rect lights do. At 90 they fold flat and hide nothing; smaller narrows the light to the opening they leave. Each fragment shades the part of the rectangle no door's tip hides, one axis at a time, so the form factor and the integrated highlight both come from that smaller rectangle, in the fixed arm, which reads the doors in the size uniform's two spare lanes, and in the froxel table's record. Each door is taken as endless along its hinge, so where two meet the corner they hide is square rather than mitred, and a shadowed rectangle's map is still baked from its whole face. Measured from straight above a 1.2 by 0.5 m panel 1.2 m over a floor with 20 degree, 30 cm doors: nothing changes within the 1.04 by 0.69 m box the door tips leave whole, nothing is lit past 4.94 and 2.32 m where they hide all of it, the fixed and clustered arms are 0 pixels apart, and doors at 90 degrees are 0 pixels from none, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.physicalSpecular` shades a lamp's and the sun's highlight as GGX's own `pi D Vis F N.L` with the specular attribute as F0, on the standard, lightmap and anisotropic models.",
+        "text": "The engine's highlight is a look control: it peaks at the specular attribute times one however rough the surface, so strength and width are set apart. A material with `physicalSpecular: true` takes GGX's own term instead, `pi * D * Vis * F * N.L` with Smith's height-correlated masking, as Unreal shades and as this engine's skin and eye already did. Its peak is `1 / (4 alpha^2)` of the light head-on, so a polished surface's highlight is several times the look's and a rough one's lower and wider; the specular attribute is read as the reflectance at normal incidence, Unreal's `0.08 * Specular`, and Fresnel brightens every surface toward grazing rather than a metal alone. Lamps, widened by their size as before, and the sun take it, on the standard, lightmap and anisotropic models; a rectangle's highlight was already the lobe integrated over it with that F0. The code is a lit switch, compiled into the lit programs the first time a material asks, so a scene that never does carries none of it. Measured with a lamp and an eye mirrored about a floor at roughness 0.5, where the term works out by hand to 4.4376: the physical highlight at 1/4.4377 of the light reads the look's middle pixel to within a level on both backends, from a lamp and from the sun, and the anisotropic model's physical lobe at strength 0 is the standard one to within a level everywhere."
+      },
+      {
+        "kind": "added",
+        "short": "`ReflectiveSurface.fresnel` reads `strength` as the surface's reflectance head-on and weighs each pixel by the split-sum BRDF at its view and `roughness`, so a reflection follows the camera.",
+        "text": "A screen-space reflection's `strength` was one share over its box, so a floor reflected as much underfoot as toward the horizon and a consumer re-matched the share to its camera's angle each frame. With `fresnel: true` the strength is the surface's reflectance head-on and each pixel returns `F0 * A + B` of what its ray finds, the split-sum environment BRDF at its own view and the box's `roughness`: Karis's fit, now one GLSL text that the lit stage and the reflection pass both include. The pass reads no material, so the reflectance and roughness are the box's, and nothing occludes the reflection where the lit stage's ambient occlusion would. Off by default, the one share as before. Measured on `demo/dev/ssr.html`: at a reflectance of 1 and roughness 0 it is 0 pixels from a strength of 1, as the fit says, and at a pixel whose view works out by hand to N.V 0.344, reflectance 0.04 matches the constant strength the fit gives there, 0.153, to within a level on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`MeshInstances.uvRegions` gives each instance its own cell of its texture, so mesh particles on different flipbook frames, or props on different tiles of an atlas, are one draw.",
+        "text": "Four floats an instance, `[scaleU, scaleV, offsetU, offsetV]`, applied to the mesh's texture coordinates before the material's own scale and offset, in the lit, depth and motion stages alike, so a cutout instance's shadow is cut by its own cell. They ride the bottom row of the instance's matrix, which a placement made of a turn, a scale and a move leaves at `[0, 0, 0, 1]` and which every stage drawing an instance now rebuilds as that, so they cost no attribute and no byte; an instanced placement must be affine, as every placement of a solid object is. Absent, every instance wears the whole texture, and a culled copy carries the cells into a target that has the array. On `demo/dev/instanceCells.html` eight cards each on their own cell of a strip, in one instanced draw, are 0 pixels from eight single draws with the cell in their materials, opaque and blended, on both backends; the published scenes and the instanced shadow, cull and opacity pages are 0 pixels from 4.8.6 on WebGPU."
+      },
+      {
+        "kind": "added",
+        "short": "`createSceneCapture` and `captureScene` draw the world from a camera of your own into a texture any material shows, a stadium screen's emissive or a monitor's, on both backends.",
+        "text": "`createSceneCapture(width, height)` makes a texture the scene can be drawn into, and `captureScene(capture, camera, clearColor, draw)` draws it: the callback is handed the camera, its matrices shaped to the capture, and submits the world exactly as it would to the screen. The texture then goes wherever an image goes, as a material's `emissive` for a screen in the world showing what another camera sees, a monitor or a security feed. It holds radiance, as a reflection probe does: the output transform and exposure are held off for the pass, at the world's colour format and sample count, half floats under `hdrScene`, so the frame grades the screen once with everything around it. It is the probe bake's arrangement and the mesh pass alone: the sky, water and particles are in it only if the callback draws them, nothing after the world runs on it, it has no mip chain, and the frame's camera, jitter, motion, refraction copy and skin spread are left alone while it draws. WebGL2 draws a capture's rows flipped, as it does a probe face's, so it reads as an image does. A second camera's view shown on a quad filling the frame is 0 pixels from that view drawn directly, single-sampled on both backends and at four samples on WebGPU, where WebGL2's multisampled capture is WebGPU's to the pixel; and a frame with a capture in it is 0 pixels from the frame without one outside the screen."
+      },
+      {
+        "kind": "added",
+        "short": "`drawDeviceParticles` draws a particle pool's material from a buffer your own compute shader wrote, where it lies, with nothing read back. WebGPU only; WebGL2 says so once.",
+        "text": "A simulation can run entirely on the device: a compute shader of the consumer's own, registered with `registerCompute`, writes its particles into a buffer of its own, and `drawDeviceParticles(batch, { buffer, count }, camera, env, time)` draws the pool's material, blend, flipbook, fades and fog from that buffer in place of the one the pool uploads into. Each particle is `DEVICE_PARTICLE_FLOATS`, sixteen floats in a `ParticleInstances`' order, and the buffer needs `VERTEX` usage beside `STORAGE`; a slot of half-width 0 draws nothing, so a fixed-size buffer can hold fewer live particles than it has room for, and a count past what the buffer holds is cut to it. The particles are not sorted. WebGL2 has no compute stage, so there it says so once and draws nothing. On `demo/dev/spriteParticles.html` sixteen sprites written by a compute shader are 0 pixels from the same sixteen uploaded, soft edges included."
+      },
+      {
+        "kind": "fixed",
+        "short": "A skin's `radius` is how far its light travels, as documented: the profile is at two fifths of it, so screen-space skin no longer smears a face seen up close over tens of pixels.",
+        "text": "`skinModel`'s `radius` was documented as how far light travels beneath the surface before it leaves, and was handed to Burley's profile as its distance `d` itself. That profile carries light 2.5 `d` on average and the blur's taps reach 9 `d`, so light travelled two and a half times as far as the model said, and `skinScattering: 'screen-space'` spread a face at arm's length over sixty pixels: a nose, lips and brows washed into one blur. The profile is now at `radius / 2.5` in both paths, the screen-space blur and the lit stage's pre-integrated fit, transmission and penumbra, so the two still agree. Measured first rather than assumed: on a step of light at 0.75 m and 800 by 600, the blur matched the profile's own masses at the old distance exactly, edges at the predicted taps, so the kernel was right and the distance was not; it now reaches 26 pixels where it reached 65, on both backends. A skin authored against the old meaning and looking right keeps its look with its `radius` raised by 2.5."
+      },
+      {
+        "kind": "fixed",
+        "short": "The anisotropic model on a mesh with neither tangents nor texture coordinates drew black, a direction normalised from zero; it takes a direction in the surface now.",
+        "text": "A brushed surface takes its direction from the tangent frame, and a mesh carrying neither tangents nor coordinates gives a frame of zeros, which normalised to a NaN and drew the whole surface black. It takes a direction in the surface's plane instead, across the world's up, so the highlight is stretched somewhere. Measured on a floor with no coordinates: the anisotropic model at strength 0 draws the standard highlight to within a level on both backends, where it drew nothing."
+      },
+      {
+        "kind": "fixed",
+        "short": "Arcs stay finite under multisampling: an edge pixel shaded off the quad took the filament's side coordinate past one and its powers to NaN, which bloom spread into a white disc.",
+        "text": "A multisampled target shades a pixel on a quad's edge at its centre, which can lie outside the quad. There an arc's side coordinate ran past one, the filament's `across` went negative, and `pow` of a negative number is NaN on both backends: one dark speck, which bloom then spread into a white disc the size of its blur around every arc. `across` is clamped before its powers. Found by a scene drawing short arcs at four samples."
+      },
+      {
+        "kind": "note",
+        "short": "The lit stage carries the falloff exponent and barn doors in every permutation: 2.8 to 6.4% more instructions on RADV at a phone's viewport, and the same registers.",
+        "text": "What every lit pipeline now compiles was measured on RADV with a phone's viewport, against 4.8.6: the fixed-arm lit pixel shader is 5,778 instructions where it was 5,618 on WebGPU and 5,171 where it was 4,989 on WebGL2, both still 96 registers; the clustered one is 6,831 where it was 6,507 and 6,313 where it was 5,934, still 120 and 108. Registers set how many fragments a phone's GPU keeps in flight, and they did not move. The physical highlight is a lit switch and costs nothing until a material asks for it. Core's gzipped size is 828.1 KB, 29.0 KB over 4.8.6, almost all of it the generated WGSL, whose sixteen lit permutations each carry the new light loop."
+      }
+    ]
+  },
   {
     "version": "4.8.6",
     "date": "2026-10-05",

package/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 777.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 828.1 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -367,8 +367,8 @@ export { seaStateForAgitation, seaStateForWind } from './render/seaState.ts';
 export type { SeaState } from './render/seaState.ts';
 export { InstancedMesh, createInstanceData, writeInstance } from './render/instancedMesh.ts';
 export { createMeshInstances, packInstances, INSTANCE_FLOATS, INSTANCE_STRIDE, } from './render/instances.ts';
-export { ParticlePool } from './render/particlePool.ts';
-export type { ParticlePoolOptions, ParticleInstances } from './render/particlePool.ts';
+export { ParticlePool, DEVICE_PARTICLE_FLOATS } from './render/particlePool.ts';
+export type { DeviceParticles, ParticlePoolOptions, ParticleInstances, } from './render/particlePool.ts';
 export { ParticleBatch } from './render/particleBatch.ts';
 export type { ParticleBatchOptions, ParticleBlend, ParticleFacing, } from './render/particleBatch.ts';
 export { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './render/shaders/particle.ts';

package/dist/index.js

@@ -474,7 +474,7 @@ export { InstancedMesh, createInstanceData, writeInstance } from './render/insta
  * pitches and rolls and a yaw cannot say so.
  */
 export { createMeshInstances, packInstances, INSTANCE_FLOATS, INSTANCE_STRIDE, } from './render/instances.js';
-export { ParticlePool } from './render/particlePool.js';
+export { ParticlePool, DEVICE_PARTICLE_FLOATS } from './render/particlePool.js';
 export { ParticleBatch } from './render/particleBatch.js';
 export { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './render/shaders/particle.js';
 export { BoltPool } from './render/boltPool.js';

package/dist/render/anisotropicLobe.d.ts

@@ -5,3 +5,13 @@ export declare function anisotropicAlphas(roughness: number, strength: number, o
  * are `th`, `bh` and `nh`. 1 at the mirror direction.
  */
 export declare function anisotropicLobe(th: number, bh: number, nh: number, alphaT: number, alphaB: number): number;
+/** Three components in the lobe's frame: along the direction, across it, along the normal. */
+export type FrameVector = readonly [number, number, number];
+/**
+ * The physical form of the same lobe, `π · D · Vis · N·L`, for a surface whose highlight is GGX's
+ * own (`SurfaceMaterial.physicalSpecular`): the stretched distribution normalised as a BRDF's, and
+ * Smith's height-correlated masking stretched with it (Heitz 2014, as Filament writes it), Fresnel
+ * left to the caller. The half vector, the light and the view are each in the lobe's frame. At
+ * strength 0 it is isotropic GGX, the term skin's and the eye's highlights are.
+ */
+export declare function anisotropicPhysicalLobe(half: FrameVector, light: FrameVector, view: FrameVector, alphaT: number, alphaB: number): number;

package/dist/render/anisotropicLobe.js

@@ -31,3 +31,22 @@ export function anisotropicLobe(th, bh, nh, alphaT, alphaB) {
     const d = x * x + y * y + nh * nh;
     return 1 / Math.max(d * d, 1e-8);
 }
+/**
+ * The physical form of the same lobe, `π · D · Vis · N·L`, for a surface whose highlight is GGX's
+ * own (`SurfaceMaterial.physicalSpecular`): the stretched distribution normalised as a BRDF's, and
+ * Smith's height-correlated masking stretched with it (Heitz 2014, as Filament writes it), Fresnel
+ * left to the caller. The half vector, the light and the view are each in the lobe's frame. At
+ * strength 0 it is isotropic GGX, the term skin's and the eye's highlights are.
+ */
+export function anisotropicPhysicalLobe(half, light, view, alphaT, alphaB) {
+    const x = half[0] / alphaT;
+    const y = half[1] / alphaB;
+    const d = x * x + y * y + half[2] * half[2];
+    const distribution = 1 / (Math.PI * alphaT * alphaB * d * d);
+    const ndl = light[2];
+    const ndv = view[2];
+    const lambdaView = ndl * Math.hypot(alphaT * view[0], alphaB * view[1], ndv);
+    const lambdaLight = ndv * Math.hypot(alphaT * light[0], alphaB * light[1], ndl);
+    const visibility = 0.5 / Math.max(lambdaView + lambdaLight, 1e-5);
+    return Math.PI * distribution * visibility * ndl;
+}

package/dist/render/areaLights.d.ts

@@ -95,6 +95,22 @@ export interface AreaLightSource {
      * of a scene unit, and never inside the rectangle itself. Unreal's `AttenuationRadius`, in metres.
      */
     range?: number;
+    /**
+     * Barn doors: a flap hinged at each of the rectangle's four edges, standing this many degrees from
+     * its normal. 90, or absent, folds them flat and they hide nothing; smaller closes them, so the
+     * light narrows to the opening they leave — a rectangle at 50° throws a beam rather than filling
+     * its hemisphere. Unreal's `BarnDoorAngle`, whose default of 88° is nearly flat.
+     *
+     * What a fragment sees past the doors is the part of the rectangle no door's tip hides, one axis
+     * at a time, and the rectangle then shades as that smaller rectangle, its highlight included.
+     * Its shadow map is still baked from the whole rectangle's centre. **What it gives up**: each
+     * door is taken as endless along its hinge, so the two axes clip apart and the corner where two
+     * doors meet hides a square rather than the mitre two real flaps make. One-sided: a two-sided
+     * rectangle's back face has none.
+     */
+    barnDoorAngle?: number;
+    /** The barn doors' length in metres. Absent, 0.2: Unreal's default of 20 cm. */
+    barnDoorLength?: number;
 }
 /** The irradiance a derived `range` ends at, in scene units. See `AreaLightSource.range`. */
 export declare const AREA_RANGE_CUTOFF = 0.001;
@@ -109,8 +125,27 @@ export interface AreaLightBuffer {
     readonly twoSided: Float32Array;
     /** One a rectangle: how far its light reaches. See `AreaLightSource.range`. */
     readonly ranges?: Float32Array;
+    /**
+     * Two a rectangle: the cosine of its barn doors' angle from its normal, then their length in
+     * metres — 0 and 0 for none. See `AreaLightSource.barnDoorAngle`.
+     */
+    readonly barnDoors?: Float32Array;
 }
 export declare function createAreaLightBuffer(capacity?: number): AreaLightBuffer;
+/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+export declare const DEFAULT_BARN_DOOR_LENGTH = 0.2;
+/**
+ * A rectangle's barn doors as the shader reads them, into `out[at]` and `out[at + 1]`: the cosine of
+ * their angle and their length. An angle not between 0 and 90 degrees, or a length not above zero,
+ * is no doors at all, written as 0 and 0 — which the shader reads as "nothing hidden".
+ */
+export declare function barnDoorsOf(light: AreaLightSource, out: Float32Array, at: number): void;
+/**
+ * The fixed arm's half extents and barn doors, four a rectangle as `uAreaLightSize` holds them: the
+ * two half extents, then the doors' cosine and length. Into a target the binder owns, for the first
+ * `MAX_AREA_LIGHTS` alone, which are all the fixed arm reads.
+ */
+export declare function packAreaSizesAndDoors(lights: AreaLightBuffer, out: Float32Array): void;
 /**
  * How far a rectangle's light reaches when it names no range: where its irradiance on its own axis,
  * `L · A / d²` for a rectangle of radiance `L` and area `A` seen from far, falls to

package/dist/render/areaLights.js

@@ -20,8 +20,41 @@ export function createAreaLightBuffer(capacity = MAX_AREA_LIGHTS) {
         sizes: new Float32Array(capacity * 2),
         twoSided: new Float32Array(capacity),
         ranges: new Float32Array(capacity),
+        barnDoors: new Float32Array(capacity * 2),
     };
 }
+/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+export const DEFAULT_BARN_DOOR_LENGTH = 0.2;
+/**
+ * A rectangle's barn doors as the shader reads them, into `out[at]` and `out[at + 1]`: the cosine of
+ * their angle and their length. An angle not between 0 and 90 degrees, or a length not above zero,
+ * is no doors at all, written as 0 and 0 — which the shader reads as "nothing hidden".
+ */
+export function barnDoorsOf(light, out, at) {
+    const angle = light.barnDoorAngle;
+    const length = light.barnDoorLength ?? DEFAULT_BARN_DOOR_LENGTH;
+    if (angle === undefined || !(angle >= 0 && angle < 90) || !(length > 0)) {
+        out[at] = 0;
+        out[at + 1] = 0;
+        return;
+    }
+    out[at] = Math.cos((angle * Math.PI) / 180);
+    out[at + 1] = length;
+}
+/**
+ * The fixed arm's half extents and barn doors, four a rectangle as `uAreaLightSize` holds them: the
+ * two half extents, then the doors' cosine and length. Into a target the binder owns, for the first
+ * `MAX_AREA_LIGHTS` alone, which are all the fixed arm reads.
+ */
+export function packAreaSizesAndDoors(lights, out) {
+    const doors = lights.barnDoors;
+    for (let a = 0; a < MAX_AREA_LIGHTS; a++) {
+        out[a * 4] = lights.sizes[a * 2] ?? 0;
+        out[a * 4 + 1] = lights.sizes[a * 2 + 1] ?? 0;
+        out[a * 4 + 2] = doors?.[a * 2] ?? 0;
+        out[a * 4 + 3] = doors?.[a * 2 + 1] ?? 0;
+    }
+}
 /**
  * How far a rectangle's light reaches when it names no range: where its irradiance on its own axis,
  * `L · A / d²` for a rectangle of radiance `L` and area `A` seen from far, falls to
@@ -106,6 +139,8 @@ export function selectAreaLights(lights, out) {
                     ? light.range
                     : areaRange(light.r, light.g, light.b, light.halfWidth, light.halfHeight);
         }
+        if (out.barnDoors !== undefined)
+            barnDoorsOf(light, out.barnDoors, slot * 2);
     }
     return out;
 }

package/dist/render/backend/api.d.ts

@@ -1,5 +1,6 @@
 import type { Bounds } from '../../math/bounds.ts';
 import type { Vec3 } from '../../math/color.ts';
+import type { Camera } from '../camera.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { MeshData } from '../mesh.ts';
 import type { ProbeBakeOptions } from '../reflectionProbe.ts';
@@ -8,6 +9,7 @@ import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
 import type { SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
+import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -187,7 +189,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -232,12 +234,33 @@ export type RendererApi = Omit<{
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
     /**
      * A baked lightmap page on the device, as the texture a `lightmapModel` material takes for its
-     * `modelMap`: two layers of half floats, the irradiance and the direction, filtered linearly and
-     * clamped at its edges, with no mip chain. Disposed as any texture is, with
+     * `modelMap`: two layers of four bytes a texel, the irradiance as an rgb9e5 word and the
+     * direction, which the lit stage decodes and filters itself, clamped at the page's edges, with no
+     * mip chain. A page whose irradiance arrives packed uploads where it lies. Disposed as any texture is, with
      * `disposeSurfaceTexture`; `updateSurfaceTexture` refuses it, as it refuses any array. See
      * `lightmap.ts` for what a surface does with it.
      */
     createLightmap(page: LightmapPage): SurfaceTextureHandle;
+    /**
+     * A texture the scene can be drawn into from a camera of the caller's (`captureScene`), which a
+     * material then shows like any image — most often as its `emissive`, for a screen in the world
+     * showing what a camera elsewhere sees. `width` and `height` in pixels, 1 to 4096. It holds
+     * radiance, at the colour format a probe takes: half floats under `hdrScene`, bytes otherwise.
+     * Disposed as any texture is; `updateSurfaceTexture` refuses it. See `sceneCapture.ts`.
+     */
+    createSceneCapture(width: number, height: number): SurfaceTextureHandle;
+    /**
+     * Draw the scene into a capture from `camera`, at the moment a caller says, usually once a frame
+     * before the frame's own world. `draw` is handed the camera, its matrices updated for the
+     * capture's shape, and submits the scene exactly as it would to the screen — `bindMeshPass`,
+     * `drawMesh` and the rest; `bindMeshPass` the frame's own camera again afterwards. The output
+     * transform is held off, so a screen showing it is graded once, with the frame.
+     *
+     * **The mesh pass alone**, as a probe bake is: what a scene draws after its world is in the
+     * capture only if `draw` draws it, and no temporal resolve or effect after the world runs on it.
+     * Returns whether it drew: false for a texture that is not a capture.
+     */
+    captureScene(capture: SurfaceTextureHandle, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * Replace a texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -444,6 +467,13 @@ export type RendererApi = Omit<{
     }): ParticleHandle;
     /** Draw a pool's live particles, after the opaque scene. */
     drawParticles(batch: ParticleHandle, data: Parameters<Renderer['drawParticles']>[1], camera: Parameters<Renderer['drawParticles']>[2], env: Parameters<Renderer['drawParticles']>[3], timeSeconds: number): void;
+    /**
+     * Draw a pool's particles from a buffer a caller's own compute wrote (`registerCompute`), where
+     * they lie: the pool's material, blend, flipbook and fades, its instance stream the caller's
+     * buffer. WebGPU only; WebGL2 says so once and draws nothing. Not sorted. See `DeviceParticles`
+     * for the layout.
+     */
+    drawDeviceParticles(batch: ParticleHandle, particles: DeviceParticles, camera: Parameters<Renderer['drawParticles']>[2], env: Parameters<Renderer['drawParticles']>[3], timeSeconds: number): void;
     /** Release a particle pool. */
     disposeParticles(batch: ParticleHandle): void;
     /** Draw a wet film over geometry, using a handle as the surface it lies on. */

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

@@ -61,7 +61,7 @@ import type { Atmosphere } from '../../atmosphere.ts';
 import { InstancedMesh } from '../../instancedMesh.ts';
 import { ParticleBatch } from '../../particleBatch.ts';
 import type { ParticleBatchOptions } from '../../particleBatch.ts';
-import type { ParticleInstances } from '../../particlePool.ts';
+import type { DeviceParticles, ParticleInstances } from '../../particlePool.ts';
 import { BoltBatch } from '../../boltBatch.ts';
 import type { BoltSegments } from '../../boltPool.ts';
 import { LineBatch } from '../../lineBatch.ts';
@@ -198,6 +198,11 @@ export interface Environment extends Atmosphere {
     lightDirections: Float32Array;
     /** Two per active light: the cosine of the inner cone angle, then of the outer. */
     lightConeCos: Float32Array;
+    /**
+     * One per active light: its own falloff exponent, or 0 for the frame's. Optional: absent is 0 for
+     * every light. See `PointLightSource.falloffExponent`.
+     */
+    lightFalloffExponents?: Float32Array;
     /** One per active light: a row of the photometric atlas, or −1 for none. */
     lightIesProfiles: Float32Array;
     /**
@@ -1231,6 +1236,15 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedEnvironmentAmbient;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
+    /**
+     * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
+     * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
+     */
+    private capturePassActive;
+    /** Each capture's framebuffer, beside the texture a material binds. See `createSceneCapture`. */
+    private readonly captureTargets;
+    /** Said once, where a driver refuses to draw into a capture. */
+    private warnedCapture;
     /** Whether the bake under way lights its faces by the grid. `ProbeBakeOptions.bounce`. */
     private probeBounce;
     /** The clip-control extension, or null where this context does not offer it. */
@@ -1833,6 +1847,21 @@ export declare class WebGL2Renderer implements RendererApi {
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): SurfaceTexture;
     /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
     createLightmap(page: LightmapPage): SurfaceTexture;
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. Half floats where the frame keeps range, as a probe does.
+     */
+    createSceneCapture(width: number, height: number): SurfaceTexture;
+    /**
+     * Draw the scene into a capture from `camera`: `draw` is handed the camera, its matrices updated
+     * for the capture's shape, and submits the scene as it would to the screen. See `RendererApi`.
+     *
+     * **Radiance, as a probe bake stores it**: the output transform and exposure are held off for the
+     * pass, so the frame grades a screen showing it once. No temporal jitter, which a capture has no
+     * resolve to undo. Returns whether it drew: false for a texture that is not a capture, or one the
+     * driver will not draw into.
+     */
+    captureScene(capture: SurfaceTexture, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1963,18 +1992,6 @@ export declare class WebGL2Renderer implements RendererApi {
      * program state, and this puts it back to what `currentSurfaceTexture` says it should be.
      */
     private restoreSurfaceTextureUnit;
-    /**
-     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
-     *
-     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
-     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
-     * This stays as the override for the case that has no answer to state: an imported model
-     * arrives with no grain information at all, and a caller drawing one decides for it.
-     *
-     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
-     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
-     * leaves geometry that did not exactly as it is.
-     */
     /**
      * The ambient the following draws take, as nine spherical-harmonic coefficients of incoming
      * radiance — red, green and blue of each, twenty-seven numbers — or `null` for the frame's own:
@@ -1986,6 +2003,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * only — a glossy surface still reflects the probes — and it is pass state like the material,
      * which `bindMeshPass` clears, so a mirror or a probe bake drawn after does not inherit it.
      */
+    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     /**
      * How much of the environment the following draws mirror, 0 to 1.
      *
@@ -1996,7 +2014,6 @@ export declare class WebGL2Renderer implements RendererApi {
      * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
      * exactly as it did.
      */
-    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     setSurfaceReflectivity(amount: number): void;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
@@ -2026,6 +2043,18 @@ export declare class WebGL2Renderer implements RendererApi {
      * a coordinated release is happening anyway.
      */
     setEnvironmentAmbient(_amount: number): void;
+    /**
+     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     *
+     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
+     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
+     * This stays as the override for the case that has no answer to state: an imported model
+     * arrives with no grain information at all, and a caller drawing one decides for it.
+     *
+     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
+     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
+     * leaves geometry that did not exactly as it is.
+     */
     setSurfaceGrain(amount: number): void;
     /**
      * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
@@ -2361,6 +2390,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * emitters; it is a material that knows what a particle is.
      */
     createParticles(capacity: number, options: ParticleBatchOptions): ParticleBatch;
+    /**
+     * Particles a caller's own compute wrote: WebGPU's alone, since this backend has no compute stage
+     * to have written them (`computeSupported`). Said once, and nothing is drawn.
+     */
+    drawDeviceParticles(_batch: ParticleBatch, _particles: DeviceParticles, _camera: Camera, _env: Environment, _timeSeconds: number): void;
+    /** Said once: see `drawDeviceParticles`. */
+    private warnedDeviceParticles;
     /**
      * Draw a live particle pool.
      *