@jgengine/shell 0.11.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/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;
 }

package/dist/water/OceanShader.d.ts

@@ -1,2 +1,2 @@
-export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
-export declare const oceanFragmentShader = "\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 normal = normalize(vNormal);\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);\n  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);\n  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);\n  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);\n  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n  gl_FragColor = vec4(color, uOpacity);\n}\n";
+export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nattribute float aDepth;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nvoid main() {\n  vOceanUv = uv;\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.\n  float depthDamp = smoothstep(0.05, 1.4, aDepth);\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y * depthDamp;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vDepth = aDepth;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
+export declare const oceanFragmentShader = "\nuniform float uTime;\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\nuniform float uDepthRange;\nuniform float uShoreFoamWidth;\nuniform float uSparkle;\nuniform vec3 uSunDirection;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\nvarying float vDepth;\nvarying vec2 vOceanUv;\n\nfloat jgWaterHash(vec2 p) {\n  uvec2 q = uvec2(ivec2(floor(p)));\n  uint x = q.x * 1664525u + q.y * 1013904223u;\n  x = (x ^ (x >> 16u)) * 2246822519u;\n  x = (x ^ (x >> 13u)) * 3266489917u;\n  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);\n}\n\nfloat jgWaterNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = jgWaterHash(i);\n  float b = jgWaterHash(i + vec2(1.0, 0.0));\n  float c = jgWaterHash(i + vec2(0.0, 1.0));\n  float d = jgWaterHash(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\nvoid main() {\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n\n  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface\n  // between the big Gerstner swells.\n  vec2 wp = vWorldPosition.xz;\n  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));\n  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));\n  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);\n\n  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.\n  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);\n  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);\n\n  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);\n  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);\n\n  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it\n  // twinkles in cells instead of sheening uniformly.\n  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));\n  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);\n  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));\n  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;\n\n  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole\n  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.\n  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));\n  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));\n  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))\n    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);\n  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);\n  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n\n  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the\n  // waterline is a blend into the terrain, not a hard tarp edge.\n  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);\n  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;\n  // The sheet's own border always dissolves \u2014 a bounded water plane must never end in a\n  // visible straight cut, whatever the bed underneath is doing.\n  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));\n  alpha *= smoothstep(0.0, 0.045, borderDist);\n  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));\n}\n";

package/dist/water/OceanShader.js

@@ -7,22 +7,29 @@ uniform float uFoamThreshold;
 uniform float uFoamSoftness;
 uniform float uFoamCoverage;
 
+attribute float aDepth;
+
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
 
 void main() {
+  vOceanUv = uv;
   vec3 displaced = position;
   vec3 tangent = vec3(1.0, 0.0, 0.0);
   vec3 bitangent = vec3(0.0, 0.0, 1.0);
   float crest = 0.0;
+  // Waves flatten as the bed shoals so swells die at the shoreline instead of clipping it.
+  float depthDamp = smoothstep(0.05, 1.4, aDepth);
 
   for (int i = 0; i < 6; i++) {
     vec2 direction = normalize(uWaveDirections[i]);
     vec4 wave = uWaveParams[i];
     float k = wave.x;
-    float amplitude = wave.y;
+    float amplitude = wave.y * depthDamp;
     float steepness = wave.z;
     float omega = wave.w;
     float phase = k * dot(direction, position.xz) - omega * uTime;
@@ -41,12 +48,14 @@ void main() {
   vNormal = normalize(cross(bitangent, tangent));
   vCrest = crest;
   vWaveHeight = displaced.y;
+  vDepth = aDepth;
   vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);
   vWorldPosition = worldPosition.xyz;
   gl_Position = projectionMatrix * viewMatrix * worldPosition;
 }
 `;
 export const oceanFragmentShader = `
+uniform float uTime;
 uniform vec3 uShallowColor;
 uniform vec3 uDeepColor;
 uniform vec3 uCrestColor;
@@ -55,24 +64,83 @@ uniform float uOpacity;
 uniform float uFresnelStrength;
 uniform float uHorizonBlend;
 uniform float uFoamIntensity;
+uniform float uDepthRange;
+uniform float uShoreFoamWidth;
+uniform float uSparkle;
+uniform vec3 uSunDirection;
 
 varying vec3 vWorldPosition;
 varying vec3 vNormal;
 varying float vCrest;
 varying float vWaveHeight;
+varying float vDepth;
+varying vec2 vOceanUv;
+
+float jgWaterHash(vec2 p) {
+  uvec2 q = uvec2(ivec2(floor(p)));
+  uint x = q.x * 1664525u + q.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);
+}
+
+float jgWaterNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgWaterHash(i);
+  float b = jgWaterHash(i + vec2(1.0, 0.0));
+  float c = jgWaterHash(i + vec2(0.0, 1.0));
+  float d = jgWaterHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
 
 void main() {
-  vec3 normal = normalize(vNormal);
   vec3 viewDirection = normalize(cameraPosition - vWorldPosition);
-  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);
-  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);
-  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);
-  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);
-  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);
+
+  // Fine scrolling normal perturbation: two counter-drifting noise layers ripple the surface
+  // between the big Gerstner swells.
+  vec2 wp = vWorldPosition.xz;
+  float ripple1 = jgWaterNoise(wp * 1.7 + vec2(uTime * 0.22, uTime * 0.15));
+  float ripple2 = jgWaterNoise(wp * 3.1 - vec2(uTime * 0.17, uTime * 0.26));
+  vec3 normal = normalize(normalize(vNormal) + vec3(ripple1 - 0.5, 0.0, ripple2 - 0.5) * 0.14);
+
+  // Depth-based body color: warm shallows at the shore ramp falling to the deep tone.
+  float depthMix = smoothstep(0.0, max(uDepthRange, 0.001), vDepth);
+  vec3 waterColor = mix(uShallowColor, uDeepColor, depthMix);
+  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.22);
+
+  // Restrained fresnel: a soft sky tint at grazing angles, never a white-out.
+  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 5.0);
+  waterColor = mix(waterColor, vec3(0.62, 0.78, 0.85), min(fresnel * uFresnelStrength, 0.45));
   float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));
