@jgengine/shell 0.25.0 → 0.27.0

package/dist/render/triplanarMaterial.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { useMaterialAssetMaterial } from "./materialAsset.js";
+const VERTEX_PARS = `varying vec3 vJgTriPos;
+varying vec3 vJgTriNormal;`;
+const VERTEX_WORLD_NORMAL = `vJgTriNormal = normalize(mat3(modelMatrix) * objectNormal);`;
+const VERTEX_WORLD_POSITION = `vec4 jgTriWorld = vec4(transformed, 1.0);
+#ifdef USE_INSTANCING
+jgTriWorld = instanceMatrix * jgTriWorld;
+#endif
+vJgTriPos = (modelMatrix * jgTriWorld).xyz;`;
+const FRAGMENT_PARS = `varying vec3 vJgTriPos;
+varying vec3 vJgTriNormal;
+uniform float uJgTriTile;
+uniform float uJgTriSharp;
+uniform float uJgTriNormalScale;
+vec3 jgTriWeights() {
+  vec3 w = pow(abs(normalize(vJgTriNormal)), vec3(uJgTriSharp));
+  return w / max(dot(w, vec3(1.0)), 1e-4);
+}
+vec3 jgTriSample(sampler2D tex, vec3 w) {
+  vec3 p = vJgTriPos / uJgTriTile;
+  return texture2D(tex, p.zy).rgb * w.x + texture2D(tex, p.xz).rgb * w.y + texture2D(tex, p.xy).rgb * w.z;
+}`;
+const FRAGMENT_COLOR = `#ifdef USE_MAP
+{
+  vec3 jgW = jgTriWeights();
+  vec3 jgP = vJgTriPos / uJgTriTile;
+  diffuseColor *= texture2D(map, jgP.zy) * jgW.x + texture2D(map, jgP.xz) * jgW.y + texture2D(map, jgP.xy) * jgW.z;
+}
+#endif`;
+const FRAGMENT_ROUGHNESS = `float roughnessFactor = roughness;
+#ifdef USE_ROUGHNESSMAP
+roughnessFactor *= jgTriSample(roughnessMap, jgTriWeights()).g;
+#endif`;
+// Each projection perturbs the world normal along its own tangent frame: an X-facing projection
+// uses +Z as U and +Y as V, a Y-facing one +X/+Z, a Z-facing one +X/+Y.
+const FRAGMENT_NORMAL = `#ifdef USE_NORMALMAP
+{
+  vec3 jgW = jgTriWeights();
+  vec3 jgP = vJgTriPos / uJgTriTile;
+  vec3 jgNx = texture2D(normalMap, jgP.zy).xyz * 2.0 - 1.0;
+  vec3 jgNy = texture2D(normalMap, jgP.xz).xyz * 2.0 - 1.0;
+  vec3 jgNz = texture2D(normalMap, jgP.xy).xyz * 2.0 - 1.0;
+  jgNx.xy *= uJgTriNormalScale;
+  jgNy.xy *= uJgTriNormalScale;
+  jgNz.xy *= uJgTriNormalScale;
+  vec3 jgPerturb = vec3(jgNx.z, jgNx.y, jgNx.x) * jgW.x
+    + vec3(jgNy.x, jgNy.z, jgNy.y) * jgW.y
+    + vec3(jgNz.x, jgNz.y, jgNz.z) * jgW.z;
+  normal = normalize((viewMatrix * vec4(normalize(vJgTriNormal + jgPerturb), 0.0)).xyz);
+}
+#endif`;
+const FRAGMENT_AO = `#ifdef USE_AOMAP
+{
+  float jgAo = jgTriSample(aoMap, jgTriWeights()).r;
+  float ambientOcclusion = ( jgAo - 1.0 ) * aoMapIntensity + 1.0;
+  reflectedLight.indirectDiffuse *= ambientOcclusion;
+  #if defined( USE_CLEARCOAT )
+    clearcoatSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_SHEEN )
+    sheenSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_ENVMAP ) && defined( STANDARD )
+    float dotNV = saturate( dot( geometryNormal, geometryViewDir ) );
+    reflectedLight.indirectSpecular *= computeSpecularOcclusion( dotNV, ambientOcclusion, material.roughness );
+  #endif
+}
+#endif`;
+/**
+ * The GLSL the triplanar path injects, split by chunk. Exposed so a test can prove the patch
+ * samples by world position instead of `vMapUv`, and so a reader can audit the projection.
+ * @internal
+ */
+export function triplanarChunks() {
+    return {
+        vertexPars: VERTEX_PARS,
+        vertexNormal: VERTEX_WORLD_NORMAL,
+        vertexPosition: VERTEX_WORLD_POSITION,
+        fragmentPars: FRAGMENT_PARS,
+        color: FRAGMENT_COLOR,
+        roughness: FRAGMENT_ROUGHNESS,
+        normal: FRAGMENT_NORMAL,
+        ao: FRAGMENT_AO,
+    };
+}
+function assertPatchable(material) {
+    const vertex = THREE.ShaderLib.physical.vertexShader;
+    const fragment = THREE.ShaderLib.physical.fragmentShader;
+    const required = [
+        [vertex, "#include <beginnormal_vertex>"],
+        [vertex, "#include <worldpos_vertex>"],
+        [fragment, "#include <map_fragment>"],
+        [fragment, "#include <roughnessmap_fragment>"],
+        [fragment, "#include <normal_fragment_maps>"],
+        [fragment, "#include <aomap_fragment>"],
+    ];
+    for (const [source, marker] of required) {
+        if (!source.includes(marker))
+            throw new Error(`Three.js r${THREE.REVISION} physical shader lacks ${marker} for the triplanar world projection`);
+    }
+    if (!material.isMeshStandardMaterial)
+        throw new Error("Triplanar projection requires a standard or physical material");
+}
+/**
+ * Projects a standard material's maps from world position instead of mesh UVs, so world geometry
+ * without a `uv` attribute still renders a textured PBR surface. Instanced meshes project in their
+ * instanced world space. Skinned meshes keep the bind-pose normal for the blend weights, which is
+ * close enough for the static world surfaces this path exists for.
+ */
+export function applyTriplanarProjection(material, options) {
+    const tile = options.tileMetres;
+    if (!Number.isFinite(tile) || tile <= 0)
+        throw new Error("Triplanar tileMetres must be finite and positive");
+    const sharpness = options.sharpness ?? 8;
+    const normalScale = options.normalScale ?? 1;
+    if (!Number.isFinite(sharpness) || sharpness <= 0)
+        throw new Error("Triplanar sharpness must be finite and positive");
+    if (!Number.isFinite(normalScale) || normalScale < 0)
+        throw new Error("Triplanar normalScale must be finite and non-negative");
+    if (material.userData["jgTriplanar"] !== undefined)
+        return material;
+    assertPatchable(material);
+    const uniforms = {
+        uJgTriTile: { value: tile },
+        uJgTriSharp: { value: sharpness },
+        uJgTriNormalScale: { value: normalScale },
+    };
+    material.userData["jgTriplanar"] = uniforms;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>\n${VERTEX_PARS}`)
+            .replace("#include <beginnormal_vertex>", `#include <beginnormal_vertex>\n${VERTEX_WORLD_NORMAL}`)
+            .replace("#include <worldpos_vertex>", `#include <worldpos_vertex>\n${VERTEX_WORLD_POSITION}`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>\n${FRAGMENT_PARS}`)
+            .replace("#include <map_fragment>", FRAGMENT_COLOR)
+            .replace("#include <roughnessmap_fragment>", FRAGMENT_ROUGHNESS)
+            .replace("#include <normal_fragment_maps>", FRAGMENT_NORMAL)
+            .replace("#include <aomap_fragment>", FRAGMENT_AO);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}|jg-triplanar:v1`;
+    material.needsUpdate = true;
+    return material;
+}
+/**
+ * Render a serializable material asset — one built by `libraryMaterialAsset`, or authored in the
+ * editor — with world-space triplanar projection, so world geometry needs no UVs. Tile size
+ * defaults to the asset's own `physicalSize`, which the shared library sets per surface.
+ * @capability material-triplanar render a material asset on world geometry without UVs
+ */
+export function useTriplanarAssetMaterial(asset, options = {}) {
+    const material = useMaterialAssetMaterial(asset);
+    const tile = options.tileMetres ?? asset.textures?.color?.physicalSize?.[0] ?? asset.textures?.normal?.physicalSize?.[0] ?? 1;
+    const sharpness = options.sharpness ?? 8;
+    const normalScale = options.normalScale ?? 1;
+    return useMemo(() => applyTriplanarProjection(material, { tileMetres: tile, sharpness, normalScale }), [material, tile, sharpness, normalScale]);
+}
+/** Mounts {@link useTriplanarAssetMaterial} on a mesh; the R3F renderer owns disposal. */
+export function TriplanarAssetMaterial({ asset, ...options }) {
+    const material = useTriplanarAssetMaterial(asset, options);
+    return _jsx("primitive", { object: material, attach: "material" });
+}

package/dist/render/useModelInstance.d.ts

@@ -1,7 +1,7 @@
 import { Group, type Object3D } from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 /** Model loading, placement, shadows and animation for a custom renderer. */
-export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail">;
+export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail" | "wind">;
 /** Caller-owned styling runs on the isolated clone, never the loader cache. */
 export interface ModelInstanceOptions {
     instanceId?: string;

package/dist/render/useModelInstance.js

@@ -5,6 +5,7 @@ import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility
 import { measureLocalBounds } from "./measureBounds.js";
 import { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
 import { cloneModelScene, disposeModelScene, modelPlacementTransform } from "./modelRender.js";
+import { applyModelWindToScene } from "./modelWind.js";
 import { useModelAnimation } from "./useModelAnimation.js";
 import { applyModelNodeVisibility, modelHiddenNodesKey } from "./modelNodeVisibility.js";
 /**
@@ -26,6 +27,7 @@ export function useModelInstance(model, options = {}) {
         const content = cloneModelScene(gltf.scene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
         try {
             configure?.(content);
+            applyModelWindToScene(content, model.wind, model.wind === false || model.wind === undefined ? 4 : model.wind.height ?? 4);
             for (const diagnostic of applyModelNodeVisibility(content, hiddenNodes))
                 console.warn(`Model ${model.url} hiddenNodes: ${diagnostic.message}`);
             const scene = new Group().add(content);
@@ -35,7 +37,7 @@ export function useModelInstance(model, options = {}) {
             disposeModelScene(content);
             throw error;
         }
-    }, [gltf.scene, model.shadows, model.surfaceDetail, configure, hiddenNodesKey]);
+    }, [gltf.scene, model.shadows, model.surfaceDetail, model.wind, configure, hiddenNodesKey]);
     const placement = useMemo(() => modelPlacementTransform(scene, model, bindBounds), [scene, bindBounds, model.scale, model.targetHeight, model.y, model.anchor, model.dims]);
     useEffect(() => () => disposeModelScene(content), [content]);
     useModelAnimation(content, gltf.animations, model.animation, instanceId);

package/dist/scatter/scatterModels.js

@@ -3,6 +3,7 @@ import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility
 import { applyMaterialOverride } from "../materialOverride.js";
 import { cloneModelScene, disposeModelScene, ownModelMaterial } from "../render/modelRender.js";
 import { applyModelSurface } from "../render/modelSurface.js";
+import { applyModelWindToScene } from "../render/modelWind.js";
 /** The scale + position offset a `ModelConfig` applies before any per-instance transform — same anchor/targetHeight rules as the single-instance entity renderer. */
 function scatterModelBaseTransform(scene, model) {
     let scale = model.scale ?? 1;
@@ -43,6 +44,7 @@ export function buildScatterModelSources(gltfScene, model) {
         throw new Error("Instanced model override maps require an owned texture loader; use EntityModel for authored maps");
     applyModelSurface(gltfScene);
     const root = cloneModelScene(gltfScene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
+    applyModelWindToScene(root, model.wind, model.dims?.maxY ?? model.targetHeight ?? 4);
     if (model.material !== undefined)
         applyMaterialOverride(root, model.material, { clone: false, ownMaterial: material => ownModelMaterial(root, material) });
     root.updateMatrixWorld(true);

package/dist/scene/DecalRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerDecalRenderer(): void;

package/dist/scene/DecalRenderer.js

@@ -0,0 +1,74 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { resolveDecalObject } from "@jgengine/core/world/decalKind";
+import { createDecalDrapeGeometry } from "../render/decalGeometry.js";
+import { createDecalTexture } from "../render/decalTexture.js";
+import { useDisposable } from "../render/useDisposable.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Tilts at or above this stand the decal up on a wall instead of draping it on the ground. */
+const WALL_TILT = 45;
+function dataTexture(style, seed) {
+    const baked = createDecalTexture(style, seed);
+    const texture = new THREE.DataTexture(baked.data, baked.size, baked.size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.magFilter = THREE.LinearFilter;
+    texture.minFilter = THREE.LinearMipmapLinearFilter;
+    texture.generateMipmaps = true;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.needsUpdate = true;
+    return texture;
+}
+function OneDecal({ object, context }) {
+    const resolved = useMemo(() => resolveDecalObject(object), [object]);
+    const rules = resolved?.rules;
+    const style = rules?.style ?? "dirt";
+    const seed = rules?.seed ?? "";
+    const texture = useDisposable(() => dataTexture(style, seed), [style, seed]);
+    const wall = (rules?.tilt ?? 0) >= WALL_TILT;
+    const geometry = useDisposable(() => {
+        if (resolved === null || rules === undefined)
+            return new THREE.BufferGeometry();
+        if (wall)
+            return new THREE.PlaneGeometry(rules.size, rules.size);
+        const draped = createDecalDrapeGeometry({
+            size: rules.size,
+            rotationY: resolved.rotationY,
+            heightAt: context.field.sampleHeight,
+            lift: rules.lift,
+        });
+        const next = new THREE.BufferGeometry();
+        next.setAttribute("position", new THREE.BufferAttribute(draped.positions, 3));
+        next.setAttribute("normal", new THREE.BufferAttribute(draped.normals, 3));
+        next.setAttribute("uv", new THREE.BufferAttribute(draped.uvs, 2));
+        next.setIndex(new THREE.BufferAttribute(draped.indices, 1));
+        next.computeBoundingSphere();
+        return next;
+    }, [resolved, rules, wall, context.field]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
+        map: texture,
+        transparent: true,
+        depthWrite: false,
+        opacity: rules?.opacity ?? 1,
+        roughness: 0.92,
+        metalness: 0,
+        polygonOffset: true,
+        polygonOffsetFactor: -4,
+        polygonOffsetUnits: -4,
+    }), [texture, rules?.opacity]);
+    if (resolved === null || rules === undefined)
+        return null;
+    const [px, py, pz] = resolved.position;
+    if (!wall) {
+        return _jsx("mesh", { geometry: geometry, material: material, position: [px, py, pz], receiveShadow: true, frustumCulled: true });
+    }
+    // A standing decal is pushed out along its own normal so it clears the wall it describes.
+    const normalX = Math.sin(resolved.rotationY);
+    const normalZ = Math.cos(resolved.rotationY);
+    return (_jsx("mesh", { geometry: geometry, material: material, position: [px + normalX * rules.offset, py + rules.lift, pz + normalZ * rules.offset], rotation: [THREE.MathUtils.degToRad(rules.tilt - 90), resolved.rotationY, 0], receiveShadow: true, frustumCulled: true }));
+}
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerDecalRenderer() {
+    registerSceneKindRenderer("decal", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneDecal, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/GrassFieldRenderer.js

@@ -1,9 +1,10 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo } from "react";
 import { resolveGrassObject } from "@jgengine/core/world/grassKind";
 import { clearanceMasksFrom, DEFAULT_CLEARANCE_KINDS } from "@jgengine/core/world/scatterRegion";
 import { masksInfluence } from "@jgengine/core/world/geometry";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.js";
 import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 /** Volume kinds turf yields to — blades never grow through cracked soil or out of open water. */
 const GRASS_YIELDS_TO = new Set(["soil", "water"]);
@@ -86,7 +87,7 @@ function OneGrass({ object, context }) {
     // footprint, and the fade only thins how many *draw* at range in the vertex shader — so a deeper
     // meadow reads expansive without raising the instance ceiling.
     const instanceCount = Math.max(1500, Math.min(250000, Math.ceil(rules.density * area[0] * area[1])));
-    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+    return (_jsxs(_Fragment, { children: [_jsx(GrassCover, { position: [center[0], center[1], center[2]], area: area, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), colorBase: rules.colorBase, colorTip: rules.colorTip, strength: rules.groundCover, edgeFeather: 2.2, heightAt: heightAt, coverageAt: coverageAt }), _jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude })] }));
 }
 /** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
 export function registerGrassFieldRenderer() {

package/dist/scene/builtinSceneKindRenderers.js

@@ -11,6 +11,7 @@ import { registerWaterRenderer } from "./WaterRenderer.js";
 import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
 import { registerCityRenderer } from "./CityRenderer.js";
 import { registerPoleLineRenderer } from "./PoleLineRenderer.js";
+import { registerDecalRenderer } from "./DecalRenderer.js";
 let registered = false;
 /** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
 export function registerBuiltinSceneKindRenderers() {
@@ -23,4 +24,5 @@ export function registerBuiltinSceneKindRenderers() {
     registerSoilPatchRenderer();
     registerCityRenderer();
     registerPoleLineRenderer();
+    registerDecalRenderer();
 }

package/dist/settings/appliedSettings.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { busVolumeSettingId, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
 import { readGraphicsSettings } from "@jgengine/core/settings/graphicsSettings";
 import { readFrameRateLimit } from "@jgengine/core/settings/frameRateLimit";
@@ -29,18 +29,21 @@ export function useSettingsRevision(store) {
     return useSyncExternalStore(subscribe, getVersion, getVersion);
 }
 export function useGraphicsSettings(store, shadowsDefault, overrides) {
-    useSettingsRevision(store);
-    const { quality, profile } = readGraphicsSettings(store, overrides);
-    const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
-    return {
-        shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: profile.renderScale,
-        uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
-        quality,
-        profile,
-        frameRateLimit: readFrameRateLimit(store),
-        showFps: store.get(SETTING_IDS.graphicsShowFps, false),
-    };
+    const rev = useSettingsRevision(store);
+    // Effects rebuild on identity change; a fresh object each render recompiled the post chain every frame.
+    return useMemo(() => {
+        const { quality, profile } = readGraphicsSettings(store, overrides);
+        const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
+        return {
+            shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
+            dpr: profile.renderScale,
+            uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
+            quality,
+            profile,
+            frameRateLimit: readFrameRateLimit(store),
+            showFps: store.get(SETTING_IDS.graphicsShowFps, false),
+        };
+    }, [store, rev, shadowsDefault, overrides]);
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {
     const rev = useSettingsRevision(store);

package/dist/terrain/GrassCover.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from "three";
+import type { TerrainHeightSampler } from "./terrainMath.js";
+/** Props for {@link GrassCover}: one authored patch's footprint, colours and drape samplers. */
+export interface GrassCoverProps {
+    area: readonly [number, number];
+    seed: number;
+    colorBase: THREE.ColorRepresentation;
+    colorTip: THREE.ColorRepresentation;
+    strength: number;
+    edgeFeather: number;
+    heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
+    segments?: number;
+    position?: readonly [number, number, number];
+}
+/**
+ * The turf surface under one authored `grass_field` patch: a ground-draped, edge-feathered mat that
+ * turns a bare pavement footprint into grass the blade field stands in. Bounded to one draw and a
+ * {@link GRASS_COVER_MAX_SEGMENTS}² grid, so a large park still costs a single mesh.
+ */
+export declare function GrassCover({ area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments, position, }: GrassCoverProps): import("react").JSX.Element | null;

package/dist/terrain/GrassCover.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
+import { createGrassCoverGeometry, GRASS_COVER_MAX_SEGMENTS } from "./grassCoverGeometry.js";
+let grainTexture = null;
+/**
+ * Tileable thatch grain for the cover mat (luminance around 0.9), generated once from a hash — no
+ * asset pull, deterministic, and cheap enough that a 96² mat still reads as grass up close.
+ */
+function coverGrain() {
+    if (grainTexture !== null)
+        return grainTexture;
+    const size = 64;
+    const data = new Uint8Array(size * size * 4);
+    const hash = (x, y) => {
+        let h = Math.imul(x + 1, 374761393) ^ Math.imul(y + 1, 668265263) ^ 0x9e3779b9;
+        h = Math.imul(h ^ (h >>> 13), 1274126177);
+        return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+    };
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const fine = (hash(x, y) + hash((x + 32) % size, (y + 17) % size)) * 0.5;
+            const clump = (hash((x >> 2) * 3, (y >> 2) * 5) + hash(((x >> 2) + 7) % 16, ((y >> 2) + 3) % 16)) * 0.5;
+            const value = Math.max(180, Math.min(255, Math.round(232 + (fine - 0.5) * 46 + (clump - 0.5) * 30)));
+            const i = (y * size + x) * 4;
+            data[i] = value;
+            data[i + 1] = value;
+            data[i + 2] = value;
+            data[i + 3] = 255;
+        }
+    }
+    grainTexture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    grainTexture.wrapS = THREE.RepeatWrapping;
+    grainTexture.wrapT = THREE.RepeatWrapping;
+    grainTexture.magFilter = THREE.LinearFilter;
+    grainTexture.minFilter = THREE.LinearMipmapLinearFilter;
+    grainTexture.generateMipmaps = true;
+    grainTexture.needsUpdate = true;
+    return grainTexture;
+}
+/**
+ * The turf surface under one authored `grass_field` patch: a ground-draped, edge-feathered mat that
+ * turns a bare pavement footprint into grass the blade field stands in. Bounded to one draw and a
+ * {@link GRASS_COVER_MAX_SEGMENTS}² grid, so a large park still costs a single mesh.
+ */
+export function GrassCover({ area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments, position, }) {
+    const geometry = useDisposable(() => {
+        const baked = createGrassCoverGeometry({
+            area,
+            seed,
+            colorBase,
+            colorTip,
+            strength,
+            edgeFeather,
+            heightAt,
+            coverageAt,
+            ...(segments === undefined ? {} : { segments }),
+        });
+        const next = new THREE.BufferGeometry();
+        if (baked.positions.length === 0)
+            return next;
+        next.setAttribute("position", new THREE.BufferAttribute(baked.positions, 3));
+        next.setAttribute("normal", new THREE.BufferAttribute(baked.normals, 3));
+        next.setAttribute("color", new THREE.BufferAttribute(baked.colors, 4));
+        next.setAttribute("uv", new THREE.BufferAttribute(baked.uvs, 2));
+        next.setIndex(new THREE.BufferAttribute(baked.indices, 1));
+        next.computeBoundingSphere();
+        return next;
+    }, [area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
+        map: coverGrain(),
+        vertexColors: true,
+        transparent: true,
+        depthWrite: false,
+        roughness: 0.96,
+        metalness: 0,
+        polygonOffset: true,
+        polygonOffsetFactor: -1,
+        polygonOffsetUnits: -1,
+    }), []);
+    if (strength <= 0)
+        return null;
+    return (_jsx("mesh", { geometry: geometry, material: material, receiveShadow: true, frustumCulled: true, ...(position === undefined ? {} : { position: [position[0], position[1], position[2]] }) }));
+}

