@jgengine/shell 0.10.0 → 0.12.0

package/dist/terrain/GrassField.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo } from "react";
-import { createGrassBladeGeometry } from "./grassGeometry.js";
-import { createGrassMaterial } from "./grassMaterial.js";
+import { createGrassBladeGeometry, grassTuftCount, GRASS_TUFT_BLADES, } from "./grassGeometry.js";
+import { createGrassMaterial, } from "./grassMaterial.js";
 import { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget, } from "./grassBudget.js";
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
-export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, ...meshProps }) {
+export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
+export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, tuftBlades = GRASS_TUFT_BLADES, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, ...meshProps }) {
     const geometry = useMemo(() => createGrassBladeGeometry({
         count,
         area,
@@ -14,16 +15,25 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         height: bladeHeight,
         width: bladeWidth,
         bend: bladeBend,
+        ...(tuftBlades === undefined ? {} : { tuftBlades }),
+        ...(tuftRadius === undefined ? {} : { tuftRadius }),
+        ...(edgeFeather === undefined ? {} : { edgeFeather }),
+        ...(exclude === undefined ? {} : { exclude }),
         heightAt,
-    }), [area, bladeBend, bladeHeight, bladeWidth, count, heightAt, seed, segments]);
+    }), [area, bladeBend, bladeHeight, bladeWidth, count, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
     const handle = useMemo(() => createGrassMaterial({
         colorBase,
         colorTip,
+        colorGround,
         colorVariation,
         wind,
+        distanceFade,
+        normalLift,
         roughness,
-    }), [colorBase, colorTip, colorVariation, roughness, wind]);
-    geometry.instanceCount = resolveGrassInstanceBudget(count, density, budget);
+    }), [colorBase, colorTip, colorGround, colorVariation, distanceFade, normalLift, roughness, wind]);
+    // Budgets stay in blades (the public unit); the instance buffer carries tufts.
+    const instanceCount = useMemo(() => grassTuftCount(resolveGrassInstanceBudget(count, density, area, budget), tuftBlades), [count, density, area, budget, tuftBlades]);
+    geometry.instanceCount = Math.min(instanceCount, grassTuftCount(count, tuftBlades));
     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

@@ -2,7 +2,19 @@ import * as THREE from "three";
 import { type TerrainSeed } from "./random.js";
 import { type TerrainArea, type TerrainHeightSampler } from "./terrainMath.js";
 export type GrassRange = number | readonly [min: number, max: number];
