@driftengine/core 3.61.0

package/dist/render/shaders/ambientOcclusion.js

@@ -0,0 +1,352 @@
+import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.js';
+/**
+ * Ambient occlusion from depth: the estimate, and the blur that makes it usable.
+ *
+ * Contact shading — the darkening where two surfaces meet, under a wheel arch, along a panel
+ * gap, where a plinth stands on a floor. It is most of what makes a model sit in a room
+ * rather than float in it, and its absence does not read as a missing effect. It reads as
+ * the geometry having been pasted over the picture.
+ *
+ * **Two passes rather than one, and that is the whole design decision.** Occlusion estimated
+ * inside the composite pass and used directly was built first and looked at: twelve depth
+ * samples per pixel is a noisy estimate of a smooth quantity, and a frame of it is salt and
+ * pepper over every surface. Every renderer that ships this blurs it, and a blur needs the
+ * estimate to exist somewhere first. So the estimate lands in its own single-channel target,
+ * gets smoothed by a separable pass that will not cross a depth edge, and the composite
+ * multiplies by the result.
+ *
+ * The pairing that makes twelve taps enough: the sampling directions are turned by a
+ * rotation that repeats every four pixels, and the blur runs over eight. Every four-pixel run
+ * contains all sixteen rotations exactly once, so averaging one recovers a sixteen-times-denser
+ * kernel; averaging two also halves what is left of the noise, and — the part that decides the
+ * width — leaves a pixel hard against a silhouette with four consecutive taps still on its own
+ * side of the edge. Neither half works alone: a random per-pixel rotation leaves noise the blur
+ * can only soften, and a window narrower than two periods leaves the tile itself on screen
+ * wherever the depth test cuts the window short, as a dotted line along every edge.
+ */
+/**
+ * The estimate. Writes one channel: 1 is open sky, 0 is fully enclosed.
+ *
+ * The estimator is the Alchemy/scalable-AO one — for each neighbour, the vector v from this
+ * surface to it, weighted max(0, v·n) / (v·v). Two properties earn it its place over a
+ * hemisphere of offset points: nothing has to be oriented, so there is no tangent frame and
+ * no rotation matrix per pixel, and the 1 / v·v term falls away on its own, so a neighbour
+ * further off contributes less without a second range test doing it by hand.
+ */
+export const AO_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/**
+ * **highp, and the whole effect depends on it.** GLSL ES gives a fragment shader's samplers a
+ * default precision of *lowp*, whatever the precision highp float line above says — that
+ * sets the default for float, not for a sampler. A lowp sampler may hand back eight bits,
+ * and eight bits of depth is a scene collapsed onto a couple of hundred planes.
+ *
+ * This was built without the qualifier and looked at first. The picture says exactly what it
+ * is once you know: the reconstructed normal came back as (0, 0, 1) over every surface,
+ * because within one of those planes the depth does not change between neighbouring pixels
+ * and the cross product of the two derivatives has nothing to work with. What reached the
+ * screen was contour banding along the planes themselves — rings up the car's flanks and
+ * stripes across the floor, which is a topographic map of the quantisation.
+ */
+uniform highp sampler2D uDepth;
+/**
+ * The projection's x and y scales, which turn a world radius into a screen one.
+ *
+ * mat4[0][0] and [1][1] of the perspective matrix and nothing else, so the whole projection
+ * does not have to be uploaded to answer "how much of the frame does half a metre cover at
+ * this depth". It carries the aspect ratio with it, which is why the reach is a vec2: a
+ * circle on screen is not a circle in UV.
+ */
+uniform vec2 uProjScale;
+/** Clip back to view space, so a depth sample becomes a position that can be compared. */
+uniform mat4 uInvProjection;
+/** How far the sampling reaches, in metres of the world. */
+uniform float uRadius;
+
+out float fragColor;
+
+/** How many depths each pixel compares itself against. Fixed, so the cost is fixed. */
+const int AO_TAPS = 12;
+/**
+ * The golden angle, in radians.
+ *
+ * Successive taps turned by it never line up into spokes, which a rational fraction of a
+ * turn does: a kernel that repeats a direction is blind along it, and it is blind the same
+ * way in every pixel, so it reads as a pattern in the surface rather than as noise.
+ */
+const float AO_GOLDEN_ANGLE = 2.39996323;
+/**
+ * How far the sampling may reach across the frame, whatever the depth says.
+ *
+ * A surface almost touching the near plane projects half a metre onto most of the screen,
+ * and without a ceiling those pixels each read the whole frame's depth: the effect stops
+ * being contact shading and becomes an expensive wide darkening. 6% of the frame.
+ */
+const float AO_MAX_REACH_UV = 0.06;
+/**
+ * Self-occlusion guard, as a fraction of the pixel's own view depth.
+ *
+ * Depth is quantised, so a flat surface samples itself very slightly in front of itself and
+ * every flat surface in the world comes back faintly dirty. The error grows with distance,
+ * which is why the guard is proportional to depth rather than a constant.
+ */
+const float AO_BIAS = 0.004;
+/**
+ * The floor under the 1 / (v·v) weighting, in square metres.
+ *
+ * Not a guard against dividing by zero, which is what a value near the float epsilon would
+ * be. The nearest taps land about a centimetre away, where v·v is 1e-4 and the weight is ten
+ * thousand — so a depth quantised to a millimetre yields several units of occlusion out of
+ * nothing at all. Measured that way first, with 1e-4 here: a flat floor came back as static.
+ * A hundredth of a square metre is a tenth of a metre of separation, which is the scale
+ * below which two samples are the same surface rather than one occluding the other.
+ */
+const float AO_EPSILON = 0.01;
+/**
+ * How many times further one neighbour may be than the other before the pair straddles an edge.
+ *
+ * Eight, and deliberately far above anything a continuous surface produces. On a plane seen at a
+ * grazing angle the two one-sided depth deltas do differ — depth grows nonlinearly with screen
+ * position — but only by a few percent except within a pixel or two of the vanishing point. A
+ * silhouette is not a factor of eight, it is a factor of hundreds, so the gate can afford to sit
+ * high and it is worth putting it there: every fragment this test lets through keeps the plain
+ * quad derivative, which is the picture that shipped.
+ */
+const float AO_EDGE_RATIO = 8.0;
+/**
+ * The floor under that ratio, as a fraction of the pixel's own view depth.
+ *
+ * **Without it the test is a comparison of two quantisation errors**, which is how a flat floor
+ * acquires a horizontal band at every contour of constant depth. Five percent of the distance is
+ * far above any depth buffer's quantum, above the difference two sides of a grazing plane show,
+ * and far below the step at any edge worth shading — a kerb against a deck is metres of it.
+ */
+const float AO_EDGE_FLOOR = 0.05;
+
+/** View-space position of whatever is at this pixel, from its depth alone. */
+vec3 viewPosition(vec2 uv, float depth) {
+  vec4 clip = vec4(uv * 2.0 - 1.0, ${glslSceneDepthToNdc('depth')}, 1.0);
+  vec4 view = uInvProjection * clip;
+  return view.xyz / view.w;
+}
+
+void main() {
+  /*
+   * One output pixel, in UV, along each axis.
+   *
+   * Taken before anything branches, because that is where a derivative is defined, and taken of
+   * vUv rather than of a reconstructed position: vUv is linear across a fullscreen triangle, so
+   * these are exact and constant. They are the *output's* pixel, which is what the neighbour
+   * taps below want — this estimate runs at half the frame on one backend and at full size on
+   * the other, and a step measured in the depth texture's texels would be wrong on one of them.
+   */
+  vec2 stepX = dFdx(vUv);
+  vec2 stepY = dFdy(vUv);
+
+  float depth = textureLod(uDepth, vUv, 0.0).r;
+  vec3 p = viewPosition(vUv, depth);
+  /*
+   * Both derivatives taken before anything branches on the depth. dFdx is only defined where
+   * every pixel of the quad reaches it, so a sky pixel returning early would leave the
+   * derivative undefined for the *geometry* pixels beside it — a wrong normal along every
+   * horizon in the frame, from a shader that reads as correct.
+   */
+  vec3 dpdx = dFdx(p);
+  vec3 dpdy = dFdy(p);
+  /* Nothing occludes the sky, and there is no surface here to occlude. */
+  if (${glslIsFarDepth('depth')}) {
+    fragColor = 1.0;
+    return;
+  }
+
+  /*
+   * At a silhouette, the quad derivative above is replaced by the one-sided difference that
+   * stays on this pixel's own surface. **Everywhere else it is left exactly alone**, and that
+   * restraint is the whole design of these twelve lines.
+   *
+   * **What it fixes.** A hardware derivative is a difference across a 2x2 quad, and every
+   * silhouette in the frame puts two surfaces in one quad: the difference is a secant from the
+   * near surface to the far one, metres long, and the cross product of two such secants is a
+   * normal roughly *perpendicular* to the real one. The dot of v with n for taps on the
+   * neighbouring surface comes back large and positive, the sum saturates, and the pixel clamps
+   * to black — every platform edge, every kerb and the character's own outline carrying black
+   * speckle. Speckle rather than a clean line, because the rotation tile below turns each
+   * pixel's taps differently, and the depth-aware blur that follows is designed *not* to cross
+   * an edge, so it preserved the garbage precisely where the garbage was.
+   *
+   * **What it must not do, learned the hard way.** The textbook cure is to take both one-sided
+   * differences everywhere and keep whichever has the smaller depth delta. That was built and
+   * shipped to a reporter, and it bands: the two sides of a flat surface differ by a
+   * quantisation step or by nothing, so "smaller delta" selects whichever side happens to read
+   * zero, the choice flips wherever the depth steps, and on a plane receding from the camera
+   * that is a contour — a horizontal stripe across the floor, over the whole world. The header
+   * above this shader describes the same picture arriving from a lowp sampler and names it: a
+   * topographic map of the quantisation.
+   *
+   * So the substitution is gated on a *discontinuity*, not on a preference. One side must be
+   * several times the other **and** clear of a floor proportional to this pixel's own distance,
+   * which no quantisation step and no continuous slope can reach. On everything that is not an
+   * edge these lines change nothing at all, which is what makes them safe to add.
+   */
+  vec3 right = viewPosition(vUv + stepX, textureLod(uDepth, vUv + stepX, 0.0).r);
+  vec3 left = viewPosition(vUv - stepX, textureLod(uDepth, vUv - stepX, 0.0).r);
+  vec3 down = viewPosition(vUv + stepY, textureLod(uDepth, vUv + stepY, 0.0).r);
+  vec3 up = viewPosition(vUv - stepY, textureLod(uDepth, vUv - stepY, 0.0).r);
+
+  /* View distance is positive down -z, and the floor is a fraction of this pixel's own. */
+  float here = -p.z;
+  float edgeFloor = AO_EDGE_FLOOR * here;
+  float rightGap = abs(-right.z - here);
+  float leftGap = abs(-left.z - here);
+  float downGap = abs(-down.z - here);
+  float upGap = abs(-up.z - here);
+
+  /* Both arms written towards increasing x and y, so which one wins cannot flip the handedness
+     of the cross product below — only the eye-facing test after it would have to notice. */
+  if (rightGap > leftGap * AO_EDGE_RATIO + edgeFloor) dpdx = p - left;
+  else if (leftGap > rightGap * AO_EDGE_RATIO + edgeFloor) dpdx = right - p;
+  if (downGap > upGap * AO_EDGE_RATIO + edgeFloor) dpdy = p - up;
+  else if (upGap > downGap * AO_EDGE_RATIO + edgeFloor) dpdy = down - p;
+
+  vec3 n = normalize(cross(dpdx, dpdy));
+  /*
+   * Turned to face the eye. Which sign the cross product comes out with is a fact about the
+   * screen-space winding and the handedness of the projection, and a normal pointing away
+   * from the camera makes every v·n come back zero, which is a frame with no occlusion in it
+   * anywhere. In view space the eye is the origin, so a normal facing it satisfies n·p < 0.
+   */
+  if (dot(n, p) > 0.0) n = -n;
+
+  /*
+   * The radius as a fraction of the frame. A metre subtends less of the screen the further
+   * away it is, which is the entire reason this is computed per pixel rather than handed in.
+   */
+  vec2 reach = min(
+    uRadius * uProjScale * 0.5 / max(-p.z, 1e-3),
+    vec2(AO_MAX_REACH_UV)
+  );
+
+  /*
+   * A rotation that repeats every four pixels: sixteen distinct turns laid out over a 4x4
+   * tile. Paired with the four-wide blur that follows, every blurred pixel averages all
+   * sixteen, which is what makes twelve taps enough. A per-pixel hash would decorrelate
+   * neighbours better in principle and is worse here, because the blur can then only soften
+   * the noise rather than complete the kernel.
+   */
+  float tile = mod(gl_FragCoord.x, 4.0) + 4.0 * mod(gl_FragCoord.y, 4.0);
+  float turn = tile * (6.2831853 / 16.0);
+
+  float sum = 0.0;
+  for (int i = 0; i < AO_TAPS; i++) {
+    float t = (float(i) + 0.5) / float(AO_TAPS);
+    float angle = turn + float(i) * AO_GOLDEN_ANGLE;
+    /* The square root spreads the taps evenly over the disk; without it they crowd the
+       centre, where they are measuring the pixel's own depth. */
+    vec2 uv = vUv + vec2(cos(angle), sin(angle)) * sqrt(t) * reach;
+
+    /*
+     * textureLod, not texture, and it is the rule rather than a preference: this sample sits
+     * inside a loop whose iterations a compiler cannot prove uniform, and an implicit
+     * derivative there is what lets one flatten the body and pay for every arm. The fetch is
+     * identical — the depth texture has one storage level and NEAREST filters, so there is no
+     * mip for a derivative to select. See AGENTS.md, 2026-08-07.
+     */
+    float sampled = textureLod(uDepth, uv, 0.0).r;
+    if (${glslIsFarDepth('sampled')}) continue;
+
+    vec3 v = viewPosition(uv, sampled) - p;
+    float vv = dot(v, v);
+    /* Past the radius it is a different surface rather than a neighbour of this one. */
+    if (vv > uRadius * uRadius) continue;
+    sum += max(0.0, dot(v, n) - AO_BIAS * (-p.z)) / (vv + AO_EPSILON);
+  }
+
+  fragColor = clamp(1.0 - 2.0 * uRadius * sum / float(AO_TAPS), 0.0, 1.0);
+}
+`;
+/**
+ * One direction of the blur. Run twice, across and then down.
+ *
+ * Separable, so a four-wide square costs eight taps rather than sixteen, and **depth-aware**,
+ * so it does not carry a car's occlusion out onto the wall behind it. That second part is
+ * what separates a blur from a smear: an ordinary gaussian over this estimate produces a
+ * dark halo around every silhouette, which is more obviously wrong than the noise it was
+ * added to remove.
+ */
+export const AO_BLUR_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+uniform sampler2D uAo;
+/** highp for the same reason as the estimate: a lowp sampler may return eight bits, and a
+    blur that decides what an edge is from eight-bit depth finds edges that are not there. */
+uniform highp sampler2D uDepth;
+/** One texel across, in UV, along the axis being blurred. The other component is zero. */
+uniform vec2 uStep;
+/**
+ * Turns a depth sample into view-space metres, as (m22, m32, m23, m33) of the inverse
+ * projection. The whole matrix is not needed to answer how far away a pixel is, and the blur
+ * asks that question five times per pixel.
+ */
+uniform vec4 uDepthToViewZ;
+
+out float fragColor;
+
+/**
+ * How far apart two pixels may be, as a fraction of their distance from the eye, before they
+ * stop being the same surface.
+ *
+ * Relative rather than absolute, because the same 5 cm step is a cliff on a dashboard and
+ * nothing at all on a far wall.
+ */
+const float AO_BLUR_DEPTH_TOLERANCE = 0.02;
+
+float viewZ(float depth) {
+  float ndc = ${glslSceneDepthToNdc('depth')};
+  return (uDepthToViewZ.x * ndc + uDepthToViewZ.y) / (uDepthToViewZ.z * ndc + uDepthToViewZ.w);
+}
+
+void main() {
+  float centre = viewZ(textureLod(uDepth, vUv, 0.0).r);
+  float tolerance = AO_BLUR_DEPTH_TOLERANCE * abs(centre) + 1e-4;
+  float sum = 0.0;
+  float weight = 0.0;
+  /*
+   * **Eight consecutive pixels: two whole periods of the rotation tile, not one.**
+   *
+   * One period was the original design and it is a quarter of a denoiser. The estimate is
+   * twelve taps of a noisy quantity, and it is only usable because a run of pixels averages
+   * the sixteen rotations of the 4x4 tile back into one kernel — but averaging four estimates
+   * divides their noise by two, and two of those four are the *same* pixel's neighbours seen
+   * from one side. What reached the screen was a soft field with a visible grain in it, and
+   * along every silhouette something worse.
+   *
+   * **The edge is what forces the second period.** The weight below is designed to fall to zero
+   * across a depth edge, so a pixel beside a rail keeps only the taps on its own side. With a
+   * four-wide window that can be a single tap — one rotation out of sixteen, at the tile's own
+   * four-pixel period, running along the edge. That is the dotted line reported along every
+   * rail, and no amount of care in the estimate removes it, because the estimate was never
+   * meant to stand alone. Eight wide, a pixel hard against an edge still has four consecutive
+   * taps on its own side, which is every phase exactly once — the kernel the estimate was
+   * designed around, recovered on the one side it can be recovered from.
+   *
+   * The cost is four more taps an axis on a single-channel target, and what it buys back is the
+   * halving of the noise that the four-wide window was already relying on and not getting.
+   */
+  for (int i = -3; i <= 4; i++) {
+    vec2 uv = vUv + uStep * float(i);
+    float z = viewZ(textureLod(uDepth, uv, 0.0).r);
+    /* One if this neighbour is on the same surface, falling to zero across an edge. */
+    float w = max(0.0, 1.0 - abs(z - centre) / tolerance);
+    sum += textureLod(uAo, uv, 0.0).r * w;
+    weight += w;
+  }
+  /* An isolated pixel — a thin rail against a far wall — keeps its own estimate rather than
+     dividing by nothing. */
+  fragColor = weight > 0.0 ? sum / weight : textureLod(uAo, vUv, 0.0).r;
+}
+`;

