Skip to content

3D engine that AI agents drive

40.2 KB
Raw Blame
import { layerTextureSupport, registerShaderFeatureCode } from './shader-registry.js';
import { causticsDeclarations, resolveWaterCaustics, waterCausticsUniform } from './water-caustics.js';

// Water bodies. A material with the water tag can carry `absorption` (RGB per metre: how fast each colour fades going down) and
// `turbidity` (0 clear to 1 murky: how much light the water scatters into shadows). The largest flat water part of a scene sets
// the water level. Every surface below it is dimmed by Beer-Lambert absorption of the column above it, and its shadows are lifted
// by in-scatter and widened with depth times turbidity (worldVisibility below). Absorption folds the way down and the way back up
// into one coefficient, so a bed `depth` metres down keeps exp(-absorption * depth) of its light.
/** Water the way people name it: where the light goes and how far a shadow stays sharp. */
export const WATER_PRESETS = Object.freeze({
  lake: Object.freeze({ absorption: Object.freeze([0.35, 0.07, 0.04]), turbidity: 0.02 }),
  sea: Object.freeze({ absorption: Object.freeze([0.4, 0.06, 0.02]), turbidity: 0.1 }),
  river: Object.freeze({ absorption: Object.freeze([0.8, 0.9, 1.6]), turbidity: 0.75 }),
});
export const WATER_DEFAULT_PRESET = 'lake';
export const WATER_MAXIMUM_ABSORPTION = 20;
// A water part counts as one level when it is this flat: thickness against its wider side.
const WATER_MAXIMUM_THICKNESS_RATIO = 0.02;

/** Resolves a material's water fields: an explicit absorption or turbidity beats the preset, which beats the default lake. */
export function resolveWaterMaterial({ waterPreset, absorption, turbidity } = {}) {
  const preset = waterPreset ?? WATER_DEFAULT_PRESET;
  if (!Object.hasOwn(WATER_PRESETS, preset)) {
    throw new RangeError(`waterPreset must be one of ${Object.keys(WATER_PRESETS).join(', ')}.`);
  }
  const resolvedAbsorption = absorption ?? WATER_PRESETS[preset].absorption;
  const absorptionValid = Array.isArray(resolvedAbsorption) && resolvedAbsorption.length === 3
    && resolvedAbsorption.every(channel => Number.isFinite(channel) && channel >= 0 && channel <= WATER_MAXIMUM_ABSORPTION);
  if (!absorptionValid) {
    throw new RangeError(`absorption must be three numbers from 0 to ${WATER_MAXIMUM_ABSORPTION} (per metre).`);
  }
  const resolvedTurbidity = turbidity ?? WATER_PRESETS[preset].turbidity;
  if (!Number.isFinite(resolvedTurbidity) || resolvedTurbidity < 0 || resolvedTurbidity > 1) {
    throw new RangeError('turbidity must be within zero and one.');
  }
  return { waterPreset: preset, absorption: [...resolvedAbsorption], turbidity: resolvedTurbidity };
}

/** Copies a recipe material's water fields: a water material always carries the resolved absorption, turbidity and preset. */
export function copyWaterFields(value, result, toVector) {
  const given = ['waterPreset', 'absorption', 'turbidity', 'caustics'].filter(field => value[field] !== undefined);
  if (result.tag !== 'water') {
    if (given.length > 0) {
      throw new RangeError(`${given.join(', ')} need the water tag.`);
    }
    return;
  }
  const absorption = value.absorption === undefined ? undefined : toVector(value.absorption, 3, 'absorption');
  Object.assign(result, resolveWaterMaterial({ ...value, absorption }));
  const caustics = resolveWaterCaustics(value.caustics);
  if (caustics) {
    result.caustics = caustics;
  }
}

export const WATER_RAMP_COLOR_COUNT = Object.freeze([3, 5]);
const WATER_RAMP_DRIVERS = Object.freeze(['height', 'facing', 'sun']);
const WATER_RAMP_FIELDS = Object.freeze(['colors', 'drivers', 'heightRange', 'steps', 'crestTint']);
const WATER_RAMP_STEPS = Object.freeze(['hard', 'soft']);
const WATER_RAMP_DEFAULT_HEIGHT_RANGE = Object.freeze([-1, 1]);

const HEX_COLOR = /^#[0-9a-f]{6}$/i;

function srgbByteToLinear(byte) {
  const encoded = byte / 255;
  return encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4;
}

/** A ramp colour: three linear numbers (0 to 16) whose sRGB encoding is the colour shown, or a `#rrggbb` hex shown as that hex. */
function rampColor(value, name, toVector) {
  if (typeof value === 'string' && HEX_COLOR.test(value)) {
    return Object.freeze([1, 3, 5].map(offset => srgbByteToLinear(Number.parseInt(value.slice(offset, offset + 2), 16))));
  }
  const color = toVector(value, 3, name);
  if (color.some(component => !Number.isFinite(component) || component < 0 || component > 16)) {
    throw new RangeError(`${name} must be three numbers from 0 to 16, such as [0.1, 0.5, 0.6].`);
  }
  return Object.freeze([...color]);
}

function rampDrivers(drivers) {
  const given = drivers ?? { height: 1 };
  const unknown = Object.keys(given).filter(name => !WATER_RAMP_DRIVERS.includes(name));
  if (unknown.length > 0) {
    throw new RangeError(`waterRamp.drivers has no ${unknown.join(', ')}; pass weights for ${WATER_RAMP_DRIVERS.join(', ')}, such as { "height": 1, "sun": 0.5 }.`);
  }
  const weights = WATER_RAMP_DRIVERS.map(name => given[name] ?? 0);
  if (weights.some(weight => !Number.isFinite(weight) || weight < 0 || weight > 1) || weights.every(weight => weight === 0)) {
    throw new RangeError('waterRamp.drivers weights must be numbers from 0 to 1 with at least one above 0, such as { "height": 1, "sun": 0.5 }.');
  }
  return Object.freeze(Object.fromEntries(WATER_RAMP_DRIVERS.map((name, index) => [name, weights[index]])));
}

/**
 * The stylized colour ramp of a water material. `colors` (3 to 5, deep to bright) are picked by a weighted mix of drivers: `height`
 * (world y across `heightRange`, default -1 to 1), `facing` (grazing view, 1 at the horizon) and `sun` (how squarely the wave face meets
 * the sun). `steps` hard (default) keeps flat tones, soft blends them. `crestTint` { color, strength 0-1 } colours the folded crests.
 */
export function resolveWaterRamp(ramp, toVector) {
  if (typeof ramp !== 'object' || ramp === null || Array.isArray(ramp)) {
    throw new RangeError('waterRamp must be an object such as { "colors": [[0.02, 0.2, 0.3], [0.1, 0.6, 0.7], [0.5, 0.95, 0.95]] }.');
  }
  const unknown = Object.keys(ramp).filter(name => !WATER_RAMP_FIELDS.includes(name));
  if (unknown.length > 0) {
    throw new RangeError(`waterRamp has no ${unknown.join(', ')}; use ${WATER_RAMP_FIELDS.join(', ')}.`);
  }
  const [minimumColors, maximumColors] = WATER_RAMP_COLOR_COUNT;
  if (!Array.isArray(ramp.colors) || ramp.colors.length < minimumColors || ramp.colors.length > maximumColors) {
    throw new RangeError(`waterRamp.colors must list ${minimumColors} to ${maximumColors} colours from deep to bright, such as [[0.02, 0.2, 0.3], [0.1, 0.6, 0.7], [0.5, 0.95, 0.95]].`);
  }
  const steps = ramp.steps ?? 'hard';
  if (!WATER_RAMP_STEPS.includes(steps)) {
    throw new RangeError(`waterRamp.steps must be one of ${WATER_RAMP_STEPS.join(', ')}, such as hard.`);
  }
  const heightRange = ramp.heightRange ?? WATER_RAMP_DEFAULT_HEIGHT_RANGE;
  if (!Array.isArray(heightRange) || heightRange.length !== 2 || !heightRange.every(Number.isFinite) || heightRange[0] >= heightRange[1]) {
    throw new RangeError('waterRamp.heightRange must be [low, high] world heights with low below high, such as [-1, 1].');
  }
  const resolved = { colors: Object.freeze(ramp.colors.map((color, index) => rampColor(color, `waterRamp.colors[${index}]`, toVector))), drivers: rampDrivers(ramp.drivers), heightRange: Object.freeze([...heightRange]), steps };
  if (ramp.crestTint !== undefined) {
    const { color, strength = 1, ...extra } = ramp.crestTint ?? {};
    if (color === undefined || Object.keys(extra).length > 0 || !Number.isFinite(strength) || strength < 0 || strength > 1) {
      throw new RangeError('waterRamp.crestTint must be { "color": [r, g, b], "strength": 0 to 1 }, such as { "color": [0.7, 1, 0.9], "strength": 0.8 }.');
    }
    resolved.crestTint = Object.freeze({ color: rampColor(color, 'waterRamp.crestTint.color', toVector), strength });
  }
  return Object.freeze(resolved);
}

/** Copies a recipe material's `waterRamp`: it needs the water tag. */
export function copyWaterRamp(value, result, toVector) {
  if (value.waterRamp === undefined) {
    return;
  }
  if (result.tag !== 'water') {
    throw new RangeError('waterRamp needs the water tag.');
  }
  result.waterRamp = resolveWaterRamp(value.waterRamp, toVector);
}

function partBounds(part) {
  const { positions } = part.geometry;
  const { matrix } = part;
  const minimum = [Infinity, Infinity, Infinity];
  const maximum = [-Infinity, -Infinity, -Infinity];
  for (let vertex = 0; vertex < positions.length; vertex += 3) {
    for (let axis = 0; axis < 3; axis++) {
      const value = matrix[axis] * positions[vertex] + matrix[4 + axis] * positions[vertex + 1] + matrix[8 + axis] * positions[vertex + 2] + matrix[12 + axis];
      minimum[axis] = Math.min(minimum[axis], value);
      maximum[axis] = Math.max(maximum[axis], value);
    }
  }
  return { minimum, maximum };
}

const boundsCache = new WeakMap();

// A part's bounds are read again only when its matrix changed.
function cachedBounds(part) {
  const cached = boundsCache.get(part);
  if (cached && cached.matrix.every((value, index) => value === part.matrix[index])) {
    return cached.bounds;
  }
  const bounds = partBounds(part);
  boundsCache.set(part, { matrix: Float32Array.from(part.matrix), bounds });
  return bounds;
}

/**
 * The water body of a set of parts, or null: the largest flat part with the water tag sets the level (its top) and the optics.
 * A water mesh that is not flat (a stream following the terrain) has no single level, so it sets none.
 */
export function findWaterBody(parts) {
  let best = null;
  for (const part of parts) {
    if (part.material.tag !== 'water') {
      continue;
    }
    const { minimum, maximum } = cachedBounds(part);
    const wider = Math.max(maximum[0] - minimum[0], maximum[2] - minimum[2]);
    const footprint = (maximum[0] - minimum[0]) * (maximum[2] - minimum[2]);
    const flat = wider > 0 && maximum[1] - minimum[1] <= wider * WATER_MAXIMUM_THICKNESS_RATIO;
    if (flat && (!best || footprint > best.footprint)) {
      best = { footprint, level: maximum[1], material: part.material, refractive: part.material.alphaMode === 'blend' };
    }
  }
  if (!best) {
    return null;
  }
  const { absorption, turbidity } = resolveWaterMaterial(best.material);
  return { level: best.level, absorption, turbidity, refractive: best.refractive, caustics: best.material.caustics ?? null };
}

const waterLocations = new WeakMap();
// The texture unit that holds the opaque scene for refraction (the splat mask unit: a scene with water and a splat ground never
// draws both in one batch).
const WATER_SCENE_UNIT = 14;

// The opaque scene is resolved into the renderer's frame texture the first time a blended batch of the frame draws, as the liquid
// pass does, and the water samples it.
function resolveOpaqueScene(renderer, locations) {
  const context = renderer.context;
  const { width, height } = renderer.canvas;
  context.bindFramebuffer(context.READ_FRAMEBUFFER, renderer.multisampleFramebuffer);
  context.bindFramebuffer(context.DRAW_FRAMEBUFFER, renderer.resolveFramebuffer);
  context.blitFramebuffer(0, 0, width, height, 0, 0, width, height, context.COLOR_BUFFER_BIT, context.NEAREST);
  context.bindFramebuffer(context.FRAMEBUFFER, renderer.multisampleFramebuffer);
  context.activeTexture(context.TEXTURE0 + WATER_SCENE_UNIT);
  context.bindTexture(context.TEXTURE_2D, renderer.frameTexture);
  context.uniform1i(locations.scene, WATER_SCENE_UNIT);
}

function bindWaterBody(renderer) {
  if (!renderer.shaderFeatures?.has('water')) {
    return;
  }
  const context = renderer.context;
  let locations = waterLocations.get(renderer);
  if (locations?.program !== renderer.program) {
    locations = { program: renderer.program, body: context.getUniformLocation(renderer.program, 'waterBody'), absorption: context.getUniformLocation(renderer.program, 'waterAbsorption'), scene: context.getUniformLocation(renderer.program, 'waterScene'), caustics: context.getUniformLocation(renderer.program, 'waterCaustics'), resolved: false };
    waterLocations.set(renderer, locations);
  }
  const waterParts = renderer.batches.flatMap(batch => (batch.parts[0].material.tag === 'water' ? batch.parts : []));
  const body = findWaterBody(waterParts);
  // The mirror and the render passes skip the underwater look: the mirror is clipped above the water, a pass reads raw surface data.
  const active = Boolean(body) && !renderer.renderingPass && !renderer.mirrorCulling;
  // Refraction needs the frame texture, so it is off for a transparent canvas, whose alpha is the picture's own.
  const refracts = active && body.refractive && !renderer.transparent && !renderer.benchmark && Boolean(renderer.frameTexture);
  context.uniform4f(locations.body, active ? body.level : 0, active ? body.turbidity : 0, active ? 1 : 0, refracts ? 1 : 0);
  context.uniform4f(locations.caustics, ...waterCausticsUniform(active ? body.caustics : null));
  context.uniform3f(locations.absorption, ...(active ? body.absorption : [0, 0, 0]));
  if (!context.isEnabled(context.BLEND)) {
    locations.resolved = false;
  } else if (refracts && !locations.resolved) {
    resolveOpaqueScene(renderer, locations);
    locations.resolved = true;
  }
}

const previousBind = layerTextureSupport.bind;
layerTextureSupport.bind = (renderer, mapState, layerState, batch) => {
  previousBind?.(renderer, mapState, layerState, batch);
  bindWaterBody(renderer);
};

// Wind for the foliage (4) and grass (7) tags, shared by the colour and shadow vertex shaders so both
// move identically. It depends only on local position, the card's uv, world position and time.
// The slow sway grows with height and with distance from the model's vertical axis (branch tips swing
// more than the crown centre) but is capped, because bark never moves and leaves must stay near their twigs.
// uv.y is 1 at a leaf's base and 0 at its tip, which drives the faster flutter.

