@jgengine/shell 0.9.0 → 0.11.0

package/dist/shellPointer.d.ts

@@ -0,0 +1,20 @@
+import { type ContextMenu } from "@jgengine/core/interaction/contextMenu";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerService } from "./pointer/pointerService.js";
+/** Minimal playable slice for context-menu verb lookup. @internal */
+export type PointerPlayable = {
+    content: {
+        entityById?: (name: string) => {
+            verbs?: ContextMenu["verbs"];
+        } | null | undefined;
+    };
+};
+/** Aim from the possessed/local player eye toward the current pointer world hit. @internal */
+export declare function pointerAimFor(ctx: GameContext, service: PointerService): Aim | undefined;
+/** Context menu for an entity/object pointer hit, or null for empty ground. @internal */
+export declare function pointerContextMenu(ctx: GameContext, playable: PointerPlayable, hit: {
+    point: readonly [number, number, number];
+    entity: string | null;
+    object: string | null;
+}): ContextMenu | null;

package/dist/shellPointer.js

@@ -0,0 +1,28 @@
+import { buildContextMenu, } from "@jgengine/core/interaction/contextMenu";
+import { aimToPoint } from "@jgengine/core/input/pointer";
+import { eyeHeightFromColliders } from "@jgengine/core/combat/shotOrigin";
+/** Aim from the possessed/local player eye toward the current pointer world hit. @internal */
+export function pointerAimFor(ctx, service) {
+    const hit = service.worldHit();
+    if (hit === null)
+        return undefined;
+    const shooter = ctx.scene.entity.get(ctx.player.possession.active(ctx.player.userId)) ??
+        ctx.scene.entity.get(ctx.player.userId);
+    if (shooter === null)
+        return undefined;
+    const eye = eyeHeightFromColliders(ctx.scene.entity.collidersOf(shooter.id));
+    return aimToPoint([shooter.position[0], shooter.position[1] + eye, shooter.position[2]], hit.point);
+}
+/** Context menu for an entity/object pointer hit, or null for empty ground. @internal */
+export function pointerContextMenu(ctx, playable, hit) {
+    if (hit.entity !== null) {
+        const entity = ctx.scene.entity.get(hit.entity);
+        const verbs = entity === null ? undefined : playable.content.entityById?.(entity.name)?.verbs;
+        return buildContextMenu({ kind: "entity", targetId: hit.entity, verbs, point: hit.point });
+    }
+    if (hit.object !== null) {
+        const verbs = ctx.scene.object.catalog(hit.object)?.verbs;
+        return buildContextMenu({ kind: "object", targetId: hit.object, verbs, point: hit.point });
+    }
+    return null;
+}

package/dist/structures/PlacementGhost.d.ts

@@ -5,4 +5,8 @@ export interface PlacementGhostProps {
     validColor?: string;
     invalidColor?: string;
 }
+/**
+ * Cursor-following build ghost: valid/invalid tint from a placement controller preview.
+ * @capability placement-ghost render valid/invalid placement preview mesh
+ */
 export declare function PlacementGhost({ preview, height, validColor, invalidColor, }: PlacementGhostProps): import("react").JSX.Element | null;

