@jgengine/shell 0.22.0 → 0.24.0

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -1,8 +1,14 @@
 import * as THREE from "three";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
+import type { TerrainPaintTextures } from "./terrainSurfaces.js";
 /** The built procedural detail terrain material, ready to mount on the ground mesh. */
 export interface TerrainDetailMaterialHandle {
     material: THREE.MeshStandardMaterial;
+    /** Editor relief-contour strength 0..1 (0 in play); write `.value` to retune without recompiling. */
+    contour: {
+        value: number;
+    };
 }
 /**
  * Loaded PBR textures matching a resolved `ResolvedTerrainDetailMaterial.maps`' roles. The caller
@@ -15,17 +21,34 @@ export interface TerrainDetailMaterialTextures {
     roughness?: THREE.Texture;
     ao?: THREE.Texture;
 }
+/** Surface-pass inputs beyond the resolved detail config. */
+export interface TerrainDetailMaterialOptions {
+    /** Authored paint coverage from {@link createTerrainPaintTextures}; omit for unpainted ground. */
+    paint?: TerrainPaintTextures;
+    /** Graphics tier. `low` draws one cheap mottle per surface and skips micro-normals. Default `high`. */
+    quality?: GraphicsQuality;
+    /**
+     * Surface classes to compile (bit `1 << classIndex`); defaults to the paint's own classes. An
+     * editor that can paint any surface passes {@link ALL_TERRAIN_SURFACE_CLASSES}.
+     */
+    classMask?: number;
+    /** Initial editor relief-contour strength. Default 0. */
+    contour?: number;
+}
+/** Compile every surface response, for an editor viewport whose paint can change to any surface. */
+export declare const ALL_TERRAIN_SURFACE_CLASSES = 511;
 /**
- * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
- * colour as the base ground and blends procedural, noise-broken rock (by slope),
- * sand (by waterline), and snow (by height) over it — textured-reading terrain
- * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
- * material, so it composes with the post-processing chain.
+ * A `MeshStandardMaterial` that renders terrain as ground rather than flat colour. Each painted
+ * layer draws its surface type's procedural response (grass clumps and blades, dirt clods and
+ * pebbles, gravel stones, cracked rock, rippled sand, wet mud, snow, road grain) in the layer's
+ * authored hue, with albedo, roughness and a micro-normal. Layers meet along noise-warped,
+ * height-aware edges instead of paint-cell blobs; steep slopes turn to rock; macro sweeps break up
+ * tiling. Unpainted ground keeps the biome-tinted vertex colour with procedural detail, plus the
+ * waterline sand and altitude snow bands. Full PBR: lit, shadowed and fogged like any standard material.
  *
  * When `detail.material` is set, pass the matching loaded `textures` (color/normal/roughness/ao):
  * they tile by world position at `detail.material.repeat` world units per tile and blend over the
- * procedural result at `detail.material.strength` — the real-texture seam layers onto the existing
- * look instead of replacing it.
-  * @internal
-  */
-export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail, textures?: TerrainDetailMaterialTextures): TerrainDetailMaterialHandle;
+ * procedural result at `detail.material.strength`.
+ * @internal
+ */
+export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail, textures?: TerrainDetailMaterialTextures, options?: TerrainDetailMaterialOptions): TerrainDetailMaterialHandle;

package/dist/terrain/terrainDetailMaterial.js

@@ -1,49 +1,58 @@
 import * as THREE from "three";
