@driftengine/core 4.8.7 → 4.10.0

package/dist/render/shaders/depth.js

@@ -5,6 +5,7 @@ import { CUTOUT_DITHER_GLSL } from '../cutoutDither.js';
 import { SKINNING_GLSL } from './skinning.js';
 import { CLOTH_BINDING_GLSL } from './clothBinding.js';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.js';
+import { BONE_ANIMATION_GLSL } from './boneAnimation.js';
 /**
  * Depth-only shadow pass. Its optional peel mode rejects the first recorded
  * surface so the next independently fading occluder can be retained.
@@ -77,6 +78,17 @@ uniform vec2 uUvOffset;
 uniform vec2 uAlphaCutout;
 #endif
 
+#if ANIMATED
+/*
+ * **A bone animation's, after every other declaration** so no field of the variants before it
+ * moves: the grain lane the vertex's bone rides in, the scene's clock, and the chunk the colour
+ * pass runs — the same expression, or a crowd's shadow stands still while the crowd moves.
+ */
+layout(location = 8) in float aGrain;
+uniform float uSceneTime;
+${BONE_ANIMATION_GLSL}
+#endif
+
 out vec4 vLightPosition;
 #if CUTOUT
 /* The texture coordinate and, in z, the texture-array layer the face wears. */
@@ -98,6 +110,12 @@ void main() {
 #else
   vec4 local = vec4(aPosition, 1.0);
 #endif
+#if ANIMATED
+  /* Turned and placed as the colour pass turns and places it; its normal and tangent unused. */
+  vec3 animatedNormal = vec3(0.0, 1.0, 0.0);
+  vec3 animatedTangent = vec3(1.0, 0.0, 0.0);
+  local = vec4(boneAnimate(local.xyz, animatedNormal, animatedTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
@@ -144,9 +162,9 @@ void main() {
 }
 `;
 /** The rigid variant: the world, a prop, a mesh with no rig behind it. */
-export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false }, 'depth');
+export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth');
 /** The skinned variant, which reads a joint palette and moves the vertex by it. */
-export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false }, 'depth-skinned');
+export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth-skinned');
 /**
  * The variant an instanced draw casts its shadow through.
  *
@@ -155,7 +173,7 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINN
  * right place and the rest stacked underneath it, which reads as a lighting fault rather than as
  * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
  */
-export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false }, 'depth-instanced');
+export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: false }, 'depth-instanced');
 /**
  * The variants a cutout caster casts through: a leaf card, a chain link, a fence, whose shape is in
  * its texture's alpha rather than in its geometry.
@@ -166,8 +184,15 @@ export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKI
  * leaves every opaque caster byte for byte as it was. What it costs is one more program each, and
  * a skinned cutout, which nothing has asked for, is not among them.
  */
-export const DEPTH_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false }, 'depth-cutout');
-export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false }, 'depth-instanced-cutout');
+export const DEPTH_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: false, ANIMATED: false }, 'depth-cutout');
+export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: false }, 'depth-instanced-cutout');
+/**
+ * The variants a crowd casts through: an instanced batch playing a bone animation, its vertices
+ * where the clip puts them at each instance's moment. See `shaders/boneAnimation.ts`. No glass
+ * variant: a crowd is not glass, and a glass batch that animates casts its tint from rest.
+ */
+export const DEPTH_INSTANCED_ANIMATED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: false, ANIMATED: true }, 'depth-instanced-animated');
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: false, ANIMATED: true }, 'depth-instanced-animated-cutout');
 export const DEPTH_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
@@ -238,11 +263,11 @@ void main() {
  * exactly where it casts its depth, deformed and placed the same way, or the coloured patch parts
  * from the pane's own shadow edge. The only addition is `vGlassWorld`.
  */
-export const GLASS_TINT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true }, 'glass-tint');
-export const GLASS_TINT_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true }, 'glass-tint-skinned');
-export const GLASS_TINT_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true }, 'glass-tint-instanced');
-export const GLASS_TINT_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true }, 'glass-tint-cutout');
-export const GLASS_TINT_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true }, 'glass-tint-instanced-cutout');
+export const GLASS_TINT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint');
+export const GLASS_TINT_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint-skinned');
+export const GLASS_TINT_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false, GLASS: true, ANIMATED: false }, 'glass-tint-instanced');
+export const GLASS_TINT_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true, GLASS: true, ANIMATED: false }, 'glass-tint-cutout');
+export const GLASS_TINT_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true, GLASS: true, ANIMATED: false }, 'glass-tint-instanced-cutout');
 /**
  * What a pane lets through: its transmission and colour, less what it reflects toward the light,
  * and how clear it is — `glassShadow.ts`'s `paneTexel`, stated for the device. Drawn with a

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

@@ -12,4 +12,4 @@
  * rainbow is generated rather than sampled.
  */
 export declare const FILM_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec3 aNormal;\nlayout(location = 2) in vec3 aColor;\n/*\n * Coverage, on the attribute the mesh format calls emissive.\n *\n * A film has no use for self-illumination, and it very much needs an edge that\n * dissolves: the first oil was flat squares, and a hard straight edge is what made\n * it read as a decal dropped on the world rather than a puddle lying in it. One\n * float per vertex, 1 in the middle of a slick and 0 at its rim.\n */\nlayout(location = 3) in float aCoverage;\n\nuniform mat4 uViewProj;\n/* The mirrored camera's projection, so a film can sample the planar target the way water does. */\nuniform mat4 uReflectionViewProj;\n\nout vec3 vWorld;\nout vec3 vNormal;\nout vec3 vTint;\nout vec4 vReflectionClip;\nout float vCoverage;\n\nvoid main() {\n  vWorld = aPosition;\n  vNormal = normalize(aNormal);\n  vTint = aColor;\n  vCoverage = aCoverage;\n  vReflectionClip = uReflectionViewProj * vec4(aPosition, 1.0);\n  gl_Position = uViewProj * vec4(aPosition, 1.0);\n}\n";
-export declare const FILM_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorld;\nin vec3 vNormal;\nin vec3 vTint;\nin vec4 vReflectionClip;\n/*\n * The scene mirrored across the plane this film lies on, and how much of it to show.\n *\n * **Sheen is iridescence and this is the image**, which is the split a consumer asked for after\n * finding that raising sheen to make a road wetter only made it oilier. A wet street at night is\n * defined by everything above it appearing twice, and no amount of interference pattern is that.\n *\n * The projection is the water shader's, unchanged and deliberately so: reproducing it outside the\n * engine is the piece most likely to be subtly wrong and least likely to be noticed, since a\n * mirror off by a small skew looks like a wet road until somebody puts a straight line across it.\n */\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform float uReflectionStrength;\nin float vCoverage;\n\nuniform vec3 uCameraPos;\nuniform float uTime;\n/*\n * The mirrored pass clips at the water plane, and it does so **in the fragment\n * shader** rather than with gl_ClipDistance.\n *\n * That is not a style choice. Clip distances in WebGL2 need\n * EXT_clip_cull_distance both enabled on the context and declared with an\n * #extension line, and without the declaration the shader fails to *compile* \u2014\n * which, since programs are built when the renderer is constructed, takes the\n * whole boot with it and leaves a black screen. This shader had never been\n * compiled when it was written, so the mistake sat harmlessly in the file until\n * the day it was wired to something. Discarding is what flat.ts does, it needs\n * no extension, and a film is a thin translucent layer where the cost of a\n * discarded fragment is nothing.\n */\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\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\n/** How strong the sheen is. Zero leaves a plain dark film. */\nuniform float uSheen;\n\n/**\n * How rough the film's own surface is, 0 to 1, and how coarse that roughness is.\n *\n * **A film had exactly one finish before this: mirror.** That is right for standing water and\n * wrong for the thing this pass is most used for, because a wet road is not a mirror \u2014 it is\n * water lying *in* aggregate, and the stone underneath breaks the reflection into a smear. With\n * no way to say so, a patch of film over a textured road met it at a hard rim: mirror on one\n * side, stone on the other, with nothing able to cross it. Feathering the coverage cannot fix\n * that, and it was tried \u2014 the alpha was never what the eye was reading.\n *\n * So the reflection is displaced by a noise field rather than blurred. **Displaced, because a\n * blur is the wrong phenomenon**: a rough surface does not soften what it reflects, it scatters\n * it, and a lamp on wet tarmac smears into a streak rather than becoming a soft disc. It is also\n * what a blur cannot afford here \u2014 the mirror has no mip chain (see the `textureLod` note\n * below), so softening it honestly would cost several taps where this costs none.\n *\n * `uFilmRoughnessCycles` is bumps to the metre, and it is the same quantity\n * `Renderer.setSurfaceRelief` takes. **Matching it to the surface underneath is the point**:\n * given the same field at the same scale, the water is broken up by the aggregate that the dry\n * road beside it is showing, and the two stop being different materials.\n *\n * Zero is the mirror this pass has always been, exactly, so nothing that does not ask for\n * roughness renders differently.\n */\nuniform float uFilmRoughness;\nuniform float uFilmRoughnessCycles;\n\nout vec4 fragColor;\n\n/** A hue wheel, without a texture. Standard 6-segment ramp. */\nvec3 hue(float h) {\n  h = fract(h) * 6.0;\n  vec3 c = clamp(vec3(abs(h - 3.0) - 1.0, 2.0 - abs(h - 2.0), 2.0 - abs(h - 4.0)), 0.0, 1.0);\n  return c;\n}\n\n/**\n * The same value noise `flat.ts` builds its relief from, and deliberately the same.\n *\n * Copied rather than shared because these two shaders have no common include beyond the fog, and\n * a film that used a *different* field would defeat the whole purpose of taking a cycle count:\n * the water would be broken up by one pattern and the road by another, which is two materials\n * again with extra steps.\n */\nfloat filmHash(vec3 p) {\n  p = fract(p * 0.1031);\n  p += dot(p, p.zyx + 31.32);\n  return fract((p.x + p.y) * p.z);\n}\n\nfloat filmNoise(vec3 p) {\n  vec3 i = floor(p);\n  vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 0.0)), filmHash(i + vec3(1.0, 0.0, 0.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 0.0)), filmHash(i + vec3(1.0, 1.0, 0.0)), u.x),\n      u.y\n    ),\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 1.0)), filmHash(i + vec3(1.0, 0.0, 1.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 1.0)), filmHash(i + vec3(1.0, 1.0, 1.0)), u.x),\n      u.y\n    ),\n    u.z\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorld, 1.0), uClipPlane) < 0.0) discard;\n\n  vec3 view = normalize(uCameraPos - vWorld);\n  float facing = max(dot(normalize(vNormal), view), 0.0);\n  /*\n   * Fresnel-ish: dark looking straight down at it, bright at a grazing angle.\n   * This is the whole effect \u2014 it is what makes a wet patch look wet rather\n   * than looking like a patch of dark paint.\n   */\n  float grazing = pow(1.0 - facing, 3.0);\n\n  /*\n   * A slow travelling interference, so the sheen crawls rather than sitting\n   * still. Two frequencies that do not divide each other, or the pattern\n   * repeats visibly across a long slick.\n   */\n  float ripple =\n    sin(vWorld.x * 0.73 + vWorld.z * 0.41 + uTime * 0.55) *\n    cos(vWorld.z * 0.91 - vWorld.x * 0.29 - uTime * 0.37);\n\n  vec3 sheen = hue(grazing * 1.35 + ripple * 0.14 + 0.55);\n  /*\n   * Dark underneath, so the film always reads as *less* than the surface it lies on even where\n   * the sheen is strongest \u2014 but not so dark that it disappears.\n   *\n   * A slick that has just launched somebody has to be findable afterwards. It was rounded,\n   * feathered and iridescent \u2014 and at a fifth of an opaque tint on a pale deck at dusk,\n   * invisible. A hazard you cannot find is not a hazard, it is a trap.\n   *\n   * So the base is darker and the sheen has a floor: even looking straight down, where the\n   * Fresnel term is nearly nothing, a slick is a distinctly wet patch rather than a faint one.\n   */\n  vec3 base = vTint * 0.9;\n  vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);\n\n  /*\n   * The mirrored scene, under the sheen rather than instead of it.\n   *\n   * Screen-space from the mirrored clip position, exactly as the water pass does it, with the\n   * same fade as the sample leaves the target: a reflection that stopped dead at the edge of its\n   * own buffer would draw a line across the road where nothing is.\n   *\n   * Weighted by the grazing term as well as by strength, because that is what a reflection does:\n   * a wet surface underfoot shows almost nothing and the same surface down the street shows the\n   * whole scene. Added before the fog so the image recedes with everything else in the frame.\n   */\n  if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    float valid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    /*\n     * An explicit level, not an implicit one, and the branch above is the whole reason.\n     *\n     * An implicit derivative inside control flow that is not provably uniform is what lets a\n     * compiler flatten the branch and pay for every arm \u2014 AGENTS.md, 2026-08-07 \u2014 and WGSL\n     * does not merely warn: the module fails to compile with \"textureSample must only be\n     * called from uniform control flow\", which invalidates the pipeline, which invalidates\n     * the command buffer, and the frame still presents. The fifth time on this branch. The\n     * mirror has no mip chain, so level 0 is the only level there is; the water shader\n     * reaches the same conclusion for the same lookup.\n     */\n    /*\n     * The aggregate under the water, as a displacement of what the water shows.\n     *\n     * The gradient of the same field the road's relief uses, taken across the surface and used\n     * to push the lookup. **Stretched along the reflection rather than isotropic**, and that is\n     * the half that makes it read as a road: a reflection on a rough horizontal surface smears\n     * *towards the viewer*, because a bump tilts the ray in the plane it is already travelling\n     * in. Displacing in a circle gives frosted glass instead, which is a different wet thing.\n     *\n     * Scaled by the grazing term for the same reason the mirror is: looking straight down at a\n     * puddle the reflection is compressed into almost nothing and a displacement of it would be\n     * enormous, so the scatter has to fall off exactly where the image does.\n     */\n    if (uFilmRoughness > 0.0) {\n      vec3 at = vWorld * uFilmRoughnessCycles;\n      float here = filmNoise(at);\n      vec2 slope = vec2(\n        filmNoise(at + vec3(0.5, 0.0, 0.0)) - here,\n        filmNoise(at + vec3(0.0, 0.0, 0.5)) - here\n      );\n      /* Along the view, which on a horizontal film is where the image runs. */\n      vec2 along = normalize(vec2(view.x, view.z) + vec2(1e-5, 0.0));\n      vec2 smear = along * dot(slope, along) * 3.0 + slope * 0.35;\n      reflectionUv += smear * uFilmRoughness * 0.016 * (0.2 + grazing * 0.8);\n      /* Re-fade at the border: a displaced sample can leave the target the original did not. */\n      vec2 movedBorder = min(reflectionUv, 1.0 - reflectionUv);\n      valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));\n    }\n    vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;\n    color = mix(color, mirrored, valid * uReflectionStrength * (0.25 + grazing * 0.75));\n  }\n\n  // The same fog every other pass applies \u2014 and now literally the same code, which\n  // it was not: this ran its own curve while claiming otherwise, so a slick receded\n  // at a different rate than the deck it was lying on.\n  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);\n  color = mix(color, mediumColor(), fog);\n\n  /*\n   * Alpha from coverage, squared.\n   *\n   * Squared because a linear ramp across the rim still reads as a visible band \u2014\n   * the eye finds the constant-gradient edge. Squaring pushes the falloff outward\n   * so the slick has a soft shoulder and no perceptible boundary. The sheen fades\n   * with it, which is right: the thinnest part of a film is the least iridescent.\n   */\n  /*\n   * Alpha from coverage, and the rim is what is squared \u2014 not the whole patch.\n   *\n   * Squaring the coverage outright made the *middle* translucent too, which is most of why a\n   * slick could not be found. The shoulder still needs to be soft, so the square is mixed in\n   * near the edge only: solid through the body, dissolving at the rim.\n   */\n  float coverage = clamp(vCoverage, 0.0, 1.0);\n  float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;\n  fragColor = vec4(color, alpha);\n}\n";
+export declare const FILM_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorld;\nin vec3 vNormal;\nin vec3 vTint;\nin vec4 vReflectionClip;\n/*\n * The scene mirrored across the plane this film lies on, and how much of it to show.\n *\n * **Sheen is iridescence and this is the image**, which is the split a consumer asked for after\n * finding that raising sheen to make a road wetter only made it oilier. A wet street at night is\n * defined by everything above it appearing twice, and no amount of interference pattern is that.\n *\n * The projection is the water shader's, unchanged and deliberately so: reproducing it outside the\n * engine is the piece most likely to be subtly wrong and least likely to be noticed, since a\n * mirror off by a small skew looks like a wet road until somebody puts a straight line across it.\n */\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform float uReflectionStrength;\nin float vCoverage;\n\nuniform vec3 uCameraPos;\nuniform float uTime;\n/*\n * The mirrored pass clips at the water plane, and it does so **in the fragment\n * shader** rather than with gl_ClipDistance.\n *\n * That is not a style choice. Clip distances in WebGL2 need\n * EXT_clip_cull_distance both enabled on the context and declared with an\n * #extension line, and without the declaration the shader fails to *compile* \u2014\n * which, since programs are built when the renderer is constructed, takes the\n * whole boot with it and leaves a black screen. This shader had never been\n * compiled when it was written, so the mistake sat harmlessly in the file until\n * the day it was wired to something. Discarding is what flat.ts does, it needs\n * no extension, and a film is a thin translucent layer where the cost of a\n * discarded fragment is nothing.\n */\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\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  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\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(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (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\n/** How strong the sheen is. Zero leaves a plain dark film. */\nuniform float uSheen;\n\n/**\n * How rough the film's own surface is, 0 to 1, and how coarse that roughness is.\n *\n * **A film had exactly one finish before this: mirror.** That is right for standing water and\n * wrong for the thing this pass is most used for, because a wet road is not a mirror \u2014 it is\n * water lying *in* aggregate, and the stone underneath breaks the reflection into a smear. With\n * no way to say so, a patch of film over a textured road met it at a hard rim: mirror on one\n * side, stone on the other, with nothing able to cross it. Feathering the coverage cannot fix\n * that, and it was tried \u2014 the alpha was never what the eye was reading.\n *\n * So the reflection is displaced by a noise field rather than blurred. **Displaced, because a\n * blur is the wrong phenomenon**: a rough surface does not soften what it reflects, it scatters\n * it, and a lamp on wet tarmac smears into a streak rather than becoming a soft disc. It is also\n * what a blur cannot afford here \u2014 the mirror has no mip chain (see the `textureLod` note\n * below), so softening it honestly would cost several taps where this costs none.\n *\n * `uFilmRoughnessCycles` is bumps to the metre, and it is the same quantity\n * `Renderer.setSurfaceRelief` takes. **Matching it to the surface underneath is the point**:\n * given the same field at the same scale, the water is broken up by the aggregate that the dry\n * road beside it is showing, and the two stop being different materials.\n *\n * Zero is the mirror this pass has always been, exactly, so nothing that does not ask for\n * roughness renders differently.\n */\nuniform float uFilmRoughness;\nuniform float uFilmRoughnessCycles;\n\nout vec4 fragColor;\n\n/** A hue wheel, without a texture. Standard 6-segment ramp. */\nvec3 hue(float h) {\n  h = fract(h) * 6.0;\n  vec3 c = clamp(vec3(abs(h - 3.0) - 1.0, 2.0 - abs(h - 2.0), 2.0 - abs(h - 4.0)), 0.0, 1.0);\n  return c;\n}\n\n/**\n * The same value noise `flat.ts` builds its relief from, and deliberately the same.\n *\n * Copied rather than shared because these two shaders have no common include beyond the fog, and\n * a film that used a *different* field would defeat the whole purpose of taking a cycle count:\n * the water would be broken up by one pattern and the road by another, which is two materials\n * again with extra steps.\n */\nfloat filmHash(vec3 p) {\n  p = fract(p * 0.1031);\n  p += dot(p, p.zyx + 31.32);\n  return fract((p.x + p.y) * p.z);\n}\n\nfloat filmNoise(vec3 p) {\n  vec3 i = floor(p);\n  vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 0.0)), filmHash(i + vec3(1.0, 0.0, 0.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 0.0)), filmHash(i + vec3(1.0, 1.0, 0.0)), u.x),\n      u.y\n    ),\n    mix(\n      mix(filmHash(i + vec3(0.0, 0.0, 1.0)), filmHash(i + vec3(1.0, 0.0, 1.0)), u.x),\n      mix(filmHash(i + vec3(0.0, 1.0, 1.0)), filmHash(i + vec3(1.0, 1.0, 1.0)), u.x),\n      u.y\n    ),\n    u.z\n  );\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorld, 1.0), uClipPlane) < 0.0) discard;\n\n  vec3 view = normalize(uCameraPos - vWorld);\n  float facing = max(dot(normalize(vNormal), view), 0.0);\n  /*\n   * Fresnel-ish: dark looking straight down at it, bright at a grazing angle.\n   * This is the whole effect \u2014 it is what makes a wet patch look wet rather\n   * than looking like a patch of dark paint.\n   */\n  float grazing = pow(1.0 - facing, 3.0);\n\n  /*\n   * A slow travelling interference, so the sheen crawls rather than sitting\n   * still. Two frequencies that do not divide each other, or the pattern\n   * repeats visibly across a long slick.\n   */\n  float ripple =\n    sin(vWorld.x * 0.73 + vWorld.z * 0.41 + uTime * 0.55) *\n    cos(vWorld.z * 0.91 - vWorld.x * 0.29 - uTime * 0.37);\n\n  vec3 sheen = hue(grazing * 1.35 + ripple * 0.14 + 0.55);\n  /*\n   * Dark underneath, so the film always reads as *less* than the surface it lies on even where\n   * the sheen is strongest \u2014 but not so dark that it disappears.\n   *\n   * A slick that has just launched somebody has to be findable afterwards. It was rounded,\n   * feathered and iridescent \u2014 and at a fifth of an opaque tint on a pale deck at dusk,\n   * invisible. A hazard you cannot find is not a hazard, it is a trap.\n   *\n   * So the base is darker and the sheen has a floor: even looking straight down, where the\n   * Fresnel term is nearly nothing, a slick is a distinctly wet patch rather than a faint one.\n   */\n  vec3 base = vTint * 0.9;\n  vec3 color = base + sheen * uSheen * (0.22 + grazing * 0.75);\n\n  /*\n   * The mirrored scene, under the sheen rather than instead of it.\n   *\n   * Screen-space from the mirrored clip position, exactly as the water pass does it, with the\n   * same fade as the sample leaves the target: a reflection that stopped dead at the edge of its\n   * own buffer would draw a line across the road where nothing is.\n   *\n   * Weighted by the grazing term as well as by strength, because that is what a reflection does:\n   * a wet surface underfoot shows almost nothing and the same surface down the street shows the\n   * whole scene. Added before the fog so the image recedes with everything else in the frame.\n   */\n  if (uReflectionEnabled != 0 && uReflectionStrength > 0.0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    float valid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    /*\n     * An explicit level, not an implicit one, and the branch above is the whole reason.\n     *\n     * An implicit derivative inside control flow that is not provably uniform is what lets a\n     * compiler flatten the branch and pay for every arm \u2014 AGENTS.md, 2026-08-07 \u2014 and WGSL\n     * does not merely warn: the module fails to compile with \"textureSample must only be\n     * called from uniform control flow\", which invalidates the pipeline, which invalidates\n     * the command buffer, and the frame still presents. The fifth time on this branch. The\n     * mirror has no mip chain, so level 0 is the only level there is; the water shader\n     * reaches the same conclusion for the same lookup.\n     */\n    /*\n     * The aggregate under the water, as a displacement of what the water shows.\n     *\n     * The gradient of the same field the road's relief uses, taken across the surface and used\n     * to push the lookup. **Stretched along the reflection rather than isotropic**, and that is\n     * the half that makes it read as a road: a reflection on a rough horizontal surface smears\n     * *towards the viewer*, because a bump tilts the ray in the plane it is already travelling\n     * in. Displacing in a circle gives frosted glass instead, which is a different wet thing.\n     *\n     * Scaled by the grazing term for the same reason the mirror is: looking straight down at a\n     * puddle the reflection is compressed into almost nothing and a displacement of it would be\n     * enormous, so the scatter has to fall off exactly where the image does.\n     */\n    if (uFilmRoughness > 0.0) {\n      vec3 at = vWorld * uFilmRoughnessCycles;\n      float here = filmNoise(at);\n      vec2 slope = vec2(\n        filmNoise(at + vec3(0.5, 0.0, 0.0)) - here,\n        filmNoise(at + vec3(0.0, 0.0, 0.5)) - here\n      );\n      /* Along the view, which on a horizontal film is where the image runs. */\n      vec2 along = normalize(vec2(view.x, view.z) + vec2(1e-5, 0.0));\n      vec2 smear = along * dot(slope, along) * 3.0 + slope * 0.35;\n      reflectionUv += smear * uFilmRoughness * 0.016 * (0.2 + grazing * 0.8);\n      /* Re-fade at the border: a displaced sample can leave the target the original did not. */\n      vec2 movedBorder = min(reflectionUv, 1.0 - reflectionUv);\n      valid = min(valid, smoothstep(0.0, 0.025, min(movedBorder.x, movedBorder.y)));\n    }\n    vec3 mirrored = textureLod(uReflectionMap, clamp(reflectionUv, 0.0, 1.0), 0.0).rgb;\n    color = mix(color, mirrored, valid * uReflectionStrength * (0.25 + grazing * 0.75));\n  }\n\n  // The same fog every other pass applies \u2014 and now literally the same code, which\n  // it was not: this ran its own curve while claiming otherwise, so a slick receded\n  // at a different rate than the deck it was lying on.\n  float fog = mediumFog(length(uCameraPos - vWorld), vWorld.y);\n  color = mix(color, mediumColor(), fog);\n\n  /*\n   * Alpha from coverage, squared.\n   *\n   * Squared because a linear ramp across the rim still reads as a visible band \u2014\n   * the eye finds the constant-gradient edge. Squaring pushes the falloff outward\n   * so the slick has a soft shoulder and no perceptible boundary. The sheen fades\n   * with it, which is right: the thinnest part of a film is the least iridescent.\n   */\n  /*\n   * Alpha from coverage, and the rim is what is squared \u2014 not the whole patch.\n   *\n   * Squaring the coverage outright made the *middle* translucent too, which is most of why a\n   * slick could not be found. The shoulder still needs to be soft, so the square is mixed in\n   * near the edge only: solid through the body, dissolving at the rim.\n   */\n  float coverage = clamp(vCoverage, 0.0, 1.0);\n  float alpha = mix(coverage * coverage, coverage, 0.65) * 0.92;\n  fragColor = vec4(color, alpha);\n}\n";

package/dist/render/shaders/filmLook.js

@@ -78,7 +78,8 @@ export function grainWeight(luma) {
     return 0.25 + 3 * l * (1 - l);
 }
 /** Both backends' words when there is no composite to apply the look in. */
-export const FILM_LOOK_WITHOUT_COMPOSITE = '[driftengine] setVignette and setFilmGrain need `screenEffects`: without a composite every ' +
+export const FILM_LOOK_WITHOUT_COMPOSITE = '[driftengine] setVignette, setFilmGrain and setChromaticAberration need `screenEffects`: ' +
+    'without a composite every ' +
     'pass is the last thing to touch the frame, so there is no one place to apply a lens or a ' +
     'print. The look was not applied.';
 /** A vignette strength as the shader takes it: 0 to 4, anything else off. */

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

@@ -9,4 +9,4 @@
  */
 /** Shared billboard vertex stage: used by fire, smoke and any future plume. */
 export declare const PLUME_VERT = "#version 300 es\nlayout(location = 0) in vec3 aCenter;\nlayout(location = 1) in vec2 aCorner;\nlayout(location = 2) in vec2 aSize;\nlayout(location = 3) in float aSeed;\nlayout(location = 4) in float aBlade;\n\nuniform mat4 uViewProj;\nuniform vec3 uCameraPos;\nuniform float uTime;\n/** Amplitude of the size pulse; 0 keeps the quad a fixed size. */\nuniform float uSizePulse;\n/**\n * Horizontal wind, m/s. Plumes lean with it, increasingly toward their top \u2014\n * the base is anchored to whatever is burning, the crown is free. Sharing one\n * wind with the rest of the world is the point: smoke drifting one way while\n * foliage leans another is the clearest tell that a scene is a pile of effects\n * rather than a place.\n */\nuniform vec2 uWind;\n/**\n * Whole-batch offset. Plume centres live in a static buffer because braziers\n * never move; a batch that *does* move \u2014 a tornado \u2014 shifts by a uniform rather\n * than rewriting geometry every frame.\n */\nuniform vec3 uOrigin;\n/** How strongly this plume type answers the wind; smoke far more than flame. */\nuniform float uWindResponse;\n\nout vec2 vUv;\nout float vSeed;\nout float vDistance;\nout vec3 vWorldPos;\n\n/**\n * Plumes are not a constant size: a fire flares and dies back, a smoke column\n * swells and thins. Two out-of-phase sines, offset per plume, so the whole\n * effect breathes rather than only its interior pattern animating.\n */\nfloat sizePulse(float seed) {\n  return 1.0 + uSizePulse * (\n    sin(uTime * 1.7 + seed * 9.1) * 0.62 +\n    sin(uTime * 3.3 + seed * 4.7) * 0.38\n  );\n}\n\nvoid main() {\n  // Height swells more than width, the way a real flame stretches upward.\n  vec3 anchor = aCenter + uOrigin;\n\n  /*\n   * No billboarding at all: the blade's heading is fixed in the world.\n   *\n   * Each plume is drawn as a CROSS of two blades 90 degrees apart (see BLADES in\n   * plumeRenderer), and aSeed advances by the golden ratio per plume, so the crosses\n   * themselves are scattered by the golden angle rather than aligned into a grid.\n   *\n   * Nothing here reads the camera, and that is the fix. Anything that does - a full\n   * billboard, or merely leaning edge-on cards toward the viewer - rotates geometry\n   * as the camera moves, which is exactly what reads as flat: orbiting a fire showed\n   * the same silhouette from every angle. A cross cannot track the viewer, so turning\n   * around a fire genuinely brings one blade broadside while the other goes edge-on.\n   * That is the parallax a volume has, and it is also why no blade needs to be turned\n   * to stay visible - its partner is square-on whenever it is not.\n   *\n   * World up stays the vertical axis: a flame that tilts with the camera reads as a\n   * decal.\n   */\n  vec3 up = vec3(0.0, 1.0, 0.0);\n  float yaw = aSeed * 6.28318530718 + aBlade * 1.57079632679;\n  vec3 right = vec3(cos(yaw), 0.0, sin(yaw));\n  float pulse = sizePulse(aSeed);\n  vec2 size = vec2(aSize.x * mix(1.0, pulse, 0.55), aSize.y * pulse);\n\n  float rise = aCorner.y * 0.5 + 0.5;\n  vec3 world = anchor\n    + right * (aCorner.x * size.x)\n    + up * (rise * size.y);\n\n  // Quadratic in height: a column bends away from its anchor rather than\n  // shearing uniformly, which would slide its base off the fire.\n  world.xz += uWind * (uWindResponse * rise * rise * size.y);\n\n  vUv = vec2(aCorner.x * 0.5 + 0.5, aCorner.y * 0.5 + 0.5);\n  vSeed = aSeed;\n  vDistance = distance(world, uCameraPos);\n  vWorldPos = world;\n  gl_Position = uViewProj * vec4(world, 1.0);\n}\n";
-export declare const FIRE_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\n/** Rising turbulence: octaves scrolled upward at different rates. */\nfloat turbulence(vec2 p, float t) {\n  float v = valueNoise(p * 3.0 + vec2(0.0, -t * 1.9)) * 0.55;\n  if (uNoiseOctaves == 1) return v / 0.55;\n  v += valueNoise(p * 6.5 + vec2(t * 0.3, -t * 3.1)) * 0.28;\n  if (uNoiseOctaves == 2) return v / 0.83;\n  return v + valueNoise(p * 13.0 + vec2(-t * 0.2, -t * 4.6)) * 0.17;\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  vec2 uv = vUv;\n  float t = uTime + vSeed * 37.0;\n\n  // Taper toward the tip and pinch the sides, so the quad never shows.\n  float sides = 1.0 - abs(uv.x - 0.5) * 2.0;\n  float taper = sides * (1.0 - uv.y * 0.72);\n  if (taper <= 0.0) discard;\n\n  // Sway: the column leans and wanders instead of standing to attention.\n  float sway = (valueNoise(vec2(t * 0.55, vSeed * 11.0)) - 0.5) * 0.34 * uv.y;\n  vec2 p = vec2(uv.x + sway, uv.y);\n\n  float n = turbulence(p, t);\n  // Flame body: noise must beat a threshold that rises with height, which is\n  // what makes the tip break into separate licks.\n  float body = n * taper * 1.9 - uv.y * 0.55;\n  if (body <= 0.02) discard;\n\n  // Colour ramp: white-hot core through yellow and orange to a dark red edge.\n  float heat = clamp(body * 1.5, 0.0, 1.0);\n  vec3 col = mix(vec3(0.62, 0.06, 0.02), vec3(1.0, 0.45, 0.06), smoothstep(0.0, 0.45, heat));\n  col = mix(col, vec3(1.0, 0.85, 0.35), smoothstep(0.45, 0.75, heat));\n  col = mix(col, vec3(1.0, 0.98, 0.88), smoothstep(0.78, 1.0, heat));\n\n  float alpha = clamp(body * 2.2, 0.0, 1.0) * (1.0 - smoothstep(0.72, 1.0, uv.y));\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant flame 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";
+export declare const FIRE_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  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\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(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (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\n/** Rising turbulence: octaves scrolled upward at different rates. */\nfloat turbulence(vec2 p, float t) {\n  float v = valueNoise(p * 3.0 + vec2(0.0, -t * 1.9)) * 0.55;\n  if (uNoiseOctaves == 1) return v / 0.55;\n  v += valueNoise(p * 6.5 + vec2(t * 0.3, -t * 3.1)) * 0.28;\n  if (uNoiseOctaves == 2) return v / 0.83;\n  return v + valueNoise(p * 13.0 + vec2(-t * 0.2, -t * 4.6)) * 0.17;\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  vec2 uv = vUv;\n  float t = uTime + vSeed * 37.0;\n\n  // Taper toward the tip and pinch the sides, so the quad never shows.\n  float sides = 1.0 - abs(uv.x - 0.5) * 2.0;\n  float taper = sides * (1.0 - uv.y * 0.72);\n  if (taper <= 0.0) discard;\n\n  // Sway: the column leans and wanders instead of standing to attention.\n  float sway = (valueNoise(vec2(t * 0.55, vSeed * 11.0)) - 0.5) * 0.34 * uv.y;\n  vec2 p = vec2(uv.x + sway, uv.y);\n\n  float n = turbulence(p, t);\n  // Flame body: noise must beat a threshold that rises with height, which is\n  // what makes the tip break into separate licks.\n  float body = n * taper * 1.9 - uv.y * 0.55;\n  if (body <= 0.02) discard;\n\n  // Colour ramp: white-hot core through yellow and orange to a dark red edge.\n  float heat = clamp(body * 1.5, 0.0, 1.0);\n  vec3 col = mix(vec3(0.62, 0.06, 0.02), vec3(1.0, 0.45, 0.06), smoothstep(0.0, 0.45, heat));\n  col = mix(col, vec3(1.0, 0.85, 0.35), smoothstep(0.45, 0.75, heat));\n  col = mix(col, vec3(1.0, 0.98, 0.88), smoothstep(0.78, 1.0, heat));\n\n  float alpha = clamp(body * 2.2, 0.0, 1.0) * (1.0 - smoothstep(0.72, 1.0, uv.y));\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant flame 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/flat/glassTint.d.ts

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */

package/dist/render/shaders/flat/glassTint.js

@@ -32,6 +32,8 @@ export function noLitSwitches() {
         SURFACE_EFFECTS: false,
         DRIFT_LIGHT: false,
         PHYSICAL_SPECULAR: false,
+        SURFACE_OVERLAY: false,
+        REFLECTION_MAPS: false,
     };
 }
 /**

package/dist/render/shaders/flat/index.d.ts

@@ -38,6 +38,12 @@ export interface FlatVertexOptions {
      * Excludes `skinned`: the joint attributes and the instance matrix want the same locations.
      */
     readonly instanced: boolean;
+    /**
+     * Whether an instanced variant follows a bone animation: \`shaders/boneAnimation.ts\`. A
+     * variant rather than a pipeline constant, because it declares three textures the other
+     * instanced pipelines would otherwise have to bind stand-ins for. Instanced only.
+     */
+    readonly animated?: boolean;
 }
 /**
  * The flat vertex shader, built for one variant.
@@ -109,6 +115,16 @@ export interface FlatShaderOptions {
      * when absent. See `modelsGlsl`.
      */
     readonly physicalSpecular?: boolean;
+    /**
+     * Whether it carries a draw's surface overlay, `uOverlay` and all (`setSurfaceOverlay`). True
+     * when absent. See `overlayGlsl`.
+     */
+    readonly surfaceOverlay?: boolean;
+    /**
+     * Whether the frame's own draws write the reflection maps beside their colour: WebGL2's way to
+     * the frame's materials' reflections. True when absent. See `reflectionSurfaceGlsl`.
+     */
+    readonly reflectionMaps?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

package/dist/render/shaders/flat/index.js

@@ -19,7 +19,10 @@ import { AREA_LIGHT_GLSL } from './areaLight.js';
 import { NORMAL_MAP_GLSL } from './normalMap.js';
 import { DRIFT_LIGHT_GLSL } from './driftLight.js';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.js';
-import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.js';
+import { overlayGlsl } from './overlay.js';
+import { reflectionSurfaceGlsl } from './reflectionSurface.js';
+import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.js';
+import { BONE_ANIMATION_GLSL } from '../boneAnimation.js';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
 /**
  * Flat-shaded vertex colours with one dominant directional source, ambient,
@@ -53,10 +56,16 @@ layout(location = 10) in vec4 aTangent;
 ${SKINNING_GLSL}
 #endif
 
-uniform mat4 uViewProj;
+uniform mat4 uViewProj; // wgsl:view
 /** 1 when the mesh carries a tangent frame. See vHasTangents. */
 uniform int uHasTangents;
-uniform mat4 uLightViewProj;
+uniform mat4 uLightViewProj; // wgsl:view
+/**
+ * The scene's clock, what \`setAnimationTime\` set: what a bone animation's instances read
+ * their moment from. In the view block, before the wind, so every variant's view block is the
+ * plain one's or a prefix of it — the instanced variant declares no wind and keeps this.
+ */
+uniform float uSceneTime; // wgsl:view
 /**
  * How often the surface texture repeats across this mesh's UV range, per axis.
  *
@@ -119,6 +128,9 @@ layout(location = 15) in vec4 aInstanceTint;
  * opacity of one. See lightmap.ts.
  */
 const bool LIGHTMAP_REGIONS = false; // wgsl:override
+#if ANIMATED
+${BONE_ANIMATION_GLSL}
+#endif
 #else
 uniform mat4 uModel;
 /**
@@ -144,7 +156,7 @@ uniform vec3 uTint;
  * agreeing about where the shared uniforms sit: the instanced variant drops these five along with
  * the two above it, and a dropped field moves nothing. flatPass.ts asserts exactly that.
  */
-${CHANNEL_ATTRIBUTE}
+${LIT_CHANNEL_ATTRIBUTE}
 ${CHANNEL_BEND}
 #endif
 
@@ -242,6 +254,10 @@ void main() {
   vec3 localNormal = aNormal;
   vec3 localTangent = aTangent.xyz;
 #endif
+#if ANIMATED
+  /* The clip's turn and place, in the mesh's own space, before the instance places it. */
+  local = vec4(boneAnimate(local.xyz, localNormal, localTangent), 1.0);
+#endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
   /*
@@ -351,7 +367,15 @@ export function flatVert(options) {
         throw new Error('flatVert: a variant cannot be both morphed and instanced — a morph weight is per draw, ' +
             'so every instance of the batch would wear one expression between them.');
     }
-    return resolveConditionals(FLAT_VERT_SOURCE, { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced }, 'flatVert');
+    if (options.animated === true && !options.instanced) {
+        throw new Error('flatVert: a bone animation is played by an instanced variant alone.');
+    }
+    return resolveConditionals(FLAT_VERT_SOURCE, {
+        SKINNED: options.skinned,
+        MORPHED: options.morphed,
+        INSTANCED: options.instanced,
+        ANIMATED: options.animated === true,
+    }, 'flatVert');
 }
 /**
  * The flat fragment shader, built for one quality profile.
@@ -471,6 +495,10 @@ export function flatFrag(options) {
         SURFACE_EFFECTS_GLSL,
         /* Depth zero and after the tangent frame and the lobes it calls; see models.ts. */
         modelsGlsl(options.physicalSpecular ?? true),
+        /* After the models, so its switch takes the next id; depth zero, as main calls it. */
+        overlayGlsl(options.surfaceOverlay ?? true),
+        /* After the overlay, so its switch takes the next id. See reflectionSurface.ts. */
+        reflectionSurfaceGlsl(options.reflectionMaps ?? true),
         /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
         AREA_LIGHT_GLSL,
         MAIN_GLSL,