@jgengine/core 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/editor/index.d.ts

@@ -124,3 +124,4 @@ export type { AsciiGridExportOptions } from "./gridAdapters.js";
 export type { CsvGridImportOptions } from "./gridAdapters.js";
 /** Options for exporting a grid layer as CSV. */
 export type { CsvGridExportOptions } from "./gridAdapters.js";
+export { TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS, type TerrainMaterial } from "./terrainMaterials.js";

package/dist/editor/index.js

@@ -15,3 +15,4 @@ export { applyDocumentPatch, applyRuntimeStateDelta, createDocumentLiveSync, get
 export { consumeRuntimePlayStep, createRuntimePlayControl, getRuntimeInspectorValue, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, summarizeRuntimeInspector, } from "./runtimeInspector.js";
 export { CURRENT_GRID_SCHEMA_VERSION, cloneGridLayer, createGridLayer, eraseGridCell, eyedropGridCell, fillGridRect, findGridPaletteEntry, floodFillGrid, forEachGridCell, getGridCell, getGridCellAtWorld, gridCellCount, gridCellEntries, gridCellKey, gridCellToWorld, gridCellsOfValue, gridEmptyValue, gridGlyphMap, inGridBounds, migrateGridLayer, paintGridCells, parseGridCellKey, resizeGridLayer, setGridCell, worldToGridCell, } from "./grid.js";
 export { exportAsciiGrid, exportCsvGrid, importAsciiGrid, importCsvGrid, } from "./gridAdapters.js";
+export { TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS } from "./terrainMaterials.js";

package/dist/editor/terrainMaterials.d.ts

@@ -0,0 +1,10 @@
+/** 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>;

package/dist/editor/terrainMaterials.js

@@ -0,0 +1,13 @@
+/** 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]));

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.21.0";
+export declare const VERSION = "0.22.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,22 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.21.0";
+export const VERSION = "0.22.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "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.",
+        ],
+        changed: [
+            "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.",
+        ],
+        removed: [],
+    },
     "0.21.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.21.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.18.0`; `@jgengine/github` is `0.8.0`.",

package/dist/world/grassKind.d.ts

@@ -16,6 +16,16 @@ export interface GrassRules {
     density: number;
     /** Blade height in meters. */
     bladeHeight: number;
+    /** Blade-width range in metres; endpoints are normalized on read. */
+    bladeWidthMin: number;
+    bladeWidthMax: number;
+    /** Bend range, 0..1. */
+    bladeBendMin: number;
+    bladeBendMax: number;
+    /** Spread of blades around each tuft root, in metres. */
+    tuftRadius: number;
+    /** Normal lift toward the sky, 0..1; controls the card lighting response. */
+    normalLift: number;
     /** Base (root) color, hex. */
     colorBase: string;
     /** Tip color, hex. */

package/dist/world/grassKind.js

@@ -15,6 +15,12 @@ export const GRASS_FIELD_KIND = "grass_field";
 export const GRASS_DEFAULTS = {
     density: 12,
     bladeHeight: 0.6,
+    bladeWidthMin: 0.05,
+    bladeWidthMax: 0.1,
+    bladeBendMin: 0.12,
+    bladeBendMax: 0.42,
+    tuftRadius: 0.16,
+    normalLift: 0.6,
     colorBase: "#3f6f37",
     colorTip: "#9ac25a",
     colorVariation: 0.35,
@@ -29,6 +35,12 @@ export const GRASS_SCHEMA = {
     fields: [
         { type: "range", key: "density", label: "density", min: 0.5, max: 160, step: 0.5, default: GRASS_DEFAULTS.density, unit: "/m²" },
         { type: "range", key: "bladeHeight", label: "blade height", min: 0.1, max: 2, step: 0.05, default: GRASS_DEFAULTS.bladeHeight, unit: "m" },
+        { type: "range", key: "bladeWidthMin", label: "minimum blade width", min: 0.005, max: 0.3, step: 0.005, default: GRASS_DEFAULTS.bladeWidthMin, unit: "m" },
+        { type: "range", key: "bladeWidthMax", label: "maximum blade width", min: 0.005, max: 0.3, step: 0.005, default: GRASS_DEFAULTS.bladeWidthMax, unit: "m" },
+        { type: "range", key: "bladeBendMin", label: "minimum bend", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.bladeBendMin },
+        { type: "range", key: "bladeBendMax", label: "maximum bend", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.bladeBendMax },
+        { type: "range", key: "tuftRadius", label: "tuft radius", min: 0, max: 0.6, step: 0.01, default: GRASS_DEFAULTS.tuftRadius, unit: "m" },
+        { type: "range", key: "normalLift", label: "normal lift", min: 0, max: 1, step: 0.01, default: GRASS_DEFAULTS.normalLift },
         { type: "color", key: "colorBase", label: "base color", default: GRASS_DEFAULTS.colorBase },
         { type: "color", key: "colorTip", label: "tip color", default: GRASS_DEFAULTS.colorTip },
         { type: "range", key: "colorVariation", label: "color variation", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.colorVariation },
@@ -49,9 +61,19 @@ function metaString(meta, key, fallback) {
 }
 /** Parse a volume's `meta` into fully-defaulted grass rules. @internal */
 export function readGrassRules(meta) {
+    const widthMin = Math.max(0.005, metaNumber(meta, "bladeWidthMin", GRASS_DEFAULTS.bladeWidthMin));
+    const widthMax = Math.max(0.005, metaNumber(meta, "bladeWidthMax", GRASS_DEFAULTS.bladeWidthMax));
+    const bendMin = Math.max(0, Math.min(1, metaNumber(meta, "bladeBendMin", GRASS_DEFAULTS.bladeBendMin)));
+    const bendMax = Math.max(0, Math.min(1, metaNumber(meta, "bladeBendMax", GRASS_DEFAULTS.bladeBendMax)));
     return {
         density: Math.max(0, metaNumber(meta, "density", GRASS_DEFAULTS.density)),
         bladeHeight: Math.max(0.05, metaNumber(meta, "bladeHeight", GRASS_DEFAULTS.bladeHeight)),
+        bladeWidthMin: Math.min(widthMin, widthMax),
+        bladeWidthMax: Math.max(widthMin, widthMax),
+        bladeBendMin: Math.min(bendMin, bendMax),
+        bladeBendMax: Math.max(bendMin, bendMax),
+        tuftRadius: Math.max(0, metaNumber(meta, "tuftRadius", GRASS_DEFAULTS.tuftRadius)),
+        normalLift: Math.max(0, Math.min(1, metaNumber(meta, "normalLift", GRASS_DEFAULTS.normalLift))),
         colorBase: metaString(meta, "colorBase", GRASS_DEFAULTS.colorBase),
         colorTip: metaString(meta, "colorTip", GRASS_DEFAULTS.colorTip),
         colorVariation: metaNumber(meta, "colorVariation", GRASS_DEFAULTS.colorVariation),

package/dist/world/terraform.d.ts

@@ -53,7 +53,7 @@ export interface TerrainMaterialLayer {
     tiling?: number;
     /** Project the material on all three axes to hide stretching on cliffs. */
     triplanar?: boolean;
-    /** Hex color multiplied over the surface color. */
+    /** Authored hex color replacing the default surface palette color in editor and runtime. */
     tint?: string;
     /** Layer master opacity 0..1 — scales this layer's blend weight everywhere. */
     opacity?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

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-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: