@jgengine/core 0.21.0 → 0.23.0

package/dist/settings/graphicsProfile.d.ts

@@ -1,4 +1,9 @@
 import type { GraphicsQuality } from "./settingsModel.js";
+/**
+ * Procedural surface detail on loaded models: `"full"` adds mottling, wear, roughness break-up, a
+ * micro-normal and cavity shading; `"lite"` drops the micro-normal; `"off"` compiles the plain material.
+ */
+export type SurfaceDetailLevel = "off" | "lite" | "full";
 /** Serializable renderer budget selected by the player's graphics tier. */
 export interface GraphicsProfile {
     renderScale: number;
@@ -14,6 +19,8 @@ export interface GraphicsProfile {
         dof: boolean;
         smaa: boolean;
     };
+    /** Default painted-surface shader on loaded models. */
+    surfaceDetail: SurfaceDetailLevel;
 }
 /** Conservative defaults that preserve the existing high-quality shell behavior. */
 export declare const DEFAULT_GRAPHICS_PROFILES: Record<GraphicsQuality, GraphicsProfile>;

package/dist/settings/graphicsProfile.js

@@ -8,6 +8,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 128,
         anisotropy: 2,
         postStages: { ao: false, bloom: true, dof: false, smaa: true },
+        surfaceDetail: "lite",
     },
     medium: {
         renderScale: 1.5,
@@ -17,6 +18,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 256,
         anisotropy: 4,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
     high: {
         renderScale: 2,
@@ -26,6 +28,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 512,
         anisotropy: 8,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
     ultra: {
         renderScale: 2,
@@ -35,6 +38,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 1024,
         anisotropy: 16,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
 };
 /** Resolve one tier and apply game-authored field and post-stage overrides. */

package/dist/settings/graphicsSettings.d.ts

@@ -38,3 +38,12 @@ export declare function readGraphicsSettings(store: Pick<SettingsStore, "get">,
  * resets the individual overrides instead of leaving stale toggles behind.
  */
 export declare function applyGraphicsQuality(store: Pick<SettingsStore, "set">, quality: GraphicsQuality, overrides?: GraphicsProfileOverrides): GraphicsProfile;
+/**
+ * Wrap a settings store so the graphics tier reads as `quality` for this session only: every
+ * graphics field resolves from that tier until the player changes it, and nothing is persisted.
+ * Capture hosts use it (`?quality=low`) to render cheap iteration shots without leaving the
+ * draft tier in the browser profile for the next full-quality shot.
+ */
+export declare function withGraphicsQualityOverride(store: SettingsStore, quality: GraphicsQuality, overrides?: GraphicsProfileOverrides): SettingsStore;
+/** Parse a `?quality=` value into a graphics tier, or null when absent or unknown. */
+export declare function parseGraphicsQuality(raw: string | null | undefined): GraphicsQuality | null;

package/dist/settings/graphicsSettings.js

@@ -79,3 +79,32 @@ export function applyGraphicsQuality(store, quality, overrides) {
     }
     return tier;
 }
+/**
+ * Wrap a settings store so the graphics tier reads as `quality` for this session only: every
+ * graphics field resolves from that tier until the player changes it, and nothing is persisted.
+ * Capture hosts use it (`?quality=low`) to render cheap iteration shots without leaving the
+ * draft tier in the browser profile for the next full-quality shot.
+ */
+export function withGraphicsQualityOverride(store, quality, overrides) {
+    const tier = resolveGraphicsProfile(quality, overrides?.[quality]);
+    const pinned = new Map([
+        [SETTING_IDS.graphicsQuality, quality],
+        [SETTING_IDS.graphicsRenderScale, tier.renderScale],
+        [SETTING_IDS.graphicsAnisotropy, String(tier.anisotropy)],
+        ...GRAPHICS_POST_STAGES.map((stage) => [graphicsPostStageSettingId(stage), tier.postStages[stage]]),
+    ]);
+    return {
+        get(id, fallback) {
+            return pinned.has(id) ? pinned.get(id) : store.get(id, fallback);
+        },
+        set(id, value) {
+            pinned.delete(id);
+            store.set(id, value);
+        },
+        subscribe: store.subscribe,
+    };
+}
+/** Parse a `?quality=` value into a graphics tier, or null when absent or unknown. */
+export function parseGraphicsQuality(raw) {
+    return isGraphicsQuality(raw) ? raw : null;
+}

package/dist/world/buildings.d.ts

@@ -140,6 +140,13 @@ export declare function resolveBuildingSurface(surface: BuildingSurface): Buildi
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, Record<BuildingPartKind, string>>;
+/**
+ * Facade part probabilities per style, so an industrial yard, a ruined block and a coastal strip
+ * differ in shape as well as colour. Unset parts keep the generic probabilities.
+ */
+export declare const BUILDING_STYLE_PROBABILITIES: Record<BuildingStyle, Partial<BuildingProbabilities>>;
+/** Style facade probabilities with explicit overrides applied on top. */
+export declare function resolveBuildingProbabilities(style?: BuildingStyle, overrides?: Partial<BuildingProbabilities>): Partial<BuildingProbabilities>;
 /**
  * Per-style facade-tone family: the wall colours a district spreads across its buildings so
  * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's

package/dist/world/buildings.js

@@ -191,6 +191,26 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/**
+ * Facade part probabilities per style, so an industrial yard, a ruined block and a coastal strip
+ * differ in shape as well as colour. Unset parts keep the generic probabilities.
+ */
+export const BUILDING_STYLE_PROBABILITIES = {
+    generic: {},
+    capital: { window: 0.95, awning: 0.3, clothesline: 0.02, storeSign: 0.5 },
+    village: { window: 0.7, openStore: 0.25, awning: 0.3, airConditioner: 0.04, clothesline: 0.4, storeSign: 0.18, roofProp: 0.12 },
+    desert: { window: 0.45, awning: 0.55, airConditioner: 0.2, clothesline: 0.18, storeSign: 0.35, roofProp: 0.4 },
+    industrial: { window: 0.3, openStore: 0.12, awning: 0, airConditioner: 0.55, clothesline: 0, storeSign: 0.08, roofProp: 0.8 },
+    coastal: { window: 0.85, awning: 0.62, clothesline: 0.32, storeSign: 0.55 },
+    neon: { window: 0.9, awning: 0.2, clothesline: 0.05, storeSign: 0.95, roofProp: 0.5 },
+    ruin: { window: 0.5, openStore: 0.2, awning: 0.04, airConditioner: 0.04, clothesline: 0.03, storeSign: 0.04, roofProp: 0.12 },
+    frontier: { window: 0.5, openStore: 0.45, awning: 0.58, airConditioner: 0, clothesline: 0.12, storeSign: 0.45, roofProp: 0.1 },
+    aerial: { window: 0.95, awning: 0, airConditioner: 0.3, clothesline: 0, storeSign: 0.2, roofProp: 0.6 },
+};
+/** Style facade probabilities with explicit overrides applied on top. */
+export function resolveBuildingProbabilities(style = DEFAULT_BUILDING_STYLE, overrides) {
+    return { ...BUILDING_STYLE_PROBABILITIES[style], ...overrides };
+}
 /**
  * Per-style facade-tone family: the wall colours a district spreads across its buildings so
  * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's

package/dist/world/environmentSummary.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, resolveBuildingProbabilities, } from "./buildings.js";
 import { buildingKitVariantCounts } from "./buildingKit.js";
 import { deriveBuildingLots } from "./buildingLots.js";
 import { pathLength } from "./roads.js";
@@ -22,7 +22,11 @@ export function resolveStructureBuildings(descriptor) {
         lotSize: descriptor.footprint,
         streetWidth: spacing,
         floorRange: descriptor.stories,
-        base: { floorHeight: descriptor.storyHeight, ...kitVariants(descriptor.kit) },
+        base: {
+            floorHeight: descriptor.storyHeight,
+            probabilities: resolveBuildingProbabilities(descriptor.style, descriptor.probabilities),
+            ...kitVariants(descriptor.kit),
+        },
         ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
     }).slice(0, descriptor.count);
 }
@@ -65,7 +69,7 @@ function resolveFrontageBuildings(descriptor, along) {
     });
     const [floorsMin, floorsMax] = descriptor.stories;
     const bayWidth = DEFAULT_BUILDING_CONFIG.bayWidth;
-    const variants = kitVariants(descriptor.kit);
+    const variants = { ...kitVariants(descriptor.kit), probabilities: resolveBuildingProbabilities(descriptor.style, descriptor.probabilities) };
     return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight, variants));
 }
 function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight, variants = {}) {

package/dist/world/features.d.ts

@@ -1,4 +1,4 @@
-import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
+import type { BuildingPaletteOverrides, BuildingProbabilities, BuildingStyle } from "./buildings.js";
 import type { BuildingKit } from "./buildingKit.js";
 import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
@@ -39,7 +39,7 @@ export interface TerrainDetailConfig {
     rockSlopeStart?: number;
     /** World height above which snow appears. Default 26. */
     snowHeight?: number;
-    /** Water level for the sand band; defaults to the terrain's `waterLevel`. */
+    /** Water level for the sand band; defaults to the terrain's `waterLevel`, and no band is drawn when the terrain has none. */
     waterLevel?: number;
     /** Fine detail noise wavelength in world units. Default 5. */
     detailScale?: number;
@@ -49,6 +49,12 @@ export interface TerrainDetailConfig {
     roughness?: number;
     /** Overall detail intensity 0..1. Default 1. */
     strength?: number;
+    /**
+     * Per-surface ground response 0..1 for painted layers: grass, dirt, gravel, rock, sand, mud, snow
+     * and road each draw their own procedural albedo, roughness and micro-normal, meet along
+     * noise-broken edges, and slopes turn to rock. Default 1; 0 keeps flat painted colour.
+     */
+    surfaceStrength?: number;
     /**
      * RGB multipliers for the two macro colour sweeps painted over the base ground. `dry` tints the
      * sun-bleached patches, `wet` the cooler pockets between them. The defaults ([1.14, 1.05, 0.76]
@@ -208,8 +214,12 @@ export interface TerrainEnvironmentConfig {
     flatten?: readonly TerrainFlattenMask[];
     /** Authored path profiles that flatten/grade/carve the heightfield along a centerline (roads, rivers, ramps) with optional retaining walls. Applied after `flatten`. */
     pathProfiles?: readonly TerrainPathProfile[];
-    /** Procedural detail surface (noise-driven rock/sand/snow over the biome base). Omit for the flat vertex-colour ground. */
-    detail?: TerrainDetailConfig;
+    /**
+     * Procedural detail surface (per-surface painted ground, slope rock, sand and snow over the biome
+     * base). Omitted, the ground still renders with default detail; `false` opts out to the flat
+     * vertex-colour ground.
+     */
+    detail?: TerrainDetailConfig | false;
 }
 export interface RainEnvironmentConfig {
     /**
@@ -388,6 +398,8 @@ export interface BuildingEnvironmentConfig {
     style?: BuildingStyle;
     /** Explicit per-part-kind hex colors; any part left unset falls back to the resolved `style` palette. */
     palette?: BuildingPaletteOverrides;
+    /** Facade part probabilities (windows, shopfronts, awnings, …); unset parts follow the `style`. */
+    probabilities?: Partial<BuildingProbabilities>;
     seed?: string;
     /**
      * Street-aware placement: derive lots along the given roads' frontage (facing each street, set
@@ -445,7 +457,7 @@ export type OceanEnvironmentDescriptor = {
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit" | "solid">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "probabilities" | "along" | "kit" | "solid">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;
@@ -471,6 +483,11 @@ export interface RoadEnvironmentConfig {
         width?: number;
         color?: string;
     } | false;
+    /**
+     * Procedural surface the carriageway shades with, named like terrain paint (`"asphalt"`,
+     * `"gravel"`, `"dirt"`). `false` keeps flat colour. Default `"road"` (asphalt grain and tyre wear).
+     */
+    surface?: string | false;
 }
 /** Resolved road descriptor produced by {@link road} and rendered by the shell environment scene. */
 export type RoadEnvironmentDescriptor = {
@@ -481,6 +498,8 @@ export type RoadEnvironmentDescriptor = {
         width: number;
         color: string;
     } | false;
+    /** Procedural carriageway surface; absent means `"road"`, `false` flat colour. */
+    surface?: string | false;
 };
 export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
 export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;

package/dist/world/features.js

@@ -233,6 +233,7 @@ export function road(config) {
         sidewalk: config.sidewalk === false
             ? false
             : { width: config.sidewalk?.width ?? 2.6, color: config.sidewalk?.color ?? "#a7adb8" },
+        ...(config.surface === undefined ? {} : { surface: config.surface }),
     };
 }
 export function island(config) {
@@ -256,6 +257,7 @@ export function building(config = {}) {
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.position === undefined ? {} : { position: config.position }),
         ...(config.palette === undefined ? {} : { palette: config.palette }),
+        ...(config.probabilities === undefined ? {} : { probabilities: config.probabilities }),
         ...(config.along === undefined ? {} : { along: config.along }),
         ...(config.kit === undefined ? {} : { kit: config.kit }),
         ...(config.solid === undefined ? {} : { solid: config.solid }),

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;
@@ -125,6 +125,8 @@ export interface EditableTerrain extends TerrainField {
     readonly cols: number;
     readonly rows: number;
     readonly cellSize: number;
+    /** World-space extent of the cell grid; cell `(gx, gz)` spans `cols`/`rows` equal slices of it. */
+    readonly gridBounds: Aabb;
     apply(edit: TerraformEdit): number;
     /** Apply an edit while reporting every touched vertex to `record` — the seam strokes record deltas through. */
     applyRecording(edit: TerraformEdit, record: TerraformDeltaRecorder): number;

package/dist/world/terraform.js

@@ -412,6 +412,7 @@ export function createEditableTerrain(config) {
         cols,
         rows,
         cellSize,
+        gridBounds: { minX: bounds.minX, minZ: bounds.minZ, maxX: bounds.minX + spanX, maxZ: bounds.minZ + spanZ },
         sampleHeight,
         sampleNormal,
         ...(base.bounds === undefined ? {} : { bounds: base.bounds }),

package/dist/world/terrain.d.ts

@@ -211,10 +211,11 @@ export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLev
         wet: readonly [number, number, number];
     };
 };
-/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level,
+ * and a terrain without one gets no sand band. `undefined` resolves the implicit default detail.
  * @internal
  */
-export declare function resolveTerrainDetail(config: TerrainDetailConfig, terrainWaterLevel?: number): ResolvedTerrainDetail;
+export declare function resolveTerrainDetail(config: TerrainDetailConfig | undefined, terrainWaterLevel?: number): ResolvedTerrainDetail;
 /** @internal */
 export declare function resolveTerrainPalette(descriptor?: Pick<TerrainEnvironmentConfig, "material" | "colors">): TerrainPalette;
 /**

package/dist/world/terrain.js

@@ -475,15 +475,27 @@ const DEFAULT_TERRAIN_DETAIL = {
     macroScale: 45,
     roughness: 0.9,
     strength: 1,
+    surfaceStrength: 1,
     sweeps: { dry: [1.14, 1.05, 0.76], wet: [0.78, 1.0, 0.86] },
 };
+/** Detail for a terrain that declares none: quieter base sweeps and no altitude snow. */
+const IMPLICIT_TERRAIN_DETAIL = {
+    strength: 0.6,
+    snowHeight: 1e6,
+    sweeps: { dry: [1.08, 1.03, 0.88], wet: [0.92, 0.98, 0.94] },
+};
 const DEFAULT_TERRAIN_MATERIAL_REPEAT = 4;
 const DEFAULT_TERRAIN_MATERIAL_STRENGTH = 1;
 const DEFAULT_TERRAIN_MATERIAL_TINT = 1;
-/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
+/** Sand-band level for a terrain with no water: far below any ground, so no beach is painted. */
+const NO_WATER_SAND_LEVEL = -1e6;
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level,
+ * and a terrain without one gets no sand band. `undefined` resolves the implicit default detail.
  * @internal
  */
-export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
+export function resolveTerrainDetail(config, terrainWaterLevel) {
+    if (config === undefined)
+        return resolveTerrainDetail(IMPLICIT_TERRAIN_DETAIL, terrainWaterLevel);
     return {
         rockColor: config.rockColor ?? DEFAULT_TERRAIN_DETAIL.rockColor,
         sandColor: config.sandColor ?? DEFAULT_TERRAIN_DETAIL.sandColor,
@@ -494,11 +506,12 @@ export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
         macroScale: config.macroScale ?? DEFAULT_TERRAIN_DETAIL.macroScale,
         roughness: config.roughness ?? DEFAULT_TERRAIN_DETAIL.roughness,
         strength: clamp01(config.strength ?? DEFAULT_TERRAIN_DETAIL.strength),
+        surfaceStrength: clamp01(config.surfaceStrength ?? DEFAULT_TERRAIN_DETAIL.surfaceStrength),
         sweeps: {
             dry: config.sweeps?.dry ?? DEFAULT_TERRAIN_DETAIL.sweeps.dry,
             wet: config.sweeps?.wet ?? DEFAULT_TERRAIN_DETAIL.sweeps.wet,
         },
-        waterLevel: config.waterLevel ?? terrainWaterLevel,
+        waterLevel: config.waterLevel ?? terrainWaterLevel ?? NO_WATER_SAND_LEVEL,
         ...(config.material === undefined
             ? {}
             : {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.21.0",
+  "version": "0.23.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.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -65,8 +65,8 @@
 - `CommandDecoder` (type): type CommandDecoder<TInput> = (input: unknown) => CommandDecodeResult<TInput> — Parses raw `unknown` transport input into `TInput`, rejecting anything that doesn't match the command's declared shape. Runs before `validate`/`apply`, so a malformed payload never reaches game logic.
 - `CommandDefinition` (interface): interface CommandDefinition<TState, TInput> { decode?: CommandDecoder<TInput>; validate?(state: TState, input: TInput): CommandRejection | null; apply(state: TState, input: TInput): TState | void } — ⚠ undocumented
 - `CommandRegistry` (interface): interface CommandRegistry<TState> { define<TInput>(name: string, definition: CommandDefinition<TState, TInput>): void; has(name: string): boolean; names(): string[]; run(state: TState, name: string, input: unknown): CommandResult<TState> } — ⚠ undocumented
-- `CommandRejection` (interface): interface CommandRejection { reason: string } — ⚠ undocumented · used by `validateCommandInput` (@jgengine/ws): Validates a `runCommand` input against a declared catalog.
-- `CommandResult` (type): type CommandResult<TState> = | { status: "applied"; state: TState } | { status: "rejected"; reason: string } | { status: "unknown-command" } — ⚠ undocumented
+- `CommandRejection` (interface): interface CommandRejection — Why a command refused: `reason` is a stable machine code; `message`, when set, is shown to the player.
+- `CommandResult` (type): type CommandResult<TState> = | { status: "applied"; state: TState } | { status: "rejected"; reason: string; message?: string } | { status: "unknown-command" } — ⚠ undocumented
 - `createCommandRegistry` (function): function createCommandRegistry<TState>(): CommandRegistry<TState> — ⚠ undocumented
 
 ## @jgengine/core/devtools/controls
@@ -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.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -292,9 +292,9 @@
 - `CommandDef` (type): type CommandDef<TInput = unknown> = { /** * `"server"` when `input` carries facts only the host may decide (unlock state, prices, multipliers): * public transports then refuse it and only trusted host calls such as `helpers.runCommand` run it. * Defaults to `"client"`, so every field of `input` must… — ⚠ undocumented · used by `defineCommand`: Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and `apply` receive the parsed type.
 - `CommandScope` (type): type CommandScope = { /** Member ids to hydrate; omit for the whole roster. */ players?: readonly string[]; /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */ chunkKeys?: readonly string[]; } — Which slice of a server has to be hydrated before some work runs against it. Both fields default to "everything", which costs a read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch.
 - `CommandScopeDefinition` (type): type CommandScopeDefinition = Omit<CommandScope, "players"> & { players?: readonly string[] | "actor" } — Declarative read scope; actor is resolved before host hydration.
-- `CommandValidationError` (type): type CommandValidationError = { reason: string } — ⚠ undocumented
+- `CommandValidationError` (type): type CommandValidationError = { reason: string; message?: string } — `reason` is a stable machine code; `message`, when set, is player-facing text the client shows on refusal.
 - `MALFORMED_COMMAND_INPUT_REASON` (const): const MALFORMED_COMMAND_INPUT_REASON: "Malformed command input" — Reason every host returns when a command's `parse` rejects its input.
-- `RunCommandResult` (type): type RunCommandResult = | { ok: true; snapshot: GameRuntimeSnapshot } | { ok: false; reason: string } — ⚠ undocumented
+- `RunCommandResult` (type): type RunCommandResult = | { ok: true; snapshot: GameRuntimeSnapshot } | { ok: false; reason: string; message?: string } — ⚠ undocumented
 - `SERVER_ONLY_COMMAND_REASON` (const): const SERVER_ONLY_COMMAND_REASON: "Command is server-only" — Reason a public transport returns for a {@link CommandDef} marked `access: "server"`.
 - `defineCommand` (function): function defineCommand<TInput>(definition: CommandDef<TInput> & { parse: (input: unknown) => TInput | null }): CommandDef — Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and `apply` receive the parsed type. Returns the untyped {@link CommandDef} a runtime's command table holds.
 
@@ -321,7 +321,7 @@
 - `GameContextItemUse` (interface): interface GameContextItemUse { register(handlers: Record<string, ItemUseHandler<GameContext>>): void; registered(): string[]; can(input: ItemUseInput): ItemUseRejection | null; use(input: ItemUseInput): ItemUseResult<GameContext> } — ⚠ undocumented
 - `GameContextLoot` (interface): interface GameContextLoot { register(def: LootTableDef): void; has(id: string): boolean; roll(id: string, rng?: () => number): Drop[]; grantToPlayer(userId: string, drops: Drop[], source?: string): void } — ⚠ undocumented
 - `GameContextModels` (interface): interface GameContextModels — Per-kind render-model lookup for {@link GameContextOptions.models}; a resolved `ModelConfig` satisfies {@link ModelBodySource} structurally.
-- `GameContextObjectEntry` (interface): interface GameContextObjectEntry { proximityPrompt?: ProximityPrompt; breakable?: false | {baseBreakTime: number}; slotInventory?: InventoryLayout; verbs?: readonly ContextVerb[]; colliders?: EntityColliderSet; halfExtents?: readonly [number, number, number] } — ⚠ undocumented
+- `GameContextObjectEntry` (interface): interface GameContextObjectEntry { proximityPrompt?: ProximityPrompt; breakable?: false | {baseBreakTime: number}; slotInventory?: InventoryLayout; verbs?: readonly ContextVerb[]; colliders?: EntityColliderSet; halfExtents?: readonly [number, number, number]; scenery?: boo… — ⚠ undocumented
 - `GameContextOptions` (interface): interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> { definition: GameDefinition<TAssetRef, TMultiplayer>; content: GameContextContent; player: {userId: string; isNew: boolean}; territory?: Territory; now?: () => number; occluder?: (from: EntityPosition, to: EntityPosition) => boolean; seed?… — ⚠ undocumented
 - `GameContextRace` (interface): interface GameContextRace { state(id: string, config?: RaceStateConfig): RaceState } — ⚠ undocumented
 - `GameContextTurn` (interface): interface GameContextTurn { loop(id: string, config?: TurnLoopConfig): TurnLoop } — ⚠ undocumented
@@ -352,7 +352,7 @@
 - `GameContextItemUse` (interface): interface GameContextItemUse { register(handlers: Record<string, ItemUseHandler<GameContext>>): void; registered(): string[]; can(input: ItemUseInput): ItemUseRejection | null; use(input: ItemUseInput): ItemUseResult<GameContext> } — ⚠ undocumented
 - `GameContextLoot` (interface): interface GameContextLoot { register(def: LootTableDef): void; has(id: string): boolean; roll(id: string, rng?: () => number): Drop[]; grantToPlayer(userId: string, drops: Drop[], source?: string): void } — ⚠ undocumented
 - `GameContextModels` (interface): interface GameContextModels — Per-kind render-model lookup for {@link GameContextOptions.models}; a resolved `ModelConfig` satisfies {@link ModelBodySource} structurally.
-- `GameContextObjectEntry` (interface): interface GameContextObjectEntry { proximityPrompt?: ProximityPrompt; breakable?: false | {baseBreakTime: number}; slotInventory?: InventoryLayout; verbs?: readonly ContextVerb[]; colliders?: EntityColliderSet; halfExtents?: readonly [number, number, number] } — ⚠ undocumented
+- `GameContextObjectEntry` (interface): interface GameContextObjectEntry { proximityPrompt?: ProximityPrompt; breakable?: false | {baseBreakTime: number}; slotInventory?: InventoryLayout; verbs?: readonly ContextVerb[]; colliders?: EntityColliderSet; halfExtents?: readonly [number, number, number]; scenery?: boo… — ⚠ undocumented
 - `GameContextOptions` (interface): interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> { definition: GameDefinition<TAssetRef, TMultiplayer>; content: GameContextContent; player: {userId: string; isNew: boolean}; territory?: Territory; now?: () => number; occluder?: (from: EntityPosition, to: EntityPosition) => boolean; seed?… — ⚠ undocumented
 - `GameContextRace` (interface): interface GameContextRace { state(id: string, config?: RaceStateConfig): RaceState } — ⚠ undocumented
 - `GameContextTurn` (interface): interface GameContextTurn { loop(id: string, config?: TurnLoopConfig): TurnLoop } — ⚠ undocumented
@@ -593,7 +593,7 @@
 - `PresenceSync` (type): type PresenceSync = { subscribe: (serverId: string, onChange: (rows: PresencePoseRow[]) => void) => FeedUnsubscribe; syncPose: (serverId: string, pose: PlayerPose) => void; } — ⚠ undocumented
 - `ResumeTicket` (type): type ResumeTicket = { userId: string; serverId: string; token: string; } — A short-lived credential allowing a disconnected client to reclaim one server membership.
 - `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; } — ⚠ undocumented
-- `TransportRunCommandResult` (type): type TransportRunCommandResult = | { ok: true } | { ok: false; reason: string } — ⚠ undocumented
+- `TransportRunCommandResult` (type): type TransportRunCommandResult = | { ok: true } /** `message` is the command's player-facing refusal text, when its `validate` gave one. */ | { ok: false; reason: string; message?: string } — ⚠ undocumented
 - `WorldSyncFrame` (type): type WorldSyncFrame = | { kind: "baseline"; revision: number; snapshot: WorldSnapshot } | { kind: "diff"; revision: number; diff: WorldDiff } — A revision-stamped world baseline or compact diff sent to a server-authoritative client.
 - `createTransportSessionId` (function): function createTransportSessionId(): string — Fresh id for one client session's join/leave pair (see {@link GameRuntimeTransport.joinServer}).
 
@@ -661,8 +661,8 @@
 
 ## @jgengine/shell/gameKit
 
-- `Clock` (function): function Clock({ format, showDay, controls, style, className, }: { format?: "24h" | "12h"; showDay?: boolean; controls?: boolean; style?: CSSProperties; className?: string; }): JSX.Element — A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds pause + the game's speed multipliers as clickable pills (the "fast-forward" bar), off by default so a game opts into letting the player scrub time.
-- `Coins` (function): function Coins({ currencyId, icon, style, className, }: { currencyId: string; icon?: ReactNode; style?: CSSProperties; className?: string; }): JSX.Element — A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. *
+- `Clock` (function): function Clock({ format = "24h", showDay = true, controls = false, style, className, }: { format?: "24h" | "12h"; showDay?: boolean; controls?: boolean; style?: CSSProperties; className?: string; }): React.JSX.Element — A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds pause + the game's speed multipliers as clickable pills (the "fast-forward" bar), off by default so a game opts into letting the player scrub time.
+- `Coins` (function): function Coins({ currencyId, icon = "🪙", style, className, }: { currencyId: string; icon?: ReactNode; style?: CSSProperties; className?: string; }): React.JSX.Element — A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. *
 - `DEFAULT_WALK_CODES` (const): const DEFAULT_WALK_CODES: { readonly moveForward: readonly ["KeyW"]; readonly moveBack: readonly ["KeyS"]; readonly moveLeft: readonly ["KeyA"]; readonly moveRight: readonly ["KeyD"]; readonly jump: readonly ["Space"]; } — Default keyboard codes for the shell walk controller (WASD + Space). Use as the base of `defineGame({ input: { ...DEFAULT_WALK_CODES, interact: ["KeyE"] } })` instead of re-typing the same five bindings in every game.
 - `EditorCatalogDefinition` (interface): interface EditorCatalogDefinition — Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code; entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
 - `EditorDocument` (interface): interface EditorDocument — The full authored scene: every marker, volume, path, note, and sculpted terrain for a game.
@@ -673,21 +673,21 @@
 - `GameHost` (function): function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor, creator, creatorOpen = false, onCreatorOpenChange }: GameHostProps): React.JSX.Element — The one documented mount: resolves multiplayer for the playable and renders the shell. With the `editor` loader prop it also owns the whole editor summon (F2+E, `?mode=editor`, dev save endpoint).
 - `GameHostProps` (interface): interface GameHostProps — Props for {@link GameHost}: the playable, optional multiplayer overrides, and the optional editor loader that enables the engine-owned F2+E summon.
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
-- `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: (item… — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
+- `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
-- `HudPanel` (function): function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack position within the region, a… — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
-- `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
-- `StatBar` (function): function StatBar({ statId, entityId, tone, label, showValue, width, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }): JSX.Element | null — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > & { /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the en… — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
+- `StatBar` (function): function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }… — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
 - `StoreHandle` (interface): interface StoreHandle<T> — A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a module-level singleton.
 - `SystemDefinition` (interface): interface SystemDefinition — A reusable game capability — lifecycle, timing, events, and optional save / replication / reset / disposal. Pass instances via `defineGame({ systems })`. Prefer one system per meaningful capability (`combat`, `quests`), not per micro-tick.
-- `authoredSpawnPosition` (function): function authoredSpawnPosition(document: AuthoredSpawnDocumentLike, options?: AuthoredSpawnOptions): [number, number, number] | null — Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the document has none. Reads the first `player_spawn` marker by default, so dragging the marker in the editor moves where players spawn — no coordinates copied into game code.
+- `authoredSpawnPosition` (function): function authoredSpawnPosition(document: AuthoredSpawnDocumentLike, options: AuthoredSpawnOptions = {}): [number, number, number] | null — Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the document has none. Reads the first `player_spawn` marker by default, so dragging the marker in the editor moves where players spawn — no coordinates copied into game code.
 - `collectAuthoredTriggers` (function): function collectAuthoredTriggers(document: SceneDocumentLike): AuthoredTrigger[] — Collect every authored trigger on a document's markers and volumes. Pure — no runtime state. Action params use the live {@link registerTriggerAction} registry when present.
 - `defineGame` (function): function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame — The one public authoring entry point: compose engine fields (systems, world, physics, input) and presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`. Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
 - `defineKeyedStore` (function): function defineKeyedStore<T>(keyFor: (id: string) => string, initial: T | (() => T)): KeyedStoreHandle<T> — Define a typed per-owner keyed family on the game store: game code expresses `read(ctx, userId)`/`write(ctx, userId, v)`/`update(...)` with the value type it means, and both the `` `prefix:${id}` `` key composition and the `unknown → T` cast live once, here, behind the boundary. Reach for this over N separate `defineStore` calls whenever the owning id varies at runtime (per-user class, per-instance auras) — `defineStore` stays the right call for a single fixed slot.
 - `defineStore` (function): function defineStore<T>(key: string, initial: T | (() => T)): StoreHandle<T> — Define a typed slot on the game store: game code expresses `read(ctx)`/`write(ctx, v)`/`update(...)` with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for a React selector, no allocation on a hot path). A value that carries functions (a closure-based run store, an input handle) is runtime-only: snapshots, saves and replication skip it and hydration keeps it in place. Hold such objects with `perContext` when they need no store notifications.
 - `defineSystem` (function): function defineSystem(definition: SystemDefinition): SystemDefinition — Declare a composable game system. Pure data + hooks — the engine compiles the schedule and installs lifecycle when the game boots.
-- `environment` (function): function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature — Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
-- `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.
+- `environment` (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature — Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+- `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.
 - `grounded` (function): function grounded(ctx: Pick<GameContext, "world">, x: number, z: number): readonly [number, number, number] — Ground an XZ point onto the live world surface as `[x, groundY, z]`.
 - `offline` (function): function offline(): MultiplayerAdapterConfig — Explicit single-player adapter. Solo games never need this — omitting `multiplayer` in the shell `defineGame` already defaults to offline; pass it only where an adapter value is structurally required.
 - `seededRng` (function): function seededRng(seed: string | number): SeededRng — Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.