@driftengine/core 3.61.0

package/dist/render/shaders/sky.js

@@ -0,0 +1,242 @@
+import { glslFarDepth } from '../depthConvention.js';
+/**
+ * Procedural gradient sky drawn as a single attribute-less fullscreen triangle.
+ * Ray direction is reconstructed per-fragment from the inverse view-projection,
+ * so the sky is correct under any camera. Drawn last at the far plane, so early-z wins —
+ * and the far plane is 0 under reversed depth and 1 otherwise, which is why the value is
+ * interpolated rather than written. A sky that says 1.0 in a reversed engine is drawn at the
+ * *near* plane and covers the world; measured, that was 743,669 changed pixels of 921,600.
+ */
+export const SKY_VERT = `#version 300 es
+const vec2 POS[3] = vec2[3](vec2(-1., -1.), vec2(3., -1.), vec2(-1., 3.));
+
+out vec2 vNdc;
+
+void main() {
+  vNdc = POS[gl_VertexID];
+  /* The far plane, whichever way depth runs: see glslFarDepth. */
+  gl_Position = vec4(vNdc, ${glslFarDepth()}, 1.0);
+}
+`;
+export const SKY_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vNdc;
+
+uniform mat4 uInvViewProj;
+uniform vec3 uCameraPos;
+uniform vec3 uTopColor;
+uniform vec3 uHorizonColor;
+uniform vec3 uDeepColor;
+uniform vec3 uSunDir;
+uniform vec3 uSunColor;
+uniform float uSunDiscExponent;
+uniform vec3 uMoonDir;
+uniform vec3 uMoonColor;
+uniform float uMoonAngularRadius;
+uniform float uMoonPhase;
+uniform float uNightFactor;
+uniform vec2 uCloudOffset;
+uniform vec3 uUnderwaterColor;
+uniform float uUnderwaterFactor;
+
+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);
+  float a = hash21(i);
+  float b = hash21(i + vec2(1.0, 0.0));
+  float c = hash21(i + vec2(0.0, 1.0));
+  float d = hash21(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+
+/** Three octaves is the ceiling — drop to two before cutting anything else. */
+float fbm(vec2 p) {
+  float v = valueNoise(p) * 0.5;
+  v += valueNoise(p * 2.03) * 0.3;
+  v += valueNoise(p * 4.01) * 0.2;
+  return v;
+}
+
+void main() {
+  vec4 world = uInvViewProj * vec4(vNdc, 1.0, 1.0);
+  vec3 dir = normalize(world.xyz / world.w - uCameraPos);
+
+  float t = dir.y;
+  vec3 col = t >= 0.0
+    ? mix(uHorizonColor, uTopColor, pow(min(t, 1.0), 0.55))
+    : mix(uHorizonColor, uDeepColor, min(-t * 1.8, 1.0));
+
+  // Celestial bodies belong to the sky, not to the void underneath. Seeing the
+  // sun below the horizon made the world read as unbounded in every direction;
+  // fading them out at the horizon leaves the deep reading as depth instead.
+  float aboveHorizon = smoothstep(-0.04, 0.06, dir.y);
+
+  /*
+   * Sunset.
+   *
+   * Low sunlight crosses far more atmosphere than high sunlight, and that path
+   * scatters the blue out of it — which is why the sun reddens as it drops and
+   * why the glow around it spreads into a band rather than staying a disc. Both
+   * effects peak right at the horizon and are gone within a few degrees of it,
+   * so they are driven by the sun's own elevation rather than by the clock.
+   *
+   * TWO EDGES, BECAUSE A SUNSET ENDS. This shipped with only the upper one, so every
+   * sun below the horizon read as maximum sunset and stayed there all the way to
+   * straight down — and a sun direction of (0, -1, 0) is what a night world writes to
+   * mean "there is no sun in this sky". A consumer measured the result on a black
+   * sun: 87% more red in the sky than the same frame with the sun pointing up, a warm
+   * band over a third of the picture in an arctic snowfield, and the world's own
+   * blue-grey horizon arriving with its channel order reversed. Four night worlds were
+   * not started over it, and this repository's own storm sea shipped it. The lower
+   * edge is where astronomical twilight ends, near -0.31, so the term now fades out
+   * over the same range the sky it models does.
+   *
+   * What it gives up: the glow is a function of the sun's elevation and nothing else,
+   * so a caller cannot place one where its own sun is not. That is deliberate — a knob
+   * here would let a world disagree with itself — but it is also what makes this wrong
+   * for a body that is not our sun in our atmosphere. A world lit by something that
+   * scatters differently needs its own term, not a wider edge here.
+   *
+   * Written ascending-and-inverted rather than as a descending smoothstep, whose
+   * result GLSL ES leaves undefined when edge0 >= edge1. Every implementation seen so
+   * far computes the ramp anybody would expect, which is why the descending form
+   * survived this long, but the spec does not owe us that.
+   */
+  float sunset = (1.0 - smoothstep(-0.03, 0.30, uSunDir.y)) *
+    smoothstep(-0.35, -0.05, uSunDir.y);
+  vec3 ember = vec3(1.0, 0.36, 0.13);
+
+  float s = max(dot(dir, uSunDir), 0.0);
+  // The disc itself reddens; the last sliver above the horizon is nearly blood
+  // orange, which is the moment the whole effect is remembered for.
+  vec3 discColor = mix(uSunColor, uSunColor * ember, sunset * 0.85);
+  col += discColor * (
+    pow(s, uSunDiscExponent) * 1.2 +
+    pow(s, max(uSunDiscExponent / 75.0, 1.0)) * 0.12
+  ) * aboveHorizon;
+
+  /*
+   * The band. Brightest toward the sun's bearing and hugging the horizon,
+   * falling off both with angle around the compass and with height — a sunset
+   * is a direction, not a uniform warm wash, and washing the whole dome is what
+   * makes a fake one look like a colour filter.
+   */
+  vec2 sunBearing = normalize(uSunDir.xz + vec2(1e-5));
+  vec2 viewBearing = normalize(dir.xz + vec2(1e-5));
+  float toward = max(dot(viewBearing, sunBearing), 0.0);
+  /*
+   * Measured from the horizon, and falling three times faster below it than above.
+   *
+   * This was abs(dir.y), which is symmetric, so the band was mirrored twenty-seven
+   * degrees down into the deep — visible in any world whose ground does not cover
+   * the lower half of the frame, and captured in the -Y face of every environment
+   * probe, where it tinted reflections warm. Nothing in the sky mirrors a sunset
+   * below the horizon; what is down there is ground, and the ground is drawn by
+   * somebody else.
+   *
+   * Not gated by aboveHorizon like the sun disc and the moon are: that factor is
+   * only 0.4 at a dir.y of zero, which is exactly where this term is brightest, so
+   * multiplying by it would cut the band's core to a third and change every sunset
+   * to fix a night. Falling faster below instead leaves everything at or above the
+   * horizon bit-for-bit as it was, and the horizon line itself unbroken. What it
+   * gives up: a camera under the world, or above a planet seen from outside its
+   * atmosphere, sees the glow end sooner than the geometry does.
+   */
+  float fromHorizon = dir.y >= 0.0 ? dir.y : -dir.y * 3.0;
+  float band = pow(1.0 - min(fromHorizon * 2.2, 1.0), 2.6);
+  col += ember * sunset * band * (0.18 + 0.75 * pow(toward, 2.2));
+
+  /*
+   * Belt of Venus: the sky opposite a setting sun takes a cool pink-violet from
+   * light already reddened on its way past. Subtle, but its absence is why an
+   * artificial sunset feels like it is only happening on one side.
+   */
+  float away = max(-dot(viewBearing, sunBearing), 0.0);
+  col += vec3(0.42, 0.28, 0.45) * sunset * band * away * 0.22;
+
+  /*
+   * Moon: a shaded procedural sphere-disc, not one dot subtracted from another.
+   * The local sphere normal gives a curved terminator and limb; lunar phase
+   * supplies the light direction around that sphere. Low-frequency noise adds
+   * maria without a texture file, while a faint earthshine keeps the dark limb
+   * just legible instead of cutting a mathematically black hole in the sky.
+   */
+  vec3 moonReference = abs(uMoonDir.y) < 0.98
+    ? vec3(0.0, 1.0, 0.0)
+    : vec3(1.0, 0.0, 0.0);
+  vec3 moonRight = normalize(cross(moonReference, uMoonDir));
+  vec3 moonUp = cross(uMoonDir, moonRight);
+  float moonRadius = clamp(uMoonAngularRadius, 0.001, 0.5);
+  vec2 moonUv = vec2(dot(dir, moonRight), dot(dir, moonUp)) / moonRadius;
+  float moonRadiusSq = dot(moonUv, moonUv);
+  float moonFacing = step(0.0, dot(dir, uMoonDir));
+  float moonDisc = (1.0 - smoothstep(0.90, 1.0, moonRadiusSq)) * moonFacing;
+  if (moonDisc > 0.0) {
+    float sphereZ = sqrt(max(1.0 - moonRadiusSq, 0.0));
+    vec3 surfaceNormal = normalize(vec3(moonUv, sphereZ));
+    float phaseAngle = uMoonPhase * 6.28318530718;
+    vec3 phaseLight = vec3(sin(phaseAngle), 0.0, -cos(phaseAngle));
+    float phaseShade = max(dot(surfaceNormal, phaseLight), 0.0);
+    float maria = valueNoise(moonUv * 3.2 + vec2(4.7, 9.1)) * 0.68 +
+      valueNoise(moonUv * 9.3 - vec2(7.4, 2.6)) * 0.32;
+    float albedo = mix(0.56, 1.02, maria);
+    float limb = mix(0.72, 1.0, sphereZ);
+    float earthshine = 0.035;
+    float lunarLight = earthshine + (1.0 - earthshine) * phaseShade;
+    col += uMoonColor * albedo * limb * lunarLight * moonDisc *
+      1.35 * uNightFactor * aboveHorizon;
+  }
+  float phaseIllumination = 0.5 - cos(uMoonPhase * 6.28318530718) * 0.5;
+  float moonHalo = (1.0 - smoothstep(1.0, 3.0, length(moonUv))) * moonFacing;
+  col += uMoonColor * moonHalo * 0.08 * phaseIllumination *
+    uNightFactor * aboveHorizon;
+
+  if (dir.y > 0.0) {
+    // Stars. Stereographic projection: unlike dir.xz/dir.y it stays finite and
+    // near-uniform all the way to the horizon, so stars don't smear into grain.
+    // Each cell holds one jittered *point* — lighting the whole cell would draw
+    // square blocks, which is what "random pixels" looks like.
+    if (uNightFactor > 0.0) {
+      vec2 p = dir.xz / (1.0 + dir.y) * 26.0;
+      vec2 cell = floor(p);
+      float h = hash21(cell);
+      if (h > 0.93) {
+        vec2 jitter = vec2(hash21(cell + 17.3), hash21(cell + 41.7));
+        float d = length(fract(p) - jitter);
+        float star = smoothstep(0.10, 0.0, d) * (0.4 + h * 0.6);
+        // Fade out near the horizon, where haze would swallow them anyway.
+        col += vec3(0.86, 0.91, 1.0) * star * uNightFactor * smoothstep(0.03, 0.3, dir.y);
+      }
+    }
+
+    // Clouds: banded value noise on a layer above the camera, carried by the
+    // world's wind — the same signal the smoke and the grass answer to, so the
+    // largest moving thing in frame agrees with the smallest.
+    // The floor on dir.y bounds the perspective stretch near the horizon.
+    if (dir.y > 0.02) {
+      vec2 uv = dir.xz / max(dir.y, 0.16) * 0.09 + uCloudOffset * 0.012;
+      float band = smoothstep(0.46, 0.60, fbm(uv));
+      float fade = smoothstep(0.02, 0.30, dir.y);
+      vec3 cloudCol = mix(uHorizonColor, vec3(1.0), 0.45) * mix(1.0, 0.32, uNightFactor);
+      col = mix(col, cloudCol, band * fade * 0.8);
+    }
+  }
+
+  // There is no outdoor sky inside a water column. Retain a little vertical
+  // gradient so the surface remains legible above and depth reads darker
+  // below, while celestial bodies and clouds disappear with the same smooth
+  // surface transition used by the geometry passes.
+  float waterLight = mix(0.62, 1.08, clamp(dir.y * 0.5 + 0.5, 0.0, 1.0));
+  col = mix(col, uUnderwaterColor * waterLight, uUnderwaterFactor);
+
+  outColor = vec4(col, 1.0);
+}
+`;

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

@@ -0,0 +1,8 @@
+/**
+ * Smoke: a column that rises, expands and dissipates. Shares the plume
+ * billboard vertex shader with fire — only the fragment behaviour differs.
+ *
+ * Alpha-blended rather than additive: smoke occludes what is behind it, and
+ * adding it would make it glow instead of darken.
+ */
+export declare const SMOKE_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\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\nfloat billow(vec2 p, float t) {\n  float v = valueNoise(p * 2.2 + vec2(0.0, -t * 0.55)) * 0.55;\n  if (uNoiseOctaves == 1) return v / 0.55;\n  v += valueNoise(p * 4.7 + vec2(t * 0.12, -t * 0.9)) * 0.29;\n  if (uNoiseOctaves == 2) return v / 0.84;\n  return v + valueNoise(p * 9.3 + vec2(-t * 0.09, -t * 1.4)) * 0.16;\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  float t = uTime + vSeed * 53.0;\n  float height = vUv.y;\n\n  // Widens as it climbs: sample a compressed space low down, a stretched one up\n  // top. Narrow at the bottom is what lets it sit inside the flame's tip.\n  float spread = mix(0.5, 1.0, height);\n  float centred = (vUv.x - 0.5) / spread + 0.5;\n\n  // Soft horizontal falloff rather than a hard cut \u2014 a clipped edge here shows\n  // the quad and is the single most obvious way smoke reads as fake.\n  float sides = smoothstep(0.0, 0.55, 1.0 - clamp(abs(centred - 0.5) * 2.0, 0.0, 1.0));\n  if (sides <= 0.001) discard;\n\n  // Leans away over its height instead of rising ruler-straight.\n  float drift = (valueNoise(vec2(t * 0.21, vSeed * 7.0)) - 0.5) * 0.6 * height * height;\n  float n = billow(vec2(centred + drift, height), t);\n\n  float density = n * sides * 1.35 - height * 0.88;\n  if (density <= 0.02) discard;\n\n  // Colour tells the story of the plume: ember-lit where it leaves the flame,\n  // cooling through soot, then dispersing into the fog. Starting at flat grey\n  // is what made it look like a separate object parked above the fire.\n  vec3 col = mix(vec3(0.90, 0.42, 0.16), vec3(0.11, 0.10, 0.10), smoothstep(0.0, 0.34, height));\n  vec3 atmosphereColor = mediumColor();\n  col = mix(col, atmosphereColor, smoothstep(0.30, 0.95, height));\n\n  // Fade in at the base so it emerges out of the flame, and out at the top so\n  // it dissipates rather than ending.\n  float emerge = smoothstep(0.0, 0.30, height);\n  float dissipate = 1.0 - smoothstep(0.22, 0.75, height);\n\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, atmosphereColor, fog);\n  float alpha = clamp(density * 0.95, 0.0, 1.0) * emerge * dissipate * 0.13;\n  outColor = vec4(col, alpha * (1.0 - fog));\n}\n";

package/dist/render/shaders/smoke.js

@@ -0,0 +1,88 @@
+import { FOG_GLSL } from './fog.js';
+/**
+ * Smoke: a column that rises, expands and dissipates. Shares the plume
+ * billboard vertex shader with fire — only the fragment behaviour differs.
+ *
+ * Alpha-blended rather than additive: smoke occludes what is behind it, and
+ * adding it would make it glow instead of darken.
+ */
+export const SMOKE_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;
+
+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
+  );
+}
+
+float billow(vec2 p, float t) {
+  float v = valueNoise(p * 2.2 + vec2(0.0, -t * 0.55)) * 0.55;
+  if (uNoiseOctaves == 1) return v / 0.55;
+  v += valueNoise(p * 4.7 + vec2(t * 0.12, -t * 0.9)) * 0.29;
+  if (uNoiseOctaves == 2) return v / 0.84;
+  return v + valueNoise(p * 9.3 + vec2(-t * 0.09, -t * 1.4)) * 0.16;
+}
+
+void main() {
+  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
+
+  float t = uTime + vSeed * 53.0;
+  float height = vUv.y;
+
+  // Widens as it climbs: sample a compressed space low down, a stretched one up
+  // top. Narrow at the bottom is what lets it sit inside the flame's tip.
+  float spread = mix(0.5, 1.0, height);
+  float centred = (vUv.x - 0.5) / spread + 0.5;
+
+  // Soft horizontal falloff rather than a hard cut — a clipped edge here shows
+  // the quad and is the single most obvious way smoke reads as fake.
+  float sides = smoothstep(0.0, 0.55, 1.0 - clamp(abs(centred - 0.5) * 2.0, 0.0, 1.0));
+  if (sides <= 0.001) discard;
+
+  // Leans away over its height instead of rising ruler-straight.
+  float drift = (valueNoise(vec2(t * 0.21, vSeed * 7.0)) - 0.5) * 0.6 * height * height;
+  float n = billow(vec2(centred + drift, height), t);
+
+  float density = n * sides * 1.35 - height * 0.88;
+  if (density <= 0.02) discard;
+
+  // Colour tells the story of the plume: ember-lit where it leaves the flame,
+  // cooling through soot, then dispersing into the fog. Starting at flat grey
+  // is what made it look like a separate object parked above the fire.
+  vec3 col = mix(vec3(0.90, 0.42, 0.16), vec3(0.11, 0.10, 0.10), smoothstep(0.0, 0.34, height));
+  vec3 atmosphereColor = mediumColor();
+  col = mix(col, atmosphereColor, smoothstep(0.30, 0.95, height));
+
+  // Fade in at the base so it emerges out of the flame, and out at the top so
+  // it dissipates rather than ending.
+  float emerge = smoothstep(0.0, 0.30, height);
+  float dissipate = 1.0 - smoothstep(0.22, 0.75, height);
+
+  float fog = mediumFog(vDistance, vWorldPos.y);
+  col = mix(col, atmosphereColor, fog);
+  float alpha = clamp(density * 0.95, 0.0, 1.0) * emerge * dissipate * 0.13;
+  outColor = vec4(col, alpha * (1.0 - fog));
+}
+`;

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

@@ -0,0 +1,15 @@
+/**
+ * The screen-space reflection resolve: what the trace found, composited over the scene.
+ *
+ * **One fetch, because the compositing is the blend state.** The trace writes premultiplied colour
+ * and coverage into a target of its own — it has to, since it samples the scene and a pass that
+ * read the colour it was writing would be a feedback loop — and this hands those texels to a
+ * `(one, one-minus-src-alpha)` blend, which is `over`. So the resolve never samples the target it
+ * is compositing onto, which is the arrangement `oitResolve.ts` reaches by the same argument.
+ *
+ * Premultiplied is what makes several reflective surfaces overlapping accumulate the way two
+ * blended layers do rather than the way two independent guesses do.
+ *
+ * The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass, its blur and the rush.
+ */
+export declare const SSR_RESOLVE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\n/** Premultiplied reflection in rgb, coverage in a. Cleared to zero: nothing found is nothing. */\nuniform sampler2D uSsrReflection;\n\nout vec4 fragColor;\n\nvoid main() {\n  fragColor = textureLod(uSsrReflection, vUv, 0.0);\n}\n";

package/dist/render/shaders/ssrResolve.js

@@ -0,0 +1,28 @@
+/**
+ * The screen-space reflection resolve: what the trace found, composited over the scene.
+ *
+ * **One fetch, because the compositing is the blend state.** The trace writes premultiplied colour
+ * and coverage into a target of its own — it has to, since it samples the scene and a pass that
+ * read the colour it was writing would be a feedback loop — and this hands those texels to a
+ * `(one, one-minus-src-alpha)` blend, which is `over`. So the resolve never samples the target it
+ * is compositing onto, which is the arrangement `oitResolve.ts` reaches by the same argument.
+ *
+ * Premultiplied is what makes several reflective surfaces overlapping accumulate the way two
+ * blended layers do rather than the way two independent guesses do.
+ *
+ * The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass, its blur and the rush.
+ */
+export const SSR_RESOLVE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** Premultiplied reflection in rgb, coverage in a. Cleared to zero: nothing found is nothing. */
+uniform sampler2D uSsrReflection;
+
+out vec4 fragColor;
+
+void main() {
+  fragColor = textureLod(uSsrReflection, vUv, 0.0);
+}
+`;

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

@@ -0,0 +1,22 @@
+/**
+ * The screen-space reflection trace: a reflected ray marched against the frame's own depth.
+ *
+ * **This mirrors `traceScreenSpaceRay` line for line**, and that is the point of writing it twice.
+ * When a crossing counts as a hit, how far behind a surface it may land, what happens at the edge
+ * of the frame and what happens over a gap in the geometry are each a defect that draws a
+ * *plausible* picture rather than failing — and each of them is settled by arithmetic that needs no
+ * GPU. The TypeScript beside this file is the specification and its tests are where those cases are
+ * pinned; this is the same walk, in the language that can sample a depth buffer.
+ *
+ * **It writes into a target of its own rather than onto the scene**, because it samples the scene:
+ * a pass that read the colour it was writing would be a feedback loop, reported once per draw on
+ * WebGL2 and rejected outright on WebGPU. `ssrPass.ts` composites the result afterwards, which is
+ * the arrangement `oitPass.ts` already uses and for the same reason.
+ *
+ * **The derivatives come first and the march comes second.** The surface normal is the cross
+ * product of the reconstructed position's screen derivatives — there being no normal buffer to read
+ * one from — and a derivative taken inside non-uniform control flow is undefined. So everything
+ * that could branch happens after them, and every fetch inside the march takes an explicit level
+ * for the same rule read the other way.
+ */
+export declare const SSR_TRACE_FRAG: string;

package/dist/render/shaders/ssrTrace.js

@@ -0,0 +1,230 @@
+/**
+ * The screen-space reflection trace: a reflected ray marched against the frame's own depth.
+ *
+ * **This mirrors `traceScreenSpaceRay` line for line**, and that is the point of writing it twice.
+ * When a crossing counts as a hit, how far behind a surface it may land, what happens at the edge
+ * of the frame and what happens over a gap in the geometry are each a defect that draws a
+ * *plausible* picture rather than failing — and each of them is settled by arithmetic that needs no
+ * GPU. The TypeScript beside this file is the specification and its tests are where those cases are
+ * pinned; this is the same walk, in the language that can sample a depth buffer.
+ *
+ * **It writes into a target of its own rather than onto the scene**, because it samples the scene:
+ * a pass that read the colour it was writing would be a feedback loop, reported once per draw on
+ * WebGL2 and rejected outright on WebGPU. `ssrPass.ts` composites the result afterwards, which is
+ * the arrangement `oitPass.ts` already uses and for the same reason.
+ *
+ * **The derivatives come first and the march comes second.** The surface normal is the cross
+ * product of the reconstructed position's screen derivatives — there being no normal buffer to read
+ * one from — and a derivative taken inside non-uniform control flow is undefined. So everything
+ * that could branch happens after them, and every fetch inside the march takes an explicit level
+ * for the same rule read the other way.
+ */
+import { glslIsFarDepth } from '../depthConvention.js';
+/**
+ * The most samples the march may take. `uSsrSteps` breaks out early.
+ *
+ * A constant bound because a loop the compiler cannot bound is one it cannot unroll or budget, and
+ * because thirty-two two-metre steps is sixty-four metres — further than a screen-space method can
+ * usefully see, since a ray that long has almost certainly left the frame.
+ */
+const MAX_STEPS = 32;
+/** How many times a bracketed crossing is halved. Matches `REFINE_STEPS` in the TypeScript. */
+const REFINE_STEPS = 6;
+export const SSR_TRACE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/**
+ * The depth the frame drew, as a copy.
+ *
+ * \`highp\` because a sampler's default precision is lowp whatever \`precision highp float\` says,
+ * and every world position below is reconstructed by dividing through it.
+ */
+uniform highp sampler2D uSsrDepth;
+/** The finished scene colour — what a ray finds is a pixel of this. */
+uniform sampler2D uSsrScene;
+/** Screen position and stored depth back to the world. See \`DEPTH_01_TO_CLIP\`. */
+uniform mat4 uSsrDepthToWorld;
+/**
+ * World back to a screen position, with the framebuffer's own Y sense already in it.
+ *
+ * **The flip is in the matrix rather than in a branch here**, so the shader is one expression on
+ * both backends and the convention lives in one place — the lesson \`DEPTH_01_TO_CLIP_Y_DOWN\`
+ * records at length, arriving through the other door.
+ */
+uniform mat4 uSsrViewProj;
+/** World into the reflective box, \`[-1, 1]\` on each axis. */
+uniform mat4 uWorldToSurface;
+uniform vec3 uSsrEye;
+/** The box's own axis. A surface reflects when it faces back along this. */
+uniform vec3 uSsrAxis;
+uniform vec3 uSsrTint;
+uniform float uSsrStrength;
+uniform float uSsrFacingCos;
+uniform float uSsrReach;
+uniform float uSsrThickness;
+uniform float uSsrSteps;
+/** How much of the frame each side is fade, as a fraction. */
+uniform float uSsrEdgeFade;
+
+out vec4 fragColor;
+
+/** What the frame drew at a screen position, as a world point. */
+vec3 worldAt(vec2 uv, float stored) {
+  vec4 world = uSsrDepthToWorld * vec4(uv * 2.0 - 1.0, stored, 1.0);
+  return world.xyz / world.w;
+}
+
+/**
+ * How far the eye is from whatever the frame drew there, and a huge number where it drew nothing.
+ *
+ * The sky is not a surface. A march that treated an untouched depth as one would reflect the whole
+ * world in the horizon, which is the failure that looks like a working effect from one angle.
+ */
+float sceneDistanceAt(vec2 uv) {
+  float stored = textureLod(uSsrDepth, uv, 0.0).r;
+  if (${glslIsFarDepth('stored')}) return 1.0e9;
+  return length(worldAt(uv, stored) - uSsrEye);
+}
+
+/** A world point to a screen position. False where it is behind the eye or outside the frame. */
+bool projectPoint(vec3 point, out vec2 uv) {
+  vec4 clip = uSsrViewProj * vec4(point, 1.0);
+  if (clip.w <= 0.0) return false;
+  uv = (clip.xy / clip.w) * 0.5 + 0.5;
+  return uv.x >= 0.0 && uv.x <= 1.0 && uv.y >= 0.0 && uv.y <= 1.0;
+}
+
+void main() {
+  float stored = textureLod(uSsrDepth, vUv, 0.0).r;
+  vec3 point = worldAt(vUv, stored);
+
+  /*
+   * **The normal from the reconstruction's own derivatives, turned to face the eye.**
+   *
+   * There is no normal buffer here and adding one is a second colour attachment written by every
+   * draw path in the engine. Two neighbouring pixels of the same surface span its plane, so their
+   * cross product is its normal — noisy along a silhouette and exact everywhere else. Which way
+   * that cross product points depends on which way the framebuffer's rows run, and the two
+   * backends disagree about that; a visible surface faces the eye by definition, which is what
+   * fixes the sign. \`decalProject.ts\` carries the same pair of facts.
+   *
+   * Taken here, before anything branches, because a derivative in non-uniform control flow is
+   * undefined and the whole of the march below is a branch.
+   */
+  vec3 plane = cross(dFdx(point), dFdy(point));
+  float span = length(plane);
+  vec3 normal = span > 0.0 ? plane / span : -uSsrAxis;
+  vec3 toEye = uSsrEye - point;
+  normal *= sign(dot(toEye, normal));
+
+  vec3 box = (uWorldToSurface * vec4(point, 1.0)).xyz;
+  vec3 inside = step(abs(box), vec3(1.0));
+  float mask = inside.x * inside.y * inside.z;
+
+  /* A surface turned away from the box's axis is not the one the caller called reflective — a wall
+     inside the volume of a wet floor is still a wall. Faded rather than cut, so the edge of the
+     rule is not an edge in the picture. */
+  float facing = dot(normal, -uSsrAxis);
+  mask *= smoothstep(uSsrFacingCos, min(1.0, uSsrFacingCos + 0.25), facing);
+  /* Nothing was drawn here, so there is no surface to reflect in. */
+  mask *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
+  mask *= uSsrStrength;
+
+  vec3 found = vec3(0.0);
+  float weight = 0.0;
+
+  if (mask > 0.0) {
+    vec3 view = normalize(point - uSsrEye);
+    vec3 ray = reflect(view, normal);
+
+    float steps = max(1.0, uSsrSteps);
+    /*
+     * Zero to begin with, because the ray starts on the surface it is reflecting off. A crossing
+     * needs the previous sample strictly in front, so the first step cannot form one on its own —
+     * which is the self-intersection guard, and without it every pixel of a reflective floor takes
+     * the comparison on rounding at once.
+     */
+    float behind = 0.0;
+    float previous = 0.0;
+    vec2 hitUv = vec2(0.0);
+    float hitDistance = 0.0;
+    bool found_hit = false;
+
+    for (int i = 1; i <= ${MAX_STEPS}; i++) {
+      if (float(i) > steps) break;
+      /* Quadratic rather than even: a first step of centimetres, where the contact seam is, and a
+         last step of nearly a metre, out where a reflection is faint and about to leave the frame.
+         \`marchDistance\` in the TypeScript is the same expression and the reason is written there. */
+      float at = float(i) / steps;
+      float t = uSsrReach * at * at;
+      vec3 sample_point = point + ray * t;
+      vec2 uv;
+      if (!projectPoint(sample_point, uv)) break;
+
+      float scene = sceneDistanceAt(uv);
+      float gap = length(sample_point - uSsrEye) - scene;
+
+      if (behind < 0.0 && gap >= 0.0) {
+        /* A crossing, bracketed. Halved rather than reported: the coarse answer is a whole step
+           out, which puts a reflection visibly beside the thing reflected. */
+        float near = previous;
+        float far = t;
+        vec2 refinedUv = uv;
+        float refinedGap = gap;
+        for (int refine = 0; refine < ${REFINE_STEPS}; refine++) {
+          float mid = (near + far) * 0.5;
+          vec3 midPoint = point + ray * mid;
+          vec2 midUv;
+          if (!projectPoint(midPoint, midUv)) break;
+          float midScene = sceneDistanceAt(midUv);
+          float midGap = length(midPoint - uSsrEye) - midScene;
+          if (midGap >= 0.0) {
+            far = mid;
+            refinedUv = midUv;
+            refinedGap = midGap;
+          } else {
+            near = mid;
+          }
+        }
+
+        /* Believed only if the refined crossing landed within the thickness. A depth buffer says
+           nothing about how thick the thing at a pixel is, so without this a ray that slides onto
+           a foreground object pastes that object into the reflection. */
+        if (refinedGap <= uSsrThickness) {
+          found_hit = true;
+          hitUv = refinedUv;
+          hitDistance = far;
+        }
+        break;
+      }
+
+      behind = gap;
+      previous = t;
+    }
+
+    if (found_hit) {
+      /*
+       * Three fades, and they are most of what keeps this from looking wrong.
+       *
+       * A hit near the edge of the frame is about to leave it, so it leaves gradually rather than
+       * along a line. A ray pointing back toward the eye can only find what is between the surface
+       * and the camera, which is usually nothing and occasionally the viewer's own geometry. And a
+       * hit at the far end of the reach is the least reliable one the march can report, since it
+       * had the most chances to slide onto something.
+       */
+      float edge = clamp(min(min(hitUv.x, 1.0 - hitUv.x), min(hitUv.y, 1.0 - hitUv.y)) /
+        max(uSsrEdgeFade, 1.0e-4), 0.0, 1.0);
+      float away = clamp((dot(normalize(ray), view) + 1.0) * 0.5, 0.0, 1.0);
+      float reach = 1.0 - clamp(hitDistance / max(uSsrReach, 1.0e-4), 0.0, 1.0);
+      weight = mask * edge * away * reach;
+      found = textureLod(uSsrScene, hitUv, 0.0).rgb * uSsrTint;
+    }
+  }
+
+  /* Premultiplied, so the pass composites with (one, one-minus-src-alpha) and several reflective
+     surfaces overlapping accumulate the way two blended layers do. */
+  fragColor = vec4(found * weight, weight);
+}
+`;

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

@@ -0,0 +1,17 @@
+/**
+ * Which way is along the texture, at a fragment.
+ *
+ * Two sources and a selection. The attribute frame is what `geometry/tangents.ts` generated,
+ * interpolated across the triangle and re-orthogonalised here; the derived frame is the standard
+ * cotangent construction from screen-space derivatives, for a mesh that never went through the
+ * generator — which is every mesh `meshBuilder` makes procedurally.
+ *
+ * **Both are computed and one is chosen, rather than one being computed under a branch.** The
+ * derivatives below are legal only under uniform control flow, and `hasTangents` arrives as a
+ * varying — flat, but a compiler cannot prove a varying uniform. The caller puts this inside its
+ * branch on `uNormalStrength`, which is a real uniform, and the selection here is a ternary rather
+ * than a branch. `main.ts` carries the same arrangement for `fwidth(vWorldPos)` and the long
+ * reason beside it; `AGENTS.md` 2026-08-07 is the rule, and WGSL refuses the module outright
+ * rather than leaving a derivative in non-uniform control flow undefined.
+ */
+export declare const TANGENT_FRAME_GLSL = "mat3 tangentFrame(vec3 n, vec3 worldPos, vec2 uv, vec4 tangent, int hasTangents) {\n  /*\n   * The derived frame: solve for the axis along u from how position and uv change together over\n   * the pixel. Exact where the surface is locally planar, approximate where it curves, which is\n   * the trade for working at all on geometry that carries no frame.\n   */\n  vec3 dp1 = dFdx(worldPos);\n  vec3 dp2 = dFdy(worldPos);\n  vec2 duv1 = dFdx(uv);\n  vec2 duv2 = dFdy(uv);\n  vec3 dp2perp = cross(dp2, n);\n  vec3 dp1perp = cross(n, dp1);\n  vec3 dt = dp2perp * duv1.x + dp1perp * duv2.x;\n  vec3 db = dp2perp * duv1.y + dp1perp * duv2.y;\n  /*\n   * **The determinant's sign, which magnitude-normalising throws away \u2014 and it is the difference\n   * between the two backends.**\n   *\n   * dFdy measures along *upward* window y in GLSL and along *downward* framebuffer y in WGSL, so\n   * dp2 and duv2 both arrive negated on WebGPU. The system this solves is invariant under that \u2014\n   * both sides of its second equation flip \u2014 but the closed form above is not: dt and db each come\n   * out negated, and dividing by their *length* keeps the negation instead of cancelling it. The\n   * frame then points the other way on one backend, which reads as a surface lit from the wrong\n   * side and nothing else.\n   *\n   * The UV determinant flips with them, so folding its sign back in restores the invariance the\n   * solve always had. Measured before and after on demo/dev/normal.html: the derived panel stood\n   * 86 of 255 rms from the attribute panel on WebGPU and 8.8 on WebGL2; with this they agree.\n   */\n  float det = duv1.x * duv2.y - duv2.x * duv1.y;\n  float handed = det < 0.0 ? -1.0 : 1.0;\n  /* One scale for both axes, so a stretched UV layout does not shear the frame it produces. */\n  float invmax = inversesqrt(max(max(dot(dt, dt), dot(db, db)), 1e-12)) * handed;\n  vec3 derivedT = dt * invmax;\n  vec3 derivedB = db * invmax;\n\n  /*\n   * The attribute frame, re-orthogonalised. Interpolating a tangent across a triangle leaves it\n   * no longer square to the interpolated normal, and Gram-Schmidt is what puts it back \u2014\n   * generateTangents does the same per vertex and says why: dropping it is a normal map that\n   * shears wherever the geometry curves.\n   */\n  vec3 attrT = normalize(tangent.xyz - n * dot(n, tangent.xyz));\n  /*\n   * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and\n   * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent\n   * computed without the sign lights that side inside out.\n   */\n  vec3 attrB = cross(n, attrT) * tangent.w;\n\n  vec3 t = hasTangents != 0 ? attrT : derivedT;\n  vec3 b = hasTangents != 0 ? attrB : derivedB;\n  return mat3(t, b, n);\n}";