@driftengine/core 3.61.0

package/src/render/shaders/scatter.ts

@@ -0,0 +1,211 @@
+import { FOG_GLSL } from './fog.ts';
+
+/**
+ * Instanced scatter: grass, flowers, foliage — anything there are thousands of.
+ *
+ * Two programs, one material. The visible one lights and fogs the batch; the depth
+ * one records it as an occluder for a shadow map. They share the instance transform
+ * below, and that sharing is the point: a caster whose depth is computed from a
+ * different pose than its picture is a shadow that has come loose from the thing
+ * casting it.
+ *
+ * Lighting deliberately mirrors the flat material's terms (sun, ambient, fog),
+ * because scatter has to sit in the same world as the geometry it stands on. A
+ * separate lighting model is exactly how foliage ends up looking pasted onto a
+ * scene rather than growing out of it.
+ */
+
+/**
+ * Where an instance's vertex ends up: scaled, turned, bent by the wind, pressed by
+ * whatever walked through it.
+ *
+ * Shared source rather than two copies, because the two programs have to agree
+ * *exactly*. A canopy bends by tens of centimetres at its crown, and a crown is
+ * metres across — so a depth pass that skipped the bend would slide a tree's whole
+ * shade off the deck it belongs to, drifting as the gust changed. One expression,
+ * two callers.
+ */
+const SCATTER_DEFORM = `
+uniform vec2 uWindDirection;
+uniform float uWindSpeed;
+uniform float uWindGust;
+uniform float uWindTime;
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase;
+/*
+ * Where something heavy has just been: xyz world position, w how pressed, 0 unused.
+ *
+ * Uniforms rather than a texture or a re-upload, because this is the hottest shader
+ * in the game and the effect is a metre wide. Eight of them is about two seconds of
+ * trail at running pace. See TrampleField.
+ */
+uniform vec4 uTrample[8];
+/* How far a press reaches, metres, and how much of a plant it takes away. */
+uniform float uTrampleRadius;
+uniform float uTrampleDepth;
+
+/* Yaw as (sin, cos). Computed once per vertex and shared by position and normal. */
+vec2 scatterYaw(float yaw) {
+  return vec2(sin(yaw), cos(yaw));
+}
+
+/* The instance's local offset from its root, after scale, yaw, wind and trampling. */
+vec3 scatterOffset(
+  vec3 position,
+  vec3 instancePos,
+  vec2 scaleYaw,
+  vec3 windResponse,
+  vec2 yawTrig
+) {
+  float s = yawTrig.x;
+  float c = yawTrig.y;
+
+  vec3 local = position * scaleYaw.x;
+  vec3 rotated = vec3(local.x * c + local.z * s, local.y, -local.x * s + local.z * c);
+
+  /*
+   * Wind phase comes from world position, so neighbouring plants are never in
+   * lockstep and a gust visibly travels across a field instead of the whole
+   * field pulsing at once. Direction and strength come from the shared wind —
+   * this adds spatial variation, never a second wind.
+   *
+   * Amplitude rises with the square of height, so the base stays planted and
+   * only the tip travels. A linear falloff slides the whole plant sideways,
+   * which reads as the ground moving.
+   */
+  float phase = dot(instancePos.xz, uWindSpatialPhase) + uWindTime + windResponse.z;
+  float rooted = clamp(rotated.y * windResponse.x, 0.0, 1.0);
+  float bend = (uWindSpeed + uWindGust * windResponse.y) * sin(phase) * rooted * rooted;
+  rotated.xz += uWindDirection * bend;
+
+  /*
+   * Trampling: pressed toward the ground and pushed away from whatever pressed it.
+   *
+   * The strongest press wins rather than the sum. Two overlapping presses adding up
+   * would drive a blade through the deck, and a character crossing their own trail is
+   * exactly when that would happen.
+   *
+   * Direction comes from the *press*, so a plant leans away from where the foot was
+   * instead of all of them lying the same way, which is what makes it read as
+   * something having gone through rather than as a second wind.
+   */
+  float pressed = 0.0;
+  vec2 away = vec2(0.0);
+  for (int i = 0; i < 8; i++) {
+    vec4 p = uTrample[i];
+    if (p.w <= 0.0) continue;
+    vec3 offset = instancePos - p.xyz;
+    float dist = length(offset);
+    if (dist >= uTrampleRadius) continue;
+    float fade = 1.0 - dist / uTrampleRadius;
+    float strength = p.w * fade * fade;
+    if (strength <= pressed) continue;
+    pressed = strength;
+    // Degenerate at the exact centre, where any direction is as good as another.
+    away = dist > 1e-4 ? offset.xz / dist : vec2(0.0);
+  }
+  if (pressed > 0.0) {
+    float take = pressed * uTrampleDepth;
+    // Height goes first — a flattened plant is shorter, and the fold outward is
+    // what makes the loss of height read as bending rather than as sinking.
+    rotated.y *= 1.0 - take;
+    rotated.xz += away * take * rotated.y * 1.4;
+  }
+
+  return rotated;
+}
+`;
+
+export const SCATTER_VERT = `#version 300 es
+layout(location = 0) in vec3 aPosition;
+layout(location = 1) in vec3 aNormal;
+layout(location = 2) in vec3 aColor;
+layout(location = 3) in vec3 aInstancePos;
+layout(location = 4) in vec2 aScaleYaw;
+layout(location = 5) in vec3 aTint;
+layout(location = 6) in vec3 aWindResponse;
+
+uniform mat4 uViewProj;
+${SCATTER_DEFORM}
+out vec3 vColor;
+out vec3 vNormal;
+out vec3 vWorldPos;
+
+void main() {
+  vec2 yawTrig = scatterYaw(aScaleYaw.y);
+  vec3 rotated = scatterOffset(aPosition, aInstancePos, aScaleYaw, aWindResponse, yawTrig);
+  vec3 world = aInstancePos + rotated;
+
+  float s = yawTrig.x;
+  float c = yawTrig.y;
+  vColor = aColor * aTint;
+  vNormal = vec3(aNormal.x * c + aNormal.z * s, aNormal.y, -aNormal.x * s + aNormal.z * c);
+  vWorldPos = world;
+  gl_Position = uViewProj * vec4(world, 1.0);
+}
+`;
+
+/**
+ * The same batch, recorded as a shadow caster.
+ *
+ * Pairs with `DEPTH_FRAG`, whose peel mode needs `vLightPosition` — so the two
+ * scatter programs and the rigid depth program all speak the same depth protocol,
+ * and a batch can be submitted to any layer a rigid mesh can.
+ *
+ * Only the four attributes the transform needs are declared. The instanced VAO
+ * also carries normals, colours and tints; a depth pass has no use for them and a
+ * program is not obliged to read every attribute a VAO offers.
+ */
+export const SCATTER_DEPTH_VERT = `#version 300 es
+layout(location = 0) in vec3 aPosition;
+layout(location = 3) in vec3 aInstancePos;
+layout(location = 4) in vec2 aScaleYaw;
+layout(location = 6) in vec3 aWindResponse;
+
+uniform mat4 uLightViewProj;
+${SCATTER_DEFORM}
+out vec4 vLightPosition;
+
+void main() {
+  vec3 rotated = scatterOffset(
+    aPosition,
+    aInstancePos,
+    aScaleYaw,
+    aWindResponse,
+    scatterYaw(aScaleYaw.y)
+  );
+  vLightPosition = uLightViewProj * vec4(aInstancePos + rotated, 1.0);
+  gl_Position = vLightPosition;
+}
+`;
+
+export const SCATTER_FRAG = `#version 300 es
+precision highp float;
+
+in vec3 vColor;
+in vec3 vNormal;
+in vec3 vWorldPos;
+
+uniform vec3 uDirectionalDir;
+uniform vec3 uDirectionalColor;
+uniform vec3 uAmbient;
+uniform vec3 uCameraPos;
+${FOG_GLSL}
+
+out vec4 outColor;
+
+void main() {
+  vec3 n = normalize(vNormal);
+  /*
+   * Two-sided. A blade of grass is a flat sliver seen from both faces, and
+   * lighting its back face as though it faced away leaves half of every field
+   * black — the cheapest and most obvious foliage tell there is.
+   */
+  float ndl = abs(dot(n, uDirectionalDir));
+  vec3 lit = vColor * (uAmbient + uDirectionalColor * ndl);
+
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+
+  outColor = vec4(mix(lit, mediumColor(), fog), 1.0);
+}
+`;

