@jgengine/core 0.9.0 → 0.10.0

package/dist/ui/swingTimer.d.ts

@@ -0,0 +1,42 @@
+/** The local player's auto-attack state for one frame. `swingTimer` counts DOWN in seconds to 0 (= a swing lands). */
+export interface SwingPlayerInput {
+    autoAttack: boolean;
+    swingTimer: number;
+    weapon: {
+        speed: number;
+    };
+}
+/** The current target, or the fields the bar needs from it. */
+export interface SwingTargetInput {
+    dead: boolean;
+    /** Entity kind; an `"object"` target (a node/chest) never shows a swing bar. */
+    kind: string;
+}
+/** Whether the bar shows a "ready" label or the seconds-remaining countdown. */
+export type SwingLabelKind = "ready" | "seconds";
+/** One frame of swing-bar state plus the cursor (`nextPeriod`/`nextTimer`) the caller carries back into the next call. */
+export interface SwingTimerState {
+    /** Whether the bar should render at all. */
+    visible: boolean;
+    /** Fill 0..1, growing toward 1 as the next swing nears. */
+    frac: number;
+    /** True the moment the swing is ready to land. */
+    ready: boolean;
+    labelKind: SwingLabelKind;
+    /** Seconds remaining until the next swing (0 when ready). */
+    seconds: number;
+    /** Recovered swing period this frame — pass back as `prevPeriod` next call. */
+    nextPeriod: number;
+    /** This frame's timer — pass back as `prevTimer` next call to detect the reset edge. */
+    nextTimer: number;
+}
+/** Threshold above which a timer jump is treated as a fresh swing (period reset). */
+export declare const SWING_EDGE_EPSILON = 0.0001;
+/**
+ * Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller
+ * threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on
+ * the reset edge (when `swingTimer` jumps up = a new swing began) as
+ * `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing
+ * the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+ */
+export declare function swingTimerState(player: SwingPlayerInput, target: SwingTargetInput | null, prevPeriod: number, prevTimer: number): SwingTimerState;

package/dist/ui/swingTimer.js

@@ -0,0 +1,38 @@
+/** Threshold above which a timer jump is treated as a fresh swing (period reset). */
+export const SWING_EDGE_EPSILON = 1e-4;
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+const HIDDEN = {
+    visible: false,
+    frac: 0,
+    ready: false,
+    labelKind: "seconds",
+    seconds: 0,
+};
+/**
+ * Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller
+ * threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on
+ * the reset edge (when `swingTimer` jumps up = a new swing began) as
+ * `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing
+ * the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+ */
+export function swingTimerState(player, target, prevPeriod, prevTimer) {
+    const swingTimer = player.swingTimer;
+    if (!player.autoAttack || target === null || target.dead || target.kind === "object") {
+        return { ...HIDDEN, nextPeriod: prevPeriod, nextTimer: swingTimer };
+    }
+    const isResetEdge = swingTimer > prevTimer + SWING_EDGE_EPSILON || prevPeriod <= 0;
+    const period = isResetEdge ? Math.max(swingTimer, player.weapon.speed) : prevPeriod;
+    const frac = period <= 0 ? 1 : clamp01(1 - swingTimer / period);
+    const ready = swingTimer <= 0;
+    return {
+        visible: true,
+        frac,
+        ready,
+        labelKind: ready ? "ready" : "seconds",
+        seconds: Math.max(0, swingTimer),
+        nextPeriod: period,
+        nextTimer: swingTimer,
+    };
+}

package/dist/visibility/spatialIndex.js

@@ -33,10 +33,10 @@ export function createSpatialIndex(options = {}) {
                     const key = packCell(x, y, z);
                     let bucket = cells.get(key);
                     if (bucket === undefined) {
-                        bucket = new Set();
+                        bucket = { x, y, z, ids: new Set() };
                         cells.set(key, bucket);
                     }
-                    bucket.add(id);
+                    bucket.ids.add(id);
                 }
             }
         }
@@ -49,8 +49,8 @@ export function createSpatialIndex(options = {}) {
                     const bucket = cells.get(key);
                     if (bucket === undefined)
                         continue;
-                    bucket.delete(id);
-                    if (bucket.size === 0)
+                    bucket.ids.delete(id);
+                    if (bucket.ids.size === 0)
                         cells.delete(key);
                 }
             }
@@ -69,17 +69,20 @@ export function createSpatialIndex(options = {}) {
         addToCells(id, range);
         entries.set(id, { range, dynamic });
     }