package/dist/terrain/grassCoverGeometry.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+import { type TerrainArea, type TerrainHeightSampler } from "./terrainMath.js";
+/** World metres one cover-texture tile spans; the mat's own grain is sampled in world space. */
+export declare const GRASS_COVER_TILE_METRES = 3;
+/** Largest grid a cover mat bakes to, per axis — a 66 m park stays one draw at ~1 m cells. */
+export declare const GRASS_COVER_MAX_SEGMENTS = 96;
+/** Inputs for {@link createGrassCoverGeometry}. */
+export interface GrassCoverGeometryOptions {
+    area: TerrainArea;
+    seed: number;
+    colorBase: THREE.ColorRepresentation;
+    colorTip: THREE.ColorRepresentation;
+    /** Ground-cover mat strength 0..1 (the authored `groundCover`); 0 produces no geometry. */
+    strength: number;
+    /** Meters of soft fringe at the patch border, matching the blade field's own feather. */
+    edgeFeather: number;
+    heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
+    /** Lift above the ground in meters so the mat never z-fights the terrain. Default 0.035. */
+    lift?: number;
+    /** Grid segments per axis; defaults to one per 2 m, clamped to {@link GRASS_COVER_MAX_SEGMENTS}. */
+    segments?: number;
+}
+/** Bake result for {@link createGrassCoverGeometry}; empty arrays when the mat is switched off. */
+export interface GrassCoverGeometry {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+    size: readonly [number, number];
+}
+/**
+ * Drapes an authored `grass_field` volume's footprint with a feathered turf mat: vertices follow the
+ * runtime ground, the patch edge fades out over `edgeFeather`, and authored clearance masks punch
+ * the cover back out where a path or footing crosses it. This is the surface under the blades, so a
+ * park reads as grass instead of bare pavement with stubble on it.
+ * @internal
+ */
+export declare function createGrassCoverGeometry(options: GrassCoverGeometryOptions): GrassCoverGeometry;

package/dist/terrain/grassCoverGeometry.js

@@ -0,0 +1,112 @@
+import * as THREE from "three";
+import { resolveTerrainSize } from "./terrainMath.js";
+/** World metres one cover-texture tile spans; the mat's own grain is sampled in world space. */
+export const GRASS_COVER_TILE_METRES = 3;
+/** Largest grid a cover mat bakes to, per axis — a 66 m park stays one draw at ~1 m cells. */
+export const GRASS_COVER_MAX_SEGMENTS = 96;
+function hash2(x, z, seed) {
+    let h = Math.imul(x | 0, 374761393) ^ Math.imul(z | 0, 668265263) ^ Math.imul(seed | 0, 2246822519);
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function smooth(t) {
+    return t * t * (3 - 2 * t);
+}
+/** Bilinear value noise in world space; deterministic per seed, no allocation on the hot path. */
+function valueNoise(x, z, seed) {
+    const xi = Math.floor(x);
+    const zi = Math.floor(z);
+    const tx = smooth(x - xi);
+    const tz = smooth(z - zi);
+    const a = hash2(xi, zi, seed);
+    const b = hash2(xi + 1, zi, seed);
+    const c = hash2(xi, zi + 1, seed);
+    const d = hash2(xi + 1, zi + 1, seed);
+    return (a + (b - a) * tx) * (1 - tz) + (c + (d - c) * tx) * tz;
+}
+/**
+ * Drapes an authored `grass_field` volume's footprint with a feathered turf mat: vertices follow the
+ * runtime ground, the patch edge fades out over `edgeFeather`, and authored clearance masks punch
+ * the cover back out where a path or footing crosses it. This is the surface under the blades, so a
+ * park reads as grass instead of bare pavement with stubble on it.
+ * @internal
+ */
+export function createGrassCoverGeometry(options) {
+    const size = resolveTerrainSize(options.area);
+    const segments = Math.max(1, Math.min(GRASS_COVER_MAX_SEGMENTS, Math.floor(options.segments ?? Math.min(GRASS_COVER_MAX_SEGMENTS, Math.max(2, Math.round(Math.max(size.width, size.depth) / 2))))));
+    if (options.strength <= 0 || size.width <= 0 || size.depth <= 0) {
+        return { positions: new Float32Array(), normals: new Float32Array(), colors: new Float32Array(), uvs: new Float32Array(), indices: new Uint32Array(), size: [size.width, size.depth] };
+    }
+    const lift = options.lift ?? 0.035;
+    const halfW = size.width / 2;
+    const halfD = size.depth / 2;
+    const base = new THREE.Color(options.colorBase);
+    const tip = new THREE.Color(options.colorTip);
+    const root = base.clone().multiplyScalar(0.55);
+    const sheen = base.clone().multiplyScalar(0.98);
+    const cols = segments + 1;
+    const count = cols * cols;
+    const positions = new Float32Array(count * 3);
+    const normals = new Float32Array(count * 3);
+    const colors = new Float32Array(count * 4);
+    const uvs = new Float32Array(count * 2);
+    const eps = Math.max(0.25, Math.min(size.width, size.depth) / segments / 2);
+    for (let iz = 0; iz < cols; iz += 1) {
+        const z = -halfD + (iz / segments) * size.depth;
+        for (let ix = 0; ix < cols; ix += 1) {
+            const x = -halfW + (ix / segments) * size.width;
+            const index = iz * cols + ix;
+            positions[index * 3] = x;
+            positions[index * 3 + 1] = options.heightAt(x, z) + lift;
+            positions[index * 3 + 2] = z;
+            const hL = options.heightAt(x - eps, z);
+            const hR = options.heightAt(x + eps, z);
+            const hD = options.heightAt(x, z - eps);
+            const hU = options.heightAt(x, z + eps);
+            const nx = hL - hR;
+            const nz = hD - hU;
+            const ny = 2 * eps;
+            const length = Math.hypot(nx, ny, nz) || 1;
+            normals[index * 3] = nx / length;
+            normals[index * 3 + 1] = ny / length;
+            normals[index * 3 + 2] = nz / length;
+            const edge = Math.min(halfW - Math.abs(x), halfD - Math.abs(z));
+            const feather = Math.max(0.001, options.edgeFeather);
+            const edgeFade = smooth(Math.min(1, Math.max(0, edge / feather)));
+            const coverage = Math.max(0, Math.min(1, options.coverageAt(x, z)));
+            const grain = valueNoise(x / 1.7, z / 1.7, options.seed);
+            const patch = valueNoise(x / 11 + 31.7, z / 11 - 9.2, options.seed + 17);
+            const alpha = options.strength * edgeFade * coverage * (0.82 + 0.18 * grain);
+            // Macro patches lift the mat toward the blade tip hue and back to a rooted shade, so a park
+            // reads as turf with light and dry pockets instead of one flat green sheet.
+            const light = smooth(Math.min(1, Math.max(0, (patch - 0.25) / 0.6)));
+            const r = root.r + (sheen.r - root.r) * light;
+            const g = root.g + (sheen.g - root.g) * light;
+            const b = root.b + (sheen.b - root.b) * light;
+            const tipMix = grain * 0.3;
+            colors[index * 4] = r + (tip.r - r) * tipMix;
+            colors[index * 4 + 1] = g + (tip.g - g) * tipMix;
+            colors[index * 4 + 2] = b + (tip.b - b) * tipMix;
+            colors[index * 4 + 3] = alpha;
+            uvs[index * 2] = x / GRASS_COVER_TILE_METRES;
+            uvs[index * 2 + 1] = z / GRASS_COVER_TILE_METRES;
+        }
+    }
+    const indices = new Uint32Array(segments * segments * 6);
+    let cursor = 0;
+    for (let iz = 0; iz < segments; iz += 1) {
+        for (let ix = 0; ix < segments; ix += 1) {
+            const a = iz * cols + ix;
+            const b = a + 1;
+            const c = a + cols;
+            const d = c + 1;
+            indices[cursor++] = a;
+            indices[cursor++] = c;
+            indices[cursor++] = b;
+            indices[cursor++] = b;
+            indices[cursor++] = c;
+            indices[cursor++] = d;
+        }
+    }
+    return { positions, normals, colors, uvs, indices, size: [size.width, size.depth] };
+}