@jgengine/shell 0.22.0 → 0.23.0

package/dist/terrain/index.js

@@ -10,3 +10,7 @@ export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";
 export { createTerrainPaintColorSampler } from "./terrainPaintColor.js";
+export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, } from "./terrainDetailMaterial.js";
+export { createTerrainPaintTextures, MAX_TERRAIN_PAINT_LAYERS, packTerrainPaintWeights, terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness, } from "./terrainSurfaces.js";
+export { TerrainQualityContext, useTerrainQuality } from "./terrainQuality.js";
+export { createSurfaceRibbonMaterial, resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonEdgeMargin, ribbonSurfaceFrame, useSurfaceRibbonMaterial, } from "./surfaceRibbonMaterial.js";

package/dist/terrain/surfaceRibbonMaterial.d.ts

@@ -0,0 +1,62 @@
+import * as THREE from "three";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export declare const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+/** How a ground ribbon (path, road, sidewalk) shades: procedural surface, edge blend and wear. */
+export interface RibbonSurfaceStyle {
+    /** Surface id classified like terrain paint (`"dirt"`, `"gravel"`, `"asphalt"`, …). */
+    surface: string;
+    /** Width of the edge fade in metres, centred on the authored edge. 0 keeps a hard opaque edge. */
+    feather: number;
+    /** How far noise pushes the edge in or out, in metres. */
+    warp: number;
+    /** Wheel ruts on soft ground, polished tyre lanes on pavement, 0..1. */
+    wear: number;
+}
+/** Options for {@link createSurfaceRibbonMaterial}. */
+export interface SurfaceRibbonMaterialOptions extends Partial<RibbonSurfaceStyle> {
+    /** Authored hue; the procedural surface varies around it. */
+    color: string;
+    /** Authored half width in metres; the edge fade is centred on it. */
+    halfWidth: number;
+    /** Override the surface class's default roughness. */
+    roughness?: number;
+    /** Pattern frequency multiplier. Default 1. */
+    scale?: number;
+    /** Graphics tier, from `useTerrainQuality()`. `low` drops micro-normals and fine octaves. Default `high`. */
+    quality?: GraphicsQuality;
+    /** Pull the ribbon toward the camera in depth so it wins over a coplanar layer beneath. */
+    polygonOffset?: boolean;
+    /** Multiply by the geometry's `color` attribute, as city ground meshes carry per-vertex tints. */
+    vertexColors?: boolean;
+}
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export declare function resolvePathSurface(kind: string, width: number, meta: Readonly<Record<string, unknown>> | undefined): RibbonSurfaceStyle | null;
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export declare function ribbonEdgeMargin(style: Pick<RibbonSurfaceStyle, "feather" | "warp">): number;
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export declare function ribbonSurfaceFrame(ribbons: readonly Float32Array[]): Float32Array;
+/**
+ * A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own
+ * procedural surface functions, so a dirt track or asphalt strip matches painted ground: the
+ * authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre
+ * lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs
+ * a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by
+ * {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
+ */
+export declare function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial;
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export declare function useSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions | null): THREE.MeshStandardMaterial | null;

package/dist/terrain/surfaceRibbonMaterial.js

@@ -0,0 +1,227 @@
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { NOISE_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+import { terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness } from "./terrainSurfaces.js";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+const SOFT_GROUND = new Set(["dirt", "mud", "sand", "gravel", "grass", "ground", "snow"]);
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export function resolvePathSurface(kind, width, meta) {
+    if (meta?.["surfaceDetail"] === false || meta?.["surface"] === false)
+        return null;
+    const id = typeof meta?.["surface"] === "string" ? meta["surface"] : kind;
+    const classified = terrainSurfaceClass(id);
+    const cls = classified === "ground" ? "dirt" : classified;
+    const surface = classified === "ground" ? "dirt" : id;
+    const soft = SOFT_GROUND.has(cls);
+    const softness = typeof meta?.["edgeSoftness"] === "number" ? Math.max(0, meta["edgeSoftness"]) : 1;
+    const feather = (soft ? clamp(width * 0.18, 0.35, 1.6) : clamp(width * 0.04, 0.08, 0.3)) * softness;
+    const warp = (soft ? clamp(width * 0.08, 0.15, 0.6) : 0.03) * softness;
+    const wear = typeof meta?.["wear"] === "number" ? clamp(meta["wear"], 0, 1) : soft ? 1 : 0.6;
+    return { surface, feather, warp, wear };
+}
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export function ribbonEdgeMargin(style) {
+    return style.feather + style.warp * 2;
+}
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export function ribbonSurfaceFrame(ribbons) {
+    const total = ribbons.reduce((sum, positions) => sum + positions.length, 0);
+    const out = new Float32Array(total);
+    let offset = 0;
+    for (const p of ribbons) {
+        const pairs = Math.floor(p.length / 6);
+        let along = 0;
+        let px = 0;
+        let pz = 0;
+        for (let i = 0; i < pairs; i++) {
+            const b = i * 6;
+            const cx = (p[b] + p[b + 3]) / 2;
+            const cz = (p[b + 2] + p[b + 5]) / 2;
+            if (i > 0)
+                along += Math.hypot(cx - px, cz - pz);
+            px = cx;
+            pz = cz;
+            const half = Math.hypot(p[b] - p[b + 3], p[b + 2] - p[b + 5]) / 2;
+            out[offset + b] = along;
+            out[offset + b + 1] = half;
+            out[offset + b + 3] = along;
+            out[offset + b + 4] = -half;
+        }
+        for (let i = 0; i < pairs; i++) {
+            const b = offset + i * 6;
+            out[b + 2] = along - out[b];
+            out[b + 5] = along - out[b + 3];
+        }
+        offset += p.length;
+    }
+    return out;
+}
+const RIBBON_FRAGMENT_GLSL = /* glsl */ `
+vec2 jgWp = vJgWorldPos.xz;
+jgFootprint = max(length(dFdx(vJgWorldPos)), length(dFdy(vJgWorldPos)));
+JgSurf jgS = jgSurface(JG_RIBBON_CLASS, diffuseColor.rgb, uJgRough, uJgScale, vJgWorldPos);
+vec3 jgCol = jgS.albedo;
+float jgRough = jgS.rough;
+float jgBumpH = jgS.bump;
+float jgAcross = vJgRibbon.y;
+jgCol *= 1.0 + (jgFbm2(jgWp / 14.0 + vec2(3.7, 61.2)) - 0.5) * 0.24;
+#if defined(JG_RIBBON_PAVED) && !defined(JG_SURFACE_LOW)
+{
+  // Weathered pavement: resurfaced patches, exposed aggregate and a partial crack network.
+  jgCol *= 1.0 + (jgFbm3o(jgWp / 5.0 + 11.0) - 0.5) * 0.34;
+  jgCol *= 1.0 + (jgVNoise(jgWp * 16.0) - 0.5) * 0.26 * jgBand(16.0);
+  vec3 jgCell = jgVoronoi(jgWp * 0.32 + 5.1);
+  float jgCrack = (1.0 - smoothstep(0.0, 0.03, jgCell.y)) * smoothstep(0.45, 0.6, jgVNoise(jgWp * 0.45 + 3.3)) * jgBand(2.0);
+  jgCol *= 1.0 - 0.4 * jgCrack;
+  jgRough += 0.05 * jgCrack;
+  jgBumpH -= jgCrack * 0.004;
+}
+#endif
+#ifdef JG_RIBBON_WEAR
+{
+  // Two wheel tracks a cart-axle apart, wandering together along the ribbon.
+  float jgWob = (jgVNoise(vec2(vJgRibbon.x * 0.09, 4.7)) - 0.5) * uJgHalfWidth * 0.35;
+  float jgRutD = abs(abs(jgAcross - jgWob) - uJgHalfWidth * 0.45);
+  float jgRutW = max(0.15, uJgHalfWidth * 0.14);
+  float jgRut = exp(-(jgRutD * jgRutD) / (jgRutW * jgRutW)) * (0.55 + 0.45 * jgVNoise(vec2(vJgRibbon.x * 0.4, 9.1))) * uJgWear;
+#ifdef JG_RIBBON_PAVED
+  jgCol *= 1.0 - 0.22 * jgRut;
+  jgRough -= 0.16 * jgRut;
+#else
+  // Trodden band: packed flat, fewer loose grains and a little dustier, so the track reads against
+  // painted dirt of the same hue; then darker ruts and loose soil heaped toward the shoulders.
+  float jgTrod = (1.0 - smoothstep(uJgHalfWidth * 0.5, uJgHalfWidth * 0.95, abs(jgAcross))) * uJgWear;
+  jgCol = mix(jgCol, diffuseColor.rgb * (0.96 + 0.12 * jgFbm2(jgWp * 0.7 + 2.9)), 0.5 * jgTrod);
+  jgCol *= 1.0 + 0.08 * jgTrod;
+  jgBumpH *= 1.0 - 0.6 * jgTrod;
+  jgCol *= 1.0 - 0.32 * jgRut;
+  jgRough -= 0.12 * jgRut;
+  jgBumpH -= jgRut * 0.03;
+  float jgShoulder = smoothstep(uJgHalfWidth * 0.6, uJgHalfWidth, abs(jgAcross)) * uJgWear;
+  jgCol *= 1.0 - 0.16 * jgShoulder;
+  jgBumpH += jgShoulder * 0.014;
+#endif
+}
+#endif
+#ifdef JG_RIBBON_EDGE
+{
+  float jgEdgeN = (jgFbm2(jgWp * 0.55 + 7.3) - 0.5) * 2.0 + (jgVNoise(jgWp * 2.3 + 1.7) - 0.5) * 0.6;
+  float jgEdge = uJgHalfWidth + jgEdgeN * uJgWarp;
+  float jgAlpha = 1.0 - smoothstep(jgEdge - uJgFeather * 0.5, jgEdge + uJgFeather * 0.5, abs(jgAcross));
+  jgAlpha *= smoothstep(0.0, uJgFeather, min(vJgRibbon.x, vJgRibbon.z) + jgEdgeN * uJgWarp);
+  // Taller grains (pebbles, clods) hold on longer, so the edge breaks up instead of fading evenly.
+  jgAlpha = clamp(jgAlpha + (jgS.height - 0.4) * 2.4 * jgAlpha * (1.0 - jgAlpha), 0.0, 1.0);
+  diffuseColor.a *= jgAlpha;
+  jgBumpH *= jgAlpha;
+}
+#endif
+#ifdef USE_COLOR_ALPHA
+{
+  // A per-vertex fade interpolated across big triangles draws straight iso-lines; warp it with noise
+  // so it breaks up like painted terrain. Fully opaque or fully clear vertices are left alone.
+  float jgA = diffuseColor.a;
+  float jgMid = min(jgA, 1.0 - jgA);
+  float jgFadeN = jgFbm2(jgWp * 0.35 + 21.7) - 0.5 + (jgVNoise(jgWp * 1.7 + 5.3) - 0.5) * 0.4;
+  diffuseColor.a = clamp(jgA + jgFadeN * min(1.0, jgMid * 4.0) * 1.1, 0.0, 1.0);
+  diffuseColor.a = smoothstep(0.08, 0.92, diffuseColor.a);
+}
+#endif
+diffuseColor.rgb = jgCol;
+`;
+/**
+ * A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own
+ * procedural surface functions, so a dirt track or asphalt strip matches painted ground: the
+ * authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre
+ * lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs
+ * a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by
+ * {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
+ */
+export function createSurfaceRibbonMaterial(options) {
+    const cls = terrainSurfaceClass(options.surface ?? "road");
+    const classIndex = terrainSurfaceClassIndex(cls);
+    const low = options.quality === "low";
+    const feather = Math.max(0, options.feather ?? 0);
+    const edge = feather > 0;
+    const wear = clamp(options.wear ?? 0, 0, 1);
+    const paved = cls === "road" || cls === "rock";
+    const roughness = options.roughness ?? terrainSurfaceRoughness(cls);
+    const material = new THREE.MeshStandardMaterial({
+        color: options.color,
+        roughness,
+        metalness: 0,
+        side: THREE.DoubleSide,
+        transparent: edge,
+        vertexColors: options.vertexColors === true,
+        ...(options.polygonOffset === true ? { polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 } : {}),
+    });
+    const uniforms = {
+        uJgRough: { value: roughness },
+        uJgScale: { value: options.scale ?? 1 },
+        uJgHalfWidth: { value: Math.max(0.01, options.halfWidth) },
+        uJgFeather: { value: Math.max(1e-3, feather) },
+        uJgWarp: { value: Math.max(0, options.warp ?? 0) },
+        uJgWear: { value: wear },
+    };
+    material.defines = {
+        JG_RIBBON_CLASS: String(classIndex),
+        JG_SURFACE_CLASSES: String(1 << classIndex),
+        ...(low ? { JG_SURFACE_LOW: "" } : {}),
+        ...(edge ? { JG_RIBBON_EDGE: "" } : {}),
+        ...(wear > 0 ? { JG_RIBBON_WEAR: "" } : {}),
+        ...(paved ? { JG_RIBBON_PAVED: "" } : {}),
+    };
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+attribute vec3 ${RIBBON_FRAME_ATTRIBUTE};
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;
+vJgRibbon = ${RIBBON_FRAME_ATTRIBUTE};`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;
+uniform float uJgRough;
+uniform float uJgScale;
+uniform float uJgHalfWidth;
+uniform float uJgFeather;
+uniform float uJgWarp;
+uniform float uJgWear;
+${NOISE_GLSL}
+${SURFACE_FUNCTIONS_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>\n${RIBBON_FRAGMENT_GLSL}`)
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+roughnessFactor = clamp(jgRough, 0.04, 1.0);`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${SURFACE_BUMP_NORMAL_GLSL}`);
+    };
+    material.customProgramCacheKey = () => `jgengine-surface-ribbon-${classIndex}-${low ? "low" : "full"}-${edge ? "edge" : "hard"}-${wear > 0 ? "wear" : "clean"}`;
+    return material;
+}
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export function useSurfaceRibbonMaterial(options) {
+    const o = options;
+    const material = useMemo(() => (o === null ? null : createSurfaceRibbonMaterial(o)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [o === null, o?.color, o?.halfWidth, o?.surface, o?.feather, o?.warp, o?.wear, o?.roughness, o?.scale, o?.quality, o?.polygonOffset, o?.vertexColors]);
+    useEffect(() => () => material?.dispose(), [material]);
+    return material;
+}

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 };
 }