@driftengine/core 3.61.0

package/dist/render/rainField.d.ts

@@ -0,0 +1,99 @@
+import type { LineSegments } from './linePoints.ts';
+import type { GroundSurface } from '../physics/ribbonSurface.ts';
+/**
+ * Falling rain, as streaks the line batch already draws.
+ *
+ * **A drop is a segment, not a billboard, and that is the whole design.** The particle pool draws
+ * round sprites with a spin, which is right for smoke and grit and wrong for water: rain in a
+ * photograph is a *streak*, because the drop moved while the shutter was open, and a round sprite
+ * stretched by a shader would need a new attribute and a new branch in both backends' particle
+ * programs. A segment from where a drop was to where it is says the same thing with geometry that
+ * has shipped for a year — and it gets the angle for free, since the streak runs along the
+ * velocity and the velocity is where the wind already is.
+ *
+ * **What was missing was never the mechanism.** `ParticlePool` and the line batch both ship; what
+ * did not exist was anything that made falling water out of either, so a consumer whose weather
+ * already wetted surfaces and raised their reflectivity had three of their four acceptance
+ * criteria and no water anybody could see fall.
+ *
+ * **Drops do not fall through roofs**, which is the requirement that usually turns a rain effect
+ * into a real one, and the query for it was already here: `GroundSurface.sampleBand` answers "is
+ * there a face in this column between these two heights", which is exactly "is something over my
+ * head". A drop under cover is not drawn. The same surface's `sample` is the floor it lands on, so
+ * rain stops at the ground rather than continuing to the bottom of the slab.
+ *
+ * **Nothing here reads a clock or a random number.** A drop's place in the slab is a hash of its
+ * index and how many times it has fallen, so the same viewer at the same instant sees the same
+ * rain — the rule the dust field in `lightVolume.ts` is under, for the same reason.
+ */
+export interface RainFieldOptions {
+    /** How many drops are in the air at once. */
+    count: number;
+    /** Half-width of the box of rain kept around the viewer, metres. */
+    radiusM: number;
+    /** How far above the viewer a drop starts, metres. Also the ceiling a roof is looked for under. */
+    heightM: number;
+    /**
+     * Fall speed. Rain reaches about 9 m/s, drizzle is nearer 2, and hail comes down at about 14.
+     *
+     * The starting value only: `RainField.speedMps` moves it while the field is running, which is
+     * what a weather state changing under a player needs.
+     */
+    speedMps?: number;
+    /**
+     * How much of a drop's own motion the streak shows, in seconds.
+     *
+     * It is a shutter time and behaves like one: 0.02 is a crisp dash, 0.1 is the smeared rain of a
+     * long exposure. It does not affect where a drop is, only how long it looks.
+     */
+    streakSec?: number;
+    /** The ground drops land on, and the roofs they do not fall through. */
+    ground?: GroundSurface;
+}
+export declare class RainField {
+    readonly segments: LineSegments;
+    private readonly x;
+    private readonly y;
+    private readonly z;
+    /** How many times each drop has been respawned, which is the other half of its hash. */
+    private readonly cycle;
+    private readonly hit;
+    private readonly count;
+    private readonly radiusM;
+    private readonly heightM;
+    /** Fall speed, metres a second. Rain is about 9, drizzle 2, hail 14. */
+    speedMps: number;
+    /**
+     * The shutter time the streak shows, seconds: 0.02 is a crisp dash, 0.1 a long exposure.
+     *
+     * It changes how long a drop *looks* and never where it is, so a downpour can smear without
+     * falling any faster.
+     */
+    streakSec: number;
+    private readonly ground;
+    /** Drops not drawn this update because something was over them. */
+    private sheltered;
+    /**
+     * Whether the first update has spread the drops through the slab.
+     *
+     * **Without it the first second of rain is a curtain.** A drop respawns near the ceiling, which
+     * is right for one that has just landed and wrong for all of them at once: a field built and
+     * updated would hold every drop in the top few metres, and what arrives is a single sheet
+     * descending rather than rain. So the first update spreads them through the whole height, and
+     * every one after that respawns them at the top, where a drop that has just fallen belongs. It
+     * cannot be done in the constructor because the slab is placed around a viewer this does not
+     * know about until it is asked to draw.
+     */
+    private primed;
+    constructor(options: RainFieldOptions);
+    /** Drops that were over the viewer's head and under something else, last update. */
+    get shelteredCount(): number;
+    /**
+     * Fall for `dt`, then rebuild the streaks around a viewer.
+     *
+     * `windX` and `windZ` are metres per second sideways, and the same numbers the rest of the scene
+     * is answering to: rain leaning one way while the smoke beside it leans another is the failure
+     * this parameter exists to prevent, and it is why the wind is passed in rather than owned here.
+     */
+    update(dt: number, viewerX: number, viewerY: number, viewerZ: number, windX?: number, windZ?: number): void;
+}

