@jgengine/core 0.8.0 → 0.10.0

package/dist/world/features.d.ts

@@ -1,16 +1,48 @@
+import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
 export interface WorldBounds {
     w: number;
     d: number;
 }
+export type TerrainMaterial = "grass" | "sand" | "snow" | "rock" | "ash" | "highland" | "slate";
 export type EnvironmentVec2 = readonly [number, number];
 export interface EnvironmentArea extends WorldBounds {
     h?: number;
+    /** World-space center of the area; default `[0, 0]` (the world origin). Sites a weather/vegetation band away from the origin, like `building()`/`ocean()` `position`. */
+    position?: EnvironmentVec2;
 }
 export interface TerrainColors {
     low?: string;
     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;
@@ -19,14 +51,77 @@ 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;
 }
+/** 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 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;
     heightMap?: string;
+    /**
+     * Game-supplied height function replacing the built-in noise field — banded biomes, ridge walls,
+     * terracing, anything expressible as `(x, z) => y`. `flatten` masks still carve into it, and both
+     * the rendered ground and `ctx.world.ground` sample it. A function doesn't serialize; keep it pure.
+     */
+    heightField?: (x: number, z: number) => number;
     /** Named palette preset (see `TERRAIN_MATERIAL_PALETTES` in `world/terrain`); default "grass". Overridden field-by-field by `colors`. */
-    material?: string;
+    material?: TerrainMaterial;
     /** Explicit low/high/waterline hex colors; any field left unset falls back to the resolved `material` preset. */
     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;
