@jgengine/shell 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -26,6 +26,24 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.22.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.22.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.19.0`; `@jgengine/github` is `0.9.0`.
+
+### Added
+
+- Editor-authored grass exposes blade width and bend ranges, tuft radius and normal lift, using the same bounded grass renderer as environment fields. Existing scene documents keep their previous shape and lighting defaults.
+- The full `jgengine skills` install includes `game-improvement`, with an ordered implementation workflow and checks for meaningful decisions, authored terrain and grass, and proven play quality.
+
+### Fixed
+
+- Grass volumes sample terrain at their authored world position and subtract their placement height once, keeping translated patches rooted on slopes instead of buried underground.
+
+- Authored grass respects spawn, objective and road/path clearances with feathered regrowth outside the usable footing. Diagonal paths keep their own corridor clear without clearing the entire surrounding rectangle.
+- Runtime environment ground now renders editor-authored terrain paint surfaces, layer tints, opacity and weighted blends through the same sampler as the editor. Legacy unpainted terrain keeps descriptor shading. Layer texture tiling, roughness and triplanar controls remain serialized authoring metadata; this fix does not add layered PBR texture rendering.
+
 ## 0.21.0
 
 ### Migrate

package/dist/defineGame.js

@@ -42,7 +42,7 @@ function isEnvironmentSource(value) {
 function authoredSceneOverlay(document, diagnostics, placement, scatterModels, flockModels, pathKinds, assets, world, Vfx) {
     const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
     return function AuthoredSceneOverlay(props) {
-        const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground), [props.ctx.world.ground]);
+        const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground, document.terrain), [props.ctx.world.ground]);
         return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, diagnostics: diagnostics, field: props.ctx.world.ground, placeObjects: placement, assets: assets, ...(scatterModels === undefined ? {} : { scatterModels }), ...(flockModels === undefined ? {} : { flockModels }), ...(pathKinds === undefined ? {} : { pathKinds }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
     };
 }

package/dist/environment/EnvironmentScene.js

@@ -10,6 +10,8 @@ import { resolveStructureBuildings } from "@jgengine/core/world/environmentSumma
 import { findRoadJunctions } from "@jgengine/core/world/streets";
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { useDisposable } from "../render/useDisposable.js";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { createTerrainPaintColorSampler } from "../terrain/terrainPaintColor.js";
 import { GroundPad } from "./GroundPad.js";
 import { RoadJunctions } from "./RoadJunctions.js";
 import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
@@ -38,9 +40,10 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, paintColorAt: layout.paintColorAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
-function TerrainGround({ terrain, field, center, }) {
+function TerrainGround({ terrain, field, center, sculpt, }) {
+    const paintColorAt = useMemo(() => sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt)), [sculpt]);
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
         const hasRegions = terrain.materialRegions !== undefined && terrain.materialRegions.length > 0;
@@ -69,9 +72,9 @@ function TerrainGround({ terrain, field, center, }) {
         : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }) }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paintColorAt, center } }) }));
     }
-    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
+    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
 function areaCenter(area) {
     return area.position ?? [0, 0];
@@ -88,8 +91,8 @@ function Vegetation({ grass, field, groundColor, }) {
     return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
-function vegetationGroundColor(terrain, field, grass) {
-    const sampler = terrainGroundColorSampler(terrain, field);
+function vegetationGroundColor(terrain, field, grass, sculpt) {
+    const sampler = terrainGroundColorSampler(terrain, field, sculpt);
     if (sampler === undefined)
         return undefined;
     const [cx, cz] = areaCenter(grass.area);
@@ -160,5 +163,5 @@ export function EnvironmentScene({ feature }) {
     const roads = feature.roads ?? [];
     const junctions = useMemo(() => findRoadJunctions(roads), [roads]);
     const roadNetwork = useMemo(() => buildAuthoredRoadNetwork(roads, junctions, (x, z) => field.sampleHeight(x, z)), [roads, junctions, field]);
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field, sculpt: feature.sculpt }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin, sculpt: feature.sculpt }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass, feature.sculpt) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -1,9 +1,10 @@
 import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
 import { type TerrainField } from "@jgengine/core/world/terrain";
+import { type TerraformSnapshot } from "@jgengine/core/world/terraform";
 /**
- * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
- * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
- * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField, sculpt?: TerraformSnapshot): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -1,21 +1,32 @@
 import * as THREE from "three";
-import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { createTerrainPaletteSampler, resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { createTerrainPaintColorSampler } from "../terrain/terrainPaintColor.js";
 /**
- * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
- * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
- * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export function terrainGroundColorSampler(terrain, field) {
-    if (terrain === undefined)
+export function terrainGroundColorSampler(terrain, field, sculpt) {
+    if (terrain === undefined && sculpt === undefined)
         return undefined;
     const palette = resolveTerrainPalette(terrain);
+    const paletteAt = terrain === undefined ? undefined : createTerrainPaletteSampler(terrain);
+    const paintColorAt = sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt));
     const low = new THREE.Color(palette.low);
     const high = new THREE.Color(palette.high);
-    const base = terrain.baseHeight ?? 0;
-    const swing = terrain.height * 1.2;
+    const base = terrain?.baseHeight ?? 0;
+    const swing = (terrain?.height ?? 0) * 1.2;
     const scratch = new THREE.Color();
     return (x, z) => {
+        if (paintColorAt?.(x, z, scratch))
+            return `#${scratch.getHexString()}`;
+        const regional = paletteAt?.(x, z);
+        if (regional !== undefined) {
+            low.set(regional.low);
+            high.set(regional.high);
+        }
         const t = swing <= 0 ? 0.5 : THREE.MathUtils.clamp((field.sampleHeight(x, z) - (base - swing)) / (swing * 2), 0, 1);
         return `#${scratch.copy(low).lerp(high, t).getHexString()}`;
     };

package/dist/scene/GrassFieldRenderer.js

@@ -1,6 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx } 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 { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 /** Volume kinds turf yields to — blades never grow through cracked soil or out of open water. */
@@ -47,9 +49,25 @@ function sampleHeight(field, x, z) {
  */
 function OneGrass({ object, context }) {
     const resolved = useMemo(() => resolveGrassObject(object), [object]);
-    const heightAt = useCallback((x, z) => sampleHeight(context.field, x, z), [context.field]);
+    const heightAt = useCallback((x, z) => resolved === null ? 0 :
+        sampleHeight(context.field, x + resolved.center[0], z + resolved.center[2]) - resolved.center[1], [context.field, resolved]);
     const area = useMemo(() => (resolved === null ? null : [resolved.size[0], resolved.size[1]]), [resolved]);
     const bladeHeight = useMemo(() => (resolved === null ? null : [resolved.rules.bladeHeight * 0.7, resolved.rules.bladeHeight]), [resolved]);
+    const bladeWidth = useMemo(() => resolved === null ? undefined : [resolved.rules.bladeWidthMin, resolved.rules.bladeWidthMax], [resolved]);
+    const bladeBend = useMemo(() => resolved === null ? undefined : [resolved.rules.bladeBendMin, resolved.rules.bladeBendMax], [resolved]);
+    const { markers, paths } = context.document;
+    const masks = useMemo(() => {
+        const authored = clearanceMasksFrom(context.document, {
+            kinds: [...DEFAULT_CLEARANCE_KINDS, "road", "walkway", "route", "path"],
+        });
+        // Keep the entire authored footing clear; feather regrowth outside its edge.
+        return {
+            discs: authored.discs.map(zone => ({ ...zone, radius: zone.radius + (zone.feather ?? 0) })),
+            corridors: authored.corridors.map(zone => ({ ...zone, halfWidth: zone.halfWidth + (zone.feather ?? 0) })),
+        };
+    }, [markers, paths, context.document.volumes]);
+    const coverageAt = useCallback((x, z) => resolved === null ? 0 :
+        1 - masksInfluence(x + resolved.center[0], z + resolved.center[2], masks), [resolved, masks]);
     const wind = useMemo(() => resolved === null
         ? null
         : { strength: resolved.rules.windStrength, speed: resolved.rules.windSpeed, gustScale: resolved.rules.windGust }, [resolved]);
@@ -68,7 +86,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, 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, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+    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 }));
 }
 /** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
 export function registerGrassFieldRenderer() {

package/dist/terrain/CarvedTerrain.d.ts

@@ -11,6 +11,7 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     colors?: FieldGroundOptions["colors"];
     heightRange?: FieldGroundOptions["heightRange"];
     paletteAt?: FieldGroundOptions["paletteAt"];
+    paintColorAt?: FieldGroundOptions["paintColorAt"];
     roughness?: number;
     metalness?: number;
     /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
@@ -23,4 +24,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

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

package/dist/terrain/GrassField.d.ts

@@ -19,6 +19,7 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     edgeFeather?: number;
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    coverageAt?: TerrainHeightSampler;
     colorBase?: GrassMaterialOptions["colorBase"];
     colorTip?: GrassMaterialOptions["colorTip"];
     colorGround?: GrassMaterialOptions["colorGround"];
@@ -29,4 +30,4 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     roughness?: number;
 }
 /** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
-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, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, coverageAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

package/dist/terrain/GrassField.js

@@ -9,7 +9,7 @@ import { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget,
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
 export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
 /** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
-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, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }) {
+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, coverageAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }) {
     const chunks = useMemo(() => createGrassGeometryChunks({
         count,
         area,
@@ -23,7 +23,8 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         ...(edgeFeather === undefined ? {} : { edgeFeather }),
         ...(exclude === undefined ? {} : { exclude }),
         heightAt,
-    }), [area, bladeBend, bladeHeight, bladeWidth, count, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
+        coverageAt,
+    }), [area, bladeBend, bladeHeight, bladeWidth, count, coverageAt, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
     useDisposable(() => chunks.map((chunk) => chunk.geometry), [chunks]);
     const handle = useMemo(() => createGrassMaterial({
         colorBase,

package/dist/terrain/grassGeometry.d.ts

@@ -31,6 +31,8 @@ export interface GrassBladeGeometryOptions {
     /** Patch-local rectangles kept clear of blades (soil patches, water) with a soft regrow ramp. */
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    /** Patch-local coverage, 0..1, composed with explicit rectangular exclusions. */
+    coverageAt?: TerrainHeightSampler;
 }
 export interface ResolvedGrassBladeGeometryOptions {
     count: number;
@@ -45,6 +47,7 @@ export interface ResolvedGrassBladeGeometryOptions {
     edgeFeather: number;
     exclude: readonly GrassExclusion[];
     heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
 }
 /** @internal */
 export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];

package/dist/terrain/grassGeometry.js

@@ -24,6 +24,7 @@ export function resolveGrassBladeGeometryOptions(options = {}) {
         edgeFeather: Math.max(0, options.edgeFeather ?? 1.5),
         exclude: options.exclude ?? [],
         heightAt: options.heightAt ?? (() => 0),
+        coverageAt: options.coverageAt ?? (() => 1),
     };
 }
 /** Tuft instances needed to carry `bladeCount` blades at `tuftBlades` blades per tuft. @internal */
@@ -123,7 +124,7 @@ export function createGrassBladeGeometry(options = {}) {
             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;
+        heights[index] = heightScale * Math.max(0, Math.min(1, resolved.coverageAt(x, z)));
         widths[index] = randomRange(random, resolved.width);
         bend[index] = randomRange(random, resolved.bend);
         phase[index] = random() * Math.PI * 2;

package/dist/terrain/index.d.ts

@@ -9,3 +9,4 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMa
 export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainSurfaceColorOptions, type TerrainVertexColorOptions, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";
+export { createTerrainPaintColorSampler, type TerrainPaintColorSampler, type TerrainPaintSource } from "./terrainPaintColor.js";

package/dist/terrain/index.js

@@ -9,3 +9,4 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./gr
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";
+export { createTerrainPaintColorSampler } from "./terrainPaintColor.js";

package/dist/terrain/terrainMath.d.ts

@@ -82,6 +82,8 @@ export interface FieldGroundOptions {
     paletteAt?: TerrainPaletteSampler;
     /** Slope/noise surface shading over the height lerp. Omit for the default terrain look; pass `{ slopeStrength: 0, mottleStrength: 0 }` for a flat gradient. */
     surface?: TerrainSurfaceColorOptions;
+    /** Authored paint overrides descriptor shading at painted vertices. */
+    paintColorAt?: (x: number, z: number, out: THREE.Color) => boolean;
 }
 /**
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a

package/dist/terrain/terrainMath.js

@@ -106,6 +106,7 @@ export function createFieldGroundGeometry(field, options = {}) {
         heightRange: options.heightRange,
         paletteAt: options.paletteAt,
         surface: options.surface,
+        paintColorAt: options.paintColorAt,
     });
 }
 function buildGroundGeometry(size, segments, sampler, opts) {
@@ -162,6 +163,7 @@ function buildGroundGeometry(size, segments, sampler, opts) {
                 slope01 = grad / (grad + 1);
             }
             applyTerrainSurfaceShading(color, x, z, slope01, surface);
+            opts.paintColorAt?.(x, z, color);
             colorValues[colorIndex] = color.r;
             colorValues[colorIndex + 1] = color.g;
             colorValues[colorIndex + 2] = color.b;

package/dist/terrain/terrainPaintColor.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+import type { EditableTerrain } from "@jgengine/core/world/terraform";
+/** Live authored paint channels needed to sample a terrain's material stack without its heightfield. */
+export type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt">;
+/** Writes authored paint into an existing linear color; returns false for unpainted ground. */
+export type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean;
+/**
+ * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
+ */
+export declare function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler;

package/dist/terrain/terrainPaintColor.js

@@ -0,0 +1,47 @@
+import * as THREE from "three";
+import { TERRAIN_MATERIAL_COLORS } from "@jgengine/core/editor/terrainMaterials";
+/**
+ * Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+ * @capability terrain-paint-color sample authored terrain surfaces and blended layers for shared ground rendering
+ */
+export function createTerrainPaintColorSampler(terrain) {
+    const layers = terrain.layers;
+    const colors = layers.map(layer => new THREE.Color(layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86"));
+    const defaults = new Map(Object.entries(TERRAIN_MATERIAL_COLORS).map(([id, color]) => [id, new THREE.Color(color)]));
+    return (x, z, out) => {
+        const weights = terrain.weightsAt(x, z);
+        if (layers.length > 0 && weights.length === layers.length) {
+            let total = 0, r = 0, g = 0, b = 0;
+            for (let i = 0; i < layers.length; i++) {
+                const weight = weights[i] * (layers[i].opacity ?? 1);
+                if (weight <= 0)
+                    continue;
+                const color = colors[i];
+                r += color.r * weight;
+                g += color.g * weight;
+                b += color.b * weight;
+                total += weight;
+            }
+            if (total > 0) {
+                out.setRGB(r / total, g / total, b / total);
+                return true;
+            }
+            return false;
+        }
+        const surface = terrain.surfaceAt(x, z);
+        if (surface === null)
+            return false;
+        const index = layers.findIndex(layer => layer.surface === surface);
+        if (index >= 0) {
+            if ((layers[index].opacity ?? 1) <= 0)
+                return false;
+            out.copy(colors[index]);
+            return true;
+        }
+        const color = defaults.get(surface);
+        if (color === undefined)
+            return false;
+        out.copy(color);
+        return true;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.21.0",
-    "@jgengine/react": "^0.21.0",
-    "@jgengine/ws": "^0.21.0"
+    "@jgengine/core": "^0.22.0",
+    "@jgengine/react": "^0.22.0",
+    "@jgengine/ws": "^0.22.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/game-design/SKILL.md

@@ -11,6 +11,8 @@ Own the intended player experience and the rules that produce it: fantasy, pilla
 
 Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
 
+For a substantial existing-game quality pass spanning concept, depth, world and presentation, use `game-improvement` to sequence these owners and keep a per-game implementation plan and acceptance evidence.
+
 For a greenfield build, read [references/application-playbook.md](references/application-playbook.md) and produce its greenfield contract (promise, pillars, anti-pillars, core decision, and falsifier) before writing code. Audits may read only the playbook's audit sections. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
 
 ## Choose the mode

package/skills/jgengine/SKILL.md

@@ -53,6 +53,7 @@ Load only rows the target needs. Do not preload every domain.
 | Need | Skill | Owner |
 | --- | --- | --- |
 | player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| substantial existing-game improvement across depth, world and presentation | `game-improvement` | ordered improvement plan and per-game completion |
 | metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
 | scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
 | runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.21.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.22.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -232,7 +232,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.21.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.22.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/api.md

@@ -2702,7 +2702,7 @@
 
 ## @jgengine/shell/terrain
 
-- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
 - `CarvedTerrainProps` (interface): interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { field: TerrainField; size?: FieldGroundOptions["size"]; segments?: FieldGroundOptions["segments"]; center?: FieldGroundOptions["center"]; colors?: FieldGroundOptions["colors"]; heightRange?: FieldGroundOptions["heightRange"]; paletteAt?: … — ⚠ undocumented · used by `CarvedTerrain`: Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
 - `DEFAULT_GRASS_WIND` (const): const DEFAULT_GRASS_WIND: Required<GrassWindOptions> — ⚠ undocumented
 - `EditableGround` (function): function EditableGround({ terrain, bounds, segments = 96, version = 0, baseColor = "#3f6b3a", surfaceColors = DEFAULT_SURFACE_COLORS, }: EditableGroundProps): React.JSX.Element — ⚠ undocumented
@@ -2710,7 +2710,7 @@
 - `FieldGroundOptions` (interface): interface FieldGroundOptions { size?: TerrainArea; segments?: number | readonly [x: number, z: number]; center?: readonly [x: number, z: number]; colors?: TerrainVertexColorOptions; heightRange?: readonly [min: number, max: number]; paletteAt?: TerrainPaletteSampler; s… — ⚠ undocumented
 - `FractalNoiseConfig` (interface): interface FractalNoiseConfig — Octave settings for {@link fractalNoise}: frequency, layering, and optional ridged shaping.
 - `GrassBladeGeometryOptions` (interface): interface GrassBladeGeometryOptions { count?: number; area?: TerrainArea; seed?: TerrainSeed; segments?: number; height?: GrassRange; width?: GrassRange; bend?: GrassRange; tuftBlades?: number; tuftRadius?: number; edgeFeather?: number; exclude?: readonly GrassExclusion[]; he… — ⚠ undocumented
-- `GrassField` (function): 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, dista… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
+- `GrassField` (function): 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, coverageAt, colorBase, colorTip, colorGround, colorVariation,… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
 - `GrassFieldProps` (interface): interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { count?: number; density?: number; budget?: number; area?: TerrainArea; seed?: GrassBladeGeometryOptions["seed"]; segments?: number; bladeHeight?: GrassRange; bladeWidth?: GrassRange; bladeBend?: GrassRange; tuftBlades?: number; tuftRadius… — ⚠ undocumented
 - `GrassMaterialHandle` (interface): interface GrassMaterialHandle { material: THREE.MeshStandardMaterial; uniforms: GrassShaderUniforms } — ⚠ undocumented
 - `GrassMaterialOptions` (interface): interface GrassMaterialOptions { colorBase?: THREE.ColorRepresentation; colorTip?: THREE.ColorRepresentation; colorGround?: THREE.ColorRepresentation; colorVariation?: number; wind?: GrassWindOptions | false; distanceFade?: GrassDistanceFadeOptions | false; normalLift?: … — ⚠ undocumented
@@ -2733,14 +2733,17 @@
 - `TerrainField` (interface): interface TerrainField — A sampleable ground surface: height and normal at any x/z, with optional bounds and water level.
 - `TerrainHeightSampler` (type): type TerrainHeightSampler = (x: number, z: number) => number — ⚠ undocumented
 - `TerrainNormal` (type): type TerrainNormal = readonly [number, number, number] — A surface normal vector at a terrain sample point.
+- `TerrainPaintColorSampler` (type): type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean — Writes authored paint into an existing linear color; returns false for unpainted ground.
+- `TerrainPaintSource` (type): type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt"> — Live authored paint channels needed to sample a terrain's material stack without its heightfield.
 - `TerrainSeed` (type): type TerrainSeed = number | string — ⚠ undocumented
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
 - `displaceHeightfieldGeometry` (function): function displaceHeightfieldGeometry(geometry: THREE.BufferGeometry, sampleHeight: (x: number, z: number) => number, options: HeightfieldDisplaceOptions): void — 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.
 
 ## @jgengine/shell/terrain
 
-- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
 - `CarvedTerrainProps` (interface): interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { field: TerrainField; size?: FieldGroundOptions["size"]; segments?: FieldGroundOptions["segments"]; center?: FieldGroundOptions["center"]; colors?: FieldGroundOptions["colors"]; heightRange?: FieldGroundOptions["heightRange"]; paletteAt?: … — ⚠ undocumented · used by `CarvedTerrain`: Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
 - `DEFAULT_GRASS_WIND` (const): const DEFAULT_GRASS_WIND: Required<GrassWindOptions> — ⚠ undocumented
 - `EditableGround` (function): function EditableGround({ terrain, bounds, segments = 96, version = 0, baseColor = "#3f6b3a", surfaceColors = DEFAULT_SURFACE_COLORS, }: EditableGroundProps): React.JSX.Element — ⚠ undocumented
@@ -2748,7 +2751,7 @@
 - `FieldGroundOptions` (interface): interface FieldGroundOptions { size?: TerrainArea; segments?: number | readonly [x: number, z: number]; center?: readonly [x: number, z: number]; colors?: TerrainVertexColorOptions; heightRange?: readonly [min: number, max: number]; paletteAt?: TerrainPaletteSampler; s… — ⚠ undocumented
 - `FractalNoiseConfig` (interface): interface FractalNoiseConfig — Octave settings for {@link fractalNoise}: frequency, layering, and optional ridged shaping.
 - `GrassBladeGeometryOptions` (interface): interface GrassBladeGeometryOptions { count?: number; area?: TerrainArea; seed?: TerrainSeed; segments?: number; height?: GrassRange; width?: GrassRange; bend?: GrassRange; tuftBlades?: number; tuftRadius?: number; edgeFeather?: number; exclude?: readonly GrassExclusion[]; he… — ⚠ undocumented
-- `GrassField` (function): 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, dista… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
+- `GrassField` (function): 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, coverageAt, colorBase, colorTip, colorGround, colorVariation,… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
 - `GrassFieldProps` (interface): interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { count?: number; density?: number; budget?: number; area?: TerrainArea; seed?: GrassBladeGeometryOptions["seed"]; segments?: number; bladeHeight?: GrassRange; bladeWidth?: GrassRange; bladeBend?: GrassRange; tuftBlades?: number; tuftRadius… — ⚠ undocumented
 - `GrassMaterialHandle` (interface): interface GrassMaterialHandle { material: THREE.MeshStandardMaterial; uniforms: GrassShaderUniforms } — ⚠ undocumented
 - `GrassMaterialOptions` (interface): interface GrassMaterialOptions { colorBase?: THREE.ColorRepresentation; colorTip?: THREE.ColorRepresentation; colorGround?: THREE.ColorRepresentation; colorVariation?: number; wind?: GrassWindOptions | false; distanceFade?: GrassDistanceFadeOptions | false; normalLift?: … — ⚠ undocumented
@@ -2771,14 +2774,17 @@
 - `TerrainField` (interface): interface TerrainField — A sampleable ground surface: height and normal at any x/z, with optional bounds and water level.
 - `TerrainHeightSampler` (type): type TerrainHeightSampler = (x: number, z: number) => number — ⚠ undocumented
 - `TerrainNormal` (type): type TerrainNormal = readonly [number, number, number] — A surface normal vector at a terrain sample point.
+- `TerrainPaintColorSampler` (type): type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean — Writes authored paint into an existing linear color; returns false for unpainted ground.
+- `TerrainPaintSource` (type): type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt"> — Live authored paint channels needed to sample a terrain's material stack without its heightfield.
 - `TerrainSeed` (type): type TerrainSeed = number | string — ⚠ undocumented
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
 - `displaceHeightfieldGeometry` (function): function displaceHeightfieldGeometry(geometry: THREE.BufferGeometry, sampleHeight: (x: number, z: number) => number, options: HeightfieldDisplaceOptions): void — 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.
 
 ## @jgengine/shell/terrain/CarvedTerrain
 
-- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+- `CarvedTerrain` (function): function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }: CarvedTerrainProps): React.JSX.Element — Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain. Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
 - `CarvedTerrainProps` (interface): interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { field: TerrainField; size?: FieldGroundOptions["size"]; segments?: FieldGroundOptions["segments"]; center?: FieldGroundOptions["center"]; colors?: FieldGroundOptions["colors"]; heightRange?: FieldGroundOptions["heightRange"]; paletteAt?: … — ⚠ undocumented · used by `CarvedTerrain`: Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
 
 ## @jgengine/shell/terrain/EditableGround
@@ -2791,7 +2797,7 @@
 - `DEFAULT_GRASS_COUNT` (const): const DEFAULT_GRASS_COUNT: 1500 — ⚠ undocumented
 - `DEFAULT_GRASS_DENSITY` (const): const DEFAULT_GRASS_DENSITY: 4 — 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.
 - `GRASS_TUFT_BLADES` (const): const GRASS_TUFT_BLADES: 5 — Blades baked into each tuft instance — one instance reads as a clump, not a lone blade.
-- `GrassField` (function): 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, dista… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
+- `GrassField` (function): 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, coverageAt, colorBase, colorTip, colorGround, colorVariation,… — Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades.
 - `GrassFieldProps` (interface): interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> { count?: number; density?: number; budget?: number; area?: TerrainArea; seed?: GrassBladeGeometryOptions["seed"]; segments?: number; bladeHeight?: GrassRange; bladeWidth?: GrassRange; bladeBend?: GrassRange; tuftBlades?: number; tuftRadius… — ⚠ undocumented
 
 ## @jgengine/shell/terrain/ProceduralGround
@@ -2859,6 +2865,12 @@
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
 
+## @jgengine/shell/terrain/terrainPaintColor
+
+- `TerrainPaintColorSampler` (type): type TerrainPaintColorSampler = (x: number, z: number, out: THREE.Color) => boolean — Writes authored paint into an existing linear color; returns false for unpainted ground.
+- `TerrainPaintSource` (type): type TerrainPaintSource = Pick<EditableTerrain, "layers" | "weightsAt" | "surfaceAt"> — Live authored paint channels needed to sample a terrain's material stack without its heightfield.
+- `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground.
+
 ## @jgengine/shell/touch/OrientationHint
 
 - `OrientationHint` (function): function OrientationHint({ wanted }: { wanted: "landscape" | "portrait" }): React.JSX.Element | null — ⚠ undocumented

package/skills/jgengine-ui/capabilities.md

@@ -670,6 +670,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `TalentTree` (function) · `import { TalentTree } from "@jgengine/react"`
 
+## terrain-paint-color — sample authored terrain surfaces and blended layers for shared ground rendering
+
+- `createTerrainPaintColorSampler` (function) · `import { createTerrainPaintColorSampler } from "@jgengine/shell/terrain"`
+
 ## territory-overlay — show footprint ownership, claim cost, and affordability
 
 - `TerritoryOverlay` (function) · `import { TerritoryOverlay } from "@jgengine/shell/TerritoryOverlay"`

package/skills/jgengine-world/api.md

@@ -3403,7 +3403,7 @@
 - `TerrainFlattenMask` (interface): interface TerrainFlattenMask { center: EnvironmentVec2; radius: number; height?: number; falloff?: number } — ⚠ undocumented · used by `padFlattenMasks`: Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it.
 - `TerrainIslandConfig` (interface): interface TerrainIslandConfig extends TerrainEnvironmentConfig — A bounded terrain patch floating at its own altitude — sky islands, arena platforms, split landmasses with void between.
 - `TerrainIslandDescriptor` (type): type TerrainIslandDescriptor = Omit<TerrainEnvironmentDescriptor, "kind"> & { kind: "island"; origin: EnvironmentVec2; } — ⚠ undocumented
-- `TerrainMaterial` (type): type TerrainMaterial = "grass" | "sand" | "snow" | "rock" | "ash" | "highland" | "slate" — ⚠ undocumented · used by `TERRAIN_MATERIALS` (@jgengine/editor): The default terrain paint palette (surface id → color) shared by the panel and the mesh.
+- `TerrainMaterial` (type): type TerrainMaterial = "grass" | "sand" | "snow" | "rock" | "ash" | "highland" | "slate" — ⚠ undocumented · used by `TERRAIN_MATERIALS` (@jgengine/core/editor): The default terrain paint palette (surface id → color) shared by the panel and the mesh.
 - `TerrainMaterialMaps` (interface): interface TerrainMaterialMaps — PBR map URLs for a real ground texture — the same shape `buildMaterialCatalog({ basePath }).resolve(id)!.maps` from `@jgengine/assets` returns. Kept dependency-free here so `core` never imports the assets package; any URLs (pulled maps, a CDN, a data URI) satisfy it. Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
 - `TerrainMaterialRegion` (type): type TerrainMaterialRegion = TerrainCircleRegion | TerrainPolylineRegion | TerrainRectRegion — A palette zone painted over the base terrain palette. Circle (the default when no `shape` is given), `polyline` ribbons for roads/rivers, and rotatable `rect` districts all paint fully inside their core and blend back across `falloff`; later regions in the list win overlaps.
 - `TerrainPolylineRegion` (interface): interface TerrainPolylineRegion extends TerrainRegionStyle — A ribbon palette zone following a centerline — roads and rivers, instead of chaining overlapping circles.

package/skills/jgengine-world/reference.md

@@ -28,6 +28,21 @@ export const overworld = world({
 
 ## Legacy world features
 
+Authored terrain paint carried by `environmentContentFromDocument(document).sculpt` renders on
+the normal environment ground. Single surface IDs use `TERRAIN_MATERIAL_COLORS` from
+`@jgengine/core/editor/terrainMaterials`; a layer's `tint` replaces that default color. Layer
+weights are multiplied by `opacity`, normalized, and blended in linear color space, matching
+the editor. Unpainted cells retain the descriptor palette. Grass roots and soil patch borders
+sample the same authored colors. Paint changes color, never ground height or collision.
+Descriptor-wide terrain detail still overlays the painted ground. Per-layer `roughness`,
+`tiling` and `triplanar` remain serialized authoring metadata; they do not select or configure
+separate runtime materials.
+
+Custom ground consumers can use `createTerrainPaintColorSampler` from `@jgengine/shell/terrain`
+with a `TerrainPaintSource` (an editable terrain's layer/surface/weight channels). The returned
+`TerrainPaintColorSampler` writes a linear `THREE.Color` and returns whether the point is painted;
+false leaves the caller's fallback color unchanged. The normal ground wires this automatically.
+
 Descriptors from `@jgengine/core/world/features` — legacy code-declared world shapes kept for
 existing games. Do not start new worlds here; `environment()` is now the consumption target for
 editor/preset-written scene data (`environmentContentFromDocument`), not a world definition: