@jgengine/shell 0.10.0 → 0.12.0

package/dist/terrain/heightfieldGeometry.js

@@ -0,0 +1,109 @@
+import * as THREE from "three";
+const EXTENT_KEY = "jgHeightfieldExtent";
+/**
+ * Re-samples a `PlaneGeometry(width, depth, segments, segments).rotateX(-π/2)` heightfield mesh
+ * from a `sampleHeight` field in place: vertex Y, optional vertex color, grid central-difference
+ * normals, and an analytically maintained bounding sphere. With a dirty `region`, the work is
+ * O(region vertices) — heights/colors update inside the covering vertex window, normals inside the
+ * window plus a one-vertex ring — never a whole-mesh `computeVertexNormals`/`computeBoundingSphere`
+ * pass, which is what keeps per-frame brush stamps inside the editor's frame budget. The bounding
+ * sphere derives from the fixed plane extents plus a running height range kept on
+ * `geometry.userData`; partial passes only expand it, a full pass resets it exactly.
+ * @capability heightfield-mesh-update in-place partial update of a displaced ground plane mesh
+ */
+export function displaceHeightfieldGeometry(geometry, sampleHeight, options) {
+    const position = geometry.attributes.position;
+    const normals = geometry.attributes.normal;
+    const { bounds } = options;
+    const cx = (bounds.minX + bounds.maxX) / 2;
+    const cz = (bounds.minZ + bounds.maxZ) / 2;
+    const width = Math.max(1, bounds.maxX - bounds.minX);
+    const depth = Math.max(1, bounds.maxZ - bounds.minZ);
+    // PlaneGeometry(w, d, s, s) rotated -π/2 about X is a (s+1)² row-major grid: x fastest ascending,
+    // z ascending per row (verified by heightfieldGeometry.test.ts against the three.js constructor).
+    const side = Math.round(Math.sqrt(position.count));
+    const segments = Math.max(1, side - 1);
+    const stepX = width / segments;
+    const stepZ = depth / segments;
+    let colors = geometry.attributes.color;
+    const wantColors = options.color !== undefined;
+    const colorsMissing = wantColors && (colors === undefined || colors.count !== position.count);
+    const region = options.region ?? null;
+    const full = region === null || colorsMissing;
+    if (colorsMissing) {
+        colors = new THREE.BufferAttribute(new Float32Array(position.count * 3), 3);
+        geometry.setAttribute("color", colors);
+    }
+    const clampCell = (value) => (value < 0 ? 0 : value > segments ? segments : value);
+    const col0 = full ? 0 : clampCell(Math.floor(((region.minX - bounds.minX) / width) * segments));
+    const col1 = full ? segments : clampCell(Math.ceil(((region.maxX - bounds.minX) / width) * segments));
+    const row0 = full ? 0 : clampCell(Math.floor(((region.minZ - bounds.minZ) / depth) * segments));
+    const row1 = full ? segments : clampCell(Math.ceil(((region.maxZ - bounds.minZ) / depth) * segments));
+    const tone = new THREE.Color();
+    let windowMin = Infinity;
+    let windowMax = -Infinity;
+    for (let row = row0; row <= row1; row += 1) {
+        const base = row * side;
+        for (let col = col0; col <= col1; col += 1) {
+            const index = base + col;
+            const x = position.getX(index) + cx;
+            const z = position.getZ(index) + cz;
+            const height = sampleHeight(x, z);
+            position.setY(index, height);
+            if (height < windowMin)
+                windowMin = height;
+            if (height > windowMax)
+                windowMax = height;
+            if (options.color !== undefined) {
+                options.color(x, z, height, tone);
+                colors.setXYZ(index, tone.r, tone.g, tone.b);
+            }
+        }
+    }
+    // Grid central-difference normals over the window plus a one-vertex ring — a height change moves
+    // its neighbors' normals too. Matches smooth shading without a whole-mesh triangle pass.
+    const nc0 = Math.max(0, col0 - 1);
+    const nc1 = Math.min(segments, col1 + 1);
+    const nr0 = Math.max(0, row0 - 1);
+    const nr1 = Math.min(segments, row1 + 1);
+    for (let row = nr0; row <= nr1; row += 1) {
+        const rowD = Math.max(0, row - 1);
+        const rowU = Math.min(segments, row + 1);
+        for (let col = nc0; col <= nc1; col += 1) {
+            const colL = Math.max(0, col - 1);
+            const colR = Math.min(segments, col + 1);
+            const hL = position.getY(row * side + colL);
+            const hR = position.getY(row * side + colR);
+            const hD = position.getY(rowD * side + col);
+            const hU = position.getY(rowU * side + col);
+            const nx = -(hR - hL) / Math.max(1e-6, (colR - colL) * stepX);
+            const nz = -(hU - hD) / Math.max(1e-6, (rowU - rowD) * stepZ);
+            const inv = 1 / Math.sqrt(nx * nx + 1 + nz * nz);
+            normals.setXYZ(row * side + col, nx * inv, inv, nz * inv);
+        }
+    }
+    const extent = geometry.userData[EXTENT_KEY] ?? {
+        minY: Infinity,
+        maxY: -Infinity,
+    };
+    if (full) {
+        extent.minY = windowMin;
+        extent.maxY = windowMax;
+    }
+    else {
+        extent.minY = Math.min(extent.minY, windowMin);
+        extent.maxY = Math.max(extent.maxY, windowMax);
+    }
+    geometry.userData[EXTENT_KEY] = extent;
+    const hasExtent = extent.minY <= extent.maxY;
+    const midY = hasExtent ? (extent.minY + extent.maxY) / 2 : 0;
+    const halfY = hasExtent ? (extent.maxY - extent.minY) / 2 : 0;
+    if (geometry.boundingSphere === null)
+        geometry.boundingSphere = new THREE.Sphere();
+    geometry.boundingSphere.center.set(0, midY, 0);
+    geometry.boundingSphere.radius = Math.sqrt((width / 2) ** 2 + (depth / 2) ** 2 + halfY ** 2);
+    position.needsUpdate = true;
+    if (colors !== undefined && wantColors)
+        colors.needsUpdate = true;
+    normals.needsUpdate = true;
+}