// The GLSL of the world materials: water, foliage, grass, terrain, moss, fire and smoke. A renderer with a part of one of those
// tags (or with moss) needs this module; any other renderer never carries it. shaders.js splices each block at its slot:
// worldFunctions (the noise and moss masks), worldSurface (the surface changes), worldLight (extra light), worldAfterEmission
// (water's reflection) and worldFinal (fire and smoke, which replace the lit colour). Other optional features can use the
// same slots, or stub them out in shaders.js, to leave their code out of renderers that do not draw them.
export const worldMaterialSlots = {
  // The water body (level, turbidity, 1 when a flat water part sets one) and its absorption per metre, sent by bindWaterBody.
  // Shadow of a surface under murky water: the classic shadow map read over a wider disc. A cascaded map is read through
  // its own macro and keeps its filter.
  declarations: `uniform vec4 waterBody;
${causticsDeclarations}
uniform vec4 waterRampHead;
uniform vec3 waterRampWeights;
uniform vec2 waterRampHeightRange;
uniform vec4 waterRampCrest;
uniform vec3 waterRampColors[5];
uniform vec3 waterAbsorption;
uniform sampler2D waterScene;
uniform mat4 viewProjection;
// The frame texture holds the picture as it leaves the shader: scaled by exposure and, outside HDR, tone mapped and encoded.
// The stylized ramp: waterRampHead is (colour count, 1 for soft steps, 0, 0) and waterRampWeights the height, facing and sun weights.
// A hard ramp has a one pixel edge (fwidth) so a band does not crawl.
vec3 waterRampTone(float height, float facing, float sun) {
  float count = waterRampHead.x;
  float heightFraction = clamp((height - waterRampHeightRange.x) / (waterRampHeightRange.y - waterRampHeightRange.x), 0.0, 1.0);
  float driven = dot(waterRampWeights, vec3(heightFraction, facing, sun)) / dot(waterRampWeights, vec3(1.0));
  if (waterRampHead.y > 0.5) {
    float blendPosition = clamp(driven, 0.0, 1.0) * (count - 1.0);
    int lower = int(floor(min(blendPosition, count - 1.001)));
    return mix(waterRampColors[lower], waterRampColors[lower + 1], blendPosition - float(lower));
  }
  float position = clamp(driven, 0.0, 0.9999) * count;
  int band = int(floor(position));
  float edge = smoothstep(0.0, max(fwidth(position), 0.0001), fract(position));
  return band == 0 ? waterRampColors[0] : mix(waterRampColors[band - 1], waterRampColors[band], edge);
}

vec3 waterDecode(vec3 encoded) {
  vec3 linear = encoded;
  if (hdrEnabled < 0.5) {
    vec3 curve = pow(encoded, vec3(2.2));
    vec3 quadratic = 2.51 - 2.43 * curve;
    vec3 slope = 0.03 - 0.59 * curve;
    linear = (-slope + sqrt(max(slope * slope + 4.0 * quadratic * 0.14 * curve, 0.0))) / (2.0 * quadratic);
  }
  return linear / max(exposure, 0.0001);
}
// Refraction (n = 1.33): the view ray bends at the surface and meets the bed at the depth the opaque pass left in the alpha
// channel of everything below the level. The picture around that point is blurred by turbidity times depth. Where nothing
// below the level is seen, the water keeps its own colour (fallback).
vec3 refractedBackground(vec3 fallback, vec3 surfacePosition, vec3 normal, vec3 viewDirection) {
  vec2 size = vec2(textureSize(waterScene, 0));
  vec3 bent = refract(-viewDirection, normal, 0.7519);
  vec2 uv = gl_FragCoord.xy / size;
  float depth = 0.0;
  for (int pass = 0; pass < 2; pass++) {
    float stored = textureLod(waterScene, uv, 0.0).a;
    depth = stored < 0.999 ? (stored - 0.5) / 0.498 * 8.0 : 0.0;
    vec4 clip = viewProjection * vec4(surfacePosition + bent * (depth / max(-bent.y, 0.1)), 1.0);
    uv = clip.xy / clip.w * 0.5 + 0.5;
  }
  float radius = min(waterBody.y * depth * 0.02 * size.y, 48.0);
  vec3 seenColor = vec3(0.0);
  float seen = 0.0;
  for (int tap = 0; tap < 16; tap++) {
    float angle = float(tap) * 2.39996;
    vec2 offset = vec2(cos(angle), sin(angle)) * sqrt((float(tap) + 0.5) / 16.0) * radius / size;
    vec2 position = uv + offset;
    vec4 sampled = textureLod(waterScene, position, 0.0);
    // A lookup that leaves the picture has nothing to show, so the water keeps its own colour there.
    float inside = all(greaterThan(position, vec2(0.0))) && all(lessThan(position, vec2(1.0))) ? 1.0 : 0.0;
    float below = sampled.a < 0.999 ? inside : 0.0;
    seenColor += waterDecode(sampled.rgb) * below;
    seen += below;
  }
  // Average only the taps that saw something below the water: a tap past the bed edge must not pull the blur toward the water colour.
  return seen > 0.5 ? seenColor / seen : fallback;
}
#ifndef shadowVisibility
float softShadowVisibility(vec3 normal, float radiusTexels) {
  vec3 projected = shadowPosition.xyz / shadowPosition.w * 0.5 + 0.5;
  if (projected.z > 1.0 || projected.z < 0.0 || any(lessThan(projected.xy, vec2(0.0))) || any(greaterThan(projected.xy, vec2(1.0)))) return 1.0;
  float cosine = max(dot(normal, normalize(lightDirection)), 0.05);
  float bias = shadowBiasPerSlope * clamp(sqrt(1.0 - cosine * cosine) / cosine, 0.25, 4.0);
  vec2 texel = 1.0 / vec2(textureSize(shadowMap, 0));
  float lit = 0.0;
  for (int tap = 0; tap < 12; tap++) {
    float angle = float(tap) * 2.39996;
    vec2 offset = vec2(cos(angle), sin(angle)) * sqrt((float(tap) + 0.5) / 12.0) * radiusTexels;
    lit += texture(shadowMap, vec3(projected.xy + offset * texel, projected.z - bias));
  }
  return lit / 12.0;
}
#endif
// Sunlight under water: in-scatter lifts the shadow (the water scatters light into it) and widens its edge, both with
// turbidity times the depth of the column above the surface.
float underwaterVisibility(float visibility, vec3 normal, float depth) {
  float scattering = waterBody.y * depth;
  float filtered = visibility;
#ifndef shadowVisibility
  if (scattering > 0.03) filtered = softShadowVisibility(normal, 1.5 + min(scattering * 6.0, 8.0));
#endif
  return filtered;
}
`,
  worldVisibility: `  float waterDepth = 0.0;
  vec3 waterTransmittance = vec3(1.0);
  vec3 waterSunTransmittance = vec3(1.0);
  float waterScatterShare = 0.0;
  float waterShadowVisibility = 1.0;
  if (TAG_WATER) {
    // Only the light that enters the water and comes back is shadowed, and most of what the eye sees comes from deeper than
    // the shadow reaches, so a shadow on the surface is faint. The reflection mixed in later never sees the shadow.
    visibility = mix(visibility, 1.0, 0.7 + 0.2 * waterBody.y);
  } else if (waterBody.z > 0.5 && worldPosition.y < waterBody.x) {
    waterDepth = waterBody.x - worldPosition.y;
    waterTransmittance = exp(-waterAbsorption * waterDepth);
    visibility = underwaterVisibility(visibility, normal, waterDepth);
    waterShadowVisibility = visibility;
    // The sun reaches the bed along the refracted ray, depth / cos(theta) with Snell n = 1.33, so its leg is absorbed over a longer path than the eye's.
    float sunSine = sqrt(max(1.0 - pow(normalize(lightDirection).y, 2.0), 0.0)) / 1.33;
    waterSunTransmittance = exp(-(waterAbsorption + 0.9 * waterBody.y * (1.0 - waterBody.y)) * waterDepth / sqrt(1.0 - sunSine * sunSine));
    waterScatterShare = waterBody.y * (1.0 - exp(-0.4 * waterBody.y * waterDepth));
    if (waterCaustics.z > 0.0) waterSunTransmittance *= causticGain(worldPosition, waterDepth);
  }
  vec3 keyColor = keyColor * waterSunTransmittance;
`,
  // Spliced into the colour and shadow vertex shaders by shaders.js.
  worldVertexWind: `
// Grass bends by how far up the blade a vertex is (uv.y is 1 at the root), so it ignores terrain height.
// Gusts roll across the field as a travelling wave along the wind direction, like the rolling bands in a meadow.
// windHeading turns the wind about the vertical axis, in radians; 0 is the default heading toward +x.
uniform float windHeading;

vec3 grassWind(vec3 worldPoint, vec2 leafUv, float seconds, float strength) {
  float tip = clamp(1.0 - leafUv.y, 0.0, 1.0);
  float bendWeight = tip * tip;
  float headingCos = cos(windHeading);
  float headingSin = sin(windHeading);
  vec2 windDirection = vec2(0.94 * headingCos - 0.34 * headingSin, 0.94 * headingSin + 0.34 * headingCos);
  float along = dot(worldPoint.xz, windDirection);
  float gust = 0.5 + 0.5 * sin(along * 0.32 - seconds * 1.7 + 2.0 * sin(worldPoint.x * 0.05 - worldPoint.z * 0.04 + seconds * 0.23));
  float push = (0.3 + 0.7 * gust * gust) * strength;
  float flutter = sin(seconds * 4.7 + worldPoint.x * 2.3 + worldPoint.z * 1.9) * strength;
  vec2 offset = windDirection * (push * 0.42 + flutter * 0.05) + vec2(-windDirection.y, windDirection.x) * flutter * 0.04;
  return vec3(offset.x, -push * 0.14, offset.y) * bendWeight;
}

vec3 windOffset(vec3 localPosition, vec3 worldPoint, vec2 leafUv, float surfaceTag, float seconds, float strength) {
  // Grass without UVs (uv is (-1, -1)) has no blade coordinate, so it keeps the height-based sway below.
  if (surfaceTag == 7.0 && leafUv.x > -0.5) return grassWind(worldPoint, leafUv, seconds, strength);
  if (surfaceTag != 4.0 && surfaceTag != 7.0) return vec3(0.0);
  float heightReach = min(max(localPosition.y + 0.5, 0.0), 2.5);
  float branchReach = 1.0 + 0.3 * min(length(localPosition.xz), 3.0);
  float sway = sin(seconds * 1.2 + worldPoint.z * 0.31 + worldPoint.x * 0.17) * strength * 0.10 * heightReach * branchReach;
  float tip = clamp(1.0 - leafUv.y, 0.0, 1.0);
  float flutter = sin(seconds * 3.1 + worldPoint.x * 1.7 + worldPoint.z * 1.3 + localPosition.y * 2.0) * strength * 0.08 * tip;
  vec2 heading = vec2(cos(windHeading), sin(windHeading));
  vec2 push = heading * (sway + flutter) + vec2(-heading.y, heading.x) * (flutter * 0.6);
  return vec3(push.x, 0.0, push.y);
}
`,
  worldFunctions: `float terrainHash(vec2 position) {
  vec3 seed = fract(vec3(position.xyx) * 0.1031);
  seed += dot(seed, seed.yzx + 33.33);
  return fract((seed.x + seed.y) * seed.z);
}

// Value noise and its analytic gradient avoid extra texture fetches for sand relief.
vec3 terrainNoise(vec2 position) {
  vec2 cell = floor(position);
  vec2 fraction = fract(position);
  vec2 blend = fraction * fraction * (3.0 - 2.0 * fraction);
  vec2 derivative = 6.0 * fraction * (1.0 - fraction);
  float lowerLeft = terrainHash(cell);
  float lowerRight = terrainHash(cell + vec2(1.0, 0.0));
  float upperLeft = terrainHash(cell + vec2(0.0, 1.0));
  float upperRight = terrainHash(cell + vec2(1.0, 1.0));
  float lower = mix(lowerLeft, lowerRight, blend.x);
  float upper = mix(upperLeft, upperRight, blend.x);
  return vec3(mix(lower, upper, blend.y),
    mix(lowerRight - lowerLeft, upperRight - upperLeft, blend.y) * derivative.x,
    (upper - lower) * derivative.y);
}

// Wind ripples the mesh is too coarse to carry: eight travelling waves from 3 m down to 0.15 m, about 0.15 rms slope in all, which
// is what breaks a sun glint into facets. The wavelengths step by an irrational ratio and the directions by the golden angle, and
// each wave's phase and strength drift with slow noise, so no pair of waves repeats the same blob pattern over the water. A wave
// stays whole while a pixel is under a fifth of its length and is gone at half (two pixels per wave, the limit of one sample per
// pixel), so far water does not shimmer but keeps every wave a pixel can still show; the slope variance the faded waves
// took with them comes back as lostVariance, to widen the glint instead.
vec2 waterDetailSlope(vec2 position, float footprint, out float lostVariance) {
  vec2 slope = vec2(0.0);
  lostVariance = 0.0;
  float wavenumber = 2.1;
  float angle = 0.4;
  for (int index = 0; index < 8; index++) {
    float visible = 1.0 - smoothstep(0.2, 0.5, footprint * wavenumber / 6.2831853);
    vec2 direction = vec2(cos(angle), sin(angle));
    float drift = terrainNoise(position * wavenumber * 0.09 + float(index) * 9.17).x - 0.5;
    float strength = 0.15 + 1.7 * terrainNoise(position * wavenumber * 0.06 + float(index) * 23.9 + 4.0).x;
    float phase = dot(position, direction) * wavenumber + time * sqrt(9.81 * wavenumber) + float(index) * 1.7 + drift * 5.0;
    float amplitude = 0.085 * pow(wavenumber / 2.1, -0.3) * strength;
    slope += direction * cos(phase) * amplitude * visible;
    lostVariance += 0.5 * amplitude * amplitude * (1.0 - visible);
    wavenumber *= 1.7320508;
    angle += 2.399963;
  }
  return slope;
}
`,
  worldMossFunction: `// Moss is its own material over the base, not a tint: fully rough, a soft sheen at grazing angles and light that wraps
// through it. Two masks, as in offline moss shading: a sharp one decides where moss is shaded, and a blurred one lifts
// it into cushions, so its relief never turns into needles. Coverage favours up-facing surfaces.
void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMask) {
  float facing = smoothstep(0.1, 0.7, normal.y);
  vec2 position = worldPosition.xz * 6.0 + worldPosition.y * vec2(2.3, -1.7);
  float patches = terrainNoise(position).x * 0.6 + terrainNoise(position * 2.7 + 5.1).x * 0.4;
  float threshold = 1.0 - amount;
  sharpMask = facing * smoothstep(threshold - 0.035, threshold + 0.035, patches);
  softMask = facing * smoothstep(threshold - 0.22, threshold + 0.18, patches);
}

`,
  worldSurface: `  float waterFoam = 0.0;
  vec3 waterRampRadiance = vec3(0.0);
  float waterRampOwns = 0.0;
  float waterLostVariance = 0.0;
  if (TAG_WATER) {
    // Small ripples tilt the surface's own normal, so a sea mesh keeps its waves; a flat sheet (normal up) gets the same ripples as before.
    vec3 rippleTilt = vec3(-cos(worldPosition.x * 1.4 + time * 0.8) * 0.035, 0.0, -cos(worldPosition.z * 1.8 - time) * 0.036);
    float radius = length(worldPosition.xz - waterRipple.xz);
    float age = time - rippleTime;
    float wave = sin(radius * 11.0 - age * 8.0) * exp(-abs(radius - age * 1.4) * 1.5) * exp(-age * 0.7) * step(0.0, age);
    rippleTilt.xz += normalize(worldPosition.xz - waterRipple.xz + 0.001) * wave * 0.07;
    float footprint = length(fwidth(worldPosition.xz));
    vec2 detailSlope = waterDetailSlope(worldPosition.xz, footprint, waterLostVariance);
    rippleTilt.xz += detailSlope;
    vec3 crestNormal = normal;
    normal = normalize(normal + rippleTilt);
    // The body is deeper at grazing angles; the foam mask (the ocean's, stored as 1 - foam in the sky visibility channel) turns it white.
    // Foam: the mask is the heavy half of the ocean's foam (about 5% of a rough sea). Three octaves of noise stretched along the crest
    // make lace: the core stays bright and solid, the edge dissolves into holes and thin veins, and it grows less opaque outwards.
    // The threshold has a soft band at least one pixel wide (fwidth), so the edge is smooth and does not follow the mesh triangles.
    vec2 crestAcross = normalize(crestNormal.xz + vec2(0.0001));
    vec2 crestAlong = vec2(-crestAcross.y, crestAcross.x);
    vec2 crestPosition = vec2(dot(worldPosition.xz, crestAlong), dot(worldPosition.xz, crestAcross));
    float broadLace = terrainNoise(crestPosition * vec2(0.45, 2.4)).x;
    float midLace = terrainNoise(crestPosition * vec2(1.3, 6.5) + 7.3).x;
    float fineLace = terrainNoise(crestPosition * vec2(3.1, 14.0) + 3.9).x;
    float lace = broadLace * 0.5 + midLace * 0.3 + fineLace * 0.2;
    float foamMask = clamp(2.0 * (1.0 - vertexSkyVisibility) - 1.0, 0.0, 1.0);
    float foamDensity = foamMask * 1.25 + (lace - 0.5) * 0.9;
    float foamBand = 0.13 + 1.5 * fwidth(foamDensity);
    float foamBody = smoothstep(0.5 - foamBand, 0.5 + foamBand, foamDensity) * smoothstep(0.03, 0.25, foamMask);
    float foamVeins = pow(1.0 - abs(2.0 * midLace - 1.0), 3.0) * smoothstep(0.45, 0.9, foamMask) * (1.0 - foamBody) * 0.32;
    waterFoam = max(foamBody * mix(0.5, 1.0, smoothstep(0.3, 0.95, foamMask)) * (0.78 + 0.22 * smoothstep(0.25, 0.75, fineLace * 0.6 + midLace * 0.4)), foamVeins);
    float grazing = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.0);
    color = mix(color, vec3(0.0137, 0.147, 0.195), grazing * 0.85);
    color = mix(color, vec3(0.92, 0.95, 0.97) * (0.68 + 0.32 * (fineLace * 0.5 + midLace * 0.5)), waterFoam);
    roughness = mix(0.16, 0.8, waterFoam);
    if (waterRampHead.x > 0.5) {
      float rampSun = clamp(dot(normal, normalize(lightDirection)), 0.0, 1.0);
      vec3 rampTone = waterRampTone(worldPosition.y, 1.0 - max(dot(normal, viewDirection), 0.0), rampSun);
      float crestEdge = waterRampHead.y > 0.5 ? 0.15 : max(1.5 * fwidth(foamMask), 0.0001);
      float crestAmount = waterRampCrest.w * smoothstep(0.2 - crestEdge, 0.2 + crestEdge, foamMask);
      waterRampRadiance = waterRampRadianceFor(mix(rampTone, waterRampCrest.rgb, crestAmount));
      waterRampOwns = 1.0;
    }
  }
  if (CANOPY_TAG) {
    float leaves = sin(worldPosition.x * 13.0 + sin(worldPosition.y * 9.0)) * sin(worldPosition.z * 11.0 - worldPosition.y * 5.0);
    color *= 0.78 + leaves * 0.16;
    normal = normalize(normal + vec3(sin(worldPosition.z * 12.0), sin(worldPosition.x * 9.0), cos(worldPosition.y * 11.0)) * 0.06);
  }
  if (TAG_TERRAIN) {
    vec2 terrainPosition = worldPosition.xz + worldPosition.y * vec2(0.31, 0.43);
    float footprint = max(fwidth(terrainPosition.x), fwidth(terrainPosition.y));
    vec3 broad = terrainNoise(terrainPosition * 0.32);
    vec3 ridges = terrainNoise(terrainPosition * 3.2 + vec2(5.2, 11.7));
    vec3 grains = terrainNoise(terrainPosition * 32.0 + vec2(17.1, 4.3));
    float ridgeWeight = 1.0 - smoothstep(0.25, 0.8, footprint * 3.2);
    float grainWeight = 1.0 - smoothstep(0.2, 0.7, footprint * 32.0);
    float ridgeColor = 1.0 - abs(ridges.x * 2.0 - 1.0);
    color *= 0.82 + broad.x * 0.26 + (ridgeColor - 0.5) * 0.12 * ridgeWeight + (grains.x - 0.5) * 0.1 * grainWeight;
    vec2 relief = ridges.yz * 0.08 * ridgeWeight + grains.yz * 0.11 * grainWeight;
    vec3 perturbation = vec3(-relief.x, 0.0, -relief.y);
    normal = normalize(normal + perturbation - normal * dot(perturbation, normal));
    roughness = clamp(roughness + (grains.x - 0.5) * 0.06 * grainWeight, 0.075, 1.0);
  }
  if (USES_MOSS) {
    float mossSoft;
    mossMasks(normal, materialMoss.x, mossCover, mossSoft);
    float mossFootprint = length(fwidth(worldPosition));
    vec3 cushion = terrainNoise(worldPosition.xz * 40.0 + worldPosition.y * 13.0);
    float cushionDetail = 1.0 - smoothstep(0.004, 0.03, mossFootprint);
    vec3 cushionTilt = vec3(-cushion.y, 0.0, -cushion.z) * 0.07 * mossSoft * cushionDetail;
    normal = normalize(normal + cushionTilt - normal * dot(cushionTilt, normal));
    mossTone = materialMoss.yzw * (0.7 + 0.6 * cushion.x);
    color = mix(color, mossTone, mossCover);
    roughness = mix(roughness, 1.0, mossCover);
    metallic = mix(metallic, 0.0, mossCover);
  }
`,
  worldLight: `  if (CANOPY_TAG) radiance += color * max(dot(gl_FrontFacing ? -normal : normal, normalize(lightDirection)), 0.0) * 0.5 * keyResponse * mix(visibility, 1.0, 0.7);
  if (mossCover > 0.001) {
    float sheen = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.0);
    float wrap = max(dot(normal, normalize(lightDirection)) + 0.5, 0.0) / 1.5;
    radiance += mossTone * (sheen * 0.8 + wrap * 0.35) * keyResponse * visibility * mossCover;
  }
  if (TAG_GRASS) {
    // Sun through thin blades: they glow yellow-green when the camera looks toward the light, most at the thin tips
    // (uv.y runs 1 at the root to 0 at the tip; grass without UVs gets a middle value).
    float towardSun = pow(max(dot(-viewDirection, normalize(lightDirection)), 0.0), 3.0);
    float thinness = textureUV.x > -0.5 ? 1.0 - textureUV.y * 0.8 : 0.6;
    radiance += color * vec3(1.1, 1.25, 0.55) * towardSun * thinness * 1.4 * keyResponse * visibility;
  }
`,
  worldAfterEmission: `  if (waterDepth > 0.0) {
    // The bed's light reaches the eye through the column, dimmed; the water adds the daylight it scattered toward the eye (clear water a little, murky water more), so deep objects fade into the water colour instead of going black.
    vec3 scatteredLight = (keyColor * max(normalize(lightDirection).y, 0.0) * 0.1 + vec3(0.04) * ambientIntensity) * exp(-waterAbsorption * 1.5);
    radiance = radiance * waterTransmittance + scatteredLight * (vec3(1.0) - waterTransmittance) * (0.25 + waterBody.y);
    // Murky water scatters sunlight toward the eye from the column above the bed, and the post shadows that column too, so a shadow keeps a floor of contrast at depth (Cycles keeps about a quarter at 4 m in a river). It never subtracts: the lit side only gains.
    radiance += color * keyResponse / max(waterSunTransmittance, vec3(0.0001)) * max(dot(normal, normalize(lightDirection)), 0.0) * waterShadowVisibility * waterScatterShare * 3.4 * exp(-waterAbsorption);
  }
  if (TAG_WATER) {
    // Fresnel (Schlick, water F0 0.02) of the sky or environment the surface mirrors; foam is rough and reflects little.
    float cosine = max(dot(normal, viewDirection), 0.0);
    float reflectivity = (0.02 + 0.98 * pow(1.0 - cosine, 5.0)) * (1.0 - waterFoam);
    vec3 mirrorDirection = reflect(-viewDirection, normal);
    mirrorDirection.y = max(mirrorDirection.y, 0.02);
    vec3 skyColor = ENVIRONMENT_ENABLED ? surroundingsColor(mirrorDirection, 0.05) : mix(vec3(0.12, 0.24, 0.28), vec3(0.40, 0.63, 0.78), clamp(mirrorDirection.y, 0.0, 1.0)) * daylight;
    radiance = mix(radiance * 0.6 + color * ambientIntensity * daylight * 1.7, skyColor * ambientIntensity, clamp(reflectivity, 0.0, 1.0));
    // A ramp owns the colour: no sky reflection, so the tones stay flat; foam and the sun glint still add on top.
    if (waterRampOwns > 0.5) radiance = waterRampRadiance * (1.0 - waterFoam);
    // Sun glint: a narrow lobe around the mirror direction, the width of open water slopes, bright enough to bloom.
    vec3 halfVector = normalize(normalize(lightDirection) + viewDirection);
    float glintSharpness = 1.0 / (1.0 / 500.0 + 0.35 * waterLostVariance);
    float glintShape = pow(max(dot(normal, halfVector), 0.0), glintSharpness);
    float glintFresnel = 0.02 + 0.98 * pow(1.0 - max(dot(halfVector, viewDirection), 0.0), 5.0);
    radiance += vec3(1.0, 0.9, 0.7) * glintShape * (0.5 + 40.0 * glintFresnel) * 6.0 * keyResponse * (1.0 - waterFoam);
    radiance += vec3(0.85, 0.9, 0.95) * waterFoam * (max(dot(normal, normalize(lightDirection)), 0.0) * keyResponse + 0.35 * daylight * ambientIntensity);
    if (waterBody.w > 0.5 && alphaMode > 1.5) {
      // Blended water draws its own background: the opaque scene refracted and blurred, not the one behind it unbent.
      radiance = radiance * alpha + refractedBackground(radiance, worldPosition, normal, viewDirection) * (1.0 - alpha);
      alpha = 1.0;
    }
  }
`,
  // The ramp colours are display colours: the radiance a ramp writes is the one the view transform maps back to the colour asked for.
  libraries: `// Radiance that exposure and the view transform turn into the display colour whose sRGB encoding is the asked linear colour.
// Newton steps on the renderer's own curve (ACES, AgX or Neutral), so a ramp stop given as a hex shows as that hex.
vec3 waterRampRadianceFor(vec3 asked) {
  vec3 encoded = mix(asked * 12.92, 1.055 * pow(max(asked, vec3(0.0031308)), vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), asked));
  vec3 target = pow(clamp(encoded, 0.0, 1.0), vec3(2.2));
  vec3 guess = target;
  for (int iteration = 0; iteration < 24; iteration++) {
    vec3 here = toneMap(guess);
    vec3 slope = (toneMap(guess + 0.002) - here) / 0.002;
    guess = max(guess + (target - here) / max(slope, vec3(0.05)), vec3(0.0));
  }
  return guess / max(exposure, 0.0001);
}
`,
  worldFinal: `  // A ramp stands clear of the distance haze, which would shift the colour it was asked to show: a local density of 0 shadows the uniform.
  float fogDensity = waterRampOwns > 0.5 ? 0.0 : fogDensity;
  if (waterDepth > 0.0 && waterBody.w > 0.5 && alphaMode < 0.5) alpha = 0.5 + 0.498 * clamp(waterDepth / 8.0, 0.0, 1.0);
  if (TAG_FIRE) {
    float turbulence = sin(worldPosition.x * 3.0 + time * 4.0) * sin(worldPosition.y * 4.2 - time * 3.0) * sin(worldPosition.z * 3.7);
    float heat = pow(clamp(0.55 + turbulence * 0.5 - explosionProgress * 0.12, 0.0, 1.0), 3.0);
    radiance = mix(vec3(0.22, 0.003, 0.0002), vec3(8.0, 2.8, 0.15), heat) * max(0.2, surface.z * 0.10);
  }
  if (TAG_SMOKE) {
    float turbulence = sin(worldPosition.x * 2.0 + time) * sin(worldPosition.y * 3.3 - time * 0.6);
    radiance = color * (0.22 + turbulence * 0.12) + vec3(0.35, 0.05, 0.005) * max(0.0, 1.0 - explosionProgress) * max(0.0, -normal.y);
  }
`,
};