package/src/render/shaders/sdfText.ts

@@ -0,0 +1,68 @@
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
+
+/**
+ * Text from a multi-channel signed distance field.
+ *
+ * GLSL is the source of truth; `npm run wgsl` produces the WGSL beside it. Written to the
+ * same rules every other shader here follows, which is why the sampler is `textureLod`:
+ * the alpha test is not uniform control flow.
+ */
+
+export const SDF_TEXT_VERT = `#version 300 es
+precision highp float;
+
+layout(location = 0) in vec3 aPosition;
+layout(location = 1) in vec2 aUv;
+
+uniform mat4 uViewProj;
+uniform mat4 uModel;
+
+out vec2 vUv;
+
+void main() {
+  vUv = aUv;
+  gl_Position = uViewProj * uModel * vec4(aPosition, 1.0);
+}
+`;
+
+export const SDF_TEXT_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+uniform sampler2D uAtlas;
+uniform vec3 uColor;
+uniform float uOpacity;
+/* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */
+uniform float uDistanceRange;
+uniform vec2 uAtlasSize;
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+/*
+ * The middle of the three channels.
+ *
+ * A single-channel field rounds every corner off at small sizes, because one distance
+ * cannot describe two edges meeting. Three channels carry the corner and the median
+ * recovers it.
+ */
+float median(vec3 rgb) {
+  return max(min(rgb.r, rgb.g), min(max(rgb.r, rgb.g), rgb.b));
+}
+
+void main() {
+  vec3 sampled = textureLod(uAtlas, vUv, 0.0).rgb;
+  float distance = median(sampled) - 0.5;
+
+  /*
+   * The band is one pixel wide *in screen space*, which is what lets one atlas serve every
+   * size. A constant band is tuned for one size and is wrong at all the others.
+   */
+  vec2 texelsPerPixel = fwidth(vUv) * uAtlasSize;
+  float pixelRange = max(0.5 * (texelsPerPixel.x + texelsPerPixel.y), 0.0001);
+  float coverage = clamp(distance * uDistanceRange / pixelRange + 0.5, 0.0, 1.0);
+
+  outColor = vec4(applyOutputTransform(uColor), coverage * uOpacity);
+}
+`;

package/src/render/shaders/skinning.ts

@@ -0,0 +1,59 @@
+/**
+ * The vertex-stage skinning prelude: the palette, its two attributes, and the weighted matrix.
+ *
+ * Included by `flat/index.ts` inside `#if SKINNED`, so `resolveConditionals` cuts every line of it
+ * out of the unskinned variant. **Absent rather than gated**, and that is measured: the vertex
+ * shader had no permutation axis at all before this, so a second variant costs **1,118 bytes
+ * gzipped**, measured on the regenerated file — two 4.4 KB strings that mostly dedupe inside
+ * deflate's 32 KB window — where a uniform gate
+ * would cost every vertex of every static mesh in the engine a branch it can never take. The
+ * 2^n cost `ARCHITECTURE.md` §1 is written about is a property of the *fragment* corpus, whose
+ * permutations are each larger than that window.
+ *
+ * What it costs is one more axis for `scripts/wgsl.ts` to expand and a second program on WebGL2.
+ * What would make it wrong is a second vertex flag: four variants dedupe less well than two, so
+ * re-measure before adding one.
+ */
+export const SKINNING_GLSL = `
+/**
+ * The joint palette, four texels a matrix, one row.
+ *
+ * A texture rather than a \`uniform mat4[]\`. The 2026-08-07 rule that keeps samples out of
+ * unprovable branches is about *implicit derivatives*, which a vertex stage does not compute, so
+ * it has nothing to say here — and \`texelFetch\` takes an integer coordinate with no level
+ * inferred at all. What a uniform array would have cost is the cap: MAX_VERTEX_UNIFORM_VECTORS is
+ * 256 on the WebGL2 floor and this shader already spends fifteen, which leaves sixty joints.
+ *
+ * What this costs is a texture upload per skinned draw. What would make it wrong is a profile
+ * showing that upload is the limit; the fix is one texture for every character with a row offset.
+ */
+uniform highp sampler2D uJointPalette;
+
+layout(location = 11) in vec4 aJoints;
+layout(location = 12) in vec4 aWeights;
+
+/** One joint's matrix, read as four consecutive texels of row 0. */
+mat4 jointMatrix(int index) {
+  int x = index * 4;
+  return mat4(
+    texelFetch(uJointPalette, ivec2(x, 0), 0),
+    texelFetch(uJointPalette, ivec2(x + 1, 0), 0),
+    texelFetch(uJointPalette, ivec2(x + 2, 0), 0),
+    texelFetch(uJointPalette, ivec2(x + 3, 0), 0));
+}
+
+/**
+ * The four influences, weighted.
+ *
+ * Weights are normalised by the importer rather than here: normalising per vertex per frame costs
+ * a divide on every vertex to correct data an importer should have fixed once, and \`gltfSkin.ts\`
+ * warns when a set does not sum to one. What would make it wrong is a caller building a MeshData
+ * by hand with unnormalised weights, which shades slightly dark or bright rather than breaking.
+ */
+mat4 skinMatrix() {
+  return jointMatrix(int(aJoints.x)) * aWeights.x
+       + jointMatrix(int(aJoints.y)) * aWeights.y
+       + jointMatrix(int(aJoints.z)) * aWeights.z
+       + jointMatrix(int(aJoints.w)) * aWeights.w;
+}
+`;

package/src/render/shaders/sky.ts

@@ -0,0 +1,243 @@
+import { glslFarDepth } from '../depthConvention.ts';
+/**
+ * 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/src/render/shaders/smoke.ts

@@ -0,0 +1,89 @@
+import { FOG_GLSL } from './fog.ts';
+
+/**
+ * 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));
+}
+`;