package/dist/render/rainField.js

@@ -0,0 +1,168 @@
+import { createLineSegments } from './linePoints.js';
+import { coveredAbove } from '../physics/heightSurface.js';
+import { createSurfaceHit } from '../physics/ribbonSurface.js';
+export class RainField {
+    segments;
+    x;
+    y;
+    z;
+    /** How many times each drop has been respawned, which is the other half of its hash. */
+    cycle;
+    hit = createSurfaceHit();
+    count;
+    radiusM;
+    heightM;
+    /*
+     * The two numbers a weather state moves, and they are public for a measured reason.
+     *
+     * **Both were `private readonly` until 2026-08-28**, and the report that ended it named the case
+     * a constructor argument cannot serve: weather changes while a game runs. A consumer with a
+     * hailstorm on one of its days had a field built at rain's nine metres a second and no way to
+     * move it, so hail — which falls at about fourteen — was expressed as a wider, denser rain and
+     * read as heavy rain.
+     *
+     * Plain fields rather than accessors because there is nothing to validate against and nothing to
+     * invalidate: no array is sized by either, nothing caches a value derived from one, and both are
+     * read fresh inside `update`. A write between updates costs an assignment.
+     *
+     * **What they give up** is that neither is checked, so a speed of zero hangs the rain in the air
+     * and a negative one is *no* rain rather than rain rising — a drop that never reaches the floor
+     * is never respawned. Both are visible in one frame, which is why a throw would be the worse
+     * trade: this is a per-frame setter, and the engine does not throw in a frame loop. **What would
+     * make it wrong** is either number gaining a consequence outside `update`.
+     */
+    /** Fall speed, metres a second. Rain is about 9, drizzle 2, hail 14. */
+    speedMps;
+    /**
+     * The shutter time the streak shows, seconds: 0.02 is a crisp dash, 0.1 a long exposure.
+     *
+     * It changes how long a drop *looks* and never where it is, so a downpour can smear without
+     * falling any faster.
+     */
+    streakSec;
+    ground;
+    /** Drops not drawn this update because something was over them. */
+    sheltered = 0;
+    /**
+     * Whether the first update has spread the drops through the slab.
+     *
+     * **Without it the first second of rain is a curtain.** A drop respawns near the ceiling, which
+     * is right for one that has just landed and wrong for all of them at once: a field built and
+     * updated would hold every drop in the top few metres, and what arrives is a single sheet
+     * descending rather than rain. So the first update spreads them through the whole height, and
+     * every one after that respawns them at the top, where a drop that has just fallen belongs. It
+     * cannot be done in the constructor because the slab is placed around a viewer this does not
+     * know about until it is asked to draw.
+     */
+    primed = false;
+    constructor(options) {
+        if (!(options.count > 0))
+            throw new Error(`RainField: count must be positive, got ${options.count}`);
+        if (!(options.radiusM > 0))
+            throw new Error(`RainField: radiusM must be positive, got ${options.radiusM}`);
+        if (!(options.heightM > 0))
+            throw new Error(`RainField: heightM must be positive, got ${options.heightM}`);
+        this.count = options.count;
+        this.radiusM = options.radiusM;
+        this.heightM = options.heightM;
+        this.speedMps = options.speedMps ?? 9;
+        this.streakSec = options.streakSec ?? 0.04;
+        this.ground = options.ground ?? null;
+        this.segments = createLineSegments(options.count);
+        this.x = new Float32Array(options.count);
+        this.y = new Float32Array(options.count);
+        this.z = new Float32Array(options.count);
+        this.cycle = new Uint32Array(options.count);
+        for (let i = 0; i < options.count; i++)
+            this.cycle[i] = i;
+    }
+    /** Drops that were over the viewer's head and under something else, last update. */
+    get shelteredCount() {
+        return this.sheltered;
+    }
+    /**
+     * Fall for `dt`, then rebuild the streaks around a viewer.
+     *
+     * `windX` and `windZ` are metres per second sideways, and the same numbers the rest of the scene
+     * is answering to: rain leaning one way while the smoke beside it leans another is the failure
+     * this parameter exists to prevent, and it is why the wind is passed in rather than owned here.
+     */
+    update(dt, viewerX, viewerY, viewerZ, windX = 0, windZ = 0) {
+        const span = this.radiusM * 2;
+        const top = viewerY + this.heightM;
+        this.segments.count = 0;
+        this.sheltered = 0;
+        for (let i = 0; i < this.count; i++) {
+            let dropY = (this.y[i] ?? 0) - this.speedMps * dt;
+            let dropX = (this.x[i] ?? 0) + windX * dt;
+            let dropZ = (this.z[i] ?? 0) + windZ * dt;
+            /*
+             * A drop that has left the slab comes back at the top in a new column, and a drop that never
+             * had a position starts the same way — which is what makes construction free of a spawn loop.
+             * The floor is the surface where there is one, so rain stops at the ground rather than
+             * falling to the bottom of a box nobody can see.
+             */
+            let floor = viewerY - this.heightM;
+            if (this.ground !== null && this.ground.sample(dropX, dropZ, this.hit, dropY)) {
+                floor = this.hit.y;
+            }
+            const outside = dropY <= floor ||
+                Math.abs(dropX - viewerX) > this.radiusM ||
+                Math.abs(dropZ - viewerZ) > this.radiusM;
+            if (outside || !this.primed) {
+                this.cycle[i] = ((this.cycle[i] ?? 0) + this.count) >>> 0;
+                const c = this.cycle[i] ?? 0;
+                dropX = viewerX - this.radiusM + hash(i, c) * span;
+                dropZ = viewerZ - this.radiusM + hash(i, c + 1) * span;
+                /*
+                 * On the first update, anywhere between the floor and the ceiling: rain that is already
+                 * falling when you look up. Afterwards, near the ceiling but not exactly at it, so drops
+                 * that wrapped on the same frame do not descend in step.
+                 */
+                dropY = this.primed
+                    ? top - hash(i, c + 2) * this.speedMps * 0.5
+                    : floor + hash(i, c + 2) * (top - floor);
+            }
+            this.x[i] = dropX;
+            this.y[i] = dropY;
+            this.z[i] = dropZ;
+            /*
+             * Under cover: anything solid in this column between the drop and the ceiling is a roof, and
+             * a drop below a roof was never rained on. It keeps falling — it is simply not drawn, which
+             * costs one query and means a viewer stepping into a doorway sees the rain stop over them
+             * rather than through them.
+             *
+             * **A hole in the roof rains, and nothing here arranges that.** `coveredAbove` asks whether
+             * the surface has a face in the column, so a gap between two pads, a stretch of `holes` in a
+             * ribbon, or the edge of a bounded field are all open sky already — cut once, in the
+             * geometry, rather than described a second time here where the two could disagree.
+             */
+            if (this.ground !== null && coveredAbove(this.ground, dropX, dropZ, dropY, top, this.hit)) {
+                this.sheltered++;
+                continue;
+            }
+            const at = this.segments.count;
+            this.segments.from[at * 3] = dropX;
+            this.segments.from[at * 3 + 1] = dropY;
+            this.segments.from[at * 3 + 2] = dropZ;
+            /* Where it was a shutter-time ago, which is the streak: down by its fall and back along the
+               wind, so a gust leans every drop at the same angle without anything trigonometric. */
+            this.segments.to[at * 3] = dropX - windX * this.streakSec;
+            this.segments.to[at * 3 + 1] = dropY + this.speedMps * this.streakSec;
+            this.segments.to[at * 3 + 2] = dropZ - windZ * this.streakSec;
+            this.segments.count = at + 1;
+        }
+        this.primed = true;
+    }
+}
+/**
+ * A number in [0, 1) from two integers, with no state and no clock.
+ *
+ * The same construction the particle pool hashes a spin with. It is not a good generator and does
+ * not need to be: what it has to avoid is neighbouring drops sharing a column, and a sine hash
+ * decorrelates adjacent integers well enough that a thousand of them look like rain.
+ */
+function hash(a, b) {
+    const value = Math.sin(a * 12.9898 + b * 78.233) * 43758.5453;
+    return value - Math.floor(value);
+}