-    function collectCell(key, out) {
-        const bucket = cells.get(key);
-        if (bucket === undefined)
-            return;
-        for (const id of bucket) {
+    function collectBucket(bucket, out) {
+        for (const id of bucket.ids) {
             if (stamps.get(id) === queryStamp)
                 continue;
             stamps.set(id, queryStamp);
             out.push(id);
         }
     }
+    function collectCell(key, out) {
+        const bucket = cells.get(key);
+        if (bucket === undefined)
+            return;
+        collectBucket(bucket, out);
+    }
     function collectOversized(out) {
         for (const id of oversized) {
             if (stamps.get(id) === queryStamp)
@@ -93,12 +96,25 @@ export function createSpatialIndex(options = {}) {
         out.length = 0;
         const x0 = cellOf(minX, size), y0 = cellOf(minY, size), z0 = cellOf(minZ, size);
         const x1 = cellOf(maxX, size), y1 = cellOf(maxY, size), z1 = cellOf(maxZ, size);
-        for (let x = x0; x <= x1; x += 1) {
-            for (let y = y0; y <= y1; y += 1) {
-                for (let z = z0; z <= z1; z += 1) {
-                    if (cellFilter !== undefined && !cellFilter(x, y, z))
-                        continue;
-                    collectCell(packCell(x, y, z), out);
+        const rangeCellCount = (x1 - x0 + 1) * (y1 - y0 + 1) * (z1 - z0 + 1);
+        if (rangeCellCount > cells.size) {
+            for (const bucket of cells.values()) {
+                if (bucket.x < x0 || bucket.x > x1 || bucket.y < y0 || bucket.y > y1 || bucket.z < z0 || bucket.z > z1) {
+                    continue;
+                }
+                if (cellFilter !== undefined && !cellFilter(bucket.x, bucket.y, bucket.z))
+                    continue;
+                collectBucket(bucket, out);
+            }
+        }
+        else {
+            for (let x = x0; x <= x1; x += 1) {
+                for (let y = y0; y <= y1; y += 1) {
+                    for (let z = z0; z <= z1; z += 1) {
+                        if (cellFilter !== undefined && !cellFilter(x, y, z))
+                            continue;
+                        collectCell(packCell(x, y, z), out);
+                    }
                 }
             }
         }
@@ -172,13 +188,11 @@ export function createSpatialIndex(options = {}) {
         cells() {
             const result = [];
             for (const [key, bucket] of cells) {
-                const parts = key.split(":");
-                const x = Number(parts[0]), y = Number(parts[1]), z = Number(parts[2]);
                 result.push({
                     key,
-                    count: bucket.size,
-                    minX: x * size, minY: y * size, minZ: z * size,
-                    maxX: (x + 1) * size, maxY: (y + 1) * size, maxZ: (z + 1) * size,
+                    count: bucket.ids.size,
+                    minX: bucket.x * size, minY: bucket.y * size, minZ: bucket.z * size,
+                    maxX: (bucket.x + 1) * size, maxY: (bucket.y + 1) * size, maxZ: (bucket.z + 1) * size,
                 });
             }
             return result;

package/dist/world/environmentSummary.d.ts

@@ -1,5 +1,5 @@
 import { type BuildingPalette, type BuildingStyle, type GeneratedBuilding } from "./buildings.js";
-import type { BuildingEnvironmentDescriptor, EnvironmentWorldFeature, WorldBounds } from "./features.js";
+import type { BuildingEnvironmentDescriptor, EnvironmentArea, EnvironmentWorldFeature, WorldBounds } from "./features.js";
 import type { Aabb } from "./geometry.js";
 import { type TerrainPalette } from "./terrain.js";
 export declare function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[];
@@ -24,7 +24,7 @@ export interface StructureSummary {
     bounds: Aabb;
 }
 export interface VegetationSummary {
-    area: WorldBounds;
+    area: EnvironmentArea;
     density: number;
 }
 export interface WaterSummary {
@@ -33,8 +33,15 @@ export interface WaterSummary {
 }
 export interface WeatherSummary {
     kind: "rain" | "snow";
+    area: EnvironmentArea;
     density: number;
 }
+/** One road descriptor's resolved footprint: vertex count, width, and total centerline length. */
+export interface RoadSummary {
+    points: number;
+    width: number;
+    length: number;
+}
 export interface EnvironmentCounts {
     terrain: number;
     islands: number;
@@ -44,6 +51,7 @@ export interface EnvironmentCounts {
     vegetationFields: number;
     waterBodies: number;
     weatherSystems: number;
+    roads: number;
 }
 export interface IslandSummary extends TerrainSummary {
     origin: readonly [number, number];
@@ -55,6 +63,7 @@ export interface EnvironmentSummary {
     vegetation: readonly VegetationSummary[];
     water: readonly WaterSummary[];
     weather: readonly WeatherSummary[];
+    roads: readonly RoadSummary[];
     counts: EnvironmentCounts;
     isEmpty: boolean;
 }

package/dist/world/environmentSummary.js

@@ -1,4 +1,5 @@
 import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
@@ -106,8 +107,14 @@ export function summarizeEnvironment(feature) {
     }));
     const weather = (feature.weather ?? []).map((entry) => ({
         kind: entry.kind,
+        area: entry.area,
         density: entry.density,
     }));
+    const roads = (feature.roads ?? []).map((entry) => ({
+        points: entry.path.length,
+        width: entry.width,
+        length: pathLength(entry.path),
+    }));
     const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
     const counts = {
         terrain: terrain === undefined ? 0 : 1,
@@ -118,13 +125,15 @@ export function summarizeEnvironment(feature) {
         vegetationFields: vegetation.length,
         waterBodies: water.length,
         weatherSystems: weather.length,
+        roads: roads.length,
     };
     const isEmpty = counts.terrain === 0 &&
         counts.islands === 0 &&
         buildings === 0 &&
         counts.vegetationFields === 0 &&
         counts.waterBodies === 0 &&
-        counts.weatherSystems === 0;
+        counts.weatherSystems === 0 &&
+        counts.roads === 0;
     return {
         ...(terrain === undefined ? {} : { terrain }),
         islands,
@@ -132,6 +141,7 @@ export function summarizeEnvironment(feature) {
         vegetation,
         water,
         weather,
+        roads,
         counts,
         isEmpty,
     };

package/dist/world/features.d.ts

@@ -15,6 +15,34 @@ 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;
+}
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;
     radius: number;
@@ -23,16 +51,59 @@ 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;
+/**
+ * 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`.
+ */
+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;
+}
 export interface TerrainEnvironmentConfig {
     bounds?: WorldBounds;
     height?: number;
@@ -49,6 +120,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,9 +131,13 @@ export interface TerrainEnvironmentConfig {
     waterLevel?: number;
     /** Flat pads carved into the noise field, e.g. for building pads or spawn circles. */
     flatten?: readonly TerrainFlattenMask[];
+    /** Procedural detail surface (noise-driven rock/sand/snow over the biome base). Omit for the flat vertex-colour ground. */
+    detail?: TerrainDetailConfig;
 }
 export interface RainEnvironmentConfig {
     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. */
+    position?: EnvironmentVec2;
     density?: number;
     speed?: number;
     dropLength?: number;
@@ -69,6 +146,8 @@ export interface RainEnvironmentConfig {
 }
 export interface SnowEnvironmentConfig {
     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. */
+    position?: EnvironmentVec2;
     density?: number;
     speed?: number;
     flakeSize?: number;
@@ -78,6 +157,8 @@ export interface SnowEnvironmentConfig {
 }
 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;
@@ -177,6 +258,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,6 +302,8 @@ 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[];
 }
@@ -203,6 +316,7 @@ export interface EnvironmentWorldFeature {
     vegetation?: readonly VegetationEnvironmentDescriptor[];
     water?: readonly WaterEnvironmentDescriptor[];
     structures?: readonly StructureEnvironmentDescriptor[];
+    roads?: readonly RoadEnvironmentDescriptor[];
     pads?: readonly PadEnvironmentDescriptor[];
 }
 export interface WorldGridCell {
@@ -242,6 +356,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 +370,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, and wind. */
 export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, and wind. */
 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,13 @@ function withPadFlatten(terrainDescriptor, pads) {
         flatten: [...(terrainDescriptor.flatten ?? []), ...padFlattenMasks(pads)],
     };
 }
+/** 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 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 +44,11 @@ export function environment(config = {}) {
         ...(vegetation === undefined ? {} : { vegetation }),
         ...(water === undefined ? {} : { water }),
         ...(structures === undefined ? {} : { structures }),
+        ...(roads === undefined ? {} : { roads }),
         ...(config.pads === undefined ? {} : { pads: config.pads }),
     };
 }
+/** 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 +66,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 +75,7 @@ export function terrain(config = {}) {
         ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
         ...(config.flatten === undefined ? {} : { flatten: config.flatten }),
+        ...(config.detail === undefined ? {} : { detail: config.detail }),
     });
 }
 export function sky(config = {}) {
@@ -85,10 +91,14 @@ export function sky(config = {}) {
         ...(config.fog === undefined ? {} : { fog: config.fog }),
     });
 }
+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. */
 export function rain(config = {}) {
     return {
         kind: "rain",
-        area: config.area ?? { w: 256, d: 256, h: 80 },
+        area: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
         density: config.density ?? 0.65,
         speed: config.speed ?? 18,
         dropLength: config.dropLength ?? 0.8,
@@ -96,10 +106,11 @@ export function rain(config = {}) {
         color: config.color ?? "#9ec8ff",
     };
 }
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, and wind. */
 export function snow(config = {}) {
     return {
         kind: "snow",
-        area: config.area ?? { w: 256, d: 256, h: 80 },
+        area: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
         density: config.density ?? 0.35,
         speed: config.speed ?? 2.4,
         flakeSize: config.flakeSize ?? 0.08,
@@ -108,10 +119,11 @@ export function snow(config = {}) {
         color: config.color ?? "#ffffff",
     };
 }
+/** 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 +131,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 +145,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 +196,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" };
 }