package/dist/render/shaders/arcane.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An arcane aura: the volume a floating object sits inside.
+ *
+ * Pairs with `PLUME_VERT`, exactly as `FIRE_FRAG` does — the vertex stage only builds
+ * a world-fixed cross of quads, and which effect that cross becomes is entirely a
+ * fragment-stage decision. So this costs no new renderer and no new geometry path.
+ *
+ * Where a flame is carved *vertically* — a taper toward the tip, a threshold rising
+ * with height, so it licks and breaks up — a spell is carved *radially*. Everything
+ * below works in polar coordinates about the quad centre: a bright thin core, a wide
+ * soft corona, and two noise bands turning in opposite directions.
+ *
+ * The counter-rotation is the whole effect. One band turning alone reads as a sheet
+ * being spun, which is the same flatness `BLADES` describes for a billboarded fire;
+ * two bands shearing against each other have no single rotation to read, so the eye
+ * gets motion without direction. That is what separates a spell from a lamp on a
+ * dimmer.
+ */
+export declare const ARCANE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin float vSeed;\nin float vDistance;\nin vec3 vWorldPos;\n\nuniform float uTime;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform int uNoiseOctaves;\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n/** The caller's colour, so an aura shifts with the world's own palette. */\nuniform vec3 uTint;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),\n    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),\n    u.y\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  // Polar about the quad centre. This is the line that makes it an orb rather\n  // than a column; everything downstream reads radius and angle, never height.\n  float radius = length(vUv - 0.5) * 2.0;\n  if (radius >= 1.0) discard;\n\n  vec2 d = vUv - 0.5;\n  float angle = atan(d.y, d.x);\n  float t = uTime + vSeed * 37.0;\n\n  /*\n   * Two bands, turning opposite ways at different rates. Sampled in (angle, radius)\n   * space so the noise wraps around the disc instead of sliding across it \u2014 noise in\n   * UV space would drift off one edge and read as a texture being scrolled.\n   */\n  float inner = valueNoise(vec2(angle * 1.9 + t * 0.55, radius * 4.2));\n  float outer = valueNoise(vec2(angle * 3.1 - t * 0.34, radius * 2.6));\n  float swirl = inner * 0.62 + outer * 0.38;\n  if (uNoiseOctaves > 1) {\n    swirl = mix(swirl, swirl * valueNoise(vec2(angle * 6.3 + t * 0.9, radius * 8.0)) * 2.0, 0.35);\n  }\n\n  /*\n   * Core and corona as two separate falloffs rather than one curve. A single falloff\n   * gives a blob; what makes this read as *contained energy* is a small bright centre\n   * with a much wider, much fainter halo, so the object inside stays legible.\n   */\n  float core = 1.0 - smoothstep(0.0, 0.28, radius);\n  float corona = (1.0 - smoothstep(0.18, 1.0, radius)) * (0.35 + swirl * 0.65);\n  float body = core * 0.9 + corona;\n  if (body <= 0.02) discard;\n\n  // Hot centre through the tint to a dark rim, so the core reads as white-hot\n  // energy and the edge as the colour it is made of.\n  vec3 col = mix(uTint * 0.35, uTint, smoothstep(0.0, 0.55, body));\n  col = mix(col, vec3(1.0), smoothstep(0.82, 1.4, body));\n  col *= uTint;\n\n  float alpha = clamp(body * 1.6, 0.0, 1.0);\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant aura glow through fog and through water.\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, mediumColor(), fog);\n  alpha *= 1.0 - fog;\n\n  outColor = vec4(col, alpha);\n}\n";