package/dist/render/reflectionProbe.d.ts

@@ -0,0 +1,188 @@
+/** A cubemap of the scene from one point, for surfaces that mirror the room they stand in. */
+import type { Vec3 } from '../math/color.ts';
+import { Camera } from './camera.ts';
+/**
+ * What a bake is for, and specifically whether it also replaces the scene's diffuse ambient.
+ *
+ * **The two halves of a probe were one decision until 2026-09-03, and nothing could ask for the
+ * first alone.** A bake fills a cubemap that reflective surfaces sample, and it then reads that
+ * cubemap back, projects it onto spherical harmonics and raises `uEnvIrradianceEnabled` — from
+ * which frame on **every diffuse surface in the world takes its ambient from the projection
+ * instead of from the values the consumer wrote into `Environment`**. A consumer who wanted a car
+ * and a puddle to mirror the village got, as well, the whole scene changing what lights it, once,
+ * at whatever moment the bake landed.
+ *
+ * That is a defensible default — a room's own light is usually better than a gradient — but it was
+ * not a *choice*, and it correlates with nothing a consumer can see. The one it was reported from
+ * gates its bake on a streamer being idle, so the substitution arrived minutes into a drive, and
+ * it was filed four times over two days as four different bugs.
+ *
+ * `irradiance: false` declines the second half. The reflection is unaffected; the ambient stays
+ * whatever the consumer set. It also **stops paying for it** — the readback and the projection are
+ * the expensive part of a bake, and a caller that does not want the result does not wait for it.
+ *
+ * **It declines rather than undoes.** A bake that declines leaves an earlier projection in place,
+ * because "do not compute this" is not "discard what is there". What a consumer gets by passing it
+ * on *every* bake is the guarantee they were asking for: their ambient is never substituted.
+ */
+export interface ProbeBakeOptions {
+    /**
+     * Whether this bake also projects the room's diffuse light and lights the scene by it.
+     *
+     * Defaults to **true**, which is what every bake did before this existed, so a caller that says
+     * nothing gets the frame it already had.
+     */
+    readonly irradiance?: boolean;
+}
+export declare class ReflectionProbe {
+    /**
+     * The captured cube, box-filtered, which the convolution reads and the projection reads.
+     *
+     * **Not what the lit pass samples any more.** A box filter averages a square of texels and a
+     * GGX lobe is not square, so sampling this chain by roughness was an approximation whose error
+     * was largest exactly where a surface looks most interesting. It stays because filtered
+     * importance sampling needs a chain to pick a level from, and because `readFaces` projects
+     * *this* onto spherical harmonics — an irradiance integral over a lobe-convolved cube would be
+     * a convolution of a convolution.
+     */
+    readonly texture: WebGLTexture;
+    /**
+     * The prefiltered cube: one GGX-convolved level per roughness, and what `uEnvironment` binds.
+     *
+     * **A second texture rather than this one rewritten in place**, and it costs one cube of
+     * memory. What it buys is worth more than that here: WebGL2's feedback-loop check is per
+     * texture object, so rendering into a level of the cube a sampler is holding is the hazard the
+     * depth peel already pays for elsewhere, and with two objects it cannot arise. It is also what
+     * stops a level being convolved from a level that was already convolved, which applies the lobe
+     * twice and compounds up the chain.
+     *
+     * **What would make it wrong** is a probe large enough for a second cube to be the memory
+     * decision; at 128 with a chain that is about a megabyte at half float.
+     */
+    readonly prefiltered: WebGLTexture;
+    /** The camera the caller draws each face with. Reused, so a bake allocates nothing. */
+    private readonly camera;
+    private readonly framebuffer;
+    /**
+     * The convolution's own framebuffer, with no depth attached.
+     *
+     * The bake's framebuffer carries a full-size depth renderbuffer, and an attachment whose size
+     * does not match the colour one makes the framebuffer *incomplete* — so reusing it above level
+     * zero would fail at the first mip rather than at the last. A convolution has nothing to sort
+     * against and needs no depth at all.
+     */
+    private readonly prefilterFramebuffer;
+    private readonly depth;
+    /** Face width in texels. Public because the convolution's solid-angle term needs it. */
+    readonly size: number;
+    /**
+     * Whether the cube holds radiance above white, or clamps at it.
+     *
+     * False on a part without `EXT_color_buffer_float`, and on any caller that did not ask for an
+     * HDR scene — where the room the probe photographs was itself clamped before it got here, so a
+     * float cube would carry the same crushed values at twice the bandwidth.
+     */
+    private readonly floatColor;
+    /**
+     * Scratch for the byte path of `readFaces`, allocated on first use and reused after.
+     *
+     * Null rather than sized at construction, because a probe that is never read back — which is
+     * every probe on a scene that bakes one and never asks for irradiance — should not carry a
+     * megabyte for it.
+     */
+    private readBytes;
+    /** Scratch for the byte path of `upload`, on the same terms as `readBytes`. */
+    private uploadBytes;
+    /**
+     * Whether anything has ever been rendered into this.
+     *
+     * The shader must not sample a cubemap nobody has filled: what is in it is whatever the
+     * driver left, and a car mirroring uninitialised memory is worse than a car mirroring a
+     * gradient. So this gates the uniform rather than the allocation.
+     */
+    private baked;
+    /**
+     * Set once if the allocation is refused, and never cleared.
+     *
+     * A reflection is an improvement to an appearance rather than a requirement. The scene still
+     * renders without one and `flat.ts` still has the sky-and-ground gradient it used before this
+     * existed, so a device that cannot afford six faces loses the room in the paint and keeps
+     * everything else.
+     */
+    private unusable;
+    constructor(gl: WebGL2RenderingContext, size: number, wantsRange?: boolean);
+    /**
+     * Fill the captured cube from six faces a caller supplies, instead of photographing a room.
+     *
+     * **The same cube, so everything downstream is the same code.** A loaded environment and a baked
+     * one differ only in where the six faces came from; the box chain, the convolution and the
+     * spherical-harmonic projection all read this texture either way. That is what keeps a loaded sky
+     * from being a second lighting path with its own bugs.
+     *
+     * **A non-float cube clips rather than tone-maps**, and that is deliberate. The cube stores
+     * radiance, and a curve applied here would be a viewing transform baked into stored light — the
+     * mistake `bakeReflectionProbe` documents at length on the other side. A part without
+     * `EXT_color_buffer_float` gets a clipped environment and a metal that cannot reflect brighter
+     * than white, which is the honest degradation and is what `floatColor` already means everywhere
+     * else in this file.
+     */
+    upload(gl: WebGL2RenderingContext, faces: readonly Float32Array[]): boolean;
+    /**
+     * Linear floats to bytes, clipped at white, for a part with no renderable float cube.
+     *
+     * Allocated on first use and reused, like `readBytes` above and for the same reason: a probe that
+     * is only ever float should not carry a megabyte for a path it never takes.
+     */
+    private clipToBytes;
+    /**
+     * Convolve the captured chain into the prefiltered one, once per bake.
+     *
+     * **The caller draws, exactly as it does for a face.** This owns the target — which cube, which
+     * face, which level, and the viewport that level wants — and `convolve` owns the program, the
+     * uniforms and the triangle, which is the same split `bake` makes with `drawFace` and for the
+     * same reason: a probe has no business knowing what a shader is.
+     *
+     * `roughness` is handed over rather than recomputed by the caller, so the level-to-roughness
+     * relation lives in exactly one place. `prefilterEnvMap.ts` is that place, and the lit pass's
+     * own level selection is the same relation read the other way.
+     */
+    prefilter(gl: WebGL2RenderingContext, convolve: (face: number, level: number, roughness: number) => void): void;
+    /** Whether the shader may sample this. False until a bake has finished. */
+    get ready(): boolean;
+    /** How many mip levels the roughness blur has to work with. */
+    get maxLod(): number;
+    /**
+     * Render the six faces from `origin`, once.
+     *
+     * `drawFace` is handed a camera already aimed and is expected to submit the scene exactly as
+     * it would to the screen. It is called six times, and it must not call anything that binds a
+     * framebuffer of its own: a shadow pass or a planar reflection inside a probe bake would
+     * leave the probe's own target unbound halfway through a face.
+     *
+     * Returns whether the bake happened. A false means the allocation was refused and the caller
+     * should carry on without a probe, which is a picture with a gradient in its paint rather
+     * than a room.
+     */
+    bake(gl: WebGL2RenderingContext, origin: Vec3, clearColor: Vec3, drawFace: (camera: Camera) => void): boolean;
+    /**
+     * Read six faces back off the GPU, at one mip level, for the irradiance projection.
+     *
+     * **Synchronous, and that is the whole reason the two backends' bindings differ.** `readPixels`
+     * blocks until the queue reaches it, and on a level this coarse that is a few thousand texels
+     * once per bake. The other backend has no synchronous read at all — its cube is not copyable and
+     * `mapAsync` answers on a later tick — so it does this over two frames. Both hand the same six
+     * arrays to the same projection, which is where the decision lives.
+     *
+     * `out` must hold six arrays of at least `(size >> level)^2 * 4` floats. Answers false if the
+     * driver would not attach a face for reading, which is the same refusal `bake` already handles
+     * by carrying on without a probe: the reflection is already in the cube either way, so a false
+     * here costs the diffuse term and nothing else.
+     *
+     * **What would make it wrong** is reading a level the chain does not have. `texStorage2D`
+     * allocated `maxLod + 1` levels, so any level up to `maxLod` is in range; a caller asking for
+     * `maxLod - 3` needs a probe of at least eight texels, and below that the projection is not
+     * worth doing and the caller skips it.
+     */
+    readFaces(gl: WebGL2RenderingContext, level: number, out: Float32Array[]): boolean;
+    dispose(gl: WebGL2RenderingContext): void;
+}