-const NOISE_GLSL = /* glsl */ `
-uint jgHashUint(uvec2 v){
-  uint x = v.x * 1664525u + v.y * 1013904223u;
-  x = (x ^ (x >> 16u)) * 2246822519u;
-  x = (x ^ (x >> 13u)) * 3266489917u;
-  x = x ^ (x >> 16u);
-  return x;
-}
-float jgHash(vec2 p){
-  ivec2 i = ivec2(floor(p));
-  return float(jgHashUint(uvec2(i))) * (1.0 / 4294967296.0);
-}
-float jgVNoise(vec2 p){
-  vec2 i = floor(p); vec2 f = fract(p);
-  vec2 u = f * f * (3.0 - 2.0 * f);
-  float a = jgHash(i);
-  float b = jgHash(i + vec2(1.0, 0.0));
-  float c = jgHash(i + vec2(0.0, 1.0));
-  float d = jgHash(i + vec2(1.0, 1.0));
-  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
-}
-float jgFbm(vec2 p){
-  float v = 0.0; float amp = 0.5;
-  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }
-  return v;
+import { NOISE_GLSL, PAINT_PARS_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+const ROCK_CLASS_BIT = 1 << 4;
+/** Compile every surface response, for an editor viewport whose paint can change to any surface. */
+export const ALL_TERRAIN_SURFACE_CLASSES = 0x1ff;
+// Slot 0 is the unpainted base, 1–8 the paint layers, 9 slope rock.
+const SLOT_GLSL = /* glsl */ `
+JgSurf jgSlot(int slot, vec3 baseTone, vec3 wp){
+  vec3 jgFlatC = baseTone;
+  JgSurf s;
+  if (slot == 9) {
+    jgFlatC = uRockColor;
+    s = jgSurface(4, uRockColor, roughness, 1.0, wp);
+  }
+#ifdef JG_TERRAIN_PAINT
+  else if (slot > 0) {
+    int i = slot - 1;
+    jgFlatC = uLayerColor[i];
+    s = jgSurface(int(uLayerClass[i] + 0.5), uLayerColor[i], uLayerRough[i], uLayerScale[i], wp);
+  }
+#endif
+  else {
+    s = jgSurface(0, baseTone, roughness, 1.0, wp);
+  }
+  s.albedo = mix(jgFlatC, s.albedo, uSurface);
+  s.height *= uSurface;
+  s.bump *= uSurface;
+  return s;
 }
 `;
 /**
- * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
- * colour as the base ground and blends procedural, noise-broken rock (by slope),
- * sand (by waterline), and snow (by height) over it — textured-reading terrain
- * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
- * material, so it composes with the post-processing chain.
+ * A `MeshStandardMaterial` that renders terrain as ground rather than flat colour. Each painted
+ * layer draws its surface type's procedural response (grass clumps and blades, dirt clods and
+ * pebbles, gravel stones, cracked rock, rippled sand, wet mud, snow, road grain) in the layer's
+ * authored hue, with albedo, roughness and a micro-normal. Layers meet along noise-warped,
+ * height-aware edges instead of paint-cell blobs; steep slopes turn to rock; macro sweeps break up
+ * tiling. Unpainted ground keeps the biome-tinted vertex colour with procedural detail, plus the
+ * waterline sand and altitude snow bands. Full PBR: lit, shadowed and fogged like any standard material.
  *
  * When `detail.material` is set, pass the matching loaded `textures` (color/normal/roughness/ao):
  * they tile by world position at `detail.material.repeat` world units per tile and blend over the
- * procedural result at `detail.material.strength` — the real-texture seam layers onto the existing
- * look instead of replacing it.
-  * @internal
-  */
-export function createTerrainDetailMaterial(detail, textures) {
+ * procedural result at `detail.material.strength`.
+ * @internal
+ */
+export function createTerrainDetailMaterial(detail, textures, options = {}) {
     const hasTexture = textures !== undefined && detail.material !== undefined;
     const repeat = detail.material?.repeat ?? 4;
     const strength = detail.material?.strength ?? 1;
     const tint = detail.material?.tint ?? 1;
+    const paint = options.paint;
+    const low = options.quality === "low";
+    const contour = { value: options.contour ?? 0 };
+    // Rock is always compiled for slope rock; each extra class costs shader time even where unused on
+    // GPUs that run both sides of a branch.
+    const classMask = (options.classMask ?? paint?.classMask ?? 0) | ROCK_CLASS_BIT;
     const uniforms = {
         uRockColor: { value: new THREE.Color(detail.rockColor) },
         uSandColor: { value: new THREE.Color(detail.sandColor) },
@@ -56,6 +65,9 @@ export function createTerrainDetailMaterial(detail, textures) {
         uDetailScale: { value: Math.max(0.5, detail.detailScale) },
         uMacroScale: { value: Math.max(0.5, detail.macroScale) },
         uStrength: { value: detail.strength },
+        uSurface: { value: detail.surfaceStrength },
+        uContour: contour,
+        ...(paint === undefined ? {} : paint.uniforms),
         ...(hasTexture
             ? {
                 uMatColor: { value: textures.color },
@@ -74,6 +86,11 @@ export function createTerrainDetailMaterial(detail, textures) {
         metalness: 0,
         vertexColors: true,
     });
+    material.defines = {
+        ...(paint === undefined ? {} : { JG_TERRAIN_PAINT: "" }),
+        ...(low ? { JG_SURFACE_LOW: "" } : {}),
+        JG_SURFACE_CLASSES: String(classMask),
+    };
     material.onBeforeCompile = (shader) => {
         Object.assign(shader.uniforms, uniforms);
         shader.vertexShader = shader.vertexShader
@@ -109,12 +126,15 @@ jgCol = mix(jgCol, jgMatColor, uMatStrength * uMatTint);`
         const materialRoughnessGlsl = hasTexture && textures.roughness !== undefined
             ? `
 float jgMatRough = texture2D(uMatRoughness, jgMatUv).g;
-roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
+// The map varies the authored roughness rather than replacing it: scanned ground roughness sits
+// near 0.45, which turned matte terrain glossy enough to throw a wet sheen across dry sand.
+roughnessFactor = clamp(roughnessFactor + (jgMatRough - 0.5) * uMatStrength * 0.6, 0.0, 1.0);`
             : "";
+        // The map's tilt is world-space (U along +X, V along +Z on flat ground); `normal` is view-space.
         const materialNormalGlsl = hasTexture
             ? `
 vec2 jgMatNormalXy = texture2D(uMatNormal, jgMatUv).rg * 2.0 - 1.0;
-normal = normalize(normal + vec3(jgMatNormalXy.x, 0.0, jgMatNormalXy.y) * uMatStrength * 0.6);`
+normal = normalize(normal + (viewMatrix * vec4(jgMatNormalXy.x, 0.0, jgMatNormalXy.y, 0.0)).xyz * uMatStrength * 0.6);`
             : "";
         const materialAoGlsl = hasTexture && textures.ao !== undefined
             ? `
@@ -136,48 +156,114 @@ uniform float uWaterLevel;
 uniform float uDetailScale;
 uniform float uMacroScale;
 uniform float uStrength;
