@3driseai/3drise-viewer 0.1.29 → 0.1.31

package/dist/shaders/glsl/terrainCore.glsl.d.ts

@@ -26,8 +26,14 @@
  *    per octave, nine octaves, several evaluations per pixel puts it into the
  *    billions of transcendentals per frame.
  */
-/** Every uniform the height field and the shading read. */
-export declare const terrainUniforms = "\nuniform int   u_terrainType;\n\nuniform float u_elevation;\nuniform float u_seaLevel;\nuniform float u_baseScale;      // 1 / featureSize\nuniform int   u_octaves;\nuniform float u_lacunarity;\nuniform float u_gain;\nuniform float u_ridge;\nuniform float u_warpStrength;\nuniform float u_warpScale;\nuniform float u_erosion;\nuniform float u_terraces;\nuniform float u_terraceSharp;\nuniform vec2  u_bearingDir;\nuniform float u_duneFreq;       // 2pi / duneWavelength\nuniform float u_duneAsym;\nuniform float u_plateau;\nuniform float u_valleyDepth;\nuniform float u_valleyWidth;\n\nuniform float u_cellSize;\nuniform float u_curvature;\n\n// surface\nuniform vec3  u_lowColor, u_midColor, u_rockColor, u_peakColor;\nuniform float u_slopeRockStart, u_slopeRockEnd;\nuniform float u_peakLevel, u_peakBlend, u_peakSlopeFalloff;\nuniform float u_macroVariation, u_macroScale;\nuniform float u_detailStrength, u_detailScale, u_detailFade;\nuniform float u_roughness, u_specular;\n\n// lighting. u_skyAmbient and u_groundAmbient come from useCloudSun through\n// applySunUniforms - the same objects that light the clouds. They are constant\n// across the frame, so computing them on the CPU rather than calling skyRadiance\n// per pixel removes an acos, a pow and three exps from every fragment.\nuniform vec3  u_skyAmbient;\nuniform vec3  u_groundAmbient;\nuniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;\nuniform float u_shadowDistance;\nuniform float u_fogDensity, u_exposure;\nuniform int   u_shadowSteps;\n\n// Ground textures. The far colour per layer is always set: the flat colour for an\n// untextured layer, the texture's own mean x tint for a textured one, so the\n// near-to-far fade has no colour jump.\nuniform vec3  u_tFar[4];\n#ifdef TERRAIN_TEXTURED\nuniform sampler2DArray u_tColor;    // albedo, sRGB\nuniform sampler2DArray u_tNormal;   // rgb tangent normal (GL), a surface height\nuniform sampler2DArray u_tOrm;      // r ambient occlusion, g roughness\nuniform vec4  u_tLayer[4];          // 1/tileSize, normalStrength, textured 0|1, -\nuniform vec3  u_tTint[4];           // layer colour / texture mean: the texture averages to the layer colour\nuniform vec4  u_tMeanC[4];          // per-array layer means, for the stochastic blend\nuniform vec4  u_tMeanN[4];\nuniform vec4  u_tMeanO[4];\nuniform float u_tDistance;\nuniform float u_tHeightBlend;\n#endif\n\n// A land object: a bounded patch of this field, placed by its object's transform.\n// Its \"terrain space\" is metres from the object's origin, unrotated, plus a seed\n// offset; height is above the object's base. See TerrainMaterial's patch vertex.\n#ifdef TERRAIN_PATCH\nuniform vec2  u_patchSize;      // footprint in metres (object scale x / z)\nuniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field\nuniform float u_edgeWidth;      // metres over which the land eases down to its base\nuniform vec3  u_camTerrain;     // the camera, in terrain space\nuniform float u_scaleY;         // object scale y: terrain metres = local y x this\nuniform float u_patchCell;      // metres per grid cell\n#define TERRAIN_CAM u_camTerrain\n#else\n#define TERRAIN_CAM cameraPosition\n#endif\n";
+/**
+ * The uniforms the height field and the sun-shadow march read — and nothing else,
+ * so another material (the ocean) can include the field without redeclaring its
+ * own u_curvature, u_exposure, u_roughness… GLSL refuses a uniform declared twice.
+ */
+export declare const terrainFormUniforms = "\nuniform int   u_terrainType;\n\nuniform float u_elevation;\nuniform float u_seaLevel;\nuniform float u_baseScale;      // 1 / featureSize\nuniform int   u_octaves;\nuniform float u_lacunarity;\nuniform float u_gain;\nuniform float u_ridge;\nuniform float u_warpStrength;\nuniform float u_warpScale;\nuniform float u_erosion;\nuniform float u_terraces;\nuniform float u_terraceSharp;\nuniform vec2  u_bearingDir;\nuniform float u_duneFreq;       // 2pi / duneWavelength\nuniform float u_duneAsym;\nuniform float u_plateau;\nuniform float u_valleyDepth;\nuniform float u_valleyWidth;\n\n// The analytic sun-shadow march (terrainShadow) - shared with the ocean, which\n// marches the same field to put headland shadows on the water.\nuniform float u_sunShadow, u_shadowSoftness;\nuniform float u_shadowDistance;\nuniform int   u_shadowSteps;\n\n// A land object: a bounded patch of this field, placed by its object's transform.\n// Its \"terrain space\" is metres from the object's origin, unrotated, plus a seed\n// offset; height is above the object's base. See TerrainMaterial's patch vertex.\n#ifdef TERRAIN_PATCH\nuniform vec2  u_patchSize;      // footprint in metres (object scale x / z)\nuniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field\nuniform float u_edgeWidth;      // metres over which the land eases down to its base\nuniform vec3  u_camTerrain;     // the camera, in terrain space\nuniform float u_scaleY;         // object scale y: terrain metres = local y x this\nuniform float u_patchCell;      // metres per grid cell\n#define TERRAIN_CAM u_camTerrain\n#else\n#define TERRAIN_CAM cameraPosition\n#endif\n";
+/** The terrain surface's own uniforms: shading, lighting, textures. */
+export declare const terrainSurfaceUniforms = "\nuniform float u_cellSize;\nuniform float u_curvature;\n\n// surface\nuniform vec3  u_lowColor, u_midColor, u_rockColor, u_peakColor;\nuniform float u_slopeRockStart, u_slopeRockEnd;\nuniform float u_peakLevel, u_peakBlend, u_peakSlopeFalloff;\nuniform float u_macroVariation, u_macroScale;\nuniform float u_detailStrength, u_detailScale, u_detailFade;\nuniform float u_roughness, u_specular;\n\n// lighting. u_skyAmbient and u_groundAmbient come from useCloudSun through\n// applySunUniforms - the same objects that light the clouds. They are constant\n// across the frame, so computing them on the CPU rather than calling skyRadiance\n// per pixel removes an acos, a pow and three exps from every fragment.\nuniform vec3  u_skyAmbient;\nuniform vec3  u_groundAmbient;\nuniform float u_ambient, u_bounce;\nuniform float u_fogDensity, u_exposure;\n\n// Ground textures. The far colour per layer is always set: the flat colour for an\n// untextured layer, the texture's own mean x tint for a textured one, so the\n// near-to-far fade has no colour jump.\nuniform vec3  u_tFar[4];\n#ifdef TERRAIN_TEXTURED\nuniform sampler2DArray u_tColor;    // albedo, sRGB\nuniform sampler2DArray u_tNormal;   // rgb tangent normal (GL), a surface height\nuniform sampler2DArray u_tOrm;      // r ambient occlusion, g roughness\nuniform vec4  u_tLayer[4];          // 1/tileSize, normalStrength, textured 0|1, -\nuniform vec3  u_tTint[4];           // layer colour / texture mean: the texture averages to the layer colour\nuniform vec4  u_tMeanC[4];          // per-array layer means, for the stochastic blend\nuniform vec4  u_tMeanN[4];\nuniform vec4  u_tMeanO[4];\nuniform float u_tDistance;\nuniform float u_tHeightBlend;\n#endif\n\n";
 /**
  * Gradient noise with an analytic derivative.
  *
@@ -70,7 +76,8 @@ export declare const terrainHeight = "\n#define TERRAIN_MOUNTAINS 0\n#define TER
  * The terminator itself stays per-pixel: `terrainLight` takes N·L from the
  * fragment's own normal, so only the CAST shadow is interpolated.
  */