package/dist/render/shaders/arcane.js

@@ -0,0 +1,102 @@
+import { FOG_GLSL } from './fog.js';
+/**
+ * An arcane aura: the volume a floating object sits inside.
+ *
+ * Pairs with `PLUME_VERT`, exactly as `FIRE_FRAG` does — the vertex stage only builds
+ * a world-fixed cross of quads, and which effect that cross becomes is entirely a
+ * fragment-stage decision. So this costs no new renderer and no new geometry path.
+ *
+ * Where a flame is carved *vertically* — a taper toward the tip, a threshold rising
+ * with height, so it licks and breaks up — a spell is carved *radially*. Everything
+ * below works in polar coordinates about the quad centre: a bright thin core, a wide
+ * soft corona, and two noise bands turning in opposite directions.
+ *
+ * The counter-rotation is the whole effect. One band turning alone reads as a sheet
+ * being spun, which is the same flatness `BLADES` describes for a billboarded fire;
+ * two bands shearing against each other have no single rotation to read, so the eye
+ * gets motion without direction. That is what separates a spell from a lamp on a
+ * dimmer.
+ */
+export const ARCANE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+in float vSeed;
+in float vDistance;
+in vec3 vWorldPos;
+
+uniform float uTime;
+${FOG_GLSL}
+uniform int uNoiseOctaves;
+uniform vec4 uClipPlane;
+uniform int uClipEnabled;
+/** The caller's colour, so an aura shifts with the world's own palette. */
+uniform vec3 uTint;
+
+out vec4 outColor;
+
+float hash21(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+}
+
+float valueNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),
+    u.y
+  );
+}
+
+void main() {
+  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
+
+  // Polar about the quad centre. This is the line that makes it an orb rather
+  // than a column; everything downstream reads radius and angle, never height.
+  float radius = length(vUv - 0.5) * 2.0;
+  if (radius >= 1.0) discard;
+
+  vec2 d = vUv - 0.5;
+  float angle = atan(d.y, d.x);
+  float t = uTime + vSeed * 37.0;
+
+  /*
+   * Two bands, turning opposite ways at different rates. Sampled in (angle, radius)
+   * space so the noise wraps around the disc instead of sliding across it — noise in
+   * UV space would drift off one edge and read as a texture being scrolled.
+   */
+  float inner = valueNoise(vec2(angle * 1.9 + t * 0.55, radius * 4.2));
+  float outer = valueNoise(vec2(angle * 3.1 - t * 0.34, radius * 2.6));
+  float swirl = inner * 0.62 + outer * 0.38;
+  if (uNoiseOctaves > 1) {
+    swirl = mix(swirl, swirl * valueNoise(vec2(angle * 6.3 + t * 0.9, radius * 8.0)) * 2.0, 0.35);
+  }
+
+  /*
+   * Core and corona as two separate falloffs rather than one curve. A single falloff
+   * gives a blob; what makes this read as *contained energy* is a small bright centre
+   * with a much wider, much fainter halo, so the object inside stays legible.
+   */
+  float core = 1.0 - smoothstep(0.0, 0.28, radius);
+  float corona = (1.0 - smoothstep(0.18, 1.0, radius)) * (0.35 + swirl * 0.65);
+  float body = core * 0.9 + corona;
+  if (body <= 0.02) discard;
+
+  // Hot centre through the tint to a dark rim, so the core reads as white-hot
+  // energy and the edge as the colour it is made of.
+  vec3 col = mix(uTint * 0.35, uTint, smoothstep(0.0, 0.55, body));
+  col = mix(col, vec3(1.0), smoothstep(0.82, 1.4, body));
+  col *= uTint;
+
+  float alpha = clamp(body * 1.6, 0.0, 1.0);
+  // Additive light must lose alpha as it scatters, or mixing its colour alone
+  // still makes a distant aura glow through fog and through water.
+  float fog = mediumFog(vDistance, vWorldPos.y);
+  col = mix(col, mediumColor(), fog);
+  alpha *= 1.0 - fog;
+
+  outColor = vec4(col, alpha);
+}
+`;

package/dist/render/shaders/bloom.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Bloom: the three stages of spreading a bright thing past its own pixels.
+ *
+ * **What it is for, in the words of the consumer who asked for it.** Nothing in this renderer
+ * makes a bright thing look bright: an emissive surface is exactly as bright as its pixels and
+ * not one pixel wider, so anything meant to overwhelm the eye has to be faked in geometry — a
+ * core sphere, a second sphere slightly larger, and fifty-four additive particles standing in
+ * for one pass. Every neon ring, lit poster, glyph band and shaft of daylight is the same
+ * request.
+ *
+ * **It composes with the tone curve rather than replacing it.** The curve decides how a bright
+ * pixel rolls off; this decides how far it spreads. So the result is added in linear scene
+ * units, before the grade, and the grade then rolls off the sum exactly as it rolls off
+ * anything else.
+ *
+ * **The threshold is in scene units, which is only meaningful with a target that keeps them.**
+ * With an eight-bit target the scene is clipped to 0..1 before the composite ever sees it, so a
+ * star and a sheet of white paper arrive as the same colour and a threshold can only mean
+ * whiteness. That is the whole reason hdrScene exists and it is why bloom asks for it.
+ *
+ * Three stages, and the middle one repeats:
+ *
+ * 1. **Prefilter**, full resolution down to half: subtract the threshold and keep what is left.
+ * 2. **Downsample**, halving each time, six levels or as many as the frame allows. Each level
+ *    is an octave of the spread, and adding them back is what produces a wide falloff rather
+ *    than one gaussian with a hard end.
+ * 3. **Upsample**, additively back up the chain through a tent filter.
+ *
+ * Deliberately absent, because they were asked against by name: lens dirt, anamorphic streaks
+ * and ghosting. One threshold, one radius, one strength.
+ */
+/**
+ * Stage one: threshold the scene and halve it.
+ *
+ * **Subtracted rather than stepped**, which is what keeps one number honest. A hard cut at the
+ * threshold puts a visible edge through any gradient that crosses it, and repairing that is
+ * where a second knob usually arrives. Scaling the colour by how far its own luminance sits
+ * past the threshold is continuous, starts at exactly nothing, and needs no knee: a pixel just
+ * over the line contributes almost none of itself, and one far over contributes nearly all.
+ *
+ * **The boxes are averaged by the Karis weighting here and nowhere else.** A single pixel far
+ * brighter than its neighbours — which this renderer produces, on glossy dark paint, and which
+ * STATUS 6.3 measures — would otherwise be spread into a visible blob by the very pass whose
+ * job is to spread bright things. Weighting each box by 1 / (1 + luma) before averaging makes
+ * one runaway pixel count for little against its four neighbours. It is applied only to the
+ * first stage because it is not energy-preserving, and running it down the whole chain darkens
+ * every large bright area rather than only taming isolated ones.
+ */
+export declare const BLOOM_PREFILTER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/** One source texel in UV. The thirteen taps are laid out in source texels. */\nuniform vec2 uTexel;\n/** In scene units. 1.0 is \"brighter than white\", which is the useful place to start. */\nuniform float uThreshold;\n\nout vec4 fragColor;\n\n/**\n * A ceiling on what any one pixel may contribute, well above anything a scene means.\n *\n * Not a look control. A half-float target can hold an infinity, and an infinity through the\n * threshold below is inf/inf, which is a NaN that the chain then spreads across the whole\n * frame \u2014 the one failure mode where a post pass destroys the picture rather than degrading\n * it. Anything above this is indistinguishable after the tone curve anyway.\n */\nconst float BLOOM_CEILING = 256.0;\n\nfloat brightness(vec3 c) {\n  return max(c.r, max(c.g, c.b));\n}\n\nvec3 fetch(vec2 uv) {\n  vec3 c = min(textureLod(uSource, uv, 0.0).rgb, vec3(BLOOM_CEILING));\n  float bright = brightness(c);\n  return c * (max(bright - uThreshold, 0.0) / max(bright, 1e-4));\n}\n\n/** How much a box counts for. A runaway pixel drags its box's brightness up and its weight down. */\nfloat firefly(vec3 c) {\n  return 1.0 / (1.0 + brightness(c));\n}\n\nvoid main() {\n\n  vec2 t = uTexel;\n  vec3 a = fetch(vUv + vec2(-2.0,  2.0) * t);\n  vec3 b = fetch(vUv + vec2( 0.0,  2.0) * t);\n  vec3 c = fetch(vUv + vec2( 2.0,  2.0) * t);\n  vec3 d = fetch(vUv + vec2(-2.0,  0.0) * t);\n  vec3 e = fetch(vUv);\n  vec3 f = fetch(vUv + vec2( 2.0,  0.0) * t);\n  vec3 g = fetch(vUv + vec2(-2.0, -2.0) * t);\n  vec3 h = fetch(vUv + vec2( 0.0, -2.0) * t);\n  vec3 i = fetch(vUv + vec2( 2.0, -2.0) * t);\n  vec3 j = fetch(vUv + vec2(-1.0,  1.0) * t);\n  vec3 k = fetch(vUv + vec2( 1.0,  1.0) * t);\n  vec3 l = fetch(vUv + vec2(-1.0, -1.0) * t);\n  vec3 m = fetch(vUv + vec2( 1.0, -1.0) * t);\n\n  vec3 box0 = (a + b + d + e) * 0.25;\n  vec3 box1 = (b + c + e + f) * 0.25;\n  vec3 box2 = (d + e + g + h) * 0.25;\n  vec3 box3 = (e + f + h + i) * 0.25;\n  vec3 box4 = (j + k + l + m) * 0.25;\n\n  float w0 = firefly(box0) * 0.125;\n  float w1 = firefly(box1) * 0.125;\n  float w2 = firefly(box2) * 0.125;\n  float w3 = firefly(box3) * 0.125;\n  float w4 = firefly(box4) * 0.5;\n  vec3 sum = box0 * w0 + box1 * w1 + box2 * w2 + box3 * w3 + box4 * w4;\n  fragColor = vec4(sum / max(w0 + w1 + w2 + w3 + w4, 1e-4), 1.0);\n}\n";
+/**
+ * Stage two: halve what is already thresholded, once per level.
+ *
+ * The weights sum to exactly one, so each level holds the average of what fed it and the chain
+ * neither gains nor loses light. Nothing is thresholded again: that decision was made once, at
+ * full resolution, where it could still be made per pixel.
+ */
+export declare const BLOOM_DOWNSAMPLE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\nuniform vec2 uTexel;\n\nout vec4 fragColor;\n\nvec3 fetch(vec2 uv) {\n  return textureLod(uSource, uv, 0.0).rgb;\n}\n\nvoid main() {\n\n  vec2 t = uTexel;\n  vec3 a = fetch(vUv + vec2(-2.0,  2.0) * t);\n  vec3 b = fetch(vUv + vec2( 0.0,  2.0) * t);\n  vec3 c = fetch(vUv + vec2( 2.0,  2.0) * t);\n  vec3 d = fetch(vUv + vec2(-2.0,  0.0) * t);\n  vec3 e = fetch(vUv);\n  vec3 f = fetch(vUv + vec2( 2.0,  0.0) * t);\n  vec3 g = fetch(vUv + vec2(-2.0, -2.0) * t);\n  vec3 h = fetch(vUv + vec2( 0.0, -2.0) * t);\n  vec3 i = fetch(vUv + vec2( 2.0, -2.0) * t);\n  vec3 j = fetch(vUv + vec2(-1.0,  1.0) * t);\n  vec3 k = fetch(vUv + vec2( 1.0,  1.0) * t);\n  vec3 l = fetch(vUv + vec2(-1.0, -1.0) * t);\n  vec3 m = fetch(vUv + vec2( 1.0, -1.0) * t);\n\n  vec3 box0 = (a + b + d + e) * 0.25;\n  vec3 box1 = (b + c + e + f) * 0.25;\n  vec3 box2 = (d + e + g + h) * 0.25;\n  vec3 box3 = (e + f + h + i) * 0.25;\n  vec3 box4 = (j + k + l + m) * 0.25;\n\n  fragColor = vec4(box4 * 0.5 + (box0 + box1 + box2 + box3) * 0.125, 1.0);\n}\n";
+/**
+ * Stage three: a 3x3 tent, added into the level above.
+ *
+ * **Additive rather than a mix, and each octave counts the same.** A lone bright pixel arrives
+ * at level n divided by four to the n, spread over four to the n pixels, so summing the levels
+ * lifts its own pixel by about a third and lays a long shallow tail around it. That falloff is
+ * what a real glare looks like; a single gaussian gives a disc with an end to it.
+ *
+ * The radius is in UV rather than in texels, so it is the same fraction of the frame at every
+ * level and on every display. A tent rather than a box because the seams between the four
+ * texels a bilinear upsample reads are otherwise visible as a grid on a wide, faint halo.
+ */
+export declare const BLOOM_UPSAMPLE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uSource;\n/** How far the tent reaches, in UV. One number for the whole chain. */\nuniform float uRadius;\n\nout vec4 fragColor;\n\nvoid main() {\n  float r = uRadius;\n  vec3 a = textureLod(uSource, vUv + vec2(-r,  r), 0.0).rgb;\n  vec3 b = textureLod(uSource, vUv + vec2(0.0, r), 0.0).rgb;\n  vec3 c = textureLod(uSource, vUv + vec2( r,  r), 0.0).rgb;\n  vec3 d = textureLod(uSource, vUv + vec2(-r, 0.0), 0.0).rgb;\n  vec3 e = textureLod(uSource, vUv, 0.0).rgb;\n  vec3 f = textureLod(uSource, vUv + vec2( r, 0.0), 0.0).rgb;\n  vec3 g = textureLod(uSource, vUv + vec2(-r, -r), 0.0).rgb;\n  vec3 h = textureLod(uSource, vUv + vec2(0.0, -r), 0.0).rgb;\n  vec3 i = textureLod(uSource, vUv + vec2( r, -r), 0.0).rgb;\n\n  vec3 sum = e * 4.0 + (b + d + f + h) * 2.0 + (a + c + g + i);\n  fragColor = vec4(sum * 0.0625, 1.0);\n}\n";