@jgengine/shell 0.11.0 → 0.13.0

package/dist/terrain/grassMaterial.js

@@ -6,6 +6,11 @@ export const DEFAULT_GRASS_WIND = {
     gustScale: 0.16,
     flutter: 0.08,
 };
+/** Default camera-distance fade band: tufts start thinning at 35 m and are gone by 95 m. */
+export const DEFAULT_GRASS_DISTANCE_FADE = {
+    start: 35,
+    end: 95,
+};
 function normalizeWindDirection(direction) {
     const vector = new THREE.Vector2(direction[0], direction[1]);
     return vector.lengthSq() === 0 ? new THREE.Vector2(1, 0) : vector.normalize();
@@ -23,8 +28,23 @@ export function resolveGrassWind(wind) {
     };
 }
 /** @internal */
+export function resolveGrassDistanceFade(fade) {
+    // start >= end disables the fade in the shader, so "off" is just an empty band.
+    if (fade === false)
+        return { start: 0, end: 0 };
+    return {
+        start: fade?.start ?? DEFAULT_GRASS_DISTANCE_FADE.start,
+        end: fade?.end ?? DEFAULT_GRASS_DISTANCE_FADE.end,
+    };
+}
+/** @internal */
 export function createGrassMaterial(options = {}) {
     const wind = resolveGrassWind(options.wind);
+    const fade = resolveGrassDistanceFade(options.distanceFade);
+    const colorBase = new THREE.Color(options.colorBase ?? "#2d431f");
+    const colorGround = options.colorGround === undefined
+        ? colorBase.clone().multiplyScalar(0.82)
+        : new THREE.Color(options.colorGround);
     const uniforms = {
         uTime: { value: 0 },
         uWindDirection: { value: normalizeWindDirection(wind.direction) },
@@ -32,9 +52,12 @@ export function createGrassMaterial(options = {}) {
         uWindSpeed: { value: wind.speed },
         uWindGustScale: { value: wind.gustScale },
         uWindFlutter: { value: wind.flutter },
-        uColorBase: { value: new THREE.Color(options.colorBase ?? "#2d431f") },
+        uColorBase: { value: colorBase },
         uColorTip: { value: new THREE.Color(options.colorTip ?? "#a6cc58") },
+        uColorGround: { value: colorGround },
         uColorVariation: { value: options.colorVariation ?? 0.28 },
+        uDistanceFade: { value: new THREE.Vector2(fade.start, fade.end) },
+        uNormalLift: { value: THREE.MathUtils.clamp(options.normalLift ?? 0.6, 0, 1) },
     };
     const material = new THREE.MeshStandardMaterial({
         color: "#ffffff",
@@ -54,36 +77,61 @@ attribute float instanceWidth;
 attribute float instanceBend;
 attribute float instancePhase;
 attribute float instanceColorMix;
+attribute vec2 bladeOffset;
+attribute vec4 bladeVary;
+attribute float bladeBendScale;
 uniform float uTime;
 uniform vec2 uWindDirection;
 uniform float uWindStrength;
 uniform float uWindSpeed;
 uniform float uWindGustScale;
 uniform float uWindFlutter;
+uniform vec2 uDistanceFade;
+uniform float uNormalLift;
 varying float vGrassBladeT;
 varying float vGrassColorMix;
+varying float vGrassFade;
 vec3 jgGrassPosition;
 vec3 jgGrassNormal;
 void jgComputeGrassBlade() {
   float t = position.y;
   float side = position.x;
-  float taper = (1.0 - t) * (0.72 + 0.28 * (1.0 - t));
-  float width = instanceWidth * taper;
-  float arc = instanceBend * t * t;
-  vec3 localPosition = vec3(side * width, instanceHeight * t - arc * instanceHeight * 0.18, arc * instanceHeight);
-  vec3 localNormal = normalize(vec3(0.0, -instanceBend * t, 1.0));
-  float cy = cos(instanceYaw);
-  float sy = sin(instanceYaw);
+  // Camera-distance thinning: each tuft draws a random threshold, so the field dissolves
+  // progressively across the fade band instead of ending at a hard curtain.
+  float camDist = distance((modelMatrix * vec4(instanceOffset, 1.0)).xyz, cameraPosition);
+  float fadeT = uDistanceFade.y > uDistanceFade.x
+    ? smoothstep(uDistanceFade.x, uDistanceFade.y, camDist)
+    : 0.0;
+  float threshold = fract(instanceColorMix * 61.7) * 0.85;
+  float keep = 1.0 - smoothstep(threshold, threshold + 0.15, fadeT);
+  float heightScale = instanceHeight * bladeVary.y * keep;
+  // Paddle taper: hold width through the mid-blade and only pinch near the tip — thin
+  // triangle blades leave the ground visible between tufts and read as stubble.
+  float taper = (1.0 - 0.3 * t) * (1.0 - smoothstep(0.5, 1.0, t) * 0.95);
+  // Surviving distant tufts widen to hold silhouette coverage as neighbors thin out.
+  float width = instanceWidth * bladeVary.z * taper * (1.0 + fadeT * 1.4);
+  float arc = instanceBend * bladeBendScale * t * t;
+  vec3 localPosition = vec3(side * width, heightScale * t - arc * heightScale * 0.18, arc * heightScale);
+  vec3 localNormal = normalize(vec3(0.0, -instanceBend * bladeBendScale * t, 1.0));
+  float bladeYaw = instanceYaw + bladeVary.x;
+  float cy = cos(bladeYaw);
+  float sy = sin(bladeYaw);
   vec3 yawedPosition = vec3(localPosition.x * cy + localPosition.z * sy, localPosition.y, -localPosition.x * sy + localPosition.z * cy);
   vec3 yawedNormal = normalize(vec3(localNormal.x * cy + localNormal.z * sy, localNormal.y, -localNormal.x * sy + localNormal.z * cy));
+  float ct = cos(instanceYaw);
+  float st = sin(instanceYaw);
+  vec3 tuftOffset = vec3(bladeOffset.x * ct + bladeOffset.y * st, 0.0, -bladeOffset.x * st + bladeOffset.y * ct);
   float gustPhase = dot(instanceOffset.xz, uWindDirection) * uWindGustScale + uTime * uWindSpeed + instancePhase;
   float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;
-  float flutter = sin(uTime * 7.5 + instancePhase * 2.7) * uWindFlutter;
-  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t;
-  jgGrassPosition = instanceOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
-  jgGrassNormal = yawedNormal;
+  float flutter = sin(uTime * 7.5 + instancePhase * 2.7 + bladeVary.w * 6.2832) * uWindFlutter;
+  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t * (0.4 + 0.6 * bladeVary.y);
+  jgGrassPosition = instanceOffset + tuftOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
+  // Lifting normals toward straight-up lights the field like a continuous meadow surface —
+  // side-lit individual blade planes read as dark stubble, not turf.
+  jgGrassNormal = normalize(mix(yawedNormal, vec3(0.0, 1.0, 0.0), uNormalLift));
   vGrassBladeT = t;
   vGrassColorMix = instanceColorMix;
+  vGrassFade = fadeT;
 }
 `)
             .replace("#include <beginnormal_vertex>", "jgComputeGrassBlade();\nvec3 objectNormal = jgGrassNormal;")
@@ -93,15 +141,20 @@ void jgComputeGrassBlade() {
 #include <common>
 uniform vec3 uColorBase;
 uniform vec3 uColorTip;
+uniform vec3 uColorGround;
 uniform float uColorVariation;
 varying float vGrassBladeT;
 varying float vGrassColorMix;
+varying float vGrassFade;
 `)
             .replace("#include <color_fragment>", `
 #include <color_fragment>
 vec3 grassColor = mix(uColorBase, uColorTip, smoothstep(0.0, 1.0, vGrassBladeT));
 grassColor *= mix(1.0 - uColorVariation, 1.0 + uColorVariation, vGrassColorMix);
-grassColor *= mix(0.58, 1.0, smoothstep(0.05, 0.45, vGrassBladeT));
+// Roots take the ground color so blades grow out of the terrain instead of floating on it,
+// and distant blades converge back toward it so the fade band blends into the mottled ground.
+grassColor = mix(uColorGround, grassColor, smoothstep(0.0, 0.55, vGrassBladeT));
+grassColor = mix(grassColor, uColorGround * 1.04, vGrassFade * 0.6);
 diffuseColor.rgb = grassColor;
 `);
     };

package/dist/terrain/heightfieldGeometry.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from "three";
+/** XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`. */
+export interface HeightfieldRect {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`. */
+export type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void;
+/** Options for {@link displaceHeightfieldGeometry}. */
+export interface HeightfieldDisplaceOptions {
+    /** World-space rect the plane spans (the plane is centered on it, XZ, +Y up). */
+    bounds: HeightfieldRect;
+    /**
+     * Dirty world-space region to re-sample; only the vertex window covering it (plus a one-vertex
+     * normal ring) updates. Omit or pass null for a full rebuild.
+     */
+    region?: HeightfieldRect | null;
+    /** When given, writes a `color` attribute (creating it on demand) via this per-vertex hook. */
+    color?: HeightfieldColorFn;
+}
+/**
+ * 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 declare function displaceHeightfieldGeometry(geometry: THREE.BufferGeometry, sampleHeight: (x: number, z: number) => number, options: HeightfieldDisplaceOptions): void;

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/soilPatchMaterial.d.ts

@@ -1,10 +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.
- * A game never calls this directly — author a soil patch via the editor's `soil` studio kind.
+ * 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): THREE.MeshStandardMaterial;
+export declare function createSoilPatchMaterial(rules: SoilRules, edge?: SoilPatchEdge): THREE.MeshStandardMaterial;

package/dist/terrain/soilPatchMaterial.js

@@ -53,6 +53,10 @@ vec2 jgSoilWorleyF1F2(vec2 p){
   }
   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;
@@ -66,15 +70,18 @@ function hashSeed(text) {
  * 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.
- * A game never calls this directly — author a soil patch via the editor's `soil` studio kind.
+ * 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) {
+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) };
@@ -83,6 +90,12 @@ export function createSoilPatchMaterial(rules) {
         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;`);
@@ -94,16 +107,41 @@ uniform float uSoilCrackIntensity;
 uniform vec3 uSoilMossColor;
 uniform float uSoilMossCoverage;
 uniform float uSoilSeed;
-${SOIL_NOISE_GLSL}`).replace("#include <color_fragment>", `#include <color_fragment>
+${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);
-vec2 jgSoilF1F2 = jgSoilWorleyF1F2(jgSoilP / uSoilCrackScale);
-float jgSoilCrack = 1.0 - smoothstep(0.0, 0.1, jgSoilF1F2.y - jgSoilF1F2.x);
+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);
-jgSoilCol = mix(jgSoilCol, uSoilMossColor, jgSoilMossMask);
-diffuseColor.rgb = jgSoilCol;`);
+// 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}`;
+    material.customProgramCacheKey = () => `jgengine-soil-${rules.crackScale}-${rules.crackIntensity}-${rules.mossCoverage}-${seedOffset}-${edge === undefined ? "solid" : "faded"}`;
     return material;
 }