+uniform float uSurface;
+uniform float uContour;
 ${materialUniformsGlsl}
-${NOISE_GLSL}`)
+${NOISE_GLSL}
+${SURFACE_FUNCTIONS_GLSL}
+#ifdef JG_TERRAIN_PAINT
+${PAINT_PARS_GLSL}
+#endif
+${SLOT_GLSL}`)
             .replace("#include <color_fragment>", `#include <color_fragment>
 vec2 jgWp = vJgWorldPos.xz;
-float jgFine = jgFbm(jgWp / uDetailScale);
+jgFootprint = max(length(dFdx(vJgWorldPos)), length(dFdy(vJgWorldPos)));
 float jgMacro = jgFbm(jgWp / uMacroScale);
-float jgPatch = jgFbm(jgWp / (uMacroScale * 0.35) + vec2(37.2, 11.7));
 float jgSlope = 1.0 - clamp(vJgWorldNormal.y, 0.0, 1.0);
 float jgH = vJgWorldPos.y;
-// Blade-scale flecks fade with view distance so close ground reads as turf without
-// shimmering into noise on the horizon.
-float jgViewDist = length(vJgWorldPos - cameraPosition);
-float jgNear = 1.0 - smoothstep(14.0, 70.0, jgViewDist);
-float jgFleck = jgVNoise(jgWp / max(0.05, uDetailScale * 0.024));
-float jgFleckMid = jgVNoise(jgWp / max(0.12, uDetailScale * 0.07) + vec2(51.3, 7.9));
+float jgRockW = smoothstep(uRockSlopeStart, uRockSlopeStart + 0.18, jgSlope) * mix(uStrength, 1.0, uSurface);
+
+// Only the two strongest of base, eight paint slots and slope rock are shaded; a third
+// contribution is negligible once the coverage is smoothed, and shading every slot cost 10x.
+vec4 jgPa = vec4(0.0);
+vec4 jgPb = vec4(0.0);
+float jgPaintTotal = 0.0;
+#ifdef JG_TERRAIN_PAINT
+vec2 jgPaintTexUv = jgPaintUv(jgWp);
+jgPa = texture2D(uPaintA, jgPaintTexUv);
+jgPb = texture2D(uPaintB, jgPaintTexUv);
+jgPaintTotal = dot(jgPa, vec4(1.0)) + dot(jgPb, vec4(1.0));
+#endif
+float jgPaintNorm = (1.0 - jgRockW) / max(1.0, jgPaintTotal);
+jgPaintTotal = min(jgPaintTotal, 1.0);
+int jgI1 = 0;
+int jgI2 = 0;
+float jgW1 = (1.0 - jgPaintTotal) * (1.0 - jgRockW);
+float jgW2 = 0.0;
+#define JG_PICK(idx, w) { float jgPk = (w); if (jgPk > jgW1) { jgI2 = jgI1; jgW2 = jgW1; jgI1 = idx; jgW1 = jgPk; } else if (jgPk > jgW2) { jgI2 = idx; jgW2 = jgPk; } }
+#ifdef JG_TERRAIN_PAINT
+JG_PICK(1, jgPa.r * jgPaintNorm)
+JG_PICK(2, jgPa.g * jgPaintNorm)
+JG_PICK(3, jgPa.b * jgPaintNorm)
+JG_PICK(4, jgPa.a * jgPaintNorm)
+JG_PICK(5, jgPb.r * jgPaintNorm)
+JG_PICK(6, jgPb.g * jgPaintNorm)
+JG_PICK(7, jgPb.b * jgPaintNorm)
+JG_PICK(8, jgPb.a * jgPaintNorm)
+#endif
+JG_PICK(9, jgRockW)
+bool jgTwo = jgW2 > 0.004;
+
 vec3 jgBase = diffuseColor.rgb;
-jgBase *= mix(1.0 - 0.2 * uStrength, 1.0 + 0.16 * uStrength, jgFine);
-// Biome patchwork: hue-shifted dry sweeps and cooler wet pockets, tinted per-world via detail.sweeps.
-jgBase = mix(jgBase, jgBase * uSweepDry, smoothstep(0.5, 0.8, jgMacro) * 0.55 * uStrength);
-jgBase = mix(jgBase, jgBase * uSweepWet, smoothstep(0.52, 0.85, jgPatch) * 0.5 * uStrength);
-// Rolling large-scale light/dark sweeps keep far hills from flattening into one tone.
-jgBase *= 1.0 + (jgFbm(jgWp / (uMacroScale * 2.3) + vec2(9.1, 73.4)) - 0.5) * 0.22 * uStrength;
-jgBase *= 1.0 + (jgFleck - 0.5) * 0.48 * uStrength * jgNear;
-jgBase *= 1.0 + (jgFleckMid - 0.5) * 0.34 * uStrength;
-vec3 jgRock = uRockColor * mix(0.72, 1.15, jgFbm(jgWp / (uDetailScale * 1.7)));
-float jgRockW = smoothstep(uRockSlopeStart, uRockSlopeStart + 0.18, jgSlope) * uStrength;
-vec3 jgCol = mix(jgBase, jgRock, jgRockW);
-vec3 jgSand = uSandColor * mix(0.9, 1.08, jgFine);
+if (jgI1 == 0 || (jgTwo && jgI2 == 0)) {
+  float jgFine = jgFbm(jgWp / uDetailScale);
+  float jgPatch = jgFbm(jgWp / (uMacroScale * 0.35) + vec2(37.2, 11.7));
+  float jgFleck = jgVNoise(jgWp / max(0.05, uDetailScale * 0.024));
+  float jgFleckMid = jgVNoise(jgWp / max(0.12, uDetailScale * 0.07) + vec2(51.3, 7.9));
+  jgBase *= mix(1.0 - 0.2 * uStrength, 1.0 + 0.16 * uStrength, jgFine);
+  // Biome patchwork: hue-shifted dry sweeps and cooler wet pockets, tinted per-world via detail.sweeps.
+  jgBase = mix(jgBase, jgBase * uSweepDry, smoothstep(0.5, 0.8, jgMacro) * 0.55 * uStrength);
+  jgBase = mix(jgBase, jgBase * uSweepWet, smoothstep(0.52, 0.85, jgPatch) * 0.5 * uStrength);
+  jgBase *= 1.0 + (jgFbm(jgWp / (uMacroScale * 2.3) + vec2(9.1, 73.4)) - 0.5) * 0.22 * uStrength;
+  jgBase *= 1.0 + (jgFleck - 0.5) * 0.48 * uStrength * jgBand(1.0 / max(0.05, uDetailScale * 0.024));
+  jgBase *= 1.0 + (jgFleckMid - 0.5) * 0.34 * uStrength * jgBand(1.0 / max(0.12, uDetailScale * 0.07));
+}
+
+JgSurf jgS1 = jgSlot(jgI1, jgBase, vJgWorldPos);
+JgSurf jgS2 = jgS1;
+float jgA1 = 1.0;
+float jgA2 = 0.0;
+if (jgTwo) {
+  jgS2 = jgSlot(jgI2, jgBase, vJgWorldPos);
+  float jgB1 = jgW1 / (jgW1 + jgW2);
+  float jgB2 = 1.0 - jgB1;
+  // Height-aware blend: along an edge the layer standing taller (gravel stones, grass clumps) wins
+  // first, so transitions read as one material breaking through another, not a cross-fade.
+  float jgH1 = jgB1 + jgS1.height * 0.5;
+  float jgH2 = jgB2 + jgS2.height * 0.5;
+  float jgM = max(jgH1, jgH2) - 0.28;
+  jgA1 = mix(jgB1, max(0.0, jgH1 - jgM), uSurface);
+  jgA2 = mix(jgB2, max(0.0, jgH2 - jgM), uSurface);
+  float jgT = max(jgA1 + jgA2, 1e-4);
+  jgA1 /= jgT;
+  jgA2 /= jgT;
+}
+vec3 jgCol = jgS1.albedo * jgA1 + jgS2.albedo * jgA2;
+float jgRough = jgS1.rough * jgA1 + jgS2.rough * jgA2;
+float jgBumpH = jgS1.bump * jgA1 + jgS2.bump * jgA2;
+
+// Large-scale light and sun-dried sweeps over painted ground, so a field painted one hue never tiles flat.
+float jgPaintCover = jgPaintTotal * (1.0 - jgRockW) * uSurface;
+jgCol *= 1.0 + (jgFbm2(jgWp / (uMacroScale * 1.3) + vec2(3.7, 61.2)) - 0.5) * 0.3 * jgPaintCover;
+jgCol = mix(jgCol, jgCol * uSweepDry, smoothstep(0.52, 0.78, jgMacro) * 0.2 * jgPaintCover);
+
 float jgSandW = smoothstep(uWaterLevel + 2.4, uWaterLevel - 0.4, jgH) * (1.0 - jgRockW) * uStrength;
-jgCol = mix(jgCol, jgSand, jgSandW);
-vec3 jgSnow = uSnowColor * mix(0.94, 1.04, jgFine);
+jgCol = mix(jgCol, uSandColor * (0.9 + 0.2 * jgMacro), jgSandW);
 float jgSnowW = smoothstep(uSnowHeight, uSnowHeight + 8.0, jgH) * (1.0 - jgRockW * 0.6) * uStrength;
-jgCol = mix(jgCol, jgSnow, jgSnowW);
+jgCol = mix(jgCol, uSnowColor * (0.94 + 0.1 * jgMacro), jgSnowW);
 ${materialColorGlsl}
+float jgContour = 0.5 + 0.5 * cos(jgH / 1.5 * 6.2831853);
+jgCol *= (1.0 - uContour * 0.4 * (1.0 - jgContour)) * (1.0 + clamp(jgH * 0.03, -0.12, 0.22) * uContour);
 diffuseColor.rgb = jgCol;`)
             .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+roughnessFactor = clamp(jgRough, 0.04, 1.0);
 ${materialRoughnessGlsl}`)
             .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${SURFACE_BUMP_NORMAL_GLSL}
 ${materialNormalGlsl}`)
             .replace("#include <aomap_fragment>", `#include <aomap_fragment>
 ${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}`;
-    return { material };
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}-${paint === undefined ? "bare" : "paint"}-${low ? "low" : "full"}-${classMask}`;
+    return { material, contour };
 }

package/dist/terrain/terrainPaintColor.d.ts

@@ -1,11 +1,20 @@
 import * as THREE from "three";
 import type { EditableTerrain } from "@jgengine/core/world/terraform";
-/** Live authored paint channels needed to sample a terrain's material stack without its heightfield. */
-export type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt">;
-/** Writes authored paint into an existing linear color; returns false for unpainted ground. */
+/**
+ * Live authored paint channels needed to sample a terrain's material stack without its heightfield.
+ * With the grid fields present, paint is filtered across neighbouring cells instead of snapping to each cell.
+ */
+export type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt"> & Partial<Pick<EditableTerrain, "gridBounds" | "cols" | "rows">>;
+/**
+ * Blends authored paint over the base ground color already in `out`; returns false (leaving `out`
+ * untouched) where no painted cell contributes.
+ */
 export type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean;
 /**
  * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends
+ * the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`),
+ * so painted paths and clearings get soft edges instead of grid-aligned stair steps.
  * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
  */
 export declare function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler;

