@jgengine/editor 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/TerrainSculpt.js

@@ -5,18 +5,14 @@ import * as THREE from "three";
 import { createTerrainPaletteSampler, raycastHeightField, } from "@jgengine/core/world/terrain";
 import { beginSurfaceStroke, beginTerraformStroke, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
 import { useGameContext } from "@jgengine/react/provider";
-import { displaceHeightfieldGeometry, normalizeHeightBlend, TerraformBrushCursor, } from "@jgengine/shell/terrain";
+import { displaceHeightfieldGeometry, normalizeHeightBlend, createTerrainPaintColorSampler, TerraformBrushCursor, } from "@jgengine/shell/terrain";
 import { editorPerfMarks } from "./perfMarks.js";
-import { TERRAIN_MATERIAL_COLORS, } from "./uiStore.js";
+import {} from "./uiStore.js";
 import { useStoreSelector } from "./useStoreSelector.js";
 const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
 const LOW = new THREE.Color("#3f5d34");
 const HIGH = new THREE.Color("#8f9c66");
 const COLOR_SPAN = 24;
-/** Resolves a material layer to its render color (its tint, else its palette surface color). */
-function layerColor(layer) {
-    return layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86";
-}
 /** The game's `environment({ terrain })` descriptor, when the world it declares carries one — the same descriptor `TerrainGround` samples at runtime via `createTerrainPaletteSampler`. */
 function terrainDescriptorOf(world) {
     return world?.kind === "environment" ? world.terrain : undefined;
@@ -65,28 +61,11 @@ function editFromSettings(settings, center, clickHeight) {
         ...(heightLimit === undefined ? {} : { heightLimit }),
     };
 }
-const BLEND_A = new THREE.Color();
-const BLEND_B = new THREE.Color();
-/** Parsed once — `toneAt` runs per vertex, so hex→Color parsing must not. */
-const SURFACE_COLOR_CACHE = new Map();
-function surfaceColor(hex) {
-    let color = SURFACE_COLOR_CACHE.get(hex);
-    if (color === undefined) {
-        color = new THREE.Color(hex);
-        SURFACE_COLOR_CACHE.set(hex, color);
-    }
-    return color;
-}
 /** World-unit spacing between topographic relief bands drawn on the sculpt preview. */
 const CONTOUR_INTERVAL = 1.5;
-/**
- * Topographic relief baked into a vertex's color so elevation reads from the editor's high camera,
- * where lighting alone leaves gentle hills invisible. Smooth cosine bands every `CONTOUR_INTERVAL`
- * darken slopes toward each band trough (a contour-map look) and higher ground brightens slightly —
- * a `multiply`, so painted grass/dirt/rock keep their hue. Flat ground at a band height (the common
- * unsculpted case at y=0) is left untouched: only varying height shows the bands. `strength` 0 is a
- * no-op.
- */
+const BLEND_A = new THREE.Color();
+const BLEND_B = new THREE.Color();
+/** Multiplicative contour bands preserve painted hue while making elevation readable. */
 function applyRelief(out, height, strength) {
     if (strength <= 0)
         return;
@@ -102,37 +81,9 @@ function applyRelief(out, height, strength) {
  * default — so `materialRegions`/base `colors`/`material` (worn paths, rock outcrops, biome tint)
  * show through in the editor the same way `TerrainGround` renders them at runtime.
  */
-function toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors) {
-    const layers = terrain.layers;
-    if (layers.length > 0) {
-        const weights = terrain.weightsAt(x, z);
-        if (weights.length === layers.length) {
-            let total = 0;
-            let r = 0;
-            let g = 0;
-            let b = 0;
-            for (let l = 0; l < layers.length; l += 1) {
-                const w = weights[l] * (layers[l].opacity ?? 1);
-                if (w <= 0)
-                    continue;
-                const color = layerColors[l];
-                r += color.r * w;
-                g += color.g * w;
-                b += color.b * w;
-                total += w;
-            }
-            if (total > 0) {
-                out.setRGB(r / total, g / total, b / total);
-                return;
-            }
-        }
-    }
-    const surface = terrain.surfaceAt(x, z);
-    const painted = surface === null ? undefined : TERRAIN_MATERIAL_COLORS[surface];
-    if (painted !== undefined) {
-        out.copy(surfaceColor(painted));
+function toneAt(x, z, height, out, paletteAt, heightRange, paintColorAt) {
+    if (paintColorAt(x, z, out))
         return;
-    }
     if (paletteAt !== null) {
         const palette = paletteAt(x, z);
         const blend = normalizeHeightBlend(height, heightRange[0], heightRange[1]);
@@ -151,12 +102,12 @@ function toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors)
  */
 function displace(geometry, terrain, bounds, region, paletteAt, heightRange, contourStrength) {
     const started = performance.now();
-    const layerColors = terrain.layers.map((layer) => surfaceColor(layerColor(layer)));
+    const paintColorAt = createTerrainPaintColorSampler(terrain);
     displaceHeightfieldGeometry(geometry, terrain.sampleHeight, {
         bounds,
         region,
         color: (x, z, height, out) => {
-            toneAt(terrain, x, z, height, out, paletteAt, heightRange, layerColors);
+            toneAt(x, z, height, out, paletteAt, heightRange, paintColorAt);
             applyRelief(out, height, contourStrength);
         },
     });

package/dist/uiStore.d.ts

@@ -7,16 +7,7 @@ export type EditorTool = "select" | "terrain";
 export type TerrainBrushKind = "raise" | "lower" | "smooth" | "flatten" | "noise" | "ramp";
 /** The terrain tool's active sub-mode: reshape the heightfield, or paint material layers onto it. */
 export type TerrainMode = "sculpt" | "paint";
-/** A paintable terrain material layer — a surface id plus the color it renders as. */
-export interface TerrainMaterial {
-    id: string;
-    label: string;
-    color: string;
-}
-/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
-export declare const TERRAIN_MATERIALS: readonly TerrainMaterial[];
-/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
-export declare const TERRAIN_MATERIAL_COLORS: Record<string, string>;
+export { TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS, type TerrainMaterial } from "@jgengine/core/editor/terrainMaterials";
 /** Live terrain material-paint controls driven by the terrain tool panel. */
 export interface PaintSettings {
     material: string;

package/dist/uiStore.js

@@ -1,16 +1,4 @@
-/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
-export const TERRAIN_MATERIALS = [
-    { id: "grass", label: "Grass", color: "#4b7f3f" },
-    { id: "dirt", label: "Dirt", color: "#6b4f34" },
-    { id: "rock", label: "Rock", color: "#7c7f86" },
-    { id: "sand", label: "Sand", color: "#c2b283" },
-    { id: "mud", label: "Mud", color: "#574433" },
-    { id: "snow", label: "Snow", color: "#eef3f7" },
-    { id: "road", label: "Road", color: "#3a3a3d" },
-    { id: "gravel", label: "Gravel", color: "#8d8d84" },
-];
-/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
-export const TERRAIN_MATERIAL_COLORS = Object.fromEntries(TERRAIN_MATERIALS.map((material) => [material.id, material.color]));
+export { TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS } from "@jgengine/core/editor/terrainMaterials";
 /** The terrain tool's default paint controls. */
 export const DEFAULT_PAINT_SETTINGS = {
     material: "grass",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/editor",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.21.0",
-    "@jgengine/navbake": "^0.21.0",
-    "@jgengine/react": "^0.21.0",
-    "@jgengine/shell": "^0.21.0"
+    "@jgengine/core": "^0.22.0",
+    "@jgengine/navbake": "^0.22.0",
+    "@jgengine/react": "^0.22.0",
+    "@jgengine/shell": "^0.22.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

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-editor/api.md

@@ -78,6 +78,9 @@
 - `SplitWorldResult` (interface): interface SplitWorldResult — The result of splitting a document: a manifest plus the shard documents keyed by their file path.
 - `StreamUpdate` (interface): interface StreamUpdate — The residency change produced by one {@link WorldStreamer.update}.
 - `StreamerShard` (interface): interface StreamerShard — The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides, as the camera moves, which shards enter and leave residency. It is pure scheduling — actually reading/merging the shard documents stays the caller's job (compose with `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a shard on a boundary from thrashing load/unload every frame.
+- `TERRAIN_MATERIALS` (const): const TERRAIN_MATERIALS: readonly TerrainMaterial[] — The default terrain paint palette (surface id → color) shared by the panel and the mesh.
+- `TERRAIN_MATERIAL_COLORS` (const): const TERRAIN_MATERIAL_COLORS: Record<string, string> — Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint.
+- `TerrainMaterial` (interface): interface TerrainMaterial — A paintable terrain material layer — a surface id plus the color it renders as.
 - `WELL_KNOWN_MARKER_KINDS` (const): const WELL_KNOWN_MARKER_KINDS: readonly ["player_spawn", "mob", "boss", "vendor", "chest", "travel", "npc", "poi", "prop", "goal", "branch"] — Standard marker kinds recognized with default colors and behavior.
 - `WELL_KNOWN_PATH_KINDS` (const): const WELL_KNOWN_PATH_KINDS: readonly ["road", "corridor", "branch", "route"] — Standard path kinds recognized with default colors and behavior.
 - `WELL_KNOWN_VOLUME_KINDS` (const): const WELL_KNOWN_VOLUME_KINDS: readonly ["zone", "flatten", "cluster", "aggro", "leash", "discover", "capture", "prompt", "poi", "respawn_skip"] — Standard volume kinds recognized with default colors and behavior.
@@ -346,6 +349,12 @@
 - `createWorldStreamer` (function): function createWorldStreamer(config: WorldStreamerConfig): WorldStreamer — Creates a proximity streamer over a world's shards. Always-resident shards are resident from the first update onward; each bounded shard loads when the camera comes within `loadRadius` of its footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up), giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the caller wires each delta to `loadWorldDocument`.
 - `shardDistance` (function): function shardDistance(shard: StreamerShard, center: { x: number; z: number }): number — Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
 
+## @jgengine/core/editor/terrainMaterials
+
+- `TERRAIN_MATERIALS` (const): const TERRAIN_MATERIALS: readonly TerrainMaterial[] — The default terrain paint palette (surface id → color) shared by the panel and the mesh.
+- `TERRAIN_MATERIAL_COLORS` (const): const TERRAIN_MATERIAL_COLORS: Record<string, string> — Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint.
+- `TerrainMaterial` (interface): interface TerrainMaterial — A paintable terrain material layer — a surface id plus the color it renders as.
+
 ## @jgengine/core/editor/types
 
 - `EditorBake` (interface): interface EditorBake — A named baked artifact produced by an editor or build tool.