package/dist/structures/PlacementGhost.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { quarterTurnsToRotationY } from "@jgengine/core/world/placementController";
+/**
+ * Cursor-following build ghost: valid/invalid tint from a placement controller preview.
+ * @capability placement-ghost render valid/invalid placement preview mesh
+ */
 export function PlacementGhost({ preview, height = 1, validColor = "#34d399", invalidColor = "#f87171", }) {
     const footprint = preview?.footprint;
     const size = useMemo(() => [footprint?.w ?? 1, height, footprint?.d ?? 1], [footprint?.w, footprint?.d, height]);

package/dist/structures/TransformGizmo.d.ts

@@ -0,0 +1,43 @@
+/** Active TransformControls mode for the runtime selection gizmo. */
+export type TransformGizmoMode = "translate" | "rotate" | "scale";
+/** Snap policy: grid quantize, free drag, or ground-height sample on release. */
+export type TransformGizmoSnap = "grid" | "free" | "ground";
+/** Pose reported by {@link TransformGizmo} when the user releases a drag. */
+export interface TransformGizmoPose {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Props for the shared runtime/editor selection gizmo. */
+export interface TransformGizmoProps {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY?: number;
+    mode?: TransformGizmoMode;
+    snapMode?: TransformGizmoSnap;
+    gridSize?: number;
+    /** Vertical offset so the gizmo sits above ground markers. */
+    lift?: number;
+    size?: number;
+    groundSnap?: (x: number, z: number) => number;
+    /** Disable orbit/pan while dragging (shell/editor cameras). */
+    onDraggingChange?: (dragging: boolean) => void;
+    onRelease: (pose: TransformGizmoPose) => void;
+}
+/**
+ * Runtime selection/move gizmo shared by games and the editor.
+ * Wraps TransformControls; callers own selection and commit side-effects.
+ * @capability transform-gizmo in-game select/move/rotate/scale gizmo
+ */
+export declare const TransformGizmo: import("react").MemoExoticComponent<({ position, rotationY, mode, snapMode, gridSize, lift, size, groundSnap, onDraggingChange, onRelease, }: TransformGizmoProps) => import("react").JSX.Element>;

package/dist/structures/TransformGizmo.js

@@ -0,0 +1,55 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TransformControls } from "@react-three/drei";
+import { useThree } from "@react-three/fiber";
+import { memo, useEffect, useRef, useState } from "react";
+/**
+ * Runtime selection/move gizmo shared by games and the editor.
+ * Wraps TransformControls; callers own selection and commit side-effects.
+ * @capability transform-gizmo in-game select/move/rotate/scale gizmo
+ */
+export const TransformGizmo = memo(function TransformGizmo({ position, rotationY = 0, mode = "translate", snapMode = "free", gridSize = 1, lift = 0, size = 0.85, groundSnap, onDraggingChange, onRelease, }) {
+    const groupRef = useRef(null);
+    const [object, setObject] = useState(null);
+    const draggingRef = useRef(false);
+    const controls = useThree((state) => state.controls);
+    const anchorKey = `${position.x}:${position.y}:${position.z}:${rotationY}:${mode}`;
+    useEffect(() => {
+        setObject(groupRef.current);
+    }, [anchorKey]);
+    useEffect(() => {
+        const group = groupRef.current;
+        if (group === null || draggingRef.current)
+            return;
+        group.position.set(position.x, position.y + lift, position.z);
+        group.rotation.set(0, rotationY, 0);
+        group.scale.set(1, 1, 1);
+    }, [position.x, position.y, position.z, rotationY, lift, anchorKey, mode]);
+    const snapProps = snapMode === "grid"
+        ? { translationSnap: gridSize, rotationSnap: Math.PI / 12 }
+        : { rotationSnap: Math.PI / 12 };
+    const handleRelease = () => {
+        draggingRef.current = false;
+        if (controls !== null && "enabled" in controls)
+            controls.enabled = true;
+        onDraggingChange?.(false);
+        const current = groupRef.current;
+        if (current === null)
+            return;
+        let y = current.position.y - lift;
+        if (snapMode === "ground" && groundSnap !== undefined) {
+            y = groundSnap(current.position.x, current.position.z);
+            current.position.y = y + lift;
+        }
+        onRelease({
+            position: { x: current.position.x, y, z: current.position.z },
+            rotationY: current.rotation.y,
+            scale: { x: current.scale.x, y: current.scale.y, z: current.scale.z },
+        });
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("group", { ref: groupRef }), object !== null ? (_jsx(TransformControls, { object: object, mode: mode, size: size, ...snapProps, onMouseDown: () => {
+                    draggingRef.current = true;
+                    if (controls !== null && "enabled" in controls)
+                        controls.enabled = false;
+                    onDraggingChange?.(true);
+                }, onMouseUp: handleRelease })) : null] }));
+});

package/dist/structures/index.d.ts

@@ -1,2 +1,3 @@
 export { BuildingBlock, GeneratedBuilding, InstancedBuildings, type BuildingBlockProps, type GeneratedBuildingProps, type InstancedBuildingPlacement, type InstancedBuildingsProps, } from "./GeneratedBuilding.js";
 export { PlacementGhost, type PlacementGhostProps } from "./PlacementGhost.js";
+export { TransformGizmo, type TransformGizmoMode, type TransformGizmoPose, type TransformGizmoProps, type TransformGizmoSnap, } from "./TransformGizmo.js";

package/dist/structures/index.js

@@ -1,2 +1,3 @@
 export { BuildingBlock, GeneratedBuilding, InstancedBuildings, } from "./GeneratedBuilding.js";
 export { PlacementGhost } from "./PlacementGhost.js";
+export { TransformGizmo, } from "./TransformGizmo.js";

package/dist/terrain/CarvedTerrain.d.ts

@@ -1,4 +1,5 @@
 import { type ThreeElements } from "@react-three/fiber";
+import * as THREE from "three";
 import type { TerrainField } from "@jgengine/core/world/terrain";
 import { type FieldGroundOptions } from "./terrainMath.js";
 export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