registerShaderFeatureCode('worldMaterials', worldMaterialSlots);

/**
 * Turns the foliage and grass wind to `radians` about the vertical axis (0 is the default heading toward +x).
 * The renderer never sets windHeading, so the value stays on the main and shadow programs between frames; call this
 * before each render, because a rebuilt program starts at 0. A turned heading marks the shadow map stale.
 */
export function applyWindHeading(renderer, radians) {
  const context = renderer.context;
  for (const program of [renderer.program, renderer.depthProgram]) {
    const location = context.getUniformLocation(program, 'windHeading');
    if (!location) continue;
    context.useProgram(program);
    context.uniform1f(location, radians);
  }
  if (renderer.windHeading !== radians) renderer.shadowsDirty = true;
  renderer.windHeading = radians;
}

const waterRampLocations = new WeakMap();
const NO_RAMP = Object.freeze({ colors: [], drivers: { height: 1, facing: 0, sun: 0 }, heightRange: [-1, 1], steps: 'hard' });
const RAMP_COLOR_SLOTS = WATER_RAMP_COLOR_COUNT[1];

/** Sends the ramp of a water batch; a batch without one sends a colour count of 0, which leaves the water as it was. */
function bindWaterRamp(renderer, batch) {
  if (!renderer.shaderFeatures?.has('water')) {
    return;
  }
  let locations = waterRampLocations.get(renderer);
  if (locations?.program !== renderer.program) {
    const locate = name => renderer.context.getUniformLocation(renderer.program, name);
    locations = { program: renderer.program, head: locate('waterRampHead'), weights: locate('waterRampWeights'), heightRange: locate('waterRampHeightRange'), crest: locate('waterRampCrest'), colors: locate('waterRampColors') };
    waterRampLocations.set(renderer, locations);
  }
  const ramp = batch.parts[0].material.waterRamp ?? NO_RAMP;
  const context = renderer.context;
  context.uniform4f(locations.head, ramp.colors.length, ramp.steps === 'soft' ? 1 : 0, 0, 0);
  context.uniform3f(locations.weights, ramp.drivers.height, ramp.drivers.facing, ramp.drivers.sun);
  context.uniform2f(locations.heightRange, ...ramp.heightRange);
  context.uniform4f(locations.crest, ...(ramp.crestTint?.color ?? [0, 0, 0]), ramp.crestTint?.strength ?? 0);
  const padding = Array.from({ length: RAMP_COLOR_SLOTS - ramp.colors.length }, () => [0, 0, 0]);
  context.uniform3fv(locations.colors, new Float32Array([...ramp.colors, ...padding].flat()));
}

const bindBeforeRamp = layerTextureSupport.bind;
layerTextureSupport.bind = (renderer, mapState, layerState, batch) => {
  bindBeforeRamp?.(renderer, mapState, layerState, batch);
  bindWaterRamp(renderer, batch);
};