@driftengine/core 3.61.0

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

@@ -0,0 +1,14 @@
+export declare const SCATTER_VERT = "#version 300 es\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec3 aNormal;\nlayout(location = 2) in vec3 aColor;\nlayout(location = 3) in vec3 aInstancePos;\nlayout(location = 4) in vec2 aScaleYaw;\nlayout(location = 5) in vec3 aTint;\nlayout(location = 6) in vec3 aWindResponse;\n\nuniform mat4 uViewProj;\n\nuniform vec2 uWindDirection;\nuniform float uWindSpeed;\nuniform float uWindGust;\nuniform float uWindTime;\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase;\n/*\n * Where something heavy has just been: xyz world position, w how pressed, 0 unused.\n *\n * Uniforms rather than a texture or a re-upload, because this is the hottest shader\n * in the game and the effect is a metre wide. Eight of them is about two seconds of\n * trail at running pace. See TrampleField.\n */\nuniform vec4 uTrample[8];\n/* How far a press reaches, metres, and how much of a plant it takes away. */\nuniform float uTrampleRadius;\nuniform float uTrampleDepth;\n\n/* Yaw as (sin, cos). Computed once per vertex and shared by position and normal. */\nvec2 scatterYaw(float yaw) {\n  return vec2(sin(yaw), cos(yaw));\n}\n\n/* The instance's local offset from its root, after scale, yaw, wind and trampling. */\nvec3 scatterOffset(\n  vec3 position,\n  vec3 instancePos,\n  vec2 scaleYaw,\n  vec3 windResponse,\n  vec2 yawTrig\n) {\n  float s = yawTrig.x;\n  float c = yawTrig.y;\n\n  vec3 local = position * scaleYaw.x;\n  vec3 rotated = vec3(local.x * c + local.z * s, local.y, -local.x * s + local.z * c);\n\n  /*\n   * Wind phase comes from world position, so neighbouring plants are never in\n   * lockstep and a gust visibly travels across a field instead of the whole\n   * field pulsing at once. Direction and strength come from the shared wind \u2014\n   * this adds spatial variation, never a second wind.\n   *\n   * Amplitude rises with the square of height, so the base stays planted and\n   * only the tip travels. A linear falloff slides the whole plant sideways,\n   * which reads as the ground moving.\n   */\n  float phase = dot(instancePos.xz, uWindSpatialPhase) + uWindTime + windResponse.z;\n  float rooted = clamp(rotated.y * windResponse.x, 0.0, 1.0);\n  float bend = (uWindSpeed + uWindGust * windResponse.y) * sin(phase) * rooted * rooted;\n  rotated.xz += uWindDirection * bend;\n\n  /*\n   * Trampling: pressed toward the ground and pushed away from whatever pressed it.\n   *\n   * The strongest press wins rather than the sum. Two overlapping presses adding up\n   * would drive a blade through the deck, and a character crossing their own trail is\n   * exactly when that would happen.\n   *\n   * Direction comes from the *press*, so a plant leans away from where the foot was\n   * instead of all of them lying the same way, which is what makes it read as\n   * something having gone through rather than as a second wind.\n   */\n  float pressed = 0.0;\n  vec2 away = vec2(0.0);\n  for (int i = 0; i < 8; i++) {\n    vec4 p = uTrample[i];\n    if (p.w <= 0.0) continue;\n    vec3 offset = instancePos - p.xyz;\n    float dist = length(offset);\n    if (dist >= uTrampleRadius) continue;\n    float fade = 1.0 - dist / uTrampleRadius;\n    float strength = p.w * fade * fade;\n    if (strength <= pressed) continue;\n    pressed = strength;\n    // Degenerate at the exact centre, where any direction is as good as another.\n    away = dist > 1e-4 ? offset.xz / dist : vec2(0.0);\n  }\n  if (pressed > 0.0) {\n    float take = pressed * uTrampleDepth;\n    // Height goes first \u2014 a flattened plant is shorter, and the fold outward is\n    // what makes the loss of height read as bending rather than as sinking.\n    rotated.y *= 1.0 - take;\n    rotated.xz += away * take * rotated.y * 1.4;\n  }\n\n  return rotated;\n}\n\nout vec3 vColor;\nout vec3 vNormal;\nout vec3 vWorldPos;\n\nvoid main() {\n  vec2 yawTrig = scatterYaw(aScaleYaw.y);\n  vec3 rotated = scatterOffset(aPosition, aInstancePos, aScaleYaw, aWindResponse, yawTrig);\n  vec3 world = aInstancePos + rotated;\n\n  float s = yawTrig.x;\n  float c = yawTrig.y;\n  vColor = aColor * aTint;\n  vNormal = vec3(aNormal.x * c + aNormal.z * s, aNormal.y, -aNormal.x * s + aNormal.z * c);\n  vWorldPos = world;\n  gl_Position = uViewProj * vec4(world, 1.0);\n}\n";
+/**
+ * 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 declare const SCATTER_DEPTH_VERT = "#version 300 es\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 3) in vec3 aInstancePos;\nlayout(location = 4) in vec2 aScaleYaw;\nlayout(location = 6) in vec3 aWindResponse;\n\nuniform mat4 uLightViewProj;\n\nuniform vec2 uWindDirection;\nuniform float uWindSpeed;\nuniform float uWindGust;\nuniform float uWindTime;\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase;\n/*\n * Where something heavy has just been: xyz world position, w how pressed, 0 unused.\n *\n * Uniforms rather than a texture or a re-upload, because this is the hottest shader\n * in the game and the effect is a metre wide. Eight of them is about two seconds of\n * trail at running pace. See TrampleField.\n */\nuniform vec4 uTrample[8];\n/* How far a press reaches, metres, and how much of a plant it takes away. */\nuniform float uTrampleRadius;\nuniform float uTrampleDepth;\n\n/* Yaw as (sin, cos). Computed once per vertex and shared by position and normal. */\nvec2 scatterYaw(float yaw) {\n  return vec2(sin(yaw), cos(yaw));\n}\n\n/* The instance's local offset from its root, after scale, yaw, wind and trampling. */\nvec3 scatterOffset(\n  vec3 position,\n  vec3 instancePos,\n  vec2 scaleYaw,\n  vec3 windResponse,\n  vec2 yawTrig\n) {\n  float s = yawTrig.x;\n  float c = yawTrig.y;\n\n  vec3 local = position * scaleYaw.x;\n  vec3 rotated = vec3(local.x * c + local.z * s, local.y, -local.x * s + local.z * c);\n\n  /*\n   * Wind phase comes from world position, so neighbouring plants are never in\n   * lockstep and a gust visibly travels across a field instead of the whole\n   * field pulsing at once. Direction and strength come from the shared wind \u2014\n   * this adds spatial variation, never a second wind.\n   *\n   * Amplitude rises with the square of height, so the base stays planted and\n   * only the tip travels. A linear falloff slides the whole plant sideways,\n   * which reads as the ground moving.\n   */\n  float phase = dot(instancePos.xz, uWindSpatialPhase) + uWindTime + windResponse.z;\n  float rooted = clamp(rotated.y * windResponse.x, 0.0, 1.0);\n  float bend = (uWindSpeed + uWindGust * windResponse.y) * sin(phase) * rooted * rooted;\n  rotated.xz += uWindDirection * bend;\n\n  /*\n   * Trampling: pressed toward the ground and pushed away from whatever pressed it.\n   *\n   * The strongest press wins rather than the sum. Two overlapping presses adding up\n   * would drive a blade through the deck, and a character crossing their own trail is\n   * exactly when that would happen.\n   *\n   * Direction comes from the *press*, so a plant leans away from where the foot was\n   * instead of all of them lying the same way, which is what makes it read as\n   * something having gone through rather than as a second wind.\n   */\n  float pressed = 0.0;\n  vec2 away = vec2(0.0);\n  for (int i = 0; i < 8; i++) {\n    vec4 p = uTrample[i];\n    if (p.w <= 0.0) continue;\n    vec3 offset = instancePos - p.xyz;\n    float dist = length(offset);\n    if (dist >= uTrampleRadius) continue;\n    float fade = 1.0 - dist / uTrampleRadius;\n    float strength = p.w * fade * fade;\n    if (strength <= pressed) continue;\n    pressed = strength;\n    // Degenerate at the exact centre, where any direction is as good as another.\n    away = dist > 1e-4 ? offset.xz / dist : vec2(0.0);\n  }\n  if (pressed > 0.0) {\n    float take = pressed * uTrampleDepth;\n    // Height goes first \u2014 a flattened plant is shorter, and the fold outward is\n    // what makes the loss of height read as bending rather than as sinking.\n    rotated.y *= 1.0 - take;\n    rotated.xz += away * take * rotated.y * 1.4;\n  }\n\n  return rotated;\n}\n\nout vec4 vLightPosition;\n\nvoid main() {\n  vec3 rotated = scatterOffset(\n    aPosition,\n    aInstancePos,\n    aScaleYaw,\n    aWindResponse,\n    scatterYaw(aScaleYaw.y)\n  );\n  vLightPosition = uLightViewProj * vec4(aInstancePos + rotated, 1.0);\n  gl_Position = vLightPosition;\n}\n";
+export declare const SCATTER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vColor;\nin vec3 vNormal;\nin vec3 vWorldPos;\n\nuniform vec3 uDirectionalDir;\nuniform vec3 uDirectionalColor;\nuniform vec3 uAmbient;\nuniform vec3 uCameraPos;\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\nout vec4 outColor;\n\nvoid main() {\n  vec3 n = normalize(vNormal);\n  /*\n   * Two-sided. A blade of grass is a flat sliver seen from both faces, and\n   * lighting its back face as though it faced away leaves half of every field\n   * black \u2014 the cheapest and most obvious foliage tell there is.\n   */\n  float ndl = abs(dot(n, uDirectionalDir));\n  vec3 lit = vColor * (uAmbient + uDirectionalColor * ndl);\n\n  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n\n  outColor = vec4(mix(lit, mediumColor(), fog), 1.0);\n}\n";

package/dist/render/shaders/scatter.js

@@ -0,0 +1,206 @@
+import { FOG_GLSL } from './fog.js';
+/**
+ * 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/dist/render/shaders/sdfText.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const SDF_TEXT_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aPosition;\nlayout(location = 1) in vec2 aUv;\n\nuniform mat4 uViewProj;\nuniform mat4 uModel;\n\nout vec2 vUv;\n\nvoid main() {\n  vUv = aUv;\n  gl_Position = uViewProj * uModel * vec4(aPosition, 1.0);\n}\n";
+export declare const SDF_TEXT_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\nuniform sampler2D uAtlas;\nuniform vec3 uColor;\nuniform float uOpacity;\n/* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */\nuniform float uDistanceRange;\nuniform vec2 uAtlasSize;\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  return linearToSrgb(c);\n}\n\n\n/*\n * The middle of the three channels.\n *\n * A single-channel field rounds every corner off at small sizes, because one distance\n * cannot describe two edges meeting. Three channels carry the corner and the median\n * recovers it.\n */\nfloat median(vec3 rgb) {\n  return max(min(rgb.r, rgb.g), min(max(rgb.r, rgb.g), rgb.b));\n}\n\nvoid main() {\n  vec3 sampled = textureLod(uAtlas, vUv, 0.0).rgb;\n  float distance = median(sampled) - 0.5;\n\n  /*\n   * The band is one pixel wide *in screen space*, which is what lets one atlas serve every\n   * size. A constant band is tuned for one size and is wrong at all the others.\n   */\n  vec2 texelsPerPixel = fwidth(vUv) * uAtlasSize;\n  float pixelRange = max(0.5 * (texelsPerPixel.x + texelsPerPixel.y), 0.0001);\n  float coverage = clamp(distance * uDistanceRange / pixelRange + 0.5, 0.0, 1.0);\n\n  outColor = vec4(applyOutputTransform(uColor), coverage * uOpacity);\n}\n";

package/dist/render/shaders/sdfText.js

@@ -0,0 +1,65 @@
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.js';
+/**
+ * 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/dist/render/shaders/skinning.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const SKINNING_GLSL = "\n/**\n * The joint palette, four texels a matrix, one row.\n *\n * A texture rather than a `uniform mat4[]`. The 2026-08-07 rule that keeps samples out of\n * unprovable branches is about *implicit derivatives*, which a vertex stage does not compute, so\n * it has nothing to say here \u2014 and `texelFetch` takes an integer coordinate with no level\n * inferred at all. What a uniform array would have cost is the cap: MAX_VERTEX_UNIFORM_VECTORS is\n * 256 on the WebGL2 floor and this shader already spends fifteen, which leaves sixty joints.\n *\n * What this costs is a texture upload per skinned draw. What would make it wrong is a profile\n * showing that upload is the limit; the fix is one texture for every character with a row offset.\n */\nuniform highp sampler2D uJointPalette;\n\nlayout(location = 11) in vec4 aJoints;\nlayout(location = 12) in vec4 aWeights;\n\n/** One joint's matrix, read as four consecutive texels of row 0. */\nmat4 jointMatrix(int index) {\n  int x = index * 4;\n  return mat4(\n    texelFetch(uJointPalette, ivec2(x, 0), 0),\n    texelFetch(uJointPalette, ivec2(x + 1, 0), 0),\n    texelFetch(uJointPalette, ivec2(x + 2, 0), 0),\n    texelFetch(uJointPalette, ivec2(x + 3, 0), 0));\n}\n\n/**\n * The four influences, weighted.\n *\n * Weights are normalised by the importer rather than here: normalising per vertex per frame costs\n * a divide on every vertex to correct data an importer should have fixed once, and `gltfSkin.ts`\n * warns when a set does not sum to one. What would make it wrong is a caller building a MeshData\n * by hand with unnormalised weights, which shades slightly dark or bright rather than breaking.\n */\nmat4 skinMatrix() {\n  return jointMatrix(int(aJoints.x)) * aWeights.x\n       + jointMatrix(int(aJoints.y)) * aWeights.y\n       + jointMatrix(int(aJoints.z)) * aWeights.z\n       + jointMatrix(int(aJoints.w)) * aWeights.w;\n}\n";

package/dist/render/shaders/skinning.js

@@ -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/dist/render/shaders/sky.d.ts

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