@@ -12,6 +13,8 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     paletteAt?: FieldGroundOptions["paletteAt"];
     roughness?: number;
     metalness?: number;
+    /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
+    surfaceMaterial?: THREE.Material;
     /** Bump after a runtime carve/deposit to re-mesh the deformed surface. */
     epoch?: number;
 }
@@ -20,4 +23,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -8,12 +8,13 @@ import { createFieldGroundGeometry } from "./terrainMath.js";
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, receiveShadow = true, epoch = 0, ...meshProps }) {
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
     const geometry = useMemo(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [field, size, segments, center, colors, heightRange, paletteAt, epoch]);
-    const material = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    const defaultMaterial = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    const material = surfaceMaterial ?? defaultMaterial;
     useEffect(() => () => geometry.dispose(), [geometry]);
-    useEffect(() => () => material.dispose(), [material]);
+    useEffect(() => () => defaultMaterial.dispose(), [defaultMaterial]);
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
 }

package/dist/terrain/GrassField.js

@@ -23,7 +23,7 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         wind,
         roughness,
     }), [colorBase, colorTip, colorVariation, roughness, wind]);
-    geometry.instanceCount = resolveGrassInstanceBudget(count, density, budget);
+    geometry.instanceCount = resolveGrassInstanceBudget(count, density, area, budget);
     useFrame((state) => {
         handle.uniforms.uTime.value = state.clock.elapsedTime;
     });

package/dist/terrain/TerraformBrushCursor.js