package/dist/terrain/index.d.ts

@@ -2,6 +2,7 @@ export { CarvedTerrain, type CarvedTerrainProps } from "./CarvedTerrain.js";
 export { GrassField, type GrassFieldProps } from "./GrassField.js";
 export { ProceduralGround, type ProceduralGroundProps } from "./ProceduralGround.js";
 export { EditableGround, type EditableGroundProps } from "./EditableGround.js";
+export { displaceHeightfieldGeometry, type HeightfieldColorFn, type HeightfieldDisplaceOptions, type HeightfieldRect, } from "./heightfieldGeometry.js";
 export { TerraformBrushCursor, type TerraformBrushCursorProps } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, type GrassBladeGeometryOptions, type GrassRange, type ResolvedGrassBladeGeometryOptions, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMaterialHandle, type GrassMaterialOptions, type GrassShaderUniforms, type GrassWindOptions, } from "./grassMaterial.js";

package/dist/terrain/index.js

@@ -2,6 +2,7 @@ export { CarvedTerrain } from "./CarvedTerrain.js";
 export { GrassField } from "./GrassField.js";
 export { ProceduralGround } from "./ProceduralGround.js";
 export { EditableGround } from "./EditableGround.js";
+export { displaceHeightfieldGeometry, } from "./heightfieldGeometry.js";
 export { TerraformBrushCursor } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./grassMaterial.js";

package/dist/terrain/random.d.ts

@@ -1,4 +1,7 @@
 export type TerrainSeed = number | string;
+/** @internal */
 export declare function seedToUint32(seed?: TerrainSeed): number;
+/** @internal */
 export declare function createSeededRandom(seed?: TerrainSeed): () => number;
+/** @internal */
 export declare function hashNoise2(x: number, z: number, seed?: TerrainSeed): number;

package/dist/terrain/random.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function seedToUint32(seed = 1) {
     if (typeof seed === "number")
         return seed >>> 0;
@@ -8,6 +9,7 @@ export function seedToUint32(seed = 1) {
     }
     return hash >>> 0;
 }