package/dist/terrain/terrainPaintColor.js

@@ -1,14 +1,18 @@
 import * as THREE from "three";
 import { TERRAIN_MATERIAL_COLORS } from "@jgengine/core/editor/terrainMaterials";
+const smooth = (t) => t * t * (3 - 2 * t);
 /**
  * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends
+ * the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`),
+ * so painted paths and clearings get soft edges instead of grid-aligned stair steps.
  * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
  */
 export function createTerrainPaintColorSampler(terrain) {
     const layers = terrain.layers;
     const colors = layers.map(layer => new THREE.Color(layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86"));
     const defaults = new Map(Object.entries(TERRAIN_MATERIAL_COLORS).map(([id, color]) => [id, new THREE.Color(color)]));
-    return (x, z, out) => {
+    const cellColor = (x, z, out) => {
         const weights = terrain.weightsAt(x, z);
         if (layers.length > 0 && weights.length === layers.length) {
             let total = 0, r = 0, g = 0, b = 0;
@@ -44,4 +48,45 @@ export function createTerrainPaintColorSampler(terrain) {
         out.copy(color);
         return true;
     };
+    const cols = terrain.cols;
+    const rows = terrain.rows;
+    if (terrain.gridBounds === undefined || cols === undefined || rows === undefined || cols < 2 || rows < 2)
+        return cellColor;
+    const grid = terrain.gridBounds;
+    const cellW = (grid.maxX - grid.minX) / cols;
+    const cellD = (grid.maxZ - grid.minZ) / rows;
+    const base = new THREE.Color();
+    const corner = new THREE.Color();
+    return (x, z, out) => {
+        if (x < grid.minX || x > grid.maxX || z < grid.minZ || z > grid.maxZ)
+            return false;
+        const fx = (x - grid.minX) / cellW - 0.5;
+        const fz = (z - grid.minZ) / cellD - 0.5;
+        const gx = Math.floor(fx);
+        const gz = Math.floor(fz);
+        const tx = smooth(fx - gx);
+        const tz = smooth(fz - gz);
+        base.copy(out);
+        let painted = false, r = 0, g = 0, b = 0;
+        for (let dz = 0; dz <= 1; dz++) {
+            const cz = Math.min(rows - 1, Math.max(0, gz + dz));
+            const wz = dz === 0 ? 1 - tz : tz;
+            for (let dx = 0; dx <= 1; dx++) {
+                const cx = Math.min(cols - 1, Math.max(0, gx + dx));
+                const w = (dx === 0 ? 1 - tx : tx) * wz;
+                if (w <= 0)
+                    continue;
+                corner.copy(base);
+                if (cellColor(grid.minX + (cx + 0.5) * cellW, grid.minZ + (cz + 0.5) * cellD, corner))
+                    painted = true;
+                r += corner.r * w;
+                g += corner.g * w;
+                b += corner.b * w;
+            }
+        }
+        if (!painted)
+            return false;
+        out.setRGB(r, g, b);
+        return true;
+    };
 }

package/dist/terrain/terrainQuality.d.ts

@@ -0,0 +1,5 @@
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/** The player's graphics tier as terrain materials see it; the shell provides it, `high` outside one. */
+export declare const TerrainQualityContext: import("react").Context<GraphicsQuality>;
+/** Graphics tier for terrain surface shading (`low` takes the cheap path). */
+export declare function useTerrainQuality(): GraphicsQuality;

package/dist/terrain/terrainQuality.js

@@ -0,0 +1,7 @@
+import { createContext, useContext } from "react";
+/** The player's graphics tier as terrain materials see it; the shell provides it, `high` outside one. */
+export const TerrainQualityContext = createContext("high");
+/** Graphics tier for terrain surface shading (`low` takes the cheap path). */
+export function useTerrainQuality() {
+    return useContext(TerrainQualityContext);
+}

package/dist/terrain/terrainSurfaceShader.d.ts

@@ -0,0 +1,16 @@
+/** Integer-hash value noise (`jgHashUint`, `jgVNoise`, `jgFbm`) every surface chunk builds on. */
+export declare const NOISE_GLSL = "\nuint jgHashUint(uvec2 v){\n  uint x = v.x * 1664525u + v.y * 1013904223u;\n  x = (x ^ (x >> 16u)) * 2246822519u;\n  x = (x ^ (x >> 13u)) * 3266489917u;\n  x = x ^ (x >> 16u);\n  return x;\n}\nfloat jgHash(vec2 p){\n  ivec2 i = ivec2(floor(p));\n  return float(jgHashUint(uvec2(i))) * (1.0 / 4294967296.0);\n}\nfloat jgVNoise(vec2 p){\n  vec2 i = floor(p); vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = jgHash(i);\n  float b = jgHash(i + vec2(1.0, 0.0));\n  float c = jgHash(i + vec2(0.0, 1.0));\n  float d = jgHash(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\nfloat jgFbm(vec2 p){\n  float v = 0.0; float amp = 0.5;\n  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }\n  return v;\n}\n";
+/**
+ * GLSL for the terrain surface pass: per-surface procedural ground (grass, dirt, gravel, rock, sand,
+ * mud, snow, road) and the height-aware blend between painted layers. Needs `NOISE_GLSL` first.
+ * Every octave is gated by `jgBand(frequency)` so detail finer than a pixel fades to its mean
+ * instead of shimmering at distance.
+ */
+export declare const SURFACE_FUNCTIONS_GLSL = "\nfloat jgFootprint;\nfloat jgFbm2(vec2 p){ return jgVNoise(p) * 0.62 + jgVNoise(p * 2.03 + 17.3) * 0.38; }\nfloat jgFbm3o(vec2 p){ return (jgVNoise(p) * 0.5 + jgVNoise(p * 2.03 + 17.3) * 0.3 + jgVNoise(p * 4.1 + 5.9) * 0.2); }\nfloat jgBand(float freq){ return 1.0 - smoothstep(0.16, 0.42, freq * jgFootprint); }\nvec2 jgHash22(vec2 cell){\n  uint h = jgHashUint(uvec2(ivec2(floor(cell + 0.5))));\n  uint h2 = h * 747796405u + 2891336453u;\n  h2 = (h2 ^ (h2 >> 15u)) * 2246822519u;\n  return vec2(float(h), float(h2 ^ (h2 >> 13u))) * (1.0 / 4294967296.0);\n}\nfloat jgHash3(vec3 i){\n  ivec3 c = ivec3(i);\n  return float(jgHashUint(uvec2(uint(c.x) ^ (uint(c.z) * 2654435761u), uint(c.y) + uint(c.z) * 1013904223u))) * (1.0 / 4294967296.0);\n}\nfloat jgVNoise3(vec3 p){\n  vec3 i = floor(p); vec3 f = fract(p);\n  vec3 u = f * f * (3.0 - 2.0 * f);\n  float a = jgHash3(i), b = jgHash3(i + vec3(1.0, 0.0, 0.0));\n  float c = jgHash3(i + vec3(0.0, 1.0, 0.0)), d = jgHash3(i + vec3(1.0, 1.0, 0.0));\n  float e = jgHash3(i + vec3(0.0, 0.0, 1.0)), g = jgHash3(i + vec3(1.0, 0.0, 1.0));\n  float h = jgHash3(i + vec3(0.0, 1.0, 1.0)), k = jgHash3(i + vec3(1.0, 1.0, 1.0));\n  return mix(mix(mix(a, b, u.x), mix(c, d, u.x), u.y), mix(mix(e, g, u.x), mix(h, k, u.x), u.y), u.z);\n}\nfloat jgFbm3(vec3 p){\n  float v = 0.0; float amp = 0.5;\n  for (int i = 0; i < 3; i++){ v += amp * jgVNoise3(p); p = p * 2.03 + vec3(1.7, 9.2, 4.1); amp *= 0.5; }\n  return v / 0.875;\n}\n// x: distance to the nearest feature point, y: F2 - F1 (0 on a cell border), z: that cell's random id.\nvec3 jgVoronoi(vec2 p){\n  vec2 n = floor(p); vec2 f = fract(p);\n  float d1 = 8.0; float d2 = 8.0; float id = 0.0;\n  for (int j = -1; j <= 1; j++){\n    for (int i = -1; i <= 1; i++){\n      vec2 g = vec2(float(i), float(j));\n      vec2 o = jgHash22(n + g);\n      vec2 r = g + 0.15 + o * 0.7 - f;\n      float d = dot(r, r);\n      if (d < d1){ d2 = d1; d1 = d; id = o.x; } else if (d < d2){ d2 = d; }\n    }\n  }\n  d1 = sqrt(d1);\n  return vec3(d1, sqrt(d2) - d1, id);\n}\n\nstruct JgSurf { vec3 albedo; float height; float rough; float bump; };\n\n// height: 0..1 relief used to decide which layer wins along a blend edge; bump: displacement in metres.\nJgSurf jgSurface(int cls, vec3 color, float rough, float scale, vec3 wp){\n  vec2 p = wp.xz * scale;\n  JgSurf s;\n  s.albedo = color; s.rough = rough; s.height = 0.4; s.bump = 0.0;\n  float m = jgFbm3o(p / 1.6 + float(cls) * 13.7);\n#ifdef JG_SURFACE_LOW\n  s.albedo = color * (0.84 + 0.34 * m);\n  s.height = m;\n  return s;\n#else\n  bool shaded = false;\n#if (JG_SURFACE_CLASSES & 2) != 0\n  if (cls == 1) {\n    float clump = jgFbm3o(p / 0.9 + 5.3);\n    float dry = smoothstep(0.5, 0.75, jgFbm2(p / 7.0 + 17.0));\n    float blade = jgVNoise(p * 11.0 + clump * 3.0);\n    float fine = jgVNoise(p * 27.0 + 91.0);\n    float bBlade = jgBand(11.0);\n    s.albedo = mix(color, color * vec3(1.24, 1.12, 0.7), dry * 0.55);\n    s.albedo *= 0.74 + 0.48 * clump;\n    s.albedo = mix(s.albedo, color * vec3(0.78, 0.64, 0.46), smoothstep(0.42, 0.24, clump) * 0.25);\n    s.albedo *= 1.0 + (blade - 0.5) * 0.5 * bBlade + (fine - 0.5) * 0.32 * jgBand(27.0);\n    s.height = 0.2 + clump * 0.55 + blade * 0.25 * bBlade;\n    s.bump = clump * 0.014 + blade * 0.008 * bBlade;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 4) != 0\n  if (cls == 2) {\n    float clod = jgVNoise(p * 3.0 + m * 2.0);\n    float crumb = jgVNoise(p * 14.0 + 7.0);\n    vec3 v = jgVoronoi(p * 2.2 + 7.7);\n    float peb = (1.0 - smoothstep(0.1, 0.2, v.x)) * step(0.7, v.z) * jgBand(7.0);\n    s.albedo = color * (0.78 + 0.44 * m);\n    s.albedo *= 1.0 + (clod - 0.5) * 0.32 * jgBand(3.0) + (crumb - 0.5) * 0.24 * jgBand(14.0);\n    s.albedo = mix(s.albedo, color * vec3(1.34, 1.3, 1.24) + 0.02, peb * 0.75);\n    s.height = 0.05 + m * 0.4 + clod * 0.2 + peb * 0.5;\n    s.bump = clod * 0.012 * jgBand(3.0) + crumb * 0.003 * jgBand(14.0) + peb * 0.012;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 8) != 0\n  if (cls == 3) {\n    // Round pebbles from F1 distance (not Voronoi cells, which read as flagstone paving), two sizes,\n    // packed over darker grit.\n    vec3 va = jgVoronoi(p * 5.5);\n    float ra = 0.28 + 0.18 * fract(va.z * 13.1);\n    float sa = 1.0 - smoothstep(ra * 0.72, ra, va.x);\n    float da = sqrt(max(0.0, 1.0 - (va.x / ra) * (va.x / ra))) * sa;\n    vec3 vb = jgVoronoi(p * 11.0 + 3.1);\n    float rb = 0.32 + 0.14 * fract(vb.z * 7.7);\n    float sb = (1.0 - smoothstep(rb * 0.66, rb, vb.x)) * (1.0 - sa);\n    float db = sqrt(max(0.0, 1.0 - (vb.x / rb) * (vb.x / rb))) * sb;\n    float grit = jgVNoise(p * 24.0);\n    float bA = jgBand(5.5);\n    float bB = jgBand(11.0);\n    vec3 hueA = mix(vec3(1.08, 1.0, 0.9), vec3(0.92, 0.97, 1.08), fract(va.z * 7.13));\n    vec3 hueB = mix(vec3(1.05, 1.0, 0.93), vec3(0.95, 0.98, 1.05), fract(vb.z * 5.71));\n    vec3 near = color * (0.58 + 0.2 * grit);\n    near = mix(near, color * hueB * (0.66 + 0.5 * vb.z) * (0.72 + 0.28 * db), sb * bB);\n    near = mix(near, color * hueA * (0.64 + 0.62 * va.z) * (0.7 + 0.3 * da), sa);\n    s.albedo = mix(color * (0.8 + 0.26 * m), near, bA);\n    s.height = 0.3 + max(da, db * 0.6 * bB) * 0.6 * bA;\n    s.bump = (da * 0.03 + db * 0.012 * bB) * bA;\n    s.rough = rough - 0.08 * sa * bA;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 16) != 0\n  if (cls == 4) {\n    vec3 q = wp * scale;\n    float n = jgFbm3(q / 1.8);\n    float n2 = jgFbm3(q * 1.7 + 5.0);\n    float grain = jgVNoise3(q * 9.0);\n    float strata = sin(q.y * 2.6 + n * 5.0) * 0.5 + 0.5;\n    float pits = smoothstep(0.72, 0.9, jgVNoise3(q * 4.3 + 11.0)) * jgBand(4.3);\n    float lichen = smoothstep(0.6, 0.78, jgFbm2(p / 3.0 + 41.0));\n    s.albedo = color * (0.4 + 1.25 * n) * (0.8 + 0.4 * n2 * jgBand(3.4)) * (1.0 - pits * 0.35) * (0.94 + strata * 0.12);\n    s.albedo *= 1.0 + (grain - 0.5) * 0.3 * jgBand(9.0);\n    s.albedo = mix(s.albedo, s.albedo * vec3(0.92, 1.06, 0.82), lichen * 0.45);\n    s.height = 0.35 + n * 0.65;\n    s.bump = n * 0.1 + n2 * 0.02 * jgBand(3.4) - pits * 0.006 + grain * 0.004 * jgBand(9.0);\n    s.rough = rough - 0.1 * n;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 32) != 0\n  if (cls == 5) {\n    float warp = jgFbm2(p / 3.0 + 3.3);\n    float ripple = sin((p.x * 0.83 + p.y * 0.56) * 6.0 + warp * 7.0) * 0.5 + 0.5;\n    float grain = jgVNoise(p * 40.0);\n    float bRipple = jgBand(1.0);\n    s.albedo = color * (0.92 + 0.16 * m) * (1.0 + (ripple - 0.5) * 0.1 * bRipple);\n    float speck = jgVNoise(p * 9.0 + 2.7);\n    s.albedo *= 1.0 + (grain - 0.5) * 0.14 * jgBand(40.0) + (speck - 0.5) * 0.12 * jgBand(9.0);\n    s.height = 0.05 + ripple * 0.25 + m * 0.2;\n    s.bump = ripple * 0.012 * bRipple;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 64) != 0\n  if (cls == 6) {\n    float puddle = smoothstep(0.56, 0.66, jgFbm3o(p / 3.2 + 31.0));\n    float lumps = jgVNoise(p * 4.0 + m);\n    s.albedo = color * (0.8 + 0.38 * m) * (1.0 + (lumps - 0.5) * 0.26 * jgBand(4.0));\n    s.albedo = mix(s.albedo, s.albedo * 0.58, puddle);\n    s.rough = mix(rough, 0.22, puddle);\n    s.height = (0.1 + m * 0.4 + lumps * 0.2) * (1.0 - puddle * 0.8);\n    s.bump = lumps * 0.012 * jgBand(4.0) * (1.0 - puddle);\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 128) != 0\n  if (cls == 7) {\n    float drift = jgFbm2(p / 4.0 + 9.0);\n    s.albedo = color * (0.93 + 0.1 * m + 0.04 * drift);\n    s.height = 0.3 + drift * 0.5;\n    s.bump = drift * 0.03 + m * 0.01;\n    shaded = true;\n  }\n#endif\n#if (JG_SURFACE_CLASSES & 256) != 0\n  if (cls == 8) {\n    float grain = jgVNoise(p * 30.0);\n    float stain = jgFbm2(p / 5.0 + 2.0);\n    s.albedo = color * (0.88 + 0.22 * stain) * (1.0 + (grain - 0.5) * 0.2 * jgBand(30.0));\n    s.height = 0.2 + stain * 0.2;\n    s.bump = grain * 0.0015 * jgBand(30.0);\n    shaded = true;\n  }\n#endif\n  if (!shaded) {\n    float fine = jgVNoise(p * 6.0 + 3.0);\n    s.albedo = color * (1.0 + (fine - 0.5) * 0.18 * jgBand(6.0));\n    s.height = 0.25 + m * 0.4;\n    s.bump = m * 0.02 + fine * 0.004 * jgBand(6.0);\n  }\n  return s;\n#endif\n}\n";
+/** Paint-coverage uniforms and the warped, smoothed cell lookup. */
+export declare const PAINT_PARS_GLSL = "\nuniform sampler2D uPaintA;\nuniform sampler2D uPaintB;\nuniform vec2 uPaintMin;\nuniform vec2 uPaintCell;\nuniform vec2 uPaintGrid;\nuniform float uPaintWarp;\nuniform vec3 uLayerColor[8];\nuniform float uLayerClass[8];\nuniform float uLayerRough[8];\nuniform float uLayerScale[8];\nfloat jgWarpNoise(vec2 p){ return (jgVNoise(p) * 0.65 + jgVNoise(p * 2.7 + 13.1) * 0.35) - 0.5; }\nvec2 jgPaintUv(vec2 wp){\n  vec2 cell = (wp - uPaintMin) / uPaintCell;\n  cell += vec2(jgWarpNoise(wp / 2.3 + 4.1), jgWarpNoise(wp / 2.3 + vec2(19.7, 3.3))) * uPaintWarp;\n  vec2 c = cell - 0.5;\n  vec2 i = floor(c); vec2 f = fract(c);\n  f = f * f * (3.0 - 2.0 * f);\n  return (i + f + 0.5) / uPaintGrid;\n}\n";
+/**
+ * Micro-normal from a surface height `jgBumpH` (metres) via screen-space derivatives; goes after
+ * `normal_fragment_maps`. Skipped on the low tier.
+ */
+export declare const SURFACE_BUMP_NORMAL_GLSL = "\n#ifndef JG_SURFACE_LOW\n{\n  // Bump from the blended surface height (metres) via screen-space derivatives, unnormalised so the\n  // tilt is the true world slope of that height field at any distance.\n  vec3 jgSigX = dFdx(-vViewPosition);\n  vec3 jgSigY = dFdy(-vViewPosition);\n  vec2 jgDh = vec2(dFdx(jgBumpH), dFdy(jgBumpH));\n  vec3 jgR1 = cross(jgSigY, normal);\n  vec3 jgR2 = cross(normal, jgSigX);\n  float jgDet = dot(jgSigX, jgR1) * faceDirection;\n  vec3 jgGrad = sign(jgDet) * (jgDh.x * jgR1 + jgDh.y * jgR2);\n  normal = normalize(abs(jgDet) * normal - jgGrad);\n}\n#endif\n";