@@ -2,7 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const MODE_COLOR = {
     raise: "#38bdf8",
     lower: "#fb923c",
+    smooth: "#c084fc",
     flatten: "#a3e635",
+    noise: "#facc15",
+    ramp: "#2dd4bf",
     paint: "#e879f9",
 };
 export function TerraformBrushCursor({ center, y = 0.05, radius, mode }) {

package/dist/terrain/grassBudget.d.ts

@@ -1,3 +1,12 @@
+import { type TerrainArea } from "./terrainMath.js";
 export declare const DEFAULT_GRASS_COUNT = 1500;
-export declare const DEFAULT_GRASS_DENSITY = 1;
-export declare function resolveGrassInstanceBudget(count: number, density: number, budget?: number): number;
+/** Blades per square meter — matches `@jgengine/core/world/vegetation`'s `VEGETATION_DEFAULTS.density`, so an editor-placed grass volume and a bare `<GrassField>` agree on what "4" means. */
+export declare const DEFAULT_GRASS_DENSITY = 4;
+/**
+ * Blade instance count for a patch: `density` (blades/m²) times the patch's
+ * `area`, capped at `budget` (defaulting to `count`, the buffer's allocated
+ * capacity) so a big field never exceeds the perf ceiling — it just renders
+ * sparser than requested and logs a devtools warning when that happens.
+  * @internal
+  */
+export declare function resolveGrassInstanceBudget(count: number, density: number, area: TerrainArea, budget?: number): number;

package/dist/terrain/grassBudget.js

@@ -1,6 +1,22 @@
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { resolveTerrainSize } from "./terrainMath.js";
 export const DEFAULT_GRASS_COUNT = 1500;
-export const DEFAULT_GRASS_DENSITY = 1;
-export function resolveGrassInstanceBudget(count, density, budget) {
-    const capped = budget === undefined ? count : Math.min(count, Math.max(0, Math.floor(budget)));
-    return Math.floor(Math.max(0, Math.min(1, density)) * capped);
+/** Blades per square meter — matches `@jgengine/core/world/vegetation`'s `VEGETATION_DEFAULTS.density`, so an editor-placed grass volume and a bare `<GrassField>` agree on what "4" means. */
+export const DEFAULT_GRASS_DENSITY = 4;
+/**
+ * Blade instance count for a patch: `density` (blades/m²) times the patch's
+ * `area`, capped at `budget` (defaulting to `count`, the buffer's allocated
+ * capacity) so a big field never exceeds the perf ceiling — it just renders
+ * sparser than requested and logs a devtools warning when that happens.
+  * @internal
+  */
+export function resolveGrassInstanceBudget(count, density, area, budget) {
+    const size = resolveTerrainSize(area);
+    const areaSqMeters = Math.max(0, size.width) * Math.max(0, size.depth);
+    const requested = Math.max(0, density) * areaSqMeters;
+    const cap = budget === undefined ? count : Math.min(count, Math.max(0, Math.floor(budget)));
+    if (requested > cap) {
+        devtools.logs.push("warn", `[jgengine:grass] density ${density} blades/m² over ${areaSqMeters.toFixed(0)}m² wants ${Math.floor(requested)} blades — clamped to budget ${cap}`);
+    }
+    return Math.floor(Math.min(Math.max(0, cap), requested));
 }

package/dist/terrain/grassGeometry.d.ts

@@ -22,6 +22,9 @@ export interface ResolvedGrassBladeGeometryOptions {
     bend: readonly [min: number, max: number];
     heightAt: TerrainHeightSampler;
 }
+/** @internal */
 export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];
+/** @internal */
 export declare function resolveGrassBladeGeometryOptions(options?: GrassBladeGeometryOptions): ResolvedGrassBladeGeometryOptions;
+/** @internal */
 export declare function createGrassBladeGeometry(options?: GrassBladeGeometryOptions): THREE.InstancedBufferGeometry;

package/dist/terrain/grassGeometry.js

@@ -1,11 +1,13 @@
 import * as THREE from "three";
 import { createSeededRandom } from "./random.js";
 import { resolveTerrainSize } from "./terrainMath.js";
+/** @internal */
 export function resolveGrassRange(value, fallback) {
     if (value === undefined)
         return fallback;
     return typeof value === "number" ? [value, value] : value;
 }
+/** @internal */
 export function resolveGrassBladeGeometryOptions(options = {}) {
     return {
         count: Math.max(0, Math.floor(options.count ?? 1500)),
@@ -21,6 +23,7 @@ export function resolveGrassBladeGeometryOptions(options = {}) {
 function randomRange(random, range) {
     return THREE.MathUtils.lerp(range[0], range[1], random());
 }
+/** @internal */
 export function createGrassBladeGeometry(options = {}) {
     const resolved = resolveGrassBladeGeometryOptions(options);
     const size = resolveTerrainSize(resolved.area);

package/dist/terrain/grassMaterial.d.ts

@@ -29,5 +29,7 @@ export interface GrassMaterialHandle {
     uniforms: GrassShaderUniforms;
 }
 export declare const DEFAULT_GRASS_WIND: Required<GrassWindOptions>;
+/** @internal */
 export declare function resolveGrassWind(wind: GrassWindOptions | false | undefined): Required<GrassWindOptions>;
+/** @internal */
 export declare function createGrassMaterial(options?: GrassMaterialOptions): GrassMaterialHandle;

package/dist/terrain/grassMaterial.js

@@ -10,6 +10,7 @@ function normalizeWindDirection(direction) {
     const vector = new THREE.Vector2(direction[0], direction[1]);
     return vector.lengthSq() === 0 ? new THREE.Vector2(1, 0) : vector.normalize();
 }
+/** @internal */
 export function resolveGrassWind(wind) {
     if (wind === false)
         return { ...DEFAULT_GRASS_WIND, strength: 0, flutter: 0 };
@@ -21,6 +22,7 @@ export function resolveGrassWind(wind) {
         flutter: wind?.flutter ?? DEFAULT_GRASS_WIND.flutter,
     };
 }
+/** @internal */
 export function createGrassMaterial(options = {}) {
     const wind = resolveGrassWind(options.wind);
     const uniforms = {

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,10 @@
+import * as THREE from "three";
+import type { SoilRules } from "@jgengine/core/world/soilKind";
+/**
+ * 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.
+ * @internal
+ */
+export declare function createSoilPatchMaterial(rules: SoilRules): THREE.MeshStandardMaterial;

package/dist/terrain/soilPatchMaterial.js

@@ -0,0 +1,109 @@
+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);
+}
+`;
+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.
+ * A game never calls this directly — author a soil patch via the editor's `soil` studio kind.
+ * @internal
+ */
+export function createSoilPatchMaterial(rules) {
+    const seedOffset = hashSeed(rules.seed);
+    const material = new THREE.MeshStandardMaterial({
+        color: rules.baseColor,
+        roughness: 0.92,
+        metalness: 0,
+    });
+    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 };
+        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;
+${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);
+vec3 jgSoilCol = mix(diffuseColor.rgb, uSoilCrackColor, jgSoilCrack * uSoilCrackIntensity);
+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;`);
+    };
+    material.customProgramCacheKey = () => `jgengine-soil-${rules.crackScale}-${rules.crackIntensity}-${rules.mossCoverage}-${seedOffset}`;
+    return material;
+}

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -0,0 +1,31 @@
+import * as THREE from "three";
+import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
+/** The built procedural detail terrain material, ready to mount on the ground mesh. */
+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.
+ *
+ * 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;