-export declare const terrainShading = "\n/** 1 lit, 0 shadowed, soft in between. */\nfloat terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){\n  if (steps < 1 || u_sunShadow <= 0.0) return 1.0;\n  // Below the horizon there is nothing to shadow; the march would also walk\n  // downhill forever.\n  if (u_sunDir.y <= 0.015) return 1.0;\n  // A surface facing away from the sun is shadowed by definition, and marching\n  // from it only finds the ground it is already part of.\n  if (dot(n, u_sunDir) <= 0.0) return 0.0;\n\n  // Lift off the surface before starting, or every sample on a steep face - a\n  // terrace riser above all - reads its own ground as an occluder and the whole\n  // wall goes black in a grid of triangles. Start ON the offset surface and\n  // compare raw heights; subtracting the bias from the height difference instead\n  // makes the first sample fail on any slope tilted a few degrees from the sun.\n  float bias = max(lodCell, u_elevation * 0.003);\n  vec3 origin = p + n * bias;\n\n  float shadowLod = (1.0 / max(u_baseScale, 1e-9)) * 0.008;\n\n  float res = 1.0;\n  float t = bias * 3.0;\n  float maxT = (u_elevation * 2.5) / max(u_sunDir.y, 0.05);\n\n  for (int i = 0; i < 48; i++){\n    if (i >= steps || t > maxT) break;\n    vec3 sp = origin + u_sunDir * t;\n    // The occluder is sampled at the SHADING lod, coarsening with distance -\n    // never at a fixed coarse lod. Testing a fine surface point against a coarse\n    // height field puts the whole valley floor in shadow, because the coarse\n    // field sits above the fine one wherever the fine one has been cut down.\n    // Sampled MUCH coarser than the surface being shaded. A shadow does not need\n    // nine octaves: what casts a visible shadow is the landform, and marching the\n    // fine field costs the same nine octaves per step for detail that is below a\n    // pixel by the time it lands. Floored against the landform's own size, so the\n    // march runs about five octaves instead of nine wherever it starts.\n    float h = terrainOccluderAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));\n    float diff = sp.y - h;\n    res = min(res, u_shadowSoftness * diff / t);\n    if (res <= 0.0) return 0.0;\n    // Geometric growth: near the surface the occluder is metres away, at the end\n    // of the march it is kilometres, and a linear step wastes every sample at one\n    // end or the other. 1.7 rather than 1.42 so twelve steps actually reach maxT -\n    // at 1.42 the march ran out around 700 m and long shadows at low sun simply\n    // did not exist, which is a quality bug that happened to look like a cheap one.\n    t = t * 1.7 + bias;\n  }\n  return saturate(res);\n}\n\n/**\n * The shadow, faded out with distance and given a step budget that falls with it.\n *\n * The march is the most expensive thing left in the renderer, and past a few\n * kilometres it is buying nothing: aerial perspective has already washed most of\n * the contrast out of the ground, and a ridge shadow out there is a couple of\n * pixels wide. Skipping it entirely beyond u_shadowDistance drops the outer\n * clipmap rings - which are two thirds of the vertices - out of the march\n * completely, and the rings in between run four steps instead of fourteen.\n *\n * Faded rather than cut, or the cut-off would draw a visible circle on the ground.\n */\nfloat terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){\n  float fade = 1.0 - saturate(dist / max(u_shadowDistance, 1.0));\n  if (fade <= 0.002) return 1.0;\n  int steps = int(mix(4.0, float(u_shadowSteps), fade));\n  return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);\n}\n\n/**\n * Albedo.\n *\n * Rock is splatted by SLOPE, everything else by height. That ordering is the\n * whole trick: it means a cliff is bare rock whether it is in a valley or on a\n * summit, which is how real ground works and why height-only splatting always\n * reads as a painted contour map.\n */\n/**\n * Splat weights for the four layers, in layer order: low, mid, rock, peak.\n * Exactly the old colour mixes written as weights \u2014 low/mid by height, the peak\n * held back on steep ground (snow does not sit on a vertical face), rock by slope\n * and applied last, which is why a cliff reads as a cliff at any altitude.\n */\nvec4 terrainLayerWeights(float h01, float slope){\n  float m = smoothstep(0.05, 0.55, h01);\n  float p = saturate(smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6));\n  float r = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);\n  return vec4((1.0 - m) * (1.0 - p) * (1.0 - r), m * (1.0 - p) * (1.0 - r), r, p * (1.0 - r));\n}\n\n/** Large-scale variation. Without it a splat layer is one flat colour across\n *  kilometres, and the eye reads flat colour as untextured rather than as ground. */\nfloat terrainMacro(vec3 wp){\n  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;\n  return 1.0 + u_macroVariation * (macro - 0.5) * 2.0;\n}\n\n/** The far-field albedo: each layer's far colour by its weight. */\nvec3 terrainAlbedo(vec3 wp, vec4 w){\n  vec3 col = u_tFar[0] * w.x + u_tFar[1] * w.y + u_tFar[2] * w.z + u_tFar[3] * w.w;\n  return col * terrainMacro(wp);\n}\n\n/** High-frequency bump, well below the mesh resolution, faded out with distance\n *  so it never becomes a field of crawling pixels on the horizon. One evaluation:\n *  the noise carries its own derivative, so the three taps a finite difference\n *  would need are not. */\nvec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){\n  float fade = 1.0 - saturate(dist * u_detailFade);\n  float amt = u_detailStrength * fade * fade;\n  if (amt <= 0.001) return n;\n  vec3 d = tNoised(wp.xz * u_detailScale);\n  return normalize(n + vec3(-d.y, 0.0, -d.z) * amt * 0.9);\n}\n\n/**\n * Direct sun, sky fill and ground bounce.\n *\n * Sun irradiance is in the units skyRadiance returns, calibrated against it rather\n * than guessed: a 0.3-albedo surface in full sun lands a little below the sky at\n * the horizon, which is the relationship the eye reads as daylight. Set it to the\n * clouds' SUN_RADIANCE and every ground surface clips to white.\n */\nconst float TERRAIN_SUN = 2.2;\n\nvec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow, float roughness, float ao){\n  float ndl = max(dot(n, u_sunDir), 0.0);\n  // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a\n  // hard terminator across a whole hillside reads as CG.\n  float wrap = max((dot(n, u_sunDir) + 0.2) / 1.2, 0.0);\n  float diff = mix(ndl, wrap, 0.4);\n\n  vec3 sun = u_sunColor * u_sunIntensity * TERRAIN_SUN * diff * shadow * sceneShadow;\n\n  // Sky fill from the same atmosphere the sky is drawn with, so it darkens and\n  // warms with the sun instead of freezing at a constant blue - but supplied as a\n  // uniform rather than evaluated here, since it is the same for every pixel.\n  // Whitened a little: a single-scattering zenith colour is very saturated, and\n  // at full saturation every shadowed slope - snow above all - comes out cyan.\n  vec3 fill = mix(u_skyAmbient, vec3(dot(u_skyAmbient, vec3(0.3333))), 0.4);\n  vec3 ambient = fill * (0.5 + 0.5 * n.y) * u_ambient * 1.05;\n\n  // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded\n  // faces off pure black without flattening them the way raising ambient does.\n  vec3 bounce = u_tFar[0] * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;\n\n  // Occlusion is a property of the small-scale surface, so it darkens the light\n  // that arrives from everywhere \u2014 sky fill and bounce \u2014 and leaves the sun alone.\n  vec3 col = albedo * (sun + (ambient + bounce) * ao);\n\n  // A single specular lobe. Rock barely needs it; wet sand and snow at low sun\n  // are almost entirely this.\n  if (u_specular > 0.0){\n    vec3 hv = normalize(u_sunDir - viewDir);\n    float a = max(roughness * roughness, 0.002);\n    float nh = max(dot(n, hv), 0.0);\n    float dd = nh * nh * (a - 1.0) + 1.0;\n    float d = a / max(3.14159265 * dd * dd, 1e-4);\n    col += u_sunColor * u_sunIntensity * TERRAIN_SUN * d * u_specular * shadow * sceneShadow * ndl;\n  }\n\n  return col;\n}\n\n/**\n * Aerial perspective.\n *\n * The single most important line in this shader for the horizon. Ground fades\n * into the exact sky colour it is seen through, at a rate that thins with\n * altitude because the atmosphere does \u2014 so a distant ridge sits behind the haze\n * and a peak above it stands clear of it, which is what tells you the scene is\n * kilometres across rather than metres.\n *\n * The one remaining per-pixel skyRadiance call, and it has to be: the colour is\n * the sky in the view direction, which is different for every fragment.\n */\nvec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){\n  float scaleHeight = exp(-max(height - u_seaLevel, 0.0) / 1400.0);\n  float f = 1.0 - exp(-dist * u_fogDensity * scaleHeight);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd), saturate(f));\n}\n";
+export declare const terrainShadow = "\n/** 1 lit, 0 shadowed, soft in between. */\nfloat terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){\n  if (steps < 1 || u_sunShadow <= 0.0) return 1.0;\n  // Below the horizon there is nothing to shadow; the march would also walk\n  // downhill forever.\n  if (u_sunDir.y <= 0.015) return 1.0;\n  // A surface facing away from the sun is shadowed by definition, and marching\n  // from it only finds the ground it is already part of.\n  if (dot(n, u_sunDir) <= 0.0) return 0.0;\n\n  // Lift off the surface before starting, or every sample on a steep face - a\n  // terrace riser above all - reads its own ground as an occluder and the whole\n  // wall goes black in a grid of triangles. Start ON the offset surface and\n  // compare raw heights; subtracting the bias from the height difference instead\n  // makes the first sample fail on any slope tilted a few degrees from the sun.\n  float bias = max(lodCell, u_elevation * 0.003);\n  vec3 origin = p + n * bias;\n\n  float shadowLod = (1.0 / max(u_baseScale, 1e-9)) * 0.008;\n\n  float res = 1.0;\n  float t = bias * 3.0;\n  float maxT = (u_elevation * 2.5) / max(u_sunDir.y, 0.05);\n\n  for (int i = 0; i < 48; i++){\n    if (i >= steps || t > maxT) break;\n    vec3 sp = origin + u_sunDir * t;\n    // The occluder is sampled at the SHADING lod, coarsening with distance -\n    // never at a fixed coarse lod. Testing a fine surface point against a coarse\n    // height field puts the whole valley floor in shadow, because the coarse\n    // field sits above the fine one wherever the fine one has been cut down.\n    // Sampled MUCH coarser than the surface being shaded. A shadow does not need\n    // nine octaves: what casts a visible shadow is the landform, and marching the\n    // fine field costs the same nine octaves per step for detail that is below a\n    // pixel by the time it lands. Floored against the landform's own size, so the\n    // march runs about five octaves instead of nine wherever it starts.\n    float h = terrainOccluderAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));\n    float diff = sp.y - h;\n    res = min(res, u_shadowSoftness * diff / t);\n    if (res <= 0.0) return 0.0;\n    // Geometric growth: near the surface the occluder is metres away, at the end\n    // of the march it is kilometres, and a linear step wastes every sample at one\n    // end or the other. 1.7 rather than 1.42 so twelve steps actually reach maxT -\n    // at 1.42 the march ran out around 700 m and long shadows at low sun simply\n    // did not exist, which is a quality bug that happened to look like a cheap one.\n    t = t * 1.7 + bias;\n  }\n  return saturate(res);\n}\n\n/**\n * The shadow, faded out with distance and given a step budget that falls with it.\n *\n * The march is the most expensive thing left in the renderer, and past a few\n * kilometres it is buying nothing: aerial perspective has already washed most of\n * the contrast out of the ground, and a ridge shadow out there is a couple of\n * pixels wide. Skipping it entirely beyond u_shadowDistance drops the outer\n * clipmap rings - which are two thirds of the vertices - out of the march\n * completely, and the rings in between run four steps instead of fourteen.\n *\n * Faded rather than cut, or the cut-off would draw a visible circle on the ground.\n */\nfloat terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){\n  float fade = 1.0 - saturate(dist / max(u_shadowDistance, 1.0));\n  if (fade <= 0.002) return 1.0;\n  int steps = int(mix(4.0, float(u_shadowSteps), fade));\n  return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);\n}\n\n";
+export declare const terrainShading = "\n/**\n * Albedo.\n *\n * Rock is splatted by SLOPE, everything else by height. That ordering is the\n * whole trick: it means a cliff is bare rock whether it is in a valley or on a\n * summit, which is how real ground works and why height-only splatting always\n * reads as a painted contour map.\n */\n/**\n * Splat weights for the four layers, in layer order: low, mid, rock, peak.\n * Exactly the old colour mixes written as weights \u2014 low/mid by height, the peak\n * held back on steep ground (snow does not sit on a vertical face), rock by slope\n * and applied last, which is why a cliff reads as a cliff at any altitude.\n */\nvec4 terrainLayerWeights(float h01, float slope){\n  float m = smoothstep(0.05, 0.55, h01);\n  float p = saturate(smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6));\n  float r = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);\n  return vec4((1.0 - m) * (1.0 - p) * (1.0 - r), m * (1.0 - p) * (1.0 - r), r, p * (1.0 - r));\n}\n\n/** Large-scale variation. Without it a splat layer is one flat colour across\n *  kilometres, and the eye reads flat colour as untextured rather than as ground. */\nfloat terrainMacro(vec3 wp){\n  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;\n  return 1.0 + u_macroVariation * (macro - 0.5) * 2.0;\n}\n\n/** The far-field albedo: each layer's far colour by its weight. */\nvec3 terrainAlbedo(vec3 wp, vec4 w){\n  vec3 col = u_tFar[0] * w.x + u_tFar[1] * w.y + u_tFar[2] * w.z + u_tFar[3] * w.w;\n  return col * terrainMacro(wp);\n}\n\n/** High-frequency bump, well below the mesh resolution, faded out with distance\n *  so it never becomes a field of crawling pixels on the horizon. One evaluation:\n *  the noise carries its own derivative, so the three taps a finite difference\n *  would need are not. */\nvec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){\n  float fade = 1.0 - saturate(dist * u_detailFade);\n  float amt = u_detailStrength * fade * fade;\n  if (amt <= 0.001) return n;\n  vec3 d = tNoised(wp.xz * u_detailScale);\n  return normalize(n + vec3(-d.y, 0.0, -d.z) * amt * 0.9);\n}\n\n/**\n * Direct sun, sky fill and ground bounce.\n *\n * Sun irradiance is in the units skyRadiance returns, calibrated against it rather\n * than guessed: a 0.3-albedo surface in full sun lands a little below the sky at\n * the horizon, which is the relationship the eye reads as daylight. Set it to the\n * clouds' SUN_RADIANCE and every ground surface clips to white.\n */\nconst float TERRAIN_SUN = 2.2;\n\nvec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow, float roughness, float ao){\n  float ndl = max(dot(n, u_sunDir), 0.0);\n  // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a\n  // hard terminator across a whole hillside reads as CG.\n  float wrap = max((dot(n, u_sunDir) + 0.2) / 1.2, 0.0);\n  float diff = mix(ndl, wrap, 0.4);\n\n  vec3 sun = u_sunColor * u_sunIntensity * TERRAIN_SUN * diff * shadow * sceneShadow;\n\n  // Sky fill from the same atmosphere the sky is drawn with, so it darkens and\n  // warms with the sun instead of freezing at a constant blue - but supplied as a\n  // uniform rather than evaluated here, since it is the same for every pixel.\n  // Whitened a little: a single-scattering zenith colour is very saturated, and\n  // at full saturation every shadowed slope - snow above all - comes out cyan.\n  vec3 fill = mix(u_skyAmbient, vec3(dot(u_skyAmbient, vec3(0.3333))), 0.4);\n  vec3 ambient = fill * (0.5 + 0.5 * n.y) * u_ambient * 1.05;\n\n  // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded\n  // faces off pure black without flattening them the way raising ambient does.\n  vec3 bounce = u_tFar[0] * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;\n\n  // Occlusion is a property of the small-scale surface, so it darkens the light\n  // that arrives from everywhere \u2014 sky fill and bounce \u2014 and leaves the sun alone.\n  vec3 col = albedo * (sun + (ambient + bounce) * ao);\n\n  // A single specular lobe. Rock barely needs it; wet sand and snow at low sun\n  // are almost entirely this.\n  if (u_specular > 0.0){\n    vec3 hv = normalize(u_sunDir - viewDir);\n    float a = max(roughness * roughness, 0.002);\n    float nh = max(dot(n, hv), 0.0);\n    float dd = nh * nh * (a - 1.0) + 1.0;\n    float d = a / max(3.14159265 * dd * dd, 1e-4);\n    col += u_sunColor * u_sunIntensity * TERRAIN_SUN * d * u_specular * shadow * sceneShadow * ndl;\n  }\n\n  return col;\n}\n\n/**\n * Aerial perspective.\n *\n * The single most important line in this shader for the horizon. Ground fades\n * into the exact sky colour it is seen through, at a rate that thins with\n * altitude because the atmosphere does \u2014 so a distant ridge sits behind the haze\n * and a peak above it stands clear of it, which is what tells you the scene is\n * kilometres across rather than metres.\n *\n * The one remaining per-pixel skyRadiance call, and it has to be: the colour is\n * the sky in the view direction, which is different for every fragment.\n */\nvec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){\n  float scaleHeight = exp(-max(height - u_seaLevel, 0.0) / 1400.0);\n  float f = 1.0 - exp(-dist * u_fogDensity * scaleHeight);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd), saturate(f));\n}\n";
 /**
  * The textured near field. Needs `surfaceSampling` (surfaceCore.glsl) before it.
  *
@@ -86,6 +93,14 @@ export declare const terrainShading = "\n/** 1 lit, 0 shadowed, soft in between.
 export declare const terrainTextured = "\n#ifdef TERRAIN_TEXTURED\nstruct TerrainGrads { vec2 topX; vec2 topY; vec2 sideXX; vec2 sideXY; vec2 sideZX; vec2 sideZY; };\n\n// The large-scale sample is the same texture, T_MACRO times bigger.\n#define T_MACRO 8.0\n\n/**\n * One layer's three arrays at one projection, at two scales.\n *\n * A ground scan is millimetres per texel: a gravel tile shows its pebbles for a\n * few metres and is a flat average colour from fifty. So past the point where a\n * pixel covers a fifth of a tile, the same texture is sampled again T_MACRO times\n * larger, and its pebbles become patches, its cracks become streaks \u2014 the set's\n * character survives out to hundreds of metres instead of dissolving into a flat\n * colour, and picking a different set is visible from where people actually look\n * at terrain. The switch is by pixel footprint, so it is the same at any tile\n * size and any camera height. Each scale is skipped when its weight is zero.\n */\nvoid terrainTap(int L, vec2 uv, vec2 dx, vec2 dy, out vec4 c, out vec4 nh, out vec4 o){\n  float layer = float(L);\n  float fp = max(length(dx), length(dy));\n  float m = smoothstep(0.04, 0.25, fp);\n  vec4 cd = vec4(0.0);\n  vec4 nd = vec4(0.0);\n  vec4 od = vec4(0.0);\n  vec4 cm = vec4(0.0);\n  vec4 nm = vec4(0.0);\n  vec4 om = vec4(0.0);\n  if (m < 0.999){\n    cd = sfSample(u_tColor,  uv, dx, dy, layer, u_tMeanC[L]);\n    nd = sfSample(u_tNormal, uv, dx, dy, layer, u_tMeanN[L]);\n    od = sfSample(u_tOrm,    uv, dx, dy, layer, u_tMeanO[L]);\n  }\n  if (m > 0.001){\n    vec2 mu = uv / T_MACRO;\n    vec2 mdx = dx / T_MACRO;\n    vec2 mdy = dy / T_MACRO;\n    cm = sfSample(u_tColor,  mu, mdx, mdy, layer, u_tMeanC[L]);\n    nm = sfSample(u_tNormal, mu, mdx, mdy, layer, u_tMeanN[L]);\n    om = sfSample(u_tOrm,    mu, mdx, mdy, layer, u_tMeanO[L]);\n    // No height blending at the large scale. A height map blown up 8x has\n    // tens-of-metres blobs, and blending layers along those contours paints\n    // the ground in camouflage. Mid height = an ordinary cross-fade.\n    nm.a = 0.5;\n  }\n  c  = mix(cd, cm, m);\n  nh = mix(nd, nm, m);\n  o  = mix(od, om, m);\n}\n\n/** One layer: albedo (tinted), an unnormalised world normal, surface height,\n *  roughness and occlusion. An untextured layer returns its flat colour. */\nvoid terrainLayerSample(int L, vec3 wp, vec3 n, TerrainGrads g,\n                        out vec3 col, out vec3 wn, out float h, out float rough, out float ao){\n  col = u_tFar[L];\n  wn = n;\n  h = 0.5;\n  rough = u_roughness;\n  ao = 1.0;\n  if (u_tLayer[L].z > 0.5){\n    float inv = u_tLayer[L].x;\n    float ns = u_tLayer[L].y;\n    vec4 c = vec4(0.0);\n    vec4 nh = vec4(0.0);\n    vec4 o = vec4(0.0);\n    vec3 acc = vec3(0.0);\n    if (L == 2){\n      // Biplanar: the two strongest axes. The third adds a fraction of a percent\n      // anywhere that is not an exact corner and costs a third of the fetches.\n      vec3 an = abs(n);\n      an = an * an * an;\n      an /= max(an.x + an.y + an.z, 1e-4);\n      float lo = min(an.x, min(an.y, an.z));\n      vec3 bw = max(an - lo, 0.0);\n      bw /= max(bw.x + bw.y + bw.z, 1e-4);\n      vec4 c1, n1, o1;\n      if (bw.y > 0.002){\n        terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c1, n1, o1);\n        c += c1 * bw.y; nh += n1 * bw.y; o += o1 * bw.y;\n        acc += sfWhiteoutTop(n, sfUnpackNormal(n1.rgb, ns)) * bw.y;\n      }\n      if (bw.x > 0.002){\n        terrainTap(L, wp.zy * inv, g.sideXX * inv, g.sideXY * inv, c1, n1, o1);\n        c += c1 * bw.x; nh += n1 * bw.x; o += o1 * bw.x;\n        acc += sfWhiteoutX(n, sfUnpackNormal(n1.rgb, ns)) * bw.x;\n      }\n      if (bw.z > 0.002){\n        terrainTap(L, wp.xy * inv, g.sideZX * inv, g.sideZY * inv, c1, n1, o1);\n        c += c1 * bw.z; nh += n1 * bw.z; o += o1 * bw.z;\n        acc += sfWhiteoutZ(n, sfUnpackNormal(n1.rgb, ns)) * bw.z;\n      }\n    } else {\n      terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c, nh, o);\n      acc = sfWhiteoutTop(n, sfUnpackNormal(nh.rgb, ns));\n    }\n    col = c.rgb * u_tTint[L];\n    wn = acc;\n    h = nh.a;\n    rough = o.g;\n    ao = o.r;\n  }\n}\n\n/** Near-field surface for weights w. Outputs albedo (no macro), normal,\n *  roughness and occlusion. */\nvoid terrainSurfaceNear(vec3 wp, vec3 n, vec4 w, TerrainGrads g,\n                        out vec3 albedo, out vec3 nrm, out float rough, out float ao){\n  float ws[4];\n  ws[0] = w.x; ws[1] = w.y; ws[2] = w.z; ws[3] = w.w;\n  int i0 = 0;\n  float b0 = -1.0;\n  for (int i = 0; i < 4; i++){ if (ws[i] > b0){ b0 = ws[i]; i0 = i; } }\n  ws[i0] = -1.0;\n  int i1 = 0;\n  float b1 = -1.0;\n  for (int i = 0; i < 4; i++){ if (ws[i] > b1){ b1 = ws[i]; i1 = i; } }\n  b0 = max(b0, 0.0);\n  b1 = max(b1, 0.0);\n  float bs = max(b0 + b1, 1e-4);\n  b0 /= bs;\n  b1 /= bs;\n\n  vec3 c0, n0, c1, n1;\n  float h0, r0, a0, h1, r1, a1;\n  terrainLayerSample(i0, wp, n, g, c0, n0, h0, r0, a0);\n  if (b1 > 0.001){\n    terrainLayerSample(i1, wp, n, g, c1, n1, h1, r1, a1);\n  } else {\n    c1 = c0; n1 = n0; h1 = h0; r1 = r0; a1 = a0;\n  }\n\n  // Height blend: the layer whose own surface is higher at this texel wins, so\n  // gravel comes through grass along the gravel's grain and rock emerges from\n  // soil along its cracks, instead of the two cross-fading into mud.\n  float hb = u_tHeightBlend;\n  float range = mix(1.0, 0.04, hb);\n  float v0 = b0 + h0 * hb;\n  float v1 = b1 + h1 * hb;\n  float peak = max(v0, v1);\n  float w0 = max(v0 - (peak - range), 0.0);\n  float w1 = max(v1 - (peak - range), 0.0);\n  if (b1 <= 0.001) w1 = 0.0;\n  float ws2 = max(w0 + w1, 1e-4);\n  w0 /= ws2;\n  w1 /= ws2;\n\n  albedo = c0 * w0 + c1 * w1;\n  nrm = normalize(n0 * w0 + n1 * w1);\n  rough = r0 * w0 + r1 * w1;\n  ao = a0 * w0 + a1 * w1;\n}\n#endif\n";
 /** Everything a surface material needs, in include order. Requires three's
  *  `<common>` and `skyLib` from cloudCore before it. */
+/** Every uniform the terrain material reads. */
+export declare const terrainUniforms: string;
 export declare const terrainField: string;
+/**
+ * The height field and its sun-shadow march, with only the uniforms they read.
+ * What another material includes to stand water (or anything else) on the
+ * terrain: the ocean uses it for shoreline depth and headland shadows.
+ */
+export declare const terrainFieldOnly: string;
 export declare const terrainFull: string;
 //# sourceMappingURL=terrainCore.glsl.d.ts.map

package/dist/shaders/glsl/terrainCore.glsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terrainCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/terrainCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,eAAe,wpGA2E3B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,uiCAiCxB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,mqbAiVzB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,s0RAuL1B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,4pLAyJ3B,CAAA;AAED;wDACwD;AACxD,eAAO,MAAM,YAAY,QAA4D,CAAA;AAErF,eAAO,MAAM,WAAW,QAA4C,CAAA"}
+{"version":3,"file":"terrainCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/terrainCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,ooDA0C/B,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,8rDAsClC,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,uiCAiCxB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,mqbAiVzB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,gjHAsEzB,CAAA;AAED,eAAO,MAAM,cAAc,6xKAkH1B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,4pLAyJ3B,CAAA;AAED;wDACwD;AACxD,gDAAgD;AAChD,eAAO,MAAM,eAAe,QAA2D,CAAA;AAEvF,eAAO,MAAM,YAAY,QAA4D,CAAA;AAErF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAA+E,CAAA;AAE5G,eAAO,MAAM,WAAW,QAA2D,CAAA"}

package/dist/shaders/glsl/terrainCore.glsl.js

@@ -26,8 +26,12 @@
  *    per octave, nine octaves, several evaluations per pixel puts it into the
  *    billions of transcendentals per frame.
  */
-/** Every uniform the height field and the shading read. */
-export const terrainUniforms = /* glsl */ `
+/**
+ * The uniforms the height field and the sun-shadow march read — and nothing else,
+ * so another material (the ocean) can include the field without redeclaring its
+ * own u_curvature, u_exposure, u_roughness… GLSL refuses a uniform declared twice.
+ */
+export const terrainFormUniforms = /* glsl */ `
 uniform int   u_terrainType;
 
 uniform float u_elevation;
@@ -49,6 +53,29 @@ uniform float u_plateau;
 uniform float u_valleyDepth;
 uniform float u_valleyWidth;
 
+// The analytic sun-shadow march (terrainShadow) - shared with the ocean, which
+// marches the same field to put headland shadows on the water.
+uniform float u_sunShadow, u_shadowSoftness;
+uniform float u_shadowDistance;
+uniform int   u_shadowSteps;
+
+// A land object: a bounded patch of this field, placed by its object's transform.
+// Its "terrain space" is metres from the object's origin, unrotated, plus a seed
+// offset; height is above the object's base. See TerrainMaterial's patch vertex.
+#ifdef TERRAIN_PATCH
+uniform vec2  u_patchSize;      // footprint in metres (object scale x / z)
+uniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field
+uniform float u_edgeWidth;      // metres over which the land eases down to its base
+uniform vec3  u_camTerrain;     // the camera, in terrain space
+uniform float u_scaleY;         // object scale y: terrain metres = local y x this
+uniform float u_patchCell;      // metres per grid cell
+#define TERRAIN_CAM u_camTerrain
+#else
+#define TERRAIN_CAM cameraPosition
+#endif
+`;
+/** The terrain surface's own uniforms: shading, lighting, textures. */
+export const terrainSurfaceUniforms = /* glsl */ `
 uniform float u_cellSize;
 uniform float u_curvature;
 
@@ -66,10 +93,8 @@ uniform float u_roughness, u_specular;
 // per pixel removes an acos, a pow and three exps from every fragment.
 uniform vec3  u_skyAmbient;
 uniform vec3  u_groundAmbient;
-uniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;
-uniform float u_shadowDistance;
+uniform float u_ambient, u_bounce;
 uniform float u_fogDensity, u_exposure;
-uniform int   u_shadowSteps;
 
 // Ground textures. The far colour per layer is always set: the flat colour for an
 // untextured layer, the texture's own mean x tint for a textured one, so the
@@ -88,20 +113,6 @@ uniform float u_tDistance;
 uniform float u_tHeightBlend;
 #endif
 
-// A land object: a bounded patch of this field, placed by its object's transform.
-// Its "terrain space" is metres from the object's origin, unrotated, plus a seed
-// offset; height is above the object's base. See TerrainMaterial's patch vertex.
-#ifdef TERRAIN_PATCH
-uniform vec2  u_patchSize;      // footprint in metres (object scale x / z)
-uniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field
-uniform float u_edgeWidth;      // metres over which the land eases down to its base
-uniform vec3  u_camTerrain;     // the camera, in terrain space
-uniform float u_scaleY;         // object scale y: terrain metres = local y x this
-uniform float u_patchCell;      // metres per grid cell
-#define TERRAIN_CAM u_camTerrain
-#else
-#define TERRAIN_CAM cameraPosition
-#endif
 `;
 /**
  * Gradient noise with an analytic derivative.
@@ -515,7 +526,7 @@ float terrainOccluderAt(vec2 p, float lodCell){ return terrainHeightAt(p, lodCel
  * The terminator itself stays per-pixel: `terrainLight` takes N·L from the
  * fragment's own normal, so only the CAST shadow is interpolated.
  */
-export const terrainShading = /* glsl */ `
+export const terrainShadow = /* glsl */ `
 /** 1 lit, 0 shadowed, soft in between. */
 float terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){
   if (steps < 1 || u_sunShadow <= 0.0) return 1.0;
@@ -585,6 +596,8 @@ float terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){
   return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);
 }
 
+`;
+export const terrainShading = /* glsl */ `
 /**
  * Albedo.
  *
@@ -867,5 +880,13 @@ void terrainSurfaceNear(vec3 wp, vec3 n, vec4 w, TerrainGrads g,
 `;
 /** Everything a surface material needs, in include order. Requires three's
  *  `<common>` and `skyLib` from cloudCore before it. */
+/** Every uniform the terrain material reads. */
+export const terrainUniforms = [terrainFormUniforms, terrainSurfaceUniforms].join('\n');
 export const terrainField = [terrainUniforms, terrainNoise, terrainHeight].join('\n');
-export const terrainFull = [terrainField, terrainShading].join('\n');
+/**
+ * The height field and its sun-shadow march, with only the uniforms they read.
+ * What another material includes to stand water (or anything else) on the
+ * terrain: the ocean uses it for shoreline depth and headland shadows.
+ */
+export const terrainFieldOnly = [terrainFormUniforms, terrainNoise, terrainHeight, terrainShadow].join('\n');
+export const terrainFull = [terrainField, terrainShadow, terrainShading].join('\n');

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts

@@ -6,6 +6,40 @@ export interface OceanMaterialUniforms {
 /** Uniform-space defaults. Config units are converted by `applyOceanUniforms`;
  *  these are only what the material holds before anything is applied. */
 export declare const oceanMaterialDefaults: {
+    u_sunDir: THREE.Vector3;
+    u_sunColor: THREE.Color;
+    u_skyAmbient: THREE.Color;
+    u_groundAmbient: THREE.Color;
+    u_sunIntensity: number;
+    u_moonDir: THREE.Vector3;
+    u_moonColor: THREE.Color;
+    u_turbidity: number;
+    u_rayleigh: number;
+    u_mieCoefficient: number;
+    u_mieG: number;
+    u_terrainType: number;
+    u_elevation: number;
+    u_seaLevel: number;
+    u_baseScale: number;
+    u_octaves: number;
+    u_lacunarity: number;
+    u_gain: number;
+    u_ridge: number;
+    u_warpStrength: number;
+    u_warpScale: number;
+    u_erosion: number;
+    u_terraces: number;
+    u_terraceSharp: number;
+    u_bearingDir: THREE.Vector2;
+    u_duneFreq: number;
+    u_duneAsym: number;
+    u_plateau: number;
+    u_valleyDepth: number;
+    u_valleyWidth: number;
+    u_sunShadow: number;
+    u_shadowSoftness: number;
+    u_shadowDistance: number;
+    u_shadowSteps: number;
     u_waveA: THREE.Vector4[];
     u_waveB: THREE.Vector4[];
     u_waveCount: number;
@@ -36,17 +70,8 @@ export declare const oceanMaterialDefaults: {
     u_exposure: number;
     u_curvature: number;
     u_receiveShadows: number;
-    u_sunDir: THREE.Vector3;
-    u_sunColor: THREE.Color;
-    u_skyAmbient: THREE.Color;
-    u_groundAmbient: THREE.Color;
-    u_sunIntensity: number;
-    u_moonDir: THREE.Vector3;
-    u_moonColor: THREE.Color;
-    u_turbidity: number;
-    u_rayleigh: number;
-    u_mieCoefficient: number;
-    u_mieG: number;
+    u_shoreDepth: number;
+    u_shoreFoam: number;
 };
 export declare class OceanSurfaceMaterial extends THREE.ShaderMaterial {
     constructor();

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAmM9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDjC,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}
+{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA0R9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDjC,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}

package/dist/shaders/ocean/OceanSurfaceMaterial.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { extend } from '@react-three/fiber';
 import { skyLib } from '../glsl/cloudCore.glsl.js';
 import { oceanFull, MAX_WAVES } from '../glsl/oceanCore.glsl.js';
+import { terrainFieldOnly } from '../glsl/terrainCore.glsl.js';
 /**
  * The water surface material. Used by both hosts — the world clipmap and a
  * placed body — and by all four water types, which differ in the spectrum the
@@ -44,6 +45,16 @@ const vertex = /* glsl */ `
 ${skyLib}
 ${oceanFull}
 
+// The ground under the water (phase 4 of the ocean plan). Only the height field
+// and its sun-shadow march, with only their own uniforms - the ocean has its own
+// u_curvature, u_exposure... and GLSL refuses a uniform declared twice. Mind the
+// trap in oceanCore: the field's u_seaLevel is the TERRAIN's; the water's level
+// is u_waterLevel.
+#ifdef OCEAN_TERRAIN
+${terrainFieldOnly}
+#endif
+uniform float u_shoreDepth;
+
 /** World size of this vertex's cell. Per-vertex so one material serves every
  *  clipmap ring, and a placed body sets it from its own grid. */
 attribute float aCell;
@@ -59,6 +70,8 @@ varying float vFoam;
 varying float vRelHeight;
 varying float vDist;
 varying float vDepthFactor;
+varying float vShoreDepth;
+varying float vTerrainShadow;
 
 void main(){
   // Geomorph first, waves second. The other order blends two different points on
@@ -85,15 +98,41 @@ void main(){
   bool isBody = u_bodyHalf.x > 0.0;
   vec2 fieldXZ = isBody ? local : wxz;
 
+  // Water depth from the terrain height field under this vertex.
+  //
+  // Waves lose their height as the water shoals and are gone at the waterline.
+  // That is the physics, and it is also the fix for the shoreline: an open-sea
+  // swell heaving a couple of metres up and down a 1:4 beach swept the waterline
+  // ~8 m in and out on every wave, and with the edge being a hard depth-buffer
+  // cut through the rock, that read as jitter. With the amplitude gone at depth
+  // 0, the line sits still where the ground meets the level. Waves get twice the
+  // shore depth to die in, because they need more room than the colour does.
+  float shoal = 1.0;
+  vShoreDepth = 1.0e4;
+  vTerrainShadow = 1.0;
+  #ifdef OCEAN_TERRAIN
+  if (!isBody) {
+    float ground = terrainHeightAt(wxz, max(cellLod, 0.5));
+    vShoreDepth = u_waterLevel - ground;
+    shoal = smoothstep(0.0, max(u_shoreDepth, 0.05) * 2.0, vShoreDepth);
+    // A headland's shadow across the bay: the terrain's own analytic march, from
+    // the flat water level, faded and stepped by distance exactly as on land.
+    vec3 sp = vec3(wxz.x, u_waterLevel, wxz.y);
+    float shadow = terrainShadowAt(sp, vec3(0.0, 1.0, 0.0), cellLod, distance(sp, cameraPosition));
+    vTerrainShadow = mix(1.0, shadow, saturate(u_sunShadow));
+  }
+  #endif
+
   vec3 disp; vec3 nrm; float jac; float rel;
-  oceanWaveSum(fieldXZ, cellLod, u_amplitudeScale * edge, disp, nrm, jac, rel);
+  oceanWaveSum(fieldXZ, cellLod, u_amplitudeScale * edge * shoal, disp, nrm, jac, rel);
 
   vFoam = oceanFoam(jac, rel, vec3(fieldXZ.x, 0.0, fieldXZ.y));
   vRelHeight = rel;
 
-  // Open water until the refraction grab lands; the shoreline reads its depth
-  // from that, and from the terrain field when it is included.
-  vDepthFactor = 1.0;
+  // 1 in open water, ramping to 0 as the bottom comes up (shallow colour). Open
+  // water everywhere without terrain, until the refraction grab gives depth for
+  // anything else standing in the water.
+  vDepthFactor = saturate(vShoreDepth / max(u_shoreDepth, 0.05));
 
   // Displacement is in field space, which for both hosts is object space up to a
   // translation - so it can be added to transformed directly. Deriving it from
@@ -148,6 +187,11 @@ varying float vFoam;
 varying float vRelHeight;
 varying float vDist;
 varying float vDepthFactor;
+varying float vShoreDepth;
+varying float vTerrainShadow;
+
+uniform float u_shoreDepth;
+uniform float u_shoreFoam;
 
 void main(){
   vec3 viewDir = normalize(vWorld - cameraPosition);
@@ -179,7 +223,19 @@ void main(){
     sceneShadow = mix(1.0, getShadowMask(), u_receiveShadows);
   #endif
 
-  vec3 col = oceanLight(vWorld, n, viewDir, vFoam, vRelHeight, sceneShadow, vDepthFactor, roughAA, vec3(0.0));
+  sceneShadow *= vTerrainShadow;
+
+  // Shore foam: a band where the ground comes up through the surface, broken by
+  // drifting noise so it reads as wash rather than a painted outline. It also
+  // covers the hard depth-buffer edge where the water plane meets the rock.
+  float foam = vFoam;
+  if (u_shoreFoam > 0.0 && vShoreDepth < 1.0e3) {
+    float band = 1.0 - smoothstep(0.0, max(u_shoreDepth * 0.35, 0.05), vShoreDepth);
+    float wash = oNoised(vWorld.xz * 0.35 + vec2(u_time * 0.15, -u_time * 0.07)).x * 0.5 + 0.5;
+    foam = max(foam, saturate(band * (0.45 + 0.55 * wash) * u_shoreFoam));
+  }
+
+  vec3 col = oceanLight(vWorld, n, viewDir, foam, vRelHeight, sceneShadow, vDepthFactor, roughAA, vec3(0.0));
   col = oceanAerial(col, viewDir, vDist);
   col *= u_exposure;
 
@@ -190,6 +246,36 @@ void main(){
   #include <fog_fragment>
 }
 `;
+/** The terrain field's uniforms (terrainFormUniforms), at harmless values until
+ *  applyTerrainFieldUniforms fills them. u_sunShadow here is the WATER's
+ *  terrainShadow strength, steps and distance its own quality knobs. */
+function terrainFieldDefaults() {
+    return {
+        u_terrainType: 2,
+        u_elevation: 180,
+        u_seaLevel: 0,
+        u_baseScale: 1 / 2600,
+        u_octaves: 8,
+        u_lacunarity: 2.06,
+        u_gain: 0.46,
+        u_ridge: 0.05,
+        u_warpStrength: 0.35,
+        u_warpScale: 0.6,
+        u_erosion: 0.45,
+        u_terraces: 0,
+        u_terraceSharp: 0.6,
+        u_bearingDir: new THREE.Vector2(0.978, 0.208),
+        u_duneFreq: (2 * Math.PI) / 340,
+        u_duneAsym: 0.62,
+        u_plateau: 0,
+        u_valleyDepth: 0,
+        u_valleyWidth: 0.25,
+        u_sunShadow: 1,
+        u_shadowSoftness: 12,
+        u_shadowDistance: 4000,
+        u_shadowSteps: 10,
+    };
+}
 function emptyWaveTable() {
     return Array.from({ length: MAX_WAVES }, () => new THREE.Vector4());
 }
@@ -226,6 +312,11 @@ export const oceanMaterialDefaults = {
     u_exposure: 1,
     u_curvature: 1 / (2 * 6371000),
     u_receiveShadows: 1,
+    // Shoreline (applyOceanShore). Read with or without terrain; the terrain
+    // field's own uniforms below only when OCEAN_TERRAIN is defined.
+    u_shoreDepth: 3,
+    u_shoreFoam: 1,
+    ...terrainFieldDefaults(),
     // Shared with the cloud and terrain materials, set by the same
     // applySunUniforms() off the same useCloudSun state.
     u_sunDir: new THREE.Vector3(0.35, 0.42, 0.84).normalize(),

package/dist/triggers/engine.d.ts

@@ -17,7 +17,7 @@ export interface RunOptions {
     catalog?: TriggerCatalog;
     effects?: boolean;
 }
-export type RunResult = 'ran' | 'queued' | 'waiting' | 'cycle' | 'refused' | 'unknown' | 'invalid';
+export type RunResult = 'ran' | 'queued' | 'waiting' | 'cycle' | 'refused' | 'unknown' | 'invalid' | 'off';
 export interface EngineContext extends TriggerContext {
     catalog: TriggerCatalog;
 }

package/dist/triggers/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/triggers/engine.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjE,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC3B,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAChD,IAAI,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACrD,KAAK,CAAC,IAAI,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9B,sFAAsF;IACtF,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnG,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD,OAAO,EAAE,cAAc,CAAC;CAC3B;AAmBD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,IAAI,CAG1E;AAYD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAI7E;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAIrF;AAED,uEAAuE;AACvE,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,aAAa,GAAG,SAA4B,CAAC;AAEvF,oEAAoE;AACpE,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAG9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAiCzE;AA6CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAGrI;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,IAAI,CAAoB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/triggers/engine.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjE,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC3B,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAChD,IAAI,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACrD,KAAK,CAAC,IAAI,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9B,sFAAsF;IACtF,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC;AAE3G,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD,OAAO,EAAE,cAAc,CAAC;CAC3B;AAmBD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,IAAI,CAG1E;AAYD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAI7E;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAIrF;AAED,uEAAuE;AACvE,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,aAAa,GAAG,SAA4B,CAAC;AAEvF,oEAAoE;AACpE,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAG9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAmCzE;AA6CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAGrI;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,IAAI,CAAoB"}

package/dist/triggers/engine.js

@@ -62,6 +62,9 @@ export function currentChain() {
 export function runCommand(cmd, opts) {
     if (!cmd || typeof cmd !== 'object' || !cmd.kind)
         return 'invalid';
+    // an effect switched off in its list is kept but never runs (a revert still goes through: it may have been on)
+    if (cmd.kind === 'effect' && cmd.effect?.enabled === false && cmd.command !== 'revert')
+        return 'off';
     const top = stack[stack.length - 1];
     const ctx = {
         source: opts.source,

package/dist/triggers/hosts/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/triggers/hosts/actions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG3F,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,YAAY,EACrC,CAAC;AAE9D,0EAA0E;AAC1E,eAAO,MAAM,eAAe,GAAI,QAAQ,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,eAAe,EAClB,CAAC;AAEnF,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAUxF"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/triggers/hosts/actions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG3F,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,YAAY,EACrC,CAAC;AAE9D,0EAA0E;AAC1E,eAAO,MAAM,eAAe,GAAI,QAAQ,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,eAAe,EACY,CAAC;AAEjH,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAWxF"}

package/dist/triggers/hosts/actions.js

@@ -2,7 +2,7 @@ import { runCommand } from '../engine.js';
 /** An action's commands, in the order they run. */
 export const actionCommandsOf = (action) => (Array.isArray(action?.commands) ? action.commands : []);
 /** The effects among an action's commands (to pre-warm their shaders). */
-export const actionEffectsOf = (action) => actionCommandsOf(action).flatMap(c => (c.kind === 'effect' ? [c.effect] : []));
+export const actionEffectsOf = (action) => actionCommandsOf(action).flatMap(c => (c.kind === 'effect' && c.effect.enabled !== false ? [c.effect] : []));
 /** Switch an action's commands on (apply) or off (revert). */
 export function runActionCommands(action, mode) {
     const source = { host: 'action', id: action.id };
@@ -14,6 +14,8 @@ export function runActionCommands(action, mode) {
             runCommand({ ...c, command: mode }, { source });
         else if (c.kind === 'action')
             runCommand({ ...c, command: mode }, { source });
+        else if (c.kind === 'change')
+            runCommand({ ...c, command: mode }, { source });
         else if (mode === 'apply')
             runCommand(c, { source });
         else if (c.command === 'play' || c.command === 'toggle')

package/dist/triggers/hosts/interactions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interactions.d.ts","sourceRoot":"","sources":["../../../src/triggers/hosts/interactions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEvE,wDAAwD;AACxD,eAAO,MAAM,UAAU,GAAI,aAAa,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,YAAY,EACvB,CAAC;AAExE,+EAA+E;AAC/E,eAAO,MAAM,SAAS,GAAI,aAAa,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,sDACG,CAAC"}
+{"version":3,"file":"interactions.d.ts","sourceRoot":"","sources":["../../../src/triggers/hosts/interactions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEvE,wDAAwD;AACxD,eAAO,MAAM,UAAU,GAAI,aAAa,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,YAAY,EACvB,CAAC;AAExE,+EAA+E;AAC/E,eAAO,MAAM,SAAS,GAAI,aAAa,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,sDACiC,CAAC"}

package/dist/triggers/hosts/interactions.js

@@ -1,4 +1,4 @@
 /** An interaction's commands, in the order they run. */
 export const commandsOf = (interaction) => (Array.isArray(interaction?.commands) ? interaction.commands : []);
 /** The effects among an interaction's commands (to pre-warm their shaders). */
-export const effectsOf = (interaction) => commandsOf(interaction).flatMap(c => (c.kind === 'effect' ? [c.effect] : []));
+export const effectsOf = (interaction) => commandsOf(interaction).flatMap(c => (c.kind === 'effect' && c.effect.enabled !== false ? [c.effect] : []));

package/dist/triggers/hosts/timelineCues.js

@@ -16,7 +16,7 @@ ClipsRuntime.setCueRunner((cmd, mode, { effects, host, timelineId, getAction })
     // fire: one-shot — an effect plays (apply), anything else runs its own command
     const run = mode === 'fire'
         ? (cmd.kind === 'effect' ? { ...cmd, command: 'apply' } : cmd)
-        : cmd.kind === 'effect' || cmd.kind === 'effectClip' || cmd.kind === 'action' ? { ...cmd, command: mode } : cmd;
+        : cmd.kind === 'effect' || cmd.kind === 'effectClip' || cmd.kind === 'action' || cmd.kind === 'change' ? { ...cmd, command: mode } : cmd;
     runCommand(run, { source, chain: [], effects, ...(catalog ? { catalog } : {}) });
     return true;
 });

package/dist/triggers/kinds/change.d.ts

@@ -0,0 +1,4 @@
+export declare const changeLayerId: (c: {
+    id: string;
+}) => string;
+//# sourceMappingURL=change.d.ts.map

package/dist/triggers/kinds/change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change.d.ts","sourceRoot":"","sources":["../../../src/triggers/kinds/change.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,aAAa,GAAI,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,WAAqB,CAAC"}

package/dist/triggers/kinds/change.js

@@ -0,0 +1,50 @@
+// Triggerable: an inline change — an action's targets (element + settings patch) without
+// the action. On lays the patches over the elements as a silent SceneActions layer
+// (`change:<id>`): the elements re-render with them, exactly as with an action, but nothing
+// lists it as an applied action. Off removes the layer. A timeline's Change cue.
+//
+// Collisions: when another action / change / the timeline's switch tracks already set the
+// same settings on an element, it is logged as a clash — not resolved (the last one to
+// change sits on top).
+import { SceneActions } from '@3driseai/3drise-core';
+import { defineTriggerable } from '../registry.js';
+import { logTrigger } from '../log.js';
+import { currentChain } from '../engine.js';
+const ENV = new Set(['camera', 'sky', 'clouds', 'ocean', 'terrain']);
+export const changeLayerId = (c) => `change:${c.id}`;
+const ownerName = (o) => (o.startsWith('layer:change:') ? `change ${o.slice(13)}` : o === 'layer:timeline' ? 'a switch track' : `action ${o}`);
+const patchesOf = (c) => {
+    const out = {};
+    for (const t of c.targets ?? [])
+        if (t?.state && t.patch && Object.keys(t.patch).length)
+            out[t.state] = t.patch;
+    return out;
+};
+defineTriggerable({
+    kind: 'change',
+    commands: ['apply', 'revert', 'toggle'],
+    timeline: 'state',
+    targets: (c) => (c.targets ?? []).map(t => t.state).filter(s => s && !ENV.has(s)),
+    subject: (c) => c.label || `change ${c.id}`,
+    claimKey: (c) => `change:${c.id}`,
+    isOn: (c) => SceneActions.hasLayer(changeLayerId(c)),
+    run: (c, ctx) => {
+        const id = changeLayerId(c);
+        const on = c.command === 'apply' || (c.command === 'toggle' && !SceneActions.hasLayer(id));
+        if (!on) {
+            SceneActions.setLayer(id, null);
+            return;
+        }
+        const patches = patchesOf(c);
+        for (const [state, patch] of Object.entries(patches)) {
+            const others = SceneActions.overlaps(state, patch, `layer:${id}`);
+            if (others.length) {
+                logTrigger({
+                    type: 'clash', kind: 'change', subject: c.label || id, source: ctx.source, chain: currentChain(),
+                    detail: `sets the same settings on ${state} as ${others.map(ownerName).join(', ')} — the last one to change wins`,
+                });
+            }
+        }
+        SceneActions.setLayer(id, patches);
+    },
+});

package/dist/triggers/kinds/index.d.ts

@@ -1,4 +1,5 @@
 import './effects';
 import './action';
 import './animations';
+import './change';
 //# sourceMappingURL=index.d.ts.map

package/dist/triggers/kinds/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/triggers/kinds/index.ts"],"names":[],"mappings":"AACA,OAAO,WAAW,CAAC;AACnB,OAAO,UAAU,CAAC;AAClB,OAAO,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/triggers/kinds/index.ts"],"names":[],"mappings":"AACA,OAAO,WAAW,CAAC;AACnB,OAAO,UAAU,CAAC;AAClB,OAAO,cAAc,CAAC;AACtB,OAAO,UAAU,CAAC"}

package/dist/triggers/kinds/index.js

@@ -2,3 +2,4 @@
 import './effects.js';
 import './action.js';
 import './animations.js';
+import './change.js';

package/dist/utils/CameraSingleton.d.ts

@@ -13,6 +13,10 @@ declare class CameraSingleton {
     animateCameraPosition(position: Vector3Array): Promise<void>;
     setCamera(camera: PerspectiveCamera): void;
     getCamera(): PerspectiveCamera | null;
+    /** The live OrbitControls (registered by CameraController) — controllers drag it directly. */
+    private controls;
+    setControls(controls: any): void;
+    getControls(): any;
     getPosition(): Vector3;
     getRotation(): Euler;
     isSynced(position: Vector3Array, orientation: Vector3Array | [number, number, number, number]): boolean;