@jgengine/shell 0.11.0 → 0.13.0

package/dist/settings/appliedSettings.d.ts

@@ -1,5 +1,5 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
-import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
 import { type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
@@ -11,6 +11,7 @@ export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault
     shadows: boolean;
     dpr: number;
     uiScale: number;
+    quality: GraphicsQuality;
 };
 export declare function AudioSettingsBridge({ store, engine, buses, }: {
     store: SettingsStore;

package/dist/settings/appliedSettings.js

@@ -16,12 +16,14 @@ export function useSettingsRevision(store) {
 }
 export function useGraphicsSettings(store, shadowsDefault) {
     useSettingsRevision(store);
-    const quality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    const rawQuality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    const quality = GRAPHICS_QUALITY_DPR[rawQuality] !== undefined ? rawQuality : "high";
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: GRAPHICS_QUALITY_DPR[quality] ?? GRAPHICS_QUALITY_DPR.high,
+        dpr: GRAPHICS_QUALITY_DPR[quality],
         uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
+        quality,
     };
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {

package/dist/structures/GeneratedBuilding.d.ts

@@ -43,6 +43,10 @@ export interface GeneratedBuildingProps {
 export interface InstancedBuildingPlacement {
     building: GeneratedBuildingData;
     position?: readonly [number, number, number];
+    /** Building yaw (radians) applied to the whole massing about `pivot` — street-aware facing. */
+    rotationY?: number;
+    /** World XZ the `rotationY` turns about (the building center); defaults to the world origin. */
+    pivot?: readonly [number, number];
 }
 export interface InstancedBuildingsProps {
     buildings: readonly InstancedBuildingPlacement[];

package/dist/structures/GeneratedBuilding.js

@@ -70,25 +70,35 @@ function bucketPartMatrices(buildings, visible) {
     const buckets = new Map();
     for (const placement of buildings) {
         const [ox, oy, oz] = placement.position ?? [0, 0, 0];
+        // Building yaw turns the whole massing about its center. Engine Y-rotation convention (matches
+        // dummy.rotation.y below): a local vector (x, z) maps to (x·cos + z·sin, −x·sin + z·cos).
+        const yaw = placement.rotationY ?? 0;
+        const [px0, pz0] = placement.pivot ?? [0, 0];
+        const cos = Math.cos(yaw);
+        const sin = Math.sin(yaw);
         for (const part of placement.building.parts) {
             if (visible !== null && !visible.has(part.kind))
                 continue;
             const [nx, nz] = normalFor(part.facade);
             const offset = outwardOffset(part);
-            const px = ox + part.position[0] + nx * offset;
+            // Local offset from the pivot (part position + facade-normal nudge), then rotated by the yaw.
+            const lx = part.position[0] - px0 + nx * offset;
+            const lz = part.position[2] - pz0 + nz * offset;
+            const px = ox + px0 + lx * cos + lz * sin;
             const py = oy + part.position[1];
-            const pz = oz + part.position[2] + nz * offset;
+            const pz = oz + pz0 - lx * sin + lz * cos;
+            const partYaw = part.rotationY + yaw;
             let bucket = buckets.get(part.kind);
             if (bucket === undefined) {
                 bucket = [];
                 buckets.set(part.kind, bucket);
             }
             if (part.kind === "clothesline") {
-                const sin = Math.sin(part.rotationY);
-                const cos = Math.cos(part.rotationY);
+                const rowSin = Math.sin(partYaw);
+                const rowCos = Math.cos(partYaw);
                 for (const row of CLOTHESLINE_ROW_OFFSETS) {
-                    dummy.position.set(px + row * sin, py, pz + row * cos);
-                    dummy.rotation.set(0, part.rotationY, 0);
+                    dummy.position.set(px + row * rowSin, py, pz + row * rowCos);
+                    dummy.rotation.set(0, partYaw, 0);
                     dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
                     dummy.updateMatrix();
                     bucket.push(dummy.matrix.clone());
@@ -96,7 +106,7 @@ function bucketPartMatrices(buildings, visible) {
                 continue;
             }
             dummy.position.set(px, py, pz);
-            dummy.rotation.set(0, part.rotationY, 0);
+            dummy.rotation.set(0, partYaw, 0);
             dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
             dummy.updateMatrix();
             bucket.push(dummy.matrix.clone());

package/dist/structures/TransformGizmo.d.ts

@@ -2,6 +2,10 @@
 export type TransformGizmoMode = "translate" | "rotate" | "scale";
 /** Snap policy: grid quantize, free drag, or ground-height sample on release. */
 export type TransformGizmoSnap = "grid" | "free" | "ground";
+/** Gizmo handle orientation: world axes, or the target's local (yaw-rotated) axes. */
+export type TransformGizmoSpace = "world" | "local";
+/** Default rotation snap increment (radians) when callers don't configure one. */
+export declare const DEFAULT_ROTATION_SNAP: number;
 /** Pose reported by {@link TransformGizmo} when the user releases a drag. */
 export interface TransformGizmoPose {
     position: {
@@ -27,6 +31,12 @@ export interface TransformGizmoProps {
     mode?: TransformGizmoMode;
     snapMode?: TransformGizmoSnap;
     gridSize?: number;
+    /** Handle orientation; `"local"` aligns handles to the target's yaw. */
+    space?: TransformGizmoSpace;
+    /** Rotation snap increment in radians; `null` rotates freely. */
+    rotationSnap?: number | null;
+    /** Scale snap increment; `null` (default) scales freely. */
+    scaleSnap?: number | null;
     /** Vertical offset so the gizmo sits above ground markers. */
     lift?: number;
     size?: number;
@@ -40,4 +50,4 @@ export interface TransformGizmoProps {
  * 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>;
+export declare const TransformGizmo: import("react").MemoExoticComponent<({ position, rotationY, mode, snapMode, gridSize, space, rotationSnap, scaleSnap, lift, size, groundSnap, onDraggingChange, onRelease, }: TransformGizmoProps) => import("react").JSX.Element>;

package/dist/structures/TransformGizmo.js

@@ -2,12 +2,14 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { TransformControls } from "@react-three/drei";
 import { useThree } from "@react-three/fiber";
 import { memo, useEffect, useRef, useState } from "react";
+/** Default rotation snap increment (radians) when callers don't configure one. */
+export const DEFAULT_ROTATION_SNAP = Math.PI / 12;
 /**
  * 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, }) {
+export const TransformGizmo = memo(function TransformGizmo({ position, rotationY = 0, mode = "translate", snapMode = "free", gridSize = 1, space = "world", rotationSnap = DEFAULT_ROTATION_SNAP, scaleSnap = null, lift = 0, size = 0.85, groundSnap, onDraggingChange, onRelease, }) {
     const groupRef = useRef(null);
     const [object, setObject] = useState(null);
     const draggingRef = useRef(false);
@@ -24,9 +26,11 @@ export const TransformGizmo = memo(function TransformGizmo({ position, rotationY
         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 snapProps = {
+        translationSnap: snapMode === "grid" ? gridSize : null,
+        rotationSnap,
+        scaleSnap,
+    };
     const handleRelease = () => {
         draggingRef.current = false;
         if (controls !== null && "enabled" in controls)
@@ -46,7 +50,7 @@ export const TransformGizmo = memo(function TransformGizmo({ position, rotationY
             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: () => {
+    return (_jsxs(_Fragment, { children: [_jsx("group", { ref: groupRef }), object !== null ? (_jsx(TransformControls, { object: object, mode: mode, size: size, space: space, ...snapProps, onMouseDown: () => {
                     draggingRef.current = true;
                     if (controls !== null && "enabled" in controls)
                         controls.enabled = false;

package/dist/terrain/GrassField.d.ts

@@ -1,8 +1,9 @@
 import { type ThreeElements } from "@react-three/fiber";
-import { type GrassBladeGeometryOptions, type GrassRange } from "./grassGeometry.js";
-import { type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
+import { type GrassBladeGeometryOptions, type GrassExclusion, type GrassRange } from "./grassGeometry.js";
+import { type GrassDistanceFadeOptions, type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
 import type { TerrainArea, TerrainHeightSampler } from "./terrainMath.js";
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
+export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
 export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
     count?: number;
     density?: number;
@@ -13,11 +14,18 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     bladeHeight?: GrassRange;
     bladeWidth?: GrassRange;
     bladeBend?: GrassRange;
+    tuftBlades?: number;
+    tuftRadius?: number;
+    edgeFeather?: number;
+    exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
     colorBase?: GrassMaterialOptions["colorBase"];
     colorTip?: GrassMaterialOptions["colorTip"];
+    colorGround?: GrassMaterialOptions["colorGround"];
     colorVariation?: number;
     wind?: GrassWindOptions | false;
+    distanceFade?: GrassDistanceFadeOptions | false;
+    normalLift?: number;
     roughness?: number;
 }
-export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

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, area, 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/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,11 +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;
-/** @internal */
+/** 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,6 +1,8 @@
 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)
@@ -15,53 +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());
 }
-/** @internal */
+/**
+ * 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;
@@ -74,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,14 +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;