@@ -36,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;
@@ -47,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;
@@ -55,7 +156,9 @@ export interface SnowEnvironmentConfig {
     color?: string;
 }
 export interface GrassEnvironmentConfig {
-    area?: WorldBounds;
+    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;
@@ -67,7 +170,15 @@ export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
     position?: EnvironmentVec2;
     level?: number;
+    /**
+     * Scheduled water level as a function of game-time seconds — tides, floods, draining chambers.
+     * Wins over `level` (which stays the initial/static value); `waterSurfaceFromDescriptor` bakes it
+     * into `WaterSurface.height`, and the shell repositions the rendered ocean from it every frame.
+     * A function doesn't serialize; keep it pure and deterministic (compose with `time/stateSchedule`).
+     */
+    levelAt?: (time: number) => number;
     waveHeight?: number;
+    /** Primary Gerstner wavelength in world units (shared with shell Ocean `waveScale`; default 18). */
     waveScale?: number;
     waveSpeed?: number;
     color?: string;
@@ -94,7 +205,10 @@ export interface BuildingEnvironmentConfig {
     stories?: readonly [number, number];
     storyHeight?: number;
     spacing?: number;
-    style?: string;
+    /** Named palette archetype (see `BUILDING_STYLE_PALETTES` in `world/buildings`); default "generic". Overridden part-by-part by `palette`. */
+    style?: BuildingStyle;
+    /** Explicit per-part-kind hex colors; any part left unset falls back to the resolved `style` palette. */
+    palette?: BuildingPaletteOverrides;
     seed?: string;
 }
 export type PadSize = readonly [number, number] | {
@@ -103,8 +217,10 @@ export type PadSize = readonly [number, number] | {
 export interface PadEnvironmentConfig {
     center: EnvironmentVec2;
     size: PadSize;
-    /** Surface offset above the terrain height at `center`; default `0.05` — just proud of the ground. */
+    /** Surface offset above the terrain height at `center`; default `0.05` — just proud of the ground. Ignored when `elevation` is set. */
     height?: number;
+    /** Absolute world-space Y for the pad surface — a landing pad on a rooftop, a floating platform. Skips the implicit terrain flatten (there's no ground to flatten toward). */
+    elevation?: number;
     color?: string;
     /** Rotation applied to rectangular pads; ignored for circular pads. */
     rotationY?: number;
@@ -112,6 +228,15 @@ export interface PadEnvironmentConfig {
 export type TerrainEnvironmentDescriptor = {
     kind: "terrain";
 } & Required<Pick<TerrainEnvironmentConfig, "bounds" | "height">> & Omit<TerrainEnvironmentConfig, "bounds" | "height">;
+/** A bounded terrain patch floating at its own altitude — sky islands, arena platforms, split landmasses with void between. */
+export interface TerrainIslandConfig extends TerrainEnvironmentConfig {
+    /** World-space center of the island; its `bounds` rect surrounds this point. */
+    origin: EnvironmentVec2;
+}
+export type TerrainIslandDescriptor = Omit<TerrainEnvironmentDescriptor, "kind"> & {
+    kind: "island";
+    origin: EnvironmentVec2;
+};
 export type RainEnvironmentDescriptor = {
     kind: "rain";
 } & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color">>;
@@ -123,16 +248,46 @@ export type GrassEnvironmentDescriptor = {
 } & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
 export type OceanEnvironmentDescriptor = {
     kind: "ocean";
-} & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position">;
+} & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
-} & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY">;
+} & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;
 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;
@@ -140,22 +295,28 @@ export type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor;
 export type EnvironmentDescriptorList<T> = T | readonly T[];
 export interface EnvironmentWorldConfig {
     terrain?: TerrainEnvironmentDescriptor;
+    /** Disconnected landmasses at independent altitudes over the base `terrain` (or over void without one) — see `island()`. */
+    islands?: readonly TerrainIslandDescriptor[];
     sky?: SkyEnvironmentDescriptor;
     weather?: EnvironmentDescriptorList<WeatherEnvironmentDescriptor>;
     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[];
 }
 export interface EnvironmentWorldFeature {
     kind: "environment";
     terrain?: TerrainEnvironmentDescriptor;
+    islands?: readonly TerrainIslandDescriptor[];
     sky?: SkyEnvironmentDescriptor;
     weather?: readonly WeatherEnvironmentDescriptor[];
     vegetation?: readonly VegetationEnvironmentDescriptor[];
     water?: readonly WaterEnvironmentDescriptor[];
     structures?: readonly StructureEnvironmentDescriptor[];
+    roads?: readonly RoadEnvironmentDescriptor[];
     pads?: readonly PadEnvironmentDescriptor[];
 }
 export interface WorldGridCell {
@@ -195,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) | ({
@@ -206,19 +368,34 @@ export type WorldFeature = ({
 } & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
-/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. */
+/** 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

@@ -7,9 +7,11 @@ function list(value) {
 function withOptional(base, optional) {
     return optional === undefined ? base : { ...base, ...optional };
 }
-/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. */
+/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. Elevated pads (absolute `elevation`) float free and carve nothing. */
 export function padFlattenMasks(pads) {
-    return pads.map((padDescriptor) => ({
+    return pads
+        .filter((padDescriptor) => padDescriptor.elevation === undefined)
+        .map((padDescriptor) => ({
         center: padDescriptor.center,
         radius: padHalfExtent(padDescriptor.size) * 1.2,
     }));
@@ -25,32 +27,46 @@ 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",
         ...(terrainDescriptor === undefined ? {} : { terrain: terrainDescriptor }),
+        ...(config.islands === undefined || config.islands.length === 0 ? {} : { islands: config.islands }),
         ...(config.sky === undefined ? {} : { sky: config.sky }),
         ...(weather === undefined ? {} : { weather }),
         ...(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 &&
+        config.heightField === undefined &&
+        typeof console !== "undefined") {
+        console.warn("[jgengine:terrain] baseHeight is set but height is not — height is the noise amplitude (defaulting to 0 here), so this terrain is a flat plateau at baseHeight. Set height explicitly (height: 0 for an intentional plateau) to silence this.");
+    }
     return withOptional({
         kind: "terrain",
         bounds: config.bounds ?? { w: 512, d: 512 },
         height: config.height ?? 0,
     }, {
         ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
+        ...(config.heightField === undefined ? {} : { heightField: config.heightField }),
         ...(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 }),
@@ -59,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 = {}) {
@@ -74,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,
@@ -85,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,
@@ -97,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,
@@ -108,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",
@@ -118,8 +142,33 @@ export function ocean(config = {}) {
         waveSpeed: config.waveSpeed ?? 0.55,
         color: config.color ?? "#1d7fa3",
         ...(config.position === undefined ? {} : { position: config.position }),
+        ...(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",
@@ -132,6 +181,7 @@ export function building(config = {}) {
     }, {
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.position === undefined ? {} : { position: config.position }),
+        ...(config.palette === undefined ? {} : { palette: config.palette }),
     });
 }
 export function pad(config) {
@@ -141,20 +191,28 @@ export function pad(config) {
         size: config.size,
         height: config.height ?? 0.05,
         color: config.color ?? "#8b8680",
-    }, config.rotationY === undefined ? undefined : { rotationY: config.rotationY });
+    }, {
+        ...(config.rotationY === undefined ? {} : { rotationY: config.rotationY }),
+        ...(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/gridInstances.d.ts

@@ -1,13 +1,12 @@
-import type { WorldGridConfig } from "./features.js";
+import type { WorldFeature, WorldGridCell, WorldGridConfig } from "./features.js";
 export interface GridInstanceTransform {
     position: readonly [number, number, number];
     scale: readonly [number, number, number];
     color: string;
 }
-/**
- * Pure cell→instance math for `biomes()`/`voxel()`/`plots()`/`tilemap()` world features: one
- * extruded box per declared cell, grounded at y=0 and centered on its cell in x/z. Consumed by
- * the shell's grid-world renderer so it can drive a single `THREE.InstancedMesh` without
- * duplicating this math per game.
- */
-export declare function resolveGridInstances(config: WorldGridConfig): readonly GridInstanceTransform[];
+type GridWorldFeature = Extract<WorldFeature, {
+    kind: "biomes" | "voxel" | "plots" | "tilemap";
+}>;
+export declare function resolveGridCells(config: WorldGridConfig | GridWorldFeature): readonly WorldGridCell[];
+export declare function resolveGridInstances(config: WorldGridConfig | GridWorldFeature): readonly GridInstanceTransform[];
+export {};