+/** @internal */
 export function createSeededRandom(seed = 1) {
     let state = seedToUint32(seed);
     return () => {
@@ -18,6 +20,7 @@ export function createSeededRandom(seed = 1) {
         return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
     };
 }
+/** @internal */
 export function hashNoise2(x, z, seed = 1) {
     let hash = seedToUint32(seed);
     hash ^= Math.imul(x | 0, 374761393);

package/dist/terrain/soilPatchMaterial.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+import type { SoilRules } from "@jgengine/core/world/soilKind";
+/** Optional noise-eroded edge-fade config for {@link createSoilPatchMaterial} — the patch dissolves into the ground at its border. */
+export interface SoilPatchEdge {
+    /** Patch center on XZ, world units — with `halfSize`, drives the noise-eroded edge fade. */
+    center: readonly [number, number];
+    /** Patch half extents on XZ, world units. */
+    halfSize: readonly [number, number];
+    /** Fade band width in meters from the patch border inward. Default 1.6. */
+    fade?: number;
+    /** Terrain color under the patch: the border blends its *color* toward the ground it meets, not just its alpha. Defaults to the soil base color (color blend off). */
+    groundColor?: string;
+}
+/**
+ * A `MeshStandardMaterial` for one authored `soil` volume: a base dirt tint with a Worley crack-line
+ * network and an FBM moss-patch overlay injected via `onBeforeCompile`, seeded from `rules.seed`. Full
+ * PBR — lit, shadowed, fogged — like the terrain detail material it borrows its noise machinery from.
+ * Pass `edge` to add a noise-eroded alpha fade at the patch border (the draped scene-kind renderer
+ * does) so the patch blends into the surrounding ground. A game never calls this directly — author a
+ * soil patch via the editor's `soil` studio kind.
+ * @internal
+ */
+export declare function createSoilPatchMaterial(rules: SoilRules, edge?: SoilPatchEdge): THREE.MeshStandardMaterial;

package/dist/terrain/soilPatchMaterial.js

@@ -0,0 +1,147 @@
+import * as THREE from "three";
+/**
+ * Worley (F1/F2 cellular) crack mask + FBM moss mask — the same noise-driven-shader technique as
+ * `terrainDetailMaterial.ts`'s rock/sand/snow blend, injected here via `onBeforeCompile` into a
+ * dedicated soil-patch material instead of the whole-ground detail material. `F2 - F1` (the gap
+ * between nearest and second-nearest Worley feature distances) goes to zero right at a cell boundary,
+ * which reads as a network of cracked-earth veins once thresholded — the standard "cracked ground"
+ * shader trick.
+ */
+const SOIL_NOISE_GLSL = /* glsl */ `
+uint jgSoilHashUint(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 jgSoilHash1(vec2 p){
+  return float(jgSoilHashUint(uvec2(floor(p)))) * (1.0 / 4294967296.0);
+}
+vec2 jgSoilHash2(vec2 p){
+  uvec2 base = uvec2(floor(p));
+  float a = float(jgSoilHashUint(base)) * (1.0 / 4294967296.0);
+  float b = float(jgSoilHashUint(base + uvec2(19u, 47u))) * (1.0 / 4294967296.0);
+  return vec2(a, b);
+}
+float jgSoilVNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgSoilHash1(i);
+  float b = jgSoilHash1(i + vec2(1.0, 0.0));
+  float c = jgSoilHash1(i + vec2(0.0, 1.0));
+  float d = jgSoilHash1(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float jgSoilFbm(vec2 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 4; i++){ v += amp * jgSoilVNoise(p); p *= 2.0; amp *= 0.5; }
+  return v;
+}
+vec2 jgSoilWorleyF1F2(vec2 p){
+  vec2 ip = floor(p);
+  vec2 fp = fract(p);
+  float f1 = 8.0; float f2 = 8.0;
+  for (int y = -1; y <= 1; y++){
+    for (int x = -1; x <= 1; x++){
+      vec2 neighbor = vec2(float(x), float(y));
+      vec2 point = jgSoilHash2(ip + neighbor);
+      float dist = length(neighbor + point - fp);
+      if (dist < f1) { f2 = f1; f1 = dist; }
+      else if (dist < f2) { f2 = dist; }
+    }
+  }
+  return vec2(f1, f2);
+}
+float jgSoilCrackMask(vec2 p, float scale){
+  vec2 f = jgSoilWorleyF1F2(p / scale);
+  return 1.0 - smoothstep(0.0, 0.065, f.y - f.x);
+}
+`;
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % 100000;
+}
+/**
+ * A `MeshStandardMaterial` for one authored `soil` volume: a base dirt tint with a Worley crack-line
+ * network and an FBM moss-patch overlay injected via `onBeforeCompile`, seeded from `rules.seed`. Full
+ * PBR — lit, shadowed, fogged — like the terrain detail material it borrows its noise machinery from.
+ * Pass `edge` to add a noise-eroded alpha fade at the patch border (the draped scene-kind renderer
+ * does) so the patch blends into the surrounding ground. A game never calls this directly — author a
+ * soil patch via the editor's `soil` studio kind.
+ * @internal
+ */
+export function createSoilPatchMaterial(rules, edge) {
+    const seedOffset = hashSeed(rules.seed);
+    const material = new THREE.MeshStandardMaterial({
+        color: rules.baseColor,
+        roughness: 0.92,
+        metalness: 0,
+        ...(edge === undefined ? {} : { transparent: true, polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2 }),
+    });
+    material.onBeforeCompile = (shader) => {
+        shader.uniforms.uSoilCrackColor = { value: new THREE.Color(rules.crackColor) };
+        shader.uniforms.uSoilCrackScale = { value: Math.max(0.1, rules.crackScale) };
+        shader.uniforms.uSoilCrackIntensity = { value: rules.crackIntensity };
+        shader.uniforms.uSoilMossColor = { value: new THREE.Color(rules.mossColor) };
+        shader.uniforms.uSoilMossCoverage = { value: rules.mossCoverage };
+        shader.uniforms.uSoilSeed = { value: seedOffset };
+        if (edge !== undefined) {
+            shader.uniforms.uSoilCenter = { value: new THREE.Vector2(edge.center[0], edge.center[1]) };
+            shader.uniforms.uSoilHalfSize = { value: new THREE.Vector2(edge.halfSize[0], edge.halfSize[1]) };
+            shader.uniforms.uSoilEdgeFade = { value: edge.fade ?? 1.6 };
+            shader.uniforms.uSoilGroundColor = { value: new THREE.Color(edge.groundColor ?? rules.baseColor) };
+        }
+        shader.vertexShader = shader.vertexShader.replace("#include <common>", `#include <common>
+varying vec3 vJgSoilWorldPos;`).replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgSoilWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
+        shader.fragmentShader = shader.fragmentShader.replace("#include <common>", `#include <common>
+varying vec3 vJgSoilWorldPos;
+uniform vec3 uSoilCrackColor;
+uniform float uSoilCrackScale;
+uniform float uSoilCrackIntensity;
+uniform vec3 uSoilMossColor;
+uniform float uSoilMossCoverage;
+uniform float uSoilSeed;
+${edge === undefined ? "" : "uniform vec2 uSoilCenter;\nuniform vec2 uSoilHalfSize;\nuniform float uSoilEdgeFade;\nuniform vec3 uSoilGroundColor;\n"}${SOIL_NOISE_GLSL}`).replace("#include <color_fragment>", `#include <color_fragment>
+vec2 jgSoilP = vJgSoilWorldPos.xz + vec2(uSoilSeed * 0.37, uSoilSeed * 0.71);
+float jgSoilCrack = jgSoilCrackMask(jgSoilP, uSoilCrackScale);
+vec3 jgSoilCol = mix(diffuseColor.rgb, uSoilCrackColor, jgSoilCrack * uSoilCrackIntensity);
+// Crack floors go darker still — paired with the relief normals they read as recessed, not painted.
+jgSoilCol *= 1.0 - jgSoilCrack * uSoilCrackIntensity * 0.4;
+// Sun-baked plate mottling so the dirt between cracks isn't one flat swatch.
+jgSoilCol *= mix(0.92, 1.08, jgSoilFbm(jgSoilP / 1.1));
+float jgSoilMossN = jgSoilFbm(jgSoilP / 2.4);
+float jgSoilMossMask = smoothstep(1.0 - uSoilMossCoverage, 1.0 - uSoilMossCoverage + 0.18, jgSoilMossN);
+// Fine clump break-up: moss creeps in speckled colonies (and pools into the cracks), not airbrushed blobs.
+jgSoilMossMask *= smoothstep(0.3, 0.75, jgSoilFbm(jgSoilP / 0.55));
+jgSoilMossMask = min(1.0, jgSoilMossMask + jgSoilMossMask * jgSoilCrack * 0.8);
+jgSoilCol = mix(jgSoilCol, uSoilMossColor * mix(0.85, 1.1, jgSoilFbm(jgSoilP / 0.9)), jgSoilMossMask);${edge === undefined
+            ? "\ndiffuseColor.rgb = jgSoilCol;"
+            : `
+// Border: color walks toward the terrain tint across the fade band (alpha alone left a decal
+// seam — the dirt must *become* the ground it meets), then a noise-eaten alpha finishes it.
+vec2 jgSoilEdgeD = uSoilHalfSize - abs(vJgSoilWorldPos.xz - uSoilCenter);
+float jgSoilEdgeDist = min(jgSoilEdgeD.x, jgSoilEdgeD.y);
+float jgSoilEdgeNoise = jgSoilFbm(jgSoilP * 0.9) * uSoilEdgeFade;
+float jgSoilInside = clamp((jgSoilEdgeDist - jgSoilEdgeNoise) / max(uSoilEdgeFade, 0.001) + 0.55, 0.0, 1.0);
+jgSoilCol = mix(uSoilGroundColor, jgSoilCol, smoothstep(0.0, 0.85, jgSoilInside));
+diffuseColor.rgb = jgSoilCol;
+diffuseColor.a *= clamp(jgSoilInside * 1.5, 0.0, 1.0);`}`).replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+// Crack relief: tilt normals along the Worley gradient so crack walls catch and lose the light
+// (finite differences over the same field that colors the cracks — they self-shadow in sync).
+vec2 jgSoilNp = vJgSoilWorldPos.xz + vec2(uSoilSeed * 0.37, uSoilSeed * 0.71);
+float jgSoilNe = 0.05;
+vec2 jgSoilGrad = vec2(
+  jgSoilCrackMask(jgSoilNp + vec2(jgSoilNe, 0.0), uSoilCrackScale) - jgSoilCrackMask(jgSoilNp - vec2(jgSoilNe, 0.0), uSoilCrackScale),
+  jgSoilCrackMask(jgSoilNp + vec2(0.0, jgSoilNe), uSoilCrackScale) - jgSoilCrackMask(jgSoilNp - vec2(0.0, jgSoilNe), uSoilCrackScale)
+) / (2.0 * jgSoilNe);
+normal = normalize(normal + vec3(jgSoilGrad.x, 0.0, jgSoilGrad.y) * uSoilCrackIntensity * 0.2);`);
+    };
+    material.customProgramCacheKey = () => `jgengine-soil-${rules.crackScale}-${rules.crackIntensity}-${rules.mossCoverage}-${seedOffset}-${edge === undefined ? "solid" : "faded"}`;
+    return material;
+}

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -4,11 +4,28 @@ import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
 export interface TerrainDetailMaterialHandle {
     material: THREE.MeshStandardMaterial;
 }
+/**
+ * Loaded PBR textures matching a resolved `ResolvedTerrainDetailMaterial.maps`' roles. The caller
+ * (a React component, via `useTexture`/`useLoader`) owns loading and disposal; `core` never touches
+ * `THREE.Texture` and this shell function never fetches a URL itself.
+ */
+export interface TerrainDetailMaterialTextures {
+    color: THREE.Texture;
+    normal: THREE.Texture;
+    roughness: THREE.Texture;
+    ao: THREE.Texture;
+}
 /**
  * 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.
- */
-export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail): TerrainDetailMaterialHandle;
+ *
+ * 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;

package/dist/terrain/terrainDetailMaterial.js

@@ -1,6 +1,16 @@
 import * as THREE from "three";
 const NOISE_GLSL = /* glsl */ `
-float jgHash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+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);
@@ -22,8 +32,17 @@ float jgFbm(vec2 p){
  * 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.
- */
-export function createTerrainDetailMaterial(detail) {
+ *
+ * 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) {
+    const hasTexture = textures !== undefined && detail.material !== undefined;
+    const repeat = detail.material?.repeat ?? 4;
+    const strength = detail.material?.strength ?? 1;
     const uniforms = {
         uRockColor: { value: new THREE.Color(detail.rockColor) },
         uSandColor: { value: new THREE.Color(detail.sandColor) },
@@ -34,6 +53,16 @@ export function createTerrainDetailMaterial(detail) {
         uDetailScale: { value: Math.max(0.5, detail.detailScale) },
         uMacroScale: { value: Math.max(0.5, detail.macroScale) },
         uStrength: { value: detail.strength },
+        ...(hasTexture
+            ? {
+                uMatColor: { value: textures.color },
+                uMatNormal: { value: textures.normal },
+                uMatRoughness: { value: textures.roughness },
+                uMatAo: { value: textures.ao },
+                uMatRepeat: { value: Math.max(0.01, repeat) },
+                uMatStrength: { value: strength },
+            }
+            : {}),
     };
     const material = new THREE.MeshStandardMaterial({
         color: "#ffffff",
@@ -51,6 +80,36 @@ varying vec3 vJgWorldNormal;`)
 vJgWorldNormal = normalize(mat3(modelMatrix) * objectNormal);`)
             .replace("#include <begin_vertex>", `#include <begin_vertex>
 vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
+        const materialUniformsGlsl = hasTexture
+            ? `
+uniform sampler2D uMatColor;
+uniform sampler2D uMatNormal;
+uniform sampler2D uMatRoughness;
+uniform sampler2D uMatAo;
+uniform float uMatRepeat;
+uniform float uMatStrength;`
+            : "";
+        const materialColorGlsl = hasTexture
+            ? `
+vec2 jgMatUv = jgWp / uMatRepeat;
+vec3 jgMatColor = texture2D(uMatColor, jgMatUv).rgb;
+jgCol = mix(jgCol, jgMatColor, uMatStrength);`
+            : "";
+        const materialRoughnessGlsl = hasTexture
+            ? `
+float jgMatRough = texture2D(uMatRoughness, jgMatUv).g;
+roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
+            : "";
+        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);`
+            : "";
+        const materialAoGlsl = hasTexture
+            ? `
+float jgMatAo = texture2D(uMatAo, jgMatUv).r;
+reflectedLight.indirectDiffuse *= mix(1.0, jgMatAo, uMatStrength);`
+            : "";
         shader.fragmentShader = shader.fragmentShader
             .replace("#include <common>", `#include <common>
 varying vec3 vJgWorldPos;
@@ -64,16 +123,30 @@ uniform float uWaterLevel;
 uniform float uDetailScale;
 uniform float uMacroScale;
 uniform float uStrength;
+${materialUniformsGlsl}
 ${NOISE_GLSL}`)
             .replace("#include <color_fragment>", `#include <color_fragment>
 vec2 jgWp = vJgWorldPos.xz;
 float jgFine = jgFbm(jgWp / uDetailScale);
 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));
 vec3 jgBase = diffuseColor.rgb;
-jgBase *= mix(1.0 - 0.22 * uStrength, 1.0 + 0.18 * uStrength, jgFine);
-jgBase = mix(jgBase, jgBase * vec3(0.86, 0.9, 0.82), jgMacro * 0.25 * uStrength);
+jgBase *= mix(1.0 - 0.2 * uStrength, 1.0 + 0.16 * uStrength, jgFine);
+// Meadow patchwork: hue-shifted sun-dried sweeps and cooler lush pockets, not just darker spots.
+jgBase = mix(jgBase, jgBase * vec3(1.14, 1.05, 0.76), smoothstep(0.5, 0.8, jgMacro) * 0.55 * uStrength);
+jgBase = mix(jgBase, jgBase * vec3(0.78, 1.0, 0.86), 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);
@@ -83,8 +156,15 @@ jgCol = mix(jgCol, jgSand, jgSandW);
 vec3 jgSnow = uSnowColor * mix(0.94, 1.04, jgFine);
 float jgSnowW = smoothstep(uSnowHeight, uSnowHeight + 8.0, jgH) * (1.0 - jgRockW * 0.6) * uStrength;
 jgCol = mix(jgCol, jgSnow, jgSnowW);
-diffuseColor.rgb = jgCol;`);
+${materialColorGlsl}
+diffuseColor.rgb = jgCol;`)
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+${materialRoughnessGlsl}`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${materialNormalGlsl}`)
+            .replace("#include <aomap_fragment>", `#include <aomap_fragment>
+${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}`;
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}`;
     return { material };
 }

package/dist/terrain/terrainMath.d.ts

@@ -27,10 +27,15 @@ export interface TerrainVertexColorOptions {
     waterline?: THREE.ColorRepresentation;
     waterlineHeight?: number;
 }
+/** @internal */
 export declare function normalizeHeightBlend(height: number, minHeight: number, maxHeight: number): number;
+/** @internal */
 export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainSize;
+/** @internal */
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
+/** @internal */
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
+/** @internal */
 export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
 /** Per-position palette override for multi-biome ground coloring — `createTerrainPaletteSampler` from `@jgengine/core/world/terrain` returns exactly this shape. */
 export type TerrainPaletteSampler = (x: number, z: number) => {
@@ -51,6 +56,8 @@ export interface FieldGroundOptions {
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
  * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
  * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
- */
+  * @internal
+  */
 export declare function createFieldGroundGeometry(field: TerrainField, options?: FieldGroundOptions): THREE.BufferGeometry;
+/** @internal */
 export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;

package/dist/terrain/terrainMath.js

@@ -1,21 +1,25 @@
 import { noiseField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import {} from "./random.js";
+/** @internal */
 export function normalizeHeightBlend(height, minHeight, maxHeight) {
     const range = maxHeight - minHeight;
     if (range <= 1e-6)
         return 0.5;
     return THREE.MathUtils.clamp((height - minHeight) / range, 0, 1);
 }
+/** @internal */
 export function resolveTerrainSize(size = 40) {
     return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
 }
+/** @internal */
 export function resolveTerrainSegments(segments = 96) {
     if (typeof segments !== "number")
         return { x: Math.max(1, Math.floor(segments[0])), z: Math.max(1, Math.floor(segments[1])) };
     const resolved = Math.max(1, Math.floor(segments));
     return { x: resolved, z: resolved };
 }
+/** @internal */
 export function toNoiseFieldConfig(config = {}) {
     return {
         seed: config.seed,
@@ -26,6 +30,7 @@ export function toNoiseFieldConfig(config = {}) {
         baseHeight: config.baseOffset ?? 0,
     };
 }
+/** @internal */
 export function createProceduralTerrainSampler(config = {}) {
     return noiseField(toNoiseFieldConfig(config)).sampleHeight;
 }
@@ -33,7 +38,8 @@ export function createProceduralTerrainSampler(config = {}) {
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
  * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
  * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
- */
+  * @internal
+  */
 export function createFieldGroundGeometry(field, options = {}) {
     const size = resolveTerrainSize(options.size);
     const segments = resolveTerrainSegments(options.segments);
@@ -118,6 +124,7 @@ function buildGroundGeometry(size, segments, sampler, opts) {
     geometry.computeBoundingSphere();
     return geometry;
 }
+/** @internal */
 export function createProceduralGroundGeometry(config = {}, colors = {}) {
     const size = resolveTerrainSize(config.size);
     const segments = resolveTerrainSegments(config.segments);

package/dist/touch/TouchControlsOverlay.d.ts

@@ -1,5 +1,5 @@
 import { type MutableRefObject } from "react";
-import { type TouchScheme } from "@jgengine/core/input/touchScheme";
+import { type TouchScheme, type TouchStyle } from "@jgengine/core/input/touchScheme";
 export interface TouchCodeSink {
     onCodeDown(code: string): void;
     onCodeUp(code: string): void;
@@ -14,9 +14,11 @@ export declare function primaryButtonOffsets(count: number, scale?: number): {
     bottom: number;
 }[] | null;
 /**
- * Vertical space (px, excluding device safe areas) the dock occupies above
- * the bottom edge. The shell publishes it as `--jg-hud-dock-clearance` so
- * `HudCanvas` regions never collide with touch controls.
+ * Vertical space (px, excluding device safe areas) that *bottom-docked* clusters
+ * occupy above the bottom edge. The shell publishes it as
+ * `--jg-hud-dock-clearance` so `HudCanvas` regions never collide with touch
+ * controls. Side rails and top clusters reserve their own rectangles through the
+ * layout registry instead of this scalar.
  */
 export declare function touchDockClearance(scheme: TouchScheme | null, scale?: number): number;
 export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }: {
@@ -27,8 +29,10 @@ export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPi
     maxPitch: number;
     onPrimaryTap: () => void;
 }): import("react").JSX.Element;
-export declare function TouchControlsDock({ scheme, sink, scale }: {
+export declare function TouchControlsDock({ scheme, sink, style, scale, }: {
     scheme: TouchScheme;
     sink: TouchCodeSink;
+    /** Player-selected skin; falls back to the scheme's game default. */
+    style?: TouchStyle;
     scale?: number;
 }): import("react").JSX.Element;