package/dist/terrain/terrainDetailMaterial.js

@@ -129,11 +129,24 @@ ${NOISE_GLSL}`)
 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);

package/dist/water/Ocean.d.ts

@@ -2,5 +2,11 @@ import { type ThreeElements } from "@react-three/fiber";
 import { type OceanConfig } from "./OceanConfig.js";
 export interface OceanProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
     config?: OceanConfig;
+    /**
+     * Water-column depth (m) under a point of the sheet, in the sheet's local XZ. When provided,
+     * the shader shades shallow→deep by real depth, foams and turns transparent at the shore, and
+     * damps waves as the bed shoals. Omit for an open ocean (everywhere-deep behavior).
+     */
+    depthAt?: (x: number, z: number) => number;
 }
-export declare function Ocean({ config, ...meshProps }: OceanProps): import("react").JSX.Element;
+export declare function Ocean({ config, depthAt, ...meshProps }: OceanProps): import("react").JSX.Element;

package/dist/water/Ocean.js

@@ -4,16 +4,29 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { createOceanConfig } from "./OceanConfig.js";
 import { createOceanMaterial, syncOceanMaterial } from "./OceanMaterial.js";
-function createOceanGeometry(config) {
+/** aDepth when no sampler is given: everywhere-deep, matching the pre-depth shader look. */
+const OCEAN_DEFAULT_DEPTH = 1000;
+function createOceanGeometry(config, depthAt) {
     const geometry = new THREE.PlaneGeometry(config.size, config.depth, config.resolution, config.resolution);
     geometry.rotateX(-Math.PI / 2);
+    const positions = geometry.getAttribute("position");
+    const depths = new Float32Array(positions.count);
+    if (depthAt === undefined) {
+        depths.fill(OCEAN_DEFAULT_DEPTH);
+    }
+    else {
+        for (let i = 0; i < positions.count; i += 1) {
+            depths[i] = Math.max(0, depthAt(positions.getX(i), positions.getZ(i)));
+        }
+    }
+    geometry.setAttribute("aDepth", new THREE.BufferAttribute(depths, 1));
     geometry.computeBoundingSphere();
     return geometry;
 }
-export function Ocean({ config, ...meshProps }) {
+export function Ocean({ config, depthAt, ...meshProps }) {
     const resolved = useMemo(() => createOceanConfig(config), [config]);
     const elapsedRef = useRef(0);
-    const geometry = useMemo(() => createOceanGeometry(resolved), [resolved]);
+    const geometry = useMemo(() => createOceanGeometry(resolved, depthAt), [resolved, depthAt]);
     const material = useMemo(() => createOceanMaterial(resolved), [resolved]);
     useEffect(() => {
         return () => geometry.dispose();

package/dist/water/OceanConfig.d.ts

@@ -21,12 +21,18 @@ export interface OceanColorConfig {
     opacity?: number;
     fresnelStrength?: number;
     horizonBlend?: number;
+    /** Water depth (m) at which the body color reaches the full `deep` tone. Default 2.6. */
+    depthRange?: number;
+    /** Sun-glint sparkle intensity, 0 disables. Default 0.35. */
+    sparkle?: number;
 }
 export interface OceanFoamConfig {
     crestThreshold?: number;
     softness?: number;
     intensity?: number;
     coverage?: number;
+    /** Shoreline foam lick width (m of water depth it covers). Default 0.5. */
+    shoreWidth?: number;
 }
 export interface OceanConfig {
     quality?: OceanQualityPreset;
@@ -59,12 +65,15 @@ export interface ResolvedOceanColorConfig {
     opacity: number;
     fresnelStrength: number;
     horizonBlend: number;
+    depthRange: number;
+    sparkle: number;
 }
 export interface ResolvedOceanFoamConfig {
     crestThreshold: number;
     softness: number;
     intensity: number;
     coverage: number;
+    shoreWidth: number;
 }
 export interface ResolvedOceanWaveConfig {
     amplitude: number;

package/dist/water/OceanConfig.js

@@ -28,12 +28,15 @@ export const DEFAULT_OCEAN_CONFIG = {
         opacity: 0.88,
         fresnelStrength: 0.7,
         horizonBlend: 0.38,
+        depthRange: 2.6,
+        sparkle: 0.35,
     },
     foam: {
         crestThreshold: 0.64,
         softness: 0.22,
         intensity: 0.8,
         coverage: 0.45,
+        shoreWidth: 0.5,
     },
     waves: [],
 };
@@ -111,6 +114,8 @@ export function createOceanConfig(patch = {}) {
             opacity: clamp(finiteOr(patch.color?.opacity, DEFAULT_OCEAN_CONFIG.color.opacity), 0, 1),
             fresnelStrength: Math.max(0, finiteOr(patch.color?.fresnelStrength, DEFAULT_OCEAN_CONFIG.color.fresnelStrength)),
             horizonBlend: clamp(finiteOr(patch.color?.horizonBlend, DEFAULT_OCEAN_CONFIG.color.horizonBlend), 0, 1),
+            depthRange: Math.max(0.05, finiteOr(patch.color?.depthRange, DEFAULT_OCEAN_CONFIG.color.depthRange)),
+            sparkle: Math.max(0, finiteOr(patch.color?.sparkle, DEFAULT_OCEAN_CONFIG.color.sparkle)),
         },
         foam: {
             ...DEFAULT_OCEAN_CONFIG.foam,
@@ -119,6 +124,7 @@ export function createOceanConfig(patch = {}) {
             softness: clamp(finiteOr(patch.foam?.softness, DEFAULT_OCEAN_CONFIG.foam.softness), 0.001, 1),
             intensity: Math.max(0, finiteOr(patch.foam?.intensity, DEFAULT_OCEAN_CONFIG.foam.intensity)),
             coverage: clamp(finiteOr(patch.foam?.coverage, DEFAULT_OCEAN_CONFIG.foam.coverage), 0, 1),
+            shoreWidth: Math.max(0, finiteOr(patch.foam?.shoreWidth, DEFAULT_OCEAN_CONFIG.foam.shoreWidth)),
         },
     };
     const defaultWaves = createDefaultWaves(withoutWaves);

package/dist/water/OceanMaterial.d.ts

@@ -46,6 +46,18 @@ export interface OceanMaterialUniforms {
     uFoamCoverage: {
         value: number;
     };
+    uDepthRange: {
+        value: number;
+    };
+    uShoreFoamWidth: {
+        value: number;
+    };
+    uSparkle: {
+        value: number;
+    };
+    uSunDirection: {
+        value: THREE.Vector3;
+    };
 }
 export type OceanShaderMaterial = THREE.ShaderMaterial & {
     uniforms: OceanMaterialUniforms;

package/dist/water/OceanMaterial.js

@@ -1,6 +1,8 @@
 import * as THREE from "three";
 import { buildOceanWaveUniforms } from "./OceanConfig.js";
 import { oceanFragmentShader, oceanVertexShader } from "./OceanShader.js";
+/** Matches the day-sky sun heading closely enough for stylized glints — not a lighting contract. */
+const OCEAN_SUN_DIRECTION = new THREE.Vector3(0.45, 0.78, 0.35).normalize();
 export function createOceanMaterial(config) {
     const material = new THREE.ShaderMaterial({
         vertexShader: oceanVertexShader,
@@ -24,6 +26,10 @@ export function createOceanMaterial(config) {
             uFoamSoftness: { value: config.foam.softness },
             uFoamIntensity: { value: config.foam.intensity },
             uFoamCoverage: { value: config.foam.coverage },
+            uDepthRange: { value: config.color.depthRange },
+            uShoreFoamWidth: { value: config.foam.shoreWidth },
+            uSparkle: { value: config.color.sparkle },
+            uSunDirection: { value: OCEAN_SUN_DIRECTION.clone() },
         },
     });
     syncOceanMaterial(material, config, 0);
@@ -46,6 +52,9 @@ export function syncOceanMaterial(material, config, elapsedSeconds) {
     material.uniforms.uFoamSoftness.value = config.foam.softness;
     material.uniforms.uFoamIntensity.value = config.foam.intensity;
     material.uniforms.uFoamCoverage.value = config.foam.coverage;
+    material.uniforms.uDepthRange.value = config.color.depthRange;
+    material.uniforms.uShoreFoamWidth.value = config.foam.shoreWidth;
+    material.uniforms.uSparkle.value = config.color.sparkle;
     material.transparent = config.color.opacity < 1;
     material.depthWrite = config.color.opacity >= 0.98;
 }