@jgengine/core 0.10.0 → 0.11.0

package/dist/world/authoredObjects.js

@@ -0,0 +1,69 @@
+function metaString(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function metaNumber(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias.
+ * Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function markerCatalogId(marker) {
+    if (typeof marker.catalogId === "string" && marker.catalogId.length > 0)
+        return marker.catalogId;
+    return metaString(marker.meta, "catalogId");
+}
+function markerVerticalOffset(marker) {
+    const fromMeta = metaNumber(marker.meta, "verticalOffset") ??
+        metaNumber(marker.meta, "offsetY") ??
+        metaNumber(marker.meta, "yOffset");
+    return fromMeta ?? 0;
+}
+/**
+ * Every marker carrying a catalog id, as placeable props — pure, no terrain sample. Parallel to
+ * {@link resolveScatter}: games and headless tests read the same list `<AuthoredObjects>` places.
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function resolveAuthoredObjects(document) {
+    const out = [];
+    for (const marker of document.markers) {
+        const catalogId = markerCatalogId(marker);
+        if (catalogId === null)
+            continue;
+        out.push({
+            catalogId,
+            x: marker.position.x,
+            z: marker.position.z,
+            rotationY: marker.rotationY ?? 0,
+            instanceId: marker.id,
+            verticalOffset: markerVerticalOffset(marker),
+        });
+    }
+    return out;
+}
+/**
+ * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
+ * per-object and options vertical offsets. Returns the instance ids that were placed (or kept).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function placeAuthoredObjects(store, objects, sampleHeight, options = {}) {
+    const lift = options.verticalOffset ?? 0;
+    const onExisting = options.onExisting;
+    const ids = [];
+    for (const object of objects) {
+        const y = sampleHeight(object.x, object.z) + object.verticalOffset + lift;
+        ids.push(store.place(object.catalogId, object.x, y, object.z, {
+            instanceId: object.instanceId,
+            rotation: object.rotationY,
+            ...(onExisting === undefined ? {} : { onExisting }),
+        }));
+    }
+    return ids;
+}
+/** Convenience: resolve a document then place every authored catalog prop. */
+export function placeAuthoredObjectsFromDocument(store, document, sampleHeight, options = {}) {
+    return placeAuthoredObjects(store, resolveAuthoredObjects(document), sampleHeight, options);
+}

package/dist/world/buildingGenerator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { type GeneratedAsset } from "../scene/assetGenerator.js";
+import type { ParamSchema, ParsedParams } from "../scene/sceneKinds.js";
+/** The generator id a catalog entry / placed marker references. */
+export declare const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export declare const BUILDING_GENERATOR_SCHEMA: ParamSchema;
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export declare function generateBuildingAsset(params: ParsedParams, seed: string): GeneratedAsset;
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerBuildingGenerator(): void;

package/dist/world/buildingGenerator.js

@@ -0,0 +1,62 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { registerAssetGenerator, partsBounds } from "../scene/assetGenerator.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, generateBuilding, resolveBuildingPalette } from "./buildings.js";
+/** The generator id a catalog entry / placed marker references. */
+export const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export const BUILDING_GENERATOR_SCHEMA = {
+    fields: [
+        { type: "range", key: "floors", label: "floors", min: 1, max: 20, step: 1, default: DEFAULT_BUILDING_CONFIG.floors },
+        { type: "range", key: "baysWide", label: "bays wide", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysWide },
+        { type: "range", key: "baysDeep", label: "bays deep", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysDeep },
+        { type: "range", key: "bayWidth", label: "bay width", min: 1, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.bayWidth, unit: "m" },
+        { type: "range", key: "floorHeight", label: "floor height", min: 2, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.floorHeight, unit: "m" },
+        {
+            type: "select",
+            key: "style",
+            label: "style",
+            default: "generic",
+            options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
+        },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export function generateBuildingAsset(params, seed) {
+    const style = params["style"];
+    const palette = resolveBuildingPalette(style);
+    const building = generateBuilding({
+        seed,
+        center: [0, 0],
+        floors: params["floors"],
+        baysWide: params["baysWide"],
+        baysDeep: params["baysDeep"],
+        bayWidth: params["bayWidth"],
+        floorHeight: params["floorHeight"],
+    });
+    const parts = building.parts.map((part) => ({
+        id: part.id,
+        kind: part.kind,
+        position: part.position,
+        size: part.scale,
+        rotationY: part.rotationY,
+        color: palette[part.kind],
+    }));
+    return { parts, bounds: partsBounds(parts) };
+}
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerBuildingGenerator() {
+    registerAssetGenerator({
+        id: BUILDING_GENERATOR_ID,
+        label: "Building",
+        schema: BUILDING_GENERATOR_SCHEMA,
+        generate: generateBuildingAsset,
+    });
+}

package/dist/world/buildings.d.ts

@@ -97,8 +97,13 @@ export type BuildingPaletteOverrides = Partial<BuildingPalette>;
 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, BuildingPalette>;
+/** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
+/** @internal */
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
+/** @internal */
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
+/** @internal */
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
+/** @internal */
 export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -176,6 +176,7 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
     if (preset === undefined) {
@@ -228,6 +229,7 @@ function rangeInt(seed, key, min, max) {
     const hi = Math.max(min, max);
     return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
 }
+/** @internal */
 export function createBuildingConfig(input = {}) {
     return {
         id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
@@ -406,6 +408,7 @@ function pushCorners(parts, config, width, depth) {
         parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
     });
 }
+/** @internal */
 export function generateBuilding(input = {}) {
     const config = createBuildingConfig(input);
     const width = config.baysWide * config.bayWidth;
@@ -429,6 +432,7 @@ export function generateBuilding(input = {}) {
         parts,
     };
 }
+/** @internal */
 export function createBuildingGrid(config) {
     const rows = positiveInt(config.rows, 1);
     const columns = positiveInt(config.columns, 1);
@@ -467,6 +471,7 @@ export function createBuildingGrid(config) {
     }
     return lots;
 }
+/** @internal */
 export function generateBuildingDistrict(config) {
     return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
 }

package/dist/world/catenary.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+export type { Vec3 } from "./geometry.js";
+import type { Vec3 } from "./geometry.js";
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export declare function sagCurve(a: Vec3, b: Vec3, sag: number, segments: number): Vec3[];
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export declare function catenaryCurve(a: Vec3, b: Vec3, slack: number, segments: number): Vec3[];

package/dist/world/catenary.js

@@ -0,0 +1,69 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export function sagCurve(a, b, sag, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const cx = (a[0] + b[0]) / 2;
+    const cy = (a[1] + b[1]) / 2 - 2 * sag;
+    const cz = (a[2] + b[2]) / 2;
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const u = 1 - t;
+        const w0 = u * u;
+        const w1 = 2 * u * t;
+        const w2 = t * t;
+        points.push([w0 * a[0] + w1 * cx + w2 * b[0], w0 * a[1] + w1 * cy + w2 * b[1], w0 * a[2] + w1 * cz + w2 * b[2]]);
+    }
+    return points;
+}
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export function catenaryCurve(a, b, slack, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const dx = b[0] - a[0];
+    const dz = b[2] - a[2];
+    const horizontal = Math.hypot(dx, dz);
+    if (horizontal < 1e-4 || slack <= 0)
+        return sagCurve(a, b, Math.max(0, slack) * horizontal * 0.5, steps);
+    const length = horizontal * (1 + slack);
+    // Solve the catenary parameter `p` (= a in y=p·cosh(x/p)) for the required arc length via bisection.
+    const targetRatio = length / horizontal;
+    let lo = 1e-3;
+    let hi = 1e6;
+    for (let i = 0; i < 48; i += 1) {
+        const mid = (lo + hi) / 2;
+        const ratio = (2 * mid * Math.sinh(horizontal / (2 * mid))) / horizontal;
+        if (ratio > targetRatio)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const p = (lo + hi) / 2;
+    const edge = p * Math.cosh(horizontal / (2 * p));
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const x = a[0] + dx * t;
+        const z = a[2] + dz * t;
+        // Local horizontal coordinate centered at mid-span → catenary drop below the chord (0 at ends).
+        const local = (t - 0.5) * horizontal;
+        const drop = p * Math.cosh(local / p) - edge;
+        const chordY = a[1] + (b[1] - a[1]) * t;
+        points.push([x, chordY + drop, z]);
+    }
+    return points;
+}

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;
@@ -42,6 +46,35 @@ export interface TerrainDetailConfig {
     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;
@@ -88,11 +121,26 @@ export interface TerrainRectRegion extends TerrainRegionStyle {
  * 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. Order the list by ascending `z`.
+ * 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. */
@@ -103,6 +151,12 @@ export interface BiomeBand {
     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;
@@ -131,22 +185,50 @@ 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`, letting a biome zone site its own weather away from the origin. */
+    /** 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`, letting a biome zone site its own weather away from the origin. */
+    /** 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;
@@ -154,6 +236,8 @@ export interface SnowEnvironmentConfig {
     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;
@@ -192,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;
@@ -239,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">;
@@ -306,6 +398,18 @@ export interface EnvironmentWorldConfig {
     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";
@@ -318,6 +422,10 @@ export interface EnvironmentWorldFeature {
     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;
@@ -375,9 +483,9 @@ export declare function environment(config?: EnvironmentWorldConfig): Environmen
 /** 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, and wind. */
+/** 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, and wind. */
+/** 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;

package/dist/world/features.js

@@ -27,9 +27,28 @@ 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);
@@ -46,6 +65,8 @@ export function environment(config = {}) {
         ...(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. */
@@ -75,6 +96,7 @@ 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 }),
     });
 }
@@ -88,35 +110,64 @@ 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;
 }
-/** Declares a rainfall weather effect for `environment()` — area, density, speed, and wind. */
+/**
+ * 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: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
+        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, and wind. */
+/** 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: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
+        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. */