+/** Blades baked into each tuft instance — one instance reads as a clump, not a lone blade. */
+export declare const GRASS_TUFT_BLADES = 5;
+/** A rectangle (patch-local XZ) the grass bake keeps clear — soil patches, water, plazas. */
+export interface GrassExclusion {
+    /** Rect center in patch-local coordinates. */
+    center: readonly [x: number, z: number];
+    /** Rect half extents. */
+    half: readonly [x: number, z: number];
+    /** Ramp width (m) outside the rect over which blades regrow to full height. Default 1.5. */
+    feather?: number;
+}
 export interface GrassBladeGeometryOptions {
+    /** Total blade budget for the patch (instances are tufts of `tuftBlades` blades each). */
     count?: number;
     area?: TerrainArea;
     seed?: TerrainSeed;
@@ -10,6 +22,14 @@ export interface GrassBladeGeometryOptions {
     height?: GrassRange;
     width?: GrassRange;
     bend?: GrassRange;
+    /** Blades merged into each instanced tuft. Default {@link GRASS_TUFT_BLADES}. */
+    tuftBlades?: number;
+    /** Tuft spread radius in meters — how far clump blades splay from the tuft root. Default 0.16. */
+    tuftRadius?: number;
+    /** Meters of density/height feathering at the patch border so the field ends in a soft fringe, not a mowed rectangle. Default 1.5; 0 disables. */
+    edgeFeather?: number;
+    /** Patch-local rectangles kept clear of blades (soil patches, water) with a soft regrow ramp. */
+    exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
 }
 export interface ResolvedGrassBladeGeometryOptions {
@@ -20,8 +40,23 @@ export interface ResolvedGrassBladeGeometryOptions {
     height: readonly [min: number, max: number];
     width: readonly [min: number, max: number];
     bend: readonly [min: number, max: number];
+    tuftBlades: number;
+    tuftRadius: number;
+    edgeFeather: number;
+    exclude: readonly GrassExclusion[];
     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;
+/** Tuft instances needed to carry `bladeCount` blades at `tuftBlades` blades per tuft. @internal */
+export declare function grassTuftCount(bladeCount: number, tuftBlades?: number): number;
+/**
+ * Instanced tuft geometry: the template mesh is a clump of `tuftBlades` blades splayed around the
+ * tuft root (per-blade yaw/offset/scale baked as vertex attributes), and each instance places one
+ * whole clump. Clumps read as turf at a fraction of the instance count single blades need, and the
+ * per-instance yaw/scale jitter hides the shared clump layout.
+ * @internal
+ */
 export declare function createGrassBladeGeometry(options?: GrassBladeGeometryOptions): THREE.InstancedBufferGeometry;

package/dist/terrain/grassGeometry.js

@@ -1,11 +1,15 @@
 import * as THREE from "three";
 import { createSeededRandom } from "./random.js";
 import { resolveTerrainSize } from "./terrainMath.js";
+/** Blades baked into each tuft instance — one instance reads as a clump, not a lone blade. */
+export const GRASS_TUFT_BLADES = 5;
+/** @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)),
@@ -13,52 +17,113 @@ export function resolveGrassBladeGeometryOptions(options = {}) {
         seed: options.seed ?? 1,
         segments: Math.max(1, Math.floor(options.segments ?? 4)),
         height: resolveGrassRange(options.height, [0.55, 1.1]),
-        width: resolveGrassRange(options.width, [0.035, 0.075]),
-        bend: resolveGrassRange(options.bend, [0.08, 0.32]),
+        width: resolveGrassRange(options.width, [0.05, 0.1]),
+        bend: resolveGrassRange(options.bend, [0.12, 0.42]),
+        tuftBlades: Math.max(1, Math.floor(options.tuftBlades ?? GRASS_TUFT_BLADES)),
+        tuftRadius: Math.max(0, options.tuftRadius ?? 0.16),
+        edgeFeather: Math.max(0, options.edgeFeather ?? 1.5),
+        exclude: options.exclude ?? [],
         heightAt: options.heightAt ?? (() => 0),
     };
 }
+/** Tuft instances needed to carry `bladeCount` blades at `tuftBlades` blades per tuft. @internal */
+export function grassTuftCount(bladeCount, tuftBlades = GRASS_TUFT_BLADES) {
+    return Math.ceil(Math.max(0, bladeCount) / Math.max(1, tuftBlades));
+}
 function randomRange(random, range) {
     return THREE.MathUtils.lerp(range[0], range[1], random());
 }
+/**
+ * Instanced tuft geometry: the template mesh is a clump of `tuftBlades` blades splayed around the
+ * tuft root (per-blade yaw/offset/scale baked as vertex attributes), and each instance places one
+ * whole clump. Clumps read as turf at a fraction of the instance count single blades need, and the
+ * per-instance yaw/scale jitter hides the shared clump layout.
+ * @internal
+ */
 export function createGrassBladeGeometry(options = {}) {
     const resolved = resolveGrassBladeGeometryOptions(options);
     const size = resolveTerrainSize(resolved.area);
     const positions = [];
     const normals = [];
     const uvs = [];
+    const bladeOffsets = [];
+    const bladeVary = [];
+    const bladeBendScale = [];
     const indices = [];
-    for (let segment = 0; segment <= resolved.segments; segment += 1) {
-        const t = segment / resolved.segments;
-        positions.push(-0.5, t, 0, 0.5, t, 0);
-        normals.push(0, 0, 1, 0, 0, 1);
-        uvs.push(0, t, 1, t);
-        if (segment < resolved.segments) {
-            const base = segment * 2;
-            indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+    // Blade layout inside the tuft is baked once from the seed, shared by every instance.
+    const templateRandom = createSeededRandom(typeof resolved.seed === "number" ? resolved.seed + 7919 : `${resolved.seed}/tuft`);
+    const vertsPerBlade = (resolved.segments + 1) * 2;
+    for (let blade = 0; blade < resolved.tuftBlades; blade += 1) {
+        // First blade anchors the root; the rest ring outward with jittered angle/radius.
+        const angle = blade === 0 ? 0 : ((blade - 1) / Math.max(1, resolved.tuftBlades - 1)) * Math.PI * 2 + templateRandom() * 1.4;
+        const radius = blade === 0 ? 0 : resolved.tuftRadius * (0.35 + 0.65 * templateRandom());
+        const offsetX = Math.cos(angle) * radius;
+        const offsetZ = Math.sin(angle) * radius;
+        // Bend direction points away from the tuft center (plus jitter) so the clump splays open.
+        const yaw = angle + Math.PI / 2 + (templateRandom() - 0.5) * 1.6;
+        const heightScale = 0.72 + templateRandom() * 0.45;
+        const widthScale = 0.8 + templateRandom() * 0.4;
+        const phase = templateRandom();
+        const bendScale = 0.7 + templateRandom() * 0.7;
+        for (let segment = 0; segment <= resolved.segments; segment += 1) {
+            const t = segment / resolved.segments;
+            positions.push(-0.5, t, 0, 0.5, t, 0);
+            normals.push(0, 0, 1, 0, 0, 1);
+            uvs.push(0, t, 1, t);
+            for (let corner = 0; corner < 2; corner += 1) {
+                bladeOffsets.push(offsetX, offsetZ);
+                bladeVary.push(yaw, heightScale, widthScale, phase);
+                bladeBendScale.push(bendScale);
+            }
+            if (segment < resolved.segments) {
+                const base = blade * vertsPerBlade + segment * 2;
+                indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+            }
         }
     }
     const geometry = new THREE.InstancedBufferGeometry();
     geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
     geometry.setAttribute("normal", new THREE.Float32BufferAttribute(normals, 3));
     geometry.setAttribute("uv", new THREE.Float32BufferAttribute(uvs, 2));
+    geometry.setAttribute("bladeOffset", new THREE.Float32BufferAttribute(bladeOffsets, 2));
+    geometry.setAttribute("bladeVary", new THREE.Float32BufferAttribute(bladeVary, 4));
+    geometry.setAttribute("bladeBendScale", new THREE.Float32BufferAttribute(bladeBendScale, 1));
     geometry.setIndex(indices);
+    const tuftCount = grassTuftCount(resolved.count, resolved.tuftBlades);
     const random = createSeededRandom(resolved.seed);
-    const offsets = new Float32Array(resolved.count * 3);
-    const yaw = new Float32Array(resolved.count);
-    const heights = new Float32Array(resolved.count);
-    const widths = new Float32Array(resolved.count);
-    const bend = new Float32Array(resolved.count);
-    const phase = new Float32Array(resolved.count);
-    const colorMix = new Float32Array(resolved.count);
-    for (let index = 0; index < resolved.count; index += 1) {
+    const offsets = new Float32Array(tuftCount * 3);
+    const yaw = new Float32Array(tuftCount);
+    const heights = new Float32Array(tuftCount);
+    const widths = new Float32Array(tuftCount);
+    const bend = new Float32Array(tuftCount);
+    const phase = new Float32Array(tuftCount);
+    const colorMix = new Float32Array(tuftCount);
+    const halfW = size.width / 2;
+    const halfD = size.depth / 2;
+    for (let index = 0; index < tuftCount; index += 1) {
         const x = (random() - 0.5) * size.width;
         const z = (random() - 0.5) * size.depth;
         offsets[index * 3] = x;
         offsets[index * 3 + 1] = resolved.heightAt(x, z);
         offsets[index * 3 + 2] = z;
         yaw[index] = random() * Math.PI * 2;
-        heights[index] = randomRange(random, resolved.height);
+        let heightScale = randomRange(random, resolved.height);
+        // Two random draws happen on every path so the seeded stream stays aligned regardless of feather.
+        const gate = random();
+        const settle = random();
+        if (resolved.edgeFeather > 0) {
+            // Tufts drop out probabilistically across the feather band (mostly keeping full height),
+            // so the border reads as grass growing sparser — not a mowed short-pile strip.
+            const edge = Math.min(halfW - Math.abs(x), halfD - Math.abs(z));
+            const inside = Math.min(1, Math.max(0, edge / resolved.edgeFeather));
+            heightScale *= gate < inside * inside ? 0.7 + 0.3 * settle : 0;
+        }
+        for (const zone of resolved.exclude) {
+            // Signed distance outside the rect: blades vanish inside and regrow across the feather ramp.
+            const d = Math.max(Math.abs(x - zone.center[0]) - zone.half[0], Math.abs(z - zone.center[1]) - zone.half[1]);
+            heightScale *= Math.min(1, Math.max(0, d / Math.max(0.001, zone.feather ?? 1.5)));
+        }
+        heights[index] = heightScale;
         widths[index] = randomRange(random, resolved.width);
         bend[index] = randomRange(random, resolved.bend);
         phase[index] = random() * Math.PI * 2;
@@ -71,7 +136,7 @@ export function createGrassBladeGeometry(options = {}) {
     geometry.setAttribute("instanceBend", new THREE.InstancedBufferAttribute(bend, 1));
     geometry.setAttribute("instancePhase", new THREE.InstancedBufferAttribute(phase, 1));
     geometry.setAttribute("instanceColorMix", new THREE.InstancedBufferAttribute(colorMix, 1));
-    geometry.instanceCount = resolved.count;
+    geometry.instanceCount = tuftCount;
     geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), Math.max(size.width, size.depth) * 0.75 + resolved.height[1]);
     return geometry;
 }

package/dist/terrain/grassMaterial.d.ts

@@ -6,11 +6,22 @@ export interface GrassWindOptions {
     gustScale?: number;
     flutter?: number;
 }
+/** Camera-distance fade band: tufts thin out between `start` and `end` meters, so the instance budget spends where the camera lives. */
+export interface GrassDistanceFadeOptions {
+    start?: number;
+    end?: number;
+}
 export interface GrassMaterialOptions {
     colorBase?: THREE.ColorRepresentation;
     colorTip?: THREE.ColorRepresentation;
+    /** Ground color the blade roots blend into (pass the terrain color under the patch so blades grow *out of* the ground instead of floating on it). Defaults to a darkened `colorBase`. */
+    colorGround?: THREE.ColorRepresentation;
     colorVariation?: number;
     wind?: GrassWindOptions | false;
+    /** Distance thinning; `false` disables. Default fades between 35 m and 95 m. */
+    distanceFade?: GrassDistanceFadeOptions | false;
+    /** 0..1 blend of blade normals toward straight-up — lit like a soft carpet instead of dark individual planes. Default 0.6. */
+    normalLift?: number;
     roughness?: number;
 }
 export interface GrassShaderUniforms {
@@ -22,12 +33,21 @@ export interface GrassShaderUniforms {
     uWindFlutter: THREE.IUniform<number>;
     uColorBase: THREE.IUniform<THREE.Color>;
     uColorTip: THREE.IUniform<THREE.Color>;
+    uColorGround: THREE.IUniform<THREE.Color>;
     uColorVariation: THREE.IUniform<number>;
+    uDistanceFade: THREE.IUniform<THREE.Vector2>;
+    uNormalLift: THREE.IUniform<number>;
 }
 export interface GrassMaterialHandle {
     material: THREE.MeshStandardMaterial;
     uniforms: GrassShaderUniforms;
 }
 export declare const DEFAULT_GRASS_WIND: Required<GrassWindOptions>;
+/** Default camera-distance fade band: tufts start thinning at 35 m and are gone by 95 m. */
+export declare const DEFAULT_GRASS_DISTANCE_FADE: Required<GrassDistanceFadeOptions>;
+/** @internal */
 export declare function resolveGrassWind(wind: GrassWindOptions | false | undefined): Required<GrassWindOptions>;
+/** @internal */
+export declare function resolveGrassDistanceFade(fade: GrassDistanceFadeOptions | false | undefined): Required<GrassDistanceFadeOptions>;
+/** @internal */
 export declare function createGrassMaterial(options?: GrassMaterialOptions): GrassMaterialHandle;

package/dist/terrain/grassMaterial.js

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

package/dist/terrain/heightfieldGeometry.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from "three";
+/** XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`. */
+export interface HeightfieldRect {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`. */
+export type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void;
+/** Options for {@link displaceHeightfieldGeometry}. */
+export interface HeightfieldDisplaceOptions {
+    /** World-space rect the plane spans (the plane is centered on it, XZ, +Y up). */
+    bounds: HeightfieldRect;
+    /**
+     * Dirty world-space region to re-sample; only the vertex window covering it (plus a one-vertex
+     * normal ring) updates. Omit or pass null for a full rebuild.
+     */
+    region?: HeightfieldRect | null;
+    /** When given, writes a `color` attribute (creating it on demand) via this per-vertex hook. */
+    color?: HeightfieldColorFn;
+}
+/**
+ * Re-samples a `PlaneGeometry(width, depth, segments, segments).rotateX(-π/2)` heightfield mesh
+ * from a `sampleHeight` field in place: vertex Y, optional vertex color, grid central-difference
+ * normals, and an analytically maintained bounding sphere. With a dirty `region`, the work is
+ * O(region vertices) — heights/colors update inside the covering vertex window, normals inside the
+ * window plus a one-vertex ring — never a whole-mesh `computeVertexNormals`/`computeBoundingSphere`
+ * pass, which is what keeps per-frame brush stamps inside the editor's frame budget. The bounding
+ * sphere derives from the fixed plane extents plus a running height range kept on
+ * `geometry.userData`; partial passes only expand it, a full pass resets it exactly.
+ * @capability heightfield-mesh-update in-place partial update of a displaced ground plane mesh
+ */
+export declare function displaceHeightfieldGeometry(geometry: THREE.BufferGeometry, sampleHeight: (x: number, z: number) => number, options: HeightfieldDisplaceOptions): void;