-  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);
-  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);
+  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend * 0.6);
+
+  // Sun glints: sparkle where the perturbed normal mirrors the sun, gated by noise so it
+  // twinkles in cells instead of sheening uniformly.
+  vec3 halfway = normalize(viewDirection + normalize(uSunDirection));
+  float glint = pow(max(dot(normal, halfway), 0.0), 150.0);
+  float glintMask = smoothstep(0.68, 0.92, jgWaterNoise(wp * 2.3 + vec2(uTime * 0.4, -uTime * 0.31)));
+  waterColor += vec3(1.0, 0.98, 0.9) * glint * glintMask * uSparkle;
+
+  // Foam: a noise-eaten shoreline lick plus crest foam. A second, larger noise gates whole
+  // stretches of shoreline so foam laps in patches instead of outlining the bank uniformly.
+  float foamNoise = jgWaterNoise(wp * 2.6 + vec2(uTime * 0.28, uTime * 0.2));
+  float foamStretch = smoothstep(0.3, 0.8, jgWaterNoise(wp * 0.33 + vec2(3.7, 9.2) + vec2(uTime * 0.05, 0.0)));
+  float shoreFoam = (1.0 - smoothstep(0.0, max(uShoreFoamWidth, 0.001), vDepth - foamNoise * uShoreFoamWidth * 0.9))
+    * smoothstep(0.25, 0.75, foamNoise) * (0.2 + 0.6 * foamStretch);
+  float crestFoam = clamp(vCrest * uFoamIntensity, 0.0, 1.0) * smoothstep(0.35, 0.75, foamNoise);
+  float foam = clamp(shoreFoam + crestFoam, 0.0, 1.0);
   vec3 color = mix(waterColor, uFoamColor, foam);
-  gl_FragColor = vec4(color, uOpacity);
+
+  // Soft shore: the sheet turns glass-clear over the last stretch of shoaling bed, so the
+  // waterline is a blend into the terrain, not a hard tarp edge.
+  float shoreAlpha = smoothstep(0.0, 0.55, vDepth);
+  float alpha = uOpacity * mix(0.35, 1.0, shoreAlpha) + foam * 0.3;
+  // The sheet's own border always dissolves — a bounded water plane must never end in a
+  // visible straight cut, whatever the bed underneath is doing.
+  float borderDist = min(min(vOceanUv.x, 1.0 - vOceanUv.x), min(vOceanUv.y, 1.0 - vOceanUv.y));
+  alpha *= smoothstep(0.0, 0.045, borderDist);
+  gl_FragColor = vec4(color, clamp(alpha, 0.0, 1.0));
 }
 `;

package/dist/world/PlaceScene.d.ts

@@ -0,0 +1,11 @@
+import type { PlaceWorldFeature } from "@jgengine/core/world/place";
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export declare function PlaceScene({ feature }: {
+    feature: PlaceWorldFeature;
+}): import("react").JSX.Element | null;