@jgengine/core 0.9.0 → 0.11.0

package/dist/world/features.d.ts

@@ -1,4 +1,8 @@
 import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
+import type { AvoidZone } from "./geometry.js";
+import type { TerrainPathProfile } from "./pathTerrain.js";
+import type { TerraformSnapshot } from "./terraform.js";
+import type { VolumetricCloudsConfig } from "./volumetricClouds.js";
 export interface WorldBounds {
     w: number;
     d: number;
@@ -15,6 +19,63 @@ export interface TerrainColors {
     high?: string;
     waterline?: string;
 }
+/**
+ * Procedural detail-surface layer for terrain: a noise-driven shader that keeps the
+ * biome-tinted base ground (from `colors`/`biomeBands`) and blends distinct rock,
+ * sand, and snow over it by slope, height, and waterline — turning a flat
+ * vertex-colour surface into varied, textured-reading ground with no image assets.
+ */
+export interface TerrainDetailConfig {
+    /** Steep-slope rock colour. Default "#6f7175". */
+    rockColor?: string;
+    /** Waterline/beach sand colour. Default "#c2b283". */
+    sandColor?: string;
+    /** High-altitude snow colour. Default "#eef3f7". */
+    snowColor?: string;
+    /** Slope (0 flat … 1 vertical) at which rock starts taking over. Default 0.42. */
+    rockSlopeStart?: number;
+    /** World height above which snow appears. Default 26. */
+    snowHeight?: number;
+    /** Water level for the sand band; defaults to the terrain's `waterLevel`. */
+    waterLevel?: number;
+    /** Fine detail noise wavelength in world units. Default 5. */
+    detailScale?: number;
+    /** Large-scale colour-variation wavelength in world units. Default 45. */
+    macroScale?: number;
+    /** Surface roughness of the detail material. Default 0.9. */
+    roughness?: number;
+    /** Overall detail intensity 0..1. Default 1. */
+    strength?: number;
+    /** Real PBR texture maps blended over the procedural detail — the seam for `@jgengine/assets` `buildMaterialCatalog` output. Omit to keep the procedural-only look. */
+    material?: TerrainDetailMaterialConfig;
+}
+/**
+ * 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.
+ */
+export interface TerrainMaterialMaps {
+    color: string;
+    normal: string;
+    roughness: string;
+    ao: string;
+    displacement: string;
+}
+/**
+ * Real PBR texture applied over the ground surface — the seam that lets a game put a
+ * `buildMaterialCatalog` material on terrain. Blends with, never replaces, the procedural detail
+ * shader: color/roughness/ao tile the maps by world position, `strength` fades them over the
+ * existing vertex-colour + noise look.
+ */
+export interface TerrainDetailMaterialConfig {
+    /** e.g. `buildMaterialCatalog({ basePath: "/materials" }).resolve("material/grass")!.maps`. */
+    maps: TerrainMaterialMaps;
+    /** World units per texture tile; smaller tiles the texture more densely. Default 4. */
+    repeat?: number;
+    /** Blend strength of the texture over the procedural/vertex-colour base, 0..1. Default 1. */
+    strength?: number;
+}
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;
     radius: number;
@@ -23,16 +84,80 @@ export interface TerrainFlattenMask {
     /** Extra blend-ring width outside `radius` where the flat height smoothsteps back to the noise value; default `radius * 0.5`. */
     falloff?: number;
 }
-/** A circular palette zone painted over the base terrain palette — snow caps, ash wastes, sand shores on one heightfield. */
-export interface TerrainMaterialRegion {
-    center: EnvironmentVec2;
-    radius: number;
+/** Palette and blend fields shared by every `TerrainMaterialRegion` shape. */
+export interface TerrainRegionStyle {
     /** Named palette preset for this region (see `TERRAIN_MATERIAL_PALETTES` in `world/terrain`); overridden field-by-field by `colors`. */
     material?: TerrainMaterial;
     colors?: TerrainColors;
-    /** Blend-ring width outside `radius` back to the surrounding palette; default `radius * 0.5`. */
+    /** Blend-ring width outside the region core back to the surrounding palette; default: half the region's characteristic size. */
     falloff?: number;
 }
+/** A circular palette zone painted over the base terrain palette — snow caps, ash wastes, spawn circles. */
+export interface TerrainCircleRegion extends TerrainRegionStyle {
+    shape?: "circle";
+    center: EnvironmentVec2;
+    radius: number;
+}
+/** A ribbon palette zone following a centerline — roads and rivers, instead of chaining overlapping circles. */
+export interface TerrainPolylineRegion extends TerrainRegionStyle {
+    shape: "polyline";
+    /** Centerline vertices in world XZ; needs at least two points. */
+    points: readonly EnvironmentVec2[];
+    /** Full ribbon width; the painted core extends `width / 2` either side of the centerline. `falloff` defaults to `width * 0.5`. */
+    width: number;
+}
+/** A rectangular palette zone, optionally rotated about the world y axis — plazas, fields, districts. */
+export interface TerrainRectRegion extends TerrainRegionStyle {
+    shape: "rect";
+    center: EnvironmentVec2;
+    /** Half-extents along the region's local x and z before rotation. `falloff` defaults to half the smaller extent. */
+    halfExtents: EnvironmentVec2;
+    /** Rotation about the world y axis in radians; default 0. */
+    rotationY?: number;
+}
+/**
+ * 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.
+ */
+export type TerrainMaterialRegion = TerrainCircleRegion | TerrainPolylineRegion | TerrainRectRegion;
+/** Per-band fog override cross-faded along z by `createBiomeFogSampler`; unset fields fall through to the base sky fog. */
+export interface BiomeFog {
+    color?: string;
+    near?: number;
+    far?: number;
+    density?: number;
+}
+/** Per-band sky/light override cross-faded along z by `createBiomeSkySampler`; unset fields fall through to the base sky. */
+export interface BiomeSky {
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+}
+/**
+ * A z-ordered ground palette zone — the linear-boundary counterpart to the radial `materialRegions`.
+ * Adjacent bands cross-fade into each other across a `fade`-wide window centered on the midpoint z
+ * between their centers, so a multi-biome world (vale → marsh → peaks along z) blends its ground
+ * color instead of hard-switching. Bands may also carry per-zone `fog`, `sky`, and `weather`. Order
+ * the list by ascending `z`.
+ */
+export interface BiomeBand {
+    /** World-space center z of the zone. */
+    z: number;
+    /** Cross-fade window width straddling the boundary to the next band. Default 64. */
+    fade?: number;
+    /** Named palette preset for the zone (see `TERRAIN_MATERIAL_PALETTES`); overridden field-by-field by `colors`. */
+    material?: TerrainMaterial;
+    /** Explicit low/high/waterline hex colors for the zone. */
+    colors?: TerrainColors;
+    /** Fog color/near/far/density for the zone, cross-faded per camera z; unset fields keep the base sky fog. */
+    fog?: BiomeFog;
+    /** Sky horizon/zenith colors and sun/ambient intensity for the zone, cross-faded per camera z; unset fields keep the base sky. */
+    sky?: BiomeSky;
+    /** Precipitation covering the zone — expands into a full-width weather strip centered at `[0, z]`, `fade`-deep. */
+    weather?: "rain" | "snow";
+}
 export interface TerrainEnvironmentConfig {
     bounds?: WorldBounds;
     height?: number;
@@ -49,6 +174,8 @@ export interface TerrainEnvironmentConfig {
     colors?: TerrainColors;
     /** Palette zones blended over the base `material`/`colors` for multi-biome readability. */
     materialRegions?: readonly TerrainMaterialRegion[];
+    /** Ordered z-banded ground palettes that cross-fade along the world's z axis (vale → marsh → peaks). Painted under `materialRegions`. */
+    biomeBands?: readonly BiomeBand[];
     segments?: number;
     seed?: string;
     frequency?: number;
@@ -58,26 +185,64 @@ export interface TerrainEnvironmentConfig {
     waterLevel?: number;
     /** Flat pads carved into the noise field, e.g. for building pads or spawn circles. */
     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;
 }
 export interface RainEnvironmentConfig {
+    /**
+     * `w`/`d`/`h` size a wrap-volume of raindrops **anchored to and re-centered on the camera every
+     * frame** — not a world-space region. `area.position` (and the `position` sugar below) has **no
+     * visual effect** on rain/snow: the shell's `RainField`/`SnowField` always run `followCamera` and
+     * never apply the mesh's transform, only `camera.position`. Keep `w`/`d`/`h` near camera scale
+     * (roughly 50-120 per axis) so drops stay a visible size at normal view distance — sizing the
+     * volume to a world region (e.g. matching a district's footprint) spreads the same drop count
+     * across that much more space until they're sub-pixel and the storm reads as empty sky, even
+     * though `summarizeEnvironment` shows the layer exists. Reach for `density`, `width`, and `opacity`
+     * to make a storm read heavier/taller instead of enlarging `area`.
+     */
     area?: EnvironmentArea;
+    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`. No visual effect on rain/snow (see `area`); kept for API symmetry with other weather-adjacent features. */
+    position?: EnvironmentVec2;
     density?: number;
     speed?: number;
     dropLength?: number;
     wind?: EnvironmentVec2;
     color?: string;
+    /** Streak width of each raindrop quad, in world units. Default 0.018 — raise for a heavier-reading storm without enlarging `area`. */
+    width?: number;
+    /** Drop opacity, 0-1. Default 0.48 — raise for a denser-reading storm without enlarging `area`. */
+    opacity?: number;
 }
 export interface SnowEnvironmentConfig {
+    /**
+     * `w`/`d`/`h` size a wrap-volume of snowflakes **anchored to and re-centered on the camera every
+     * frame** — not a world-space region. `area.position` (and the `position` sugar below) has **no
+     * visual effect** on rain/snow: the shell's `RainField`/`SnowField` always run `followCamera` and
+     * never apply the mesh's transform, only `camera.position`. Keep `w`/`d`/`h` near camera scale
+     * (roughly 50-120 per axis) so flakes stay a visible size at normal view distance — sizing the
+     * volume to a world region (e.g. matching a district's footprint) spreads the same flake count
+     * across that much more space until they're sub-pixel and the storm reads as empty sky, even
+     * though `summarizeEnvironment` shows the layer exists. Reach for `density`, `flakeSize`, and
+     * `opacity` to make a storm read heavier instead of enlarging `area`.
+     */
     area?: EnvironmentArea;
+    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`. No visual effect on rain/snow (see `area`); kept for API symmetry with other weather-adjacent features. */
+    position?: EnvironmentVec2;
     density?: number;
     speed?: number;
     flakeSize?: number;
     drift?: number;
     wind?: EnvironmentVec2;
     color?: string;
+    /** Flake opacity, 0-1. Default 0.86 — raise for a denser-reading storm without enlarging `area`. */
+    opacity?: number;
 }
 export interface GrassEnvironmentConfig {
     area?: EnvironmentArea;
+    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`, letting a biome zone site its own vegetation away from the origin. */
+    position?: EnvironmentVec2;
     density?: number;
     bladeHeight?: readonly [number, number];
     bladeWidth?: number;
@@ -111,11 +276,19 @@ export interface SkyEnvironmentConfig {
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Default 260. */
+    radius?: number;
+    /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
+    hazeStrength?: number;
+    /** Sun-glow brightness multiplier around the sun disc. Default 1. */
+    sunGlowStrength?: number;
     fog?: {
         color?: string;
         near?: number;
         far?: number;
     };
+    /** Raymarched volumetric cloud layer over the sky dome. Off by default — omit for no clouds. */
+    volumetricClouds?: VolumetricCloudsConfig;
 }
 export interface BuildingEnvironmentConfig {
     count?: number;
@@ -158,10 +331,10 @@ export type TerrainIslandDescriptor = Omit<TerrainEnvironmentDescriptor, "kind">
 };
 export type RainEnvironmentDescriptor = {
     kind: "rain";
-} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color">>;
+} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color" | "width" | "opacity">>;
 export type SnowEnvironmentDescriptor = {
     kind: "snow";
-} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color">>;
+} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
 } & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
@@ -177,6 +350,36 @@ export type PadEnvironmentDescriptor = {
 export type SkyEnvironmentDescriptor = {
     kind: "sky";
 } & Required<Pick<SkyEnvironmentConfig, "preset" | "timeOfDay">> & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay">;
+/** Config for {@link road}: a flat asphalt ribbon draped over the terrain along a centerline. */
+export interface RoadEnvironmentConfig {
+    /** Centerline vertices in world XZ; at least two points. */
+    path: readonly (readonly [number, number])[];
+    /** Ribbon width in world units. Default 8. */
+    width?: number;
+    /** Asphalt color. Default "#3b3e47". */
+    color?: string;
+    /** Paint a dashed centerline. Default true. */
+    markings?: boolean;
+    /** Centerline dash color. Default "#e8c74a". */
+    markingColor?: string;
+    /** Lift above the terrain to avoid z-fighting; stagger overlapping roads. Default 0.08. */
+    elevation?: number;
+    /** Sidewalk bands on both edges; `false` for none. Default `{ width: 2.6, color: "#a7adb8" }`. */
+    sidewalk?: {
+        width?: number;
+        color?: string;
+    } | false;
+}
+/** Resolved road descriptor produced by {@link road} and rendered by the shell environment scene. */
+export type RoadEnvironmentDescriptor = {
+    kind: "road";
+} & Required<Pick<RoadEnvironmentConfig, "path" | "width" | "color" | "markings" | "markingColor" | "elevation">> & {
+    /** Resolved sidewalk band, or `false` when the road has none. */
+    sidewalk: {
+        width: number;
+        color: string;
+    } | false;
+};
 export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
 export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;
 export type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor;
@@ -191,8 +394,22 @@ export interface EnvironmentWorldConfig {
     vegetation?: EnvironmentDescriptorList<VegetationEnvironmentDescriptor>;
     water?: EnvironmentDescriptorList<WaterEnvironmentDescriptor>;
     structures?: EnvironmentDescriptorList<StructureEnvironmentDescriptor>;
+    /** Road ribbons draped over the terrain — see `road()`. */
+    roads?: EnvironmentDescriptorList<RoadEnvironmentDescriptor>;
     /** Ground pads, e.g. platforms or paved patches; each implicitly flattens the terrain beneath it. */
     pads?: readonly PadEnvironmentDescriptor[];
+    /**
+     * An authored editor {@link TerraformSnapshot} whose offsets layer over the base terrain — the
+     * editor-to-runtime ground seam. The same snapshot in a game's `editorLayers.terrain` renders and
+     * collides identically at runtime.
+     */
+    sculpt?: TerraformSnapshot;
+    /**
+     * Clearance discs flattened into the ground (spawns, plots, paths) — the terrain half of a
+     * clearance zone whose foliage half is scatter's `avoid`. Derive them from a document with
+     * `clearanceZonesFrom`.
+     */
+    clearings?: readonly AvoidZone[];
 }
 export interface EnvironmentWorldFeature {
     kind: "environment";
@@ -203,7 +420,12 @@ export interface EnvironmentWorldFeature {
     vegetation?: readonly VegetationEnvironmentDescriptor[];
     water?: readonly WaterEnvironmentDescriptor[];
     structures?: readonly StructureEnvironmentDescriptor[];
+    roads?: readonly RoadEnvironmentDescriptor[];
     pads?: readonly PadEnvironmentDescriptor[];
+    /** Authored sculpt snapshot layered over the base terrain — see {@link EnvironmentWorldConfig.sculpt}. */
+    sculpt?: TerraformSnapshot;
+    /** Clearance discs flattened into the ground — see {@link EnvironmentWorldConfig.clearings}. */
+    clearings?: readonly AvoidZone[];
 }
 export interface WorldGridCell {
     x: number;
@@ -242,6 +464,7 @@ export interface PlotsWorldConfig extends WorldGridConfig {
 export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
 }
+/** A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`. */
 export type WorldFeature = ({
     kind: "biomes";
 } & BiomesWorldConfig) | ({
@@ -255,18 +478,32 @@ export type WorldFeature = ({
 };
 /** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. Elevated pads (absolute `elevation`) float free and carve nothing. */
 export declare function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[];
+/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
 export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
+/** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
 export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
 export declare function sky(config?: SkyEnvironmentConfig): SkyEnvironmentDescriptor;
+/** Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity. */
 export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity. */
 export declare function snow(config?: SnowEnvironmentConfig): SnowEnvironmentDescriptor;
+/** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */
 export declare function grass(config?: GrassEnvironmentConfig): GrassEnvironmentDescriptor;
+/** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */
 export declare function ocean(config?: OceanEnvironmentConfig): OceanEnvironmentDescriptor;
+/** Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain. */
+export declare function road(config: RoadEnvironmentConfig): RoadEnvironmentDescriptor;
 export declare function island(config: TerrainIslandConfig): TerrainIslandDescriptor;
+/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. */
 export declare function building(config?: BuildingEnvironmentConfig): BuildingEnvironmentDescriptor;
 export declare function pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor;
+/** Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain. */
 export declare function biomes(config: BiomesWorldConfig): WorldFeature;
+/** Declares a voxel-grid world for block-based games. */
 export declare function voxel(config: VoxelWorldConfig): WorldFeature;
+/** Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts. */
 export declare function plots(config?: PlotsWorldConfig): WorldFeature;
+/** Declares a 2D tilemap world from a map string. */
 export declare function tilemap(config: TilemapWorldConfig): WorldFeature;
+/** Declares an empty flat world — the minimal `WorldFeature` for games with no terrain of their own. */
 export declare function flat(): WorldFeature;

package/dist/world/features.js

@@ -27,11 +27,32 @@ function withPadFlatten(terrainDescriptor, pads) {
         flatten: [...(terrainDescriptor.flatten ?? []), ...padFlattenMasks(pads)],
     };
 }
+/** Expands each `biomeBand.weather` into a full-width precipitation strip centered on the band's z, `fade`-deep. */
+function bandWeatherDescriptors(terrainDescriptor) {
+    const bands = terrainDescriptor?.biomeBands;
+    if (bands === undefined || bands.length === 0)
+        return [];
+    const width = terrainDescriptor.bounds.w;
+    const out = [];
+    for (const band of bands) {
+        if (band.weather === undefined)
+            continue;
+        const area = { w: width, d: band.fade ?? 64, h: 80 };
+        const position = [0, band.z];
+        out.push(band.weather === "rain" ? rain({ area, position }) : snow({ area, position }));
+    }
+    return out;
+}
+/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
 export function environment(config = {}) {
-    const weather = list(config.weather);
+    const explicitWeather = list(config.weather);
+    const bandWeather = bandWeatherDescriptors(config.terrain);
+    const weatherAll = [...(explicitWeather ?? []), ...bandWeather];
+    const weather = weatherAll.length === 0 ? undefined : weatherAll;
     const vegetation = list(config.vegetation);
     const water = list(config.water);
     const structures = list(config.structures);
+    const roads = list(config.roads);
     const terrainDescriptor = withPadFlatten(config.terrain, config.pads);
     return {
         kind: "environment",
@@ -42,9 +63,13 @@ export function environment(config = {}) {
         ...(vegetation === undefined ? {} : { vegetation }),
         ...(water === undefined ? {} : { water }),
         ...(structures === undefined ? {} : { structures }),
+        ...(roads === undefined ? {} : { roads }),
         ...(config.pads === undefined ? {} : { pads: config.pads }),
+        ...(config.sculpt === undefined ? {} : { sculpt: config.sculpt }),
+        ...(config.clearings === undefined || config.clearings.length === 0 ? {} : { clearings: config.clearings }),
     };
 }
+/** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
 export function terrain(config = {}) {
     if (config.baseHeight !== undefined &&
         config.height === undefined &&
@@ -62,6 +87,7 @@ export function terrain(config = {}) {
         ...(config.material === undefined ? {} : { material: config.material }),
         ...(config.colors === undefined ? {} : { colors: config.colors }),
         ...(config.materialRegions === undefined ? {} : { materialRegions: config.materialRegions }),
+        ...(config.biomeBands === undefined ? {} : { biomeBands: config.biomeBands }),
         ...(config.segments === undefined ? {} : { segments: config.segments }),
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.frequency === undefined ? {} : { frequency: config.frequency }),
@@ -70,6 +96,8 @@ export function terrain(config = {}) {
         ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
         ...(config.flatten === undefined ? {} : { flatten: config.flatten }),
+        ...(config.pathProfiles === undefined ? {} : { pathProfiles: config.pathProfiles }),
+        ...(config.detail === undefined ? {} : { detail: config.detail }),
     });
 }
 export function sky(config = {}) {
@@ -82,36 +110,71 @@ export function sky(config = {}) {
         ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
         ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
         ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.radius === undefined ? {} : { radius: config.radius }),
+        ...(config.hazeStrength === undefined ? {} : { hazeStrength: config.hazeStrength }),
+        ...(config.sunGlowStrength === undefined ? {} : { sunGlowStrength: config.sunGlowStrength }),
         ...(config.fog === undefined ? {} : { fog: config.fog }),
+        ...(config.volumetricClouds === undefined ? {} : { volumetricClouds: config.volumetricClouds }),
     });
 }
+function withAreaPosition(area, position) {
+    return position !== undefined && area.position === undefined ? { ...area, position } : area;
+}
+/**
+ * Practical ceiling (world units per axis) past which an author-specified rain/snow `area` is almost
+ * certainly a world-region size mistakenly handed to the camera-anchored wrap-volume — see the
+ * `area` doc on `RainEnvironmentConfig`/`SnowEnvironmentConfig`.
+ */
+const WEATHER_AREA_CAMERA_SCALE_HINT = 120;
+function warnIfOversizedWeatherArea(kind, area) {
+    if (typeof console === "undefined")
+        return;
+    if (area.w <= WEATHER_AREA_CAMERA_SCALE_HINT &&
+        area.d <= WEATHER_AREA_CAMERA_SCALE_HINT &&
+        (area.h ?? 0) <= WEATHER_AREA_CAMERA_SCALE_HINT) {
+        return;
+    }
+    console.warn(`[jgengine:${kind}] area ${area.w}x${area.d}x${area.h ?? "default"} is far larger than the camera-anchored wrap-volume ${kind}() actually renders — area.position is ignored, and an oversized area.w/d/h just spreads drops/flakes thinner until they're sub-pixel at normal view distance, not wider visible coverage. Keep area near camera scale (~50-120 per axis); use density/width/opacity (or flakeSize for snow) to make a storm read heavier instead.`);
+}
+/** Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity. */
 export function rain(config = {}) {
+    const area = withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position);
+    if (config.area !== undefined)
+        warnIfOversizedWeatherArea("rain", area);
     return {
         kind: "rain",
-        area: config.area ?? { w: 256, d: 256, h: 80 },
+        area,
         density: config.density ?? 0.65,
         speed: config.speed ?? 18,
         dropLength: config.dropLength ?? 0.8,
         wind: config.wind ?? [0, 0],
         color: config.color ?? "#9ec8ff",
+        width: config.width ?? 0.018,
+        opacity: config.opacity ?? 0.48,
     };
 }
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity. */
 export function snow(config = {}) {
+    const area = withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position);
+    if (config.area !== undefined)
+        warnIfOversizedWeatherArea("snow", area);
     return {
         kind: "snow",
-        area: config.area ?? { w: 256, d: 256, h: 80 },
+        area,
         density: config.density ?? 0.35,
         speed: config.speed ?? 2.4,
         flakeSize: config.flakeSize ?? 0.08,
         drift: config.drift ?? 0.4,
         wind: config.wind ?? [0, 0],
         color: config.color ?? "#ffffff",
+        opacity: config.opacity ?? 0.86,
     };
 }
+/** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */
 export function grass(config = {}) {
     return withOptional({
         kind: "grass",
-        area: config.area ?? { w: 128, d: 128 },
+        area: withAreaPosition(config.area ?? { w: 128, d: 128 }, config.position),
         density: config.density ?? 4,
         bladeHeight: config.bladeHeight ?? [0.25, 0.9],
         bladeWidth: config.bladeWidth ?? 0.035,
@@ -119,6 +182,7 @@ export function grass(config = {}) {
         colors: config.colors ?? ["#3f7d2d", "#66a83f"],
     }, config.seed === undefined ? undefined : { seed: config.seed });
 }
+/** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */
 export function ocean(config = {}) {
     return {
         kind: "ocean",
@@ -132,11 +196,30 @@ export function ocean(config = {}) {
         ...(config.levelAt === undefined ? {} : { levelAt: config.levelAt }),
     };
 }
+/** Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain. */
+export function road(config) {
+    if (config.path.length < 2) {
+        throw new Error("road: path needs at least two points");
+    }
+    return {
+        kind: "road",
+        path: config.path,
+        width: config.width ?? 8,
+        color: config.color ?? "#3b3e47",
+        markings: config.markings ?? true,
+        markingColor: config.markingColor ?? "#e8c74a",
+        elevation: config.elevation ?? 0.08,
+        sidewalk: config.sidewalk === false
+            ? false
+            : { width: config.sidewalk?.width ?? 2.6, color: config.sidewalk?.color ?? "#a7adb8" },
+    };
+}
 export function island(config) {
     const { origin, ...terrainConfig } = config;
     const { kind: _kind, ...descriptor } = terrain(terrainConfig);
     return { ...descriptor, kind: "island", origin };
 }
+/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. */
 export function building(config = {}) {
     return withOptional({
         kind: "building",
@@ -164,18 +247,23 @@ export function pad(config) {
         ...(config.elevation === undefined ? {} : { elevation: config.elevation }),
     });
 }
+/** Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain. */
 export function biomes(config) {
     return { kind: "biomes", ...config };
 }
+/** Declares a voxel-grid world for block-based games. */
 export function voxel(config) {
     return { kind: "voxel", ...config };
 }
+/** Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts. */
 export function plots(config = {}) {
     return { kind: "plots", ...config };
 }
+/** Declares a 2D tilemap world from a map string. */
 export function tilemap(config) {
     return { kind: "tilemap", ...config };
 }
+/** Declares an empty flat world — the minimal `WorldFeature` for games with no terrain of their own. */
 export function flat() {
     return { kind: "flat" };
 }

package/dist/world/footprintGrid.d.ts

@@ -0,0 +1,59 @@
+import type { Footprint, Vec2 } from "./geometry.js";
+import type { PlacementObstacle } from "./placement.js";
+/** One integer cell address on a {@link FootprintGrid}. */
+export interface GridCell {
+    col: number;
+    row: number;
+}
+/** Config for {@link createFootprintGrid}. */
+export interface FootprintGridOptions {
+    /** World units per cell. Default 1. */
+    cellSize?: number;
+}
+/** A live claim on a {@link FootprintGrid}: which cells `id` (a `kind` tag for adjacency checks) holds. */
+export interface FootprintReservation {
+    id: string;
+    kind: string;
+    cells: readonly GridCell[];
+}
+/** Handle returned by {@link createFootprintGrid}. */
+export interface FootprintGrid {
+    readonly cellSize: number;
+    /** The cells a `footprint` centered on `origin` (world units) covers, honoring `quarterTurns` — feed straight into `reserve`/`isFree`. */
+    cellsFor(origin: Vec2, footprint: Footprint, quarterTurns?: number): GridCell[];
+    isFree(cells: readonly GridCell[]): boolean;
+    /** Claims every cell for `id`/`kind`; fails (no partial reservation) if `id` already holds a reservation or any cell is occupied. */
+    reserve(id: string, kind: string, cells: readonly GridCell[]): boolean;
+    release(id: string): boolean;
+    occupantAt(cell: GridCell): string | null;
+    kindAt(cell: GridCell): string | null;
+    reservationOf(id: string): FootprintReservation | null;
+    list(): readonly FootprintReservation[];
+    clear(): void;
+}
+/**
+ * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
+ * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
+ * hover's `isFree` check (or another player's, in a shared world) sees it. Bridge into
+ * `world/placement`'s `PlacementRules.obstacles` with {@link footprintObstacles} instead of
+ * hand-rolling an occupancy map per game.
+ *
+ * @capability footprint-grid multi-cell footprint occupancy/reservation on a shared build grid
+ */
+export declare function createFootprintGrid(options?: FootprintGridOptions): FootprintGrid;
+/** One occupied neighbor cell reported by {@link boundaryNeighbors}. */
+export interface AdjacentCell {
+    cell: GridCell;
+    kind: string;
+}
+/** Every occupied cell orthogonally touching `cells` but outside them — the connective-piece neighbor set. */
+export declare function boundaryNeighbors(grid: FootprintGrid, cells: readonly GridCell[]): AdjacentCell[];
+/**
+ * Connective-piece adjacency validity: every occupied neighbor of `cells` must satisfy `accepts`
+ * (no incompatible piece touching), and when `requireConnection` is true at least one neighbor must
+ * (a road/pipe/belt segment placed with nothing to connect to is invalid). An empty-bordered footprint
+ * (no occupied neighbors at all) passes unless `requireConnection` demands one.
+ */
+export declare function hasValidAdjacency(grid: FootprintGrid, cells: readonly GridCell[], accepts: (neighborKind: string) => boolean, requireConnection?: boolean): boolean;
+/** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
+export declare function footprintObstacles(grid: FootprintGrid): PlacementObstacle[];