@jgengine/core 0.8.0 → 0.9.0

package/dist/world/buildings.js

@@ -33,6 +33,158 @@ export const DEFAULT_BUILDING_CONFIG = {
     probabilities: DEFAULT_PROBABILITIES,
     variants: DEFAULT_VARIANTS,
 };
+export const DEFAULT_BUILDING_STYLE = "generic";
+export const BUILDING_STYLE_PALETTES = {
+    generic: {
+        wall: "#83766a",
+        window: "#8ecae6",
+        awning: "#c2410c",
+        airConditioner: "#d4d4d8",
+        clothesline: "#facc15",
+        storefront: "#3f3f46",
+        shutter: "#52525b",
+        storeSign: "#f97316",
+        roof: "#57534e",
+        roofProp: "#14b8a6",
+        guardrail: "#a8a29e",
+        corner: "#6b6258",
+    },
+    capital: {
+        wall: "#cfc5ad",
+        window: "#33506e",
+        awning: "#7a1f2b",
+        airConditioner: "#b9b3a4",
+        clothesline: "#d9cfae",
+        storefront: "#4a3f33",
+        shutter: "#5d5647",
+        storeSign: "#d4af37",
+        roof: "#3b4252",
+        roofProp: "#8c7a4e",
+        guardrail: "#a89f88",
+        corner: "#b3a98d",
+    },
+    village: {
+        wall: "#b59e7a",
+        window: "#e9c46a",
+        awning: "#7f5539",
+        airConditioner: "#a8a29e",
+        clothesline: "#e07a5f",
+        storefront: "#5c4a36",
+        shutter: "#6e5a40",
+        storeSign: "#c8894a",
+        roof: "#8a5a3b",
+        roofProp: "#97724d",
+        guardrail: "#8f8271",
+        corner: "#8d7354",
+    },
+    desert: {
+        wall: "#c9a877",
+        window: "#3f6f6b",
+        awning: "#a3512e",
+        airConditioner: "#c9bfa8",
+        clothesline: "#d9b16f",
+        storefront: "#6e5233",
+        shutter: "#7d6140",
+        storeSign: "#b8742f",
+        roof: "#b5946a",
+        roofProp: "#9a7648",
+        guardrail: "#b09b77",
+        corner: "#a98c5d",
+    },
+    industrial: {
+        wall: "#6b7280",
+        window: "#9fb3c8",
+        awning: "#f97316",
+        airConditioner: "#9ca3af",
+        clothesline: "#eab308",
+        storefront: "#374151",
+        shutter: "#4b5563",
+        storeSign: "#f59e0b",
+        roof: "#374151",
+        roofProp: "#ef4444",
+        guardrail: "#d1d5db",
+        corner: "#52596b",
+    },
+    coastal: {
+        wall: "#e8e2d2",
+        window: "#7cc3d8",
+        awning: "#e76f51",
+        airConditioner: "#cfd8dc",
+        clothesline: "#f2cc8f",
+        storefront: "#35526b",
+        shutter: "#3a7ca5",
+        storeSign: "#ee6c4d",
+        roof: "#4f6d7a",
+        roofProp: "#62b6cb",
+        guardrail: "#c5ccc2",
+        corner: "#cfc5ab",
+    },
+    neon: {
+        wall: "#1b1b26",
+        window: "#22d3ee",
+        awning: "#ff2d95",
+        airConditioner: "#3f3f50",
+        clothesline: "#a78bfa",
+        storefront: "#12121a",
+        shutter: "#2a2a3a",
+        storeSign: "#f0abfc",
+        roof: "#14141d",
+        roofProp: "#34d399",
+        guardrail: "#52525f",
+        corner: "#24242f",
+    },
+    ruin: {
+        wall: "#6b6156",
+        window: "#1c1917",
+        awning: "#4a4238",
+        airConditioner: "#57534e",
+        clothesline: "#6b7f4f",
+        storefront: "#292524",
+        shutter: "#44403c",
+        storeSign: "#78716c",
+        roof: "#4a443e",
+        roofProp: "#6b7f4f",
+        guardrail: "#7c7268",
+        corner: "#57503f",
+    },
+    frontier: {
+        wall: "#7f5539",
+        window: "#d9ae62",
+        awning: "#6e3f1f",
+        airConditioner: "#8d8072",
+        clothesline: "#c98a5e",
+        storefront: "#4a3220",
+        shutter: "#5c3d26",
+        storeSign: "#b3702f",
+        roof: "#9c4a1a",
+        roofProp: "#7d6b52",
+        guardrail: "#937b5f",
+        corner: "#66492f",
+    },
+    aerial: {
+        wall: "#dfe7ec",
+        window: "#67c3cc",
+        awning: "#4d7ea8",
+        airConditioner: "#b8c4cc",
+        clothesline: "#9fd8df",
+        storefront: "#5c7684",
+        shutter: "#7b95a3",
+        storeSign: "#3aa7b8",
+        roof: "#aebcc4",
+        roofProp: "#e0f2f5",
+        guardrail: "#98a8b0",
+        corner: "#c3d0d7",
+    },
+};
+export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
+    const preset = BUILDING_STYLE_PALETTES[style];
+    if (preset === undefined) {
+        throw new Error(`Unknown building style "${style}". Valid styles: ${Object.keys(BUILDING_STYLE_PALETTES).join(", ")}. Use palette: { wall, window, ... } for a custom look.`);
+    }
+    if (overrides === undefined)
+        return preset;
+    return { ...preset, ...overrides };
+}
 function hashU32(input) {
     let hash = 2166136261;
     for (let index = 0; index < input.length; index += 1) {

package/dist/world/carve.d.ts

@@ -95,11 +95,16 @@ export declare class CarvableField implements TerrainField {
     readonly sampleNormal: TerrainField["sampleNormal"];
     private readonly base;
     private readonly edits;
+    private nextEditId;
     constructor(base: TerrainField);
     get editCount(): number;
     sampleHeight(x: number, z: number): number;
-    carve(op: CraterOp): void;
-    deposit(op: MoundOp): void;
+    /** Digs a bowl; the returned id undoes just this crater via `removeEdit` (#284.7). */
+    carve(op: CraterOp): number;
+    /** Raises a mound; the returned id undoes just this mound via `removeEdit` (#284.7). */
+    deposit(op: MoundOp): number;
+    /** Removes one edit by the id `carve`/`deposit` returned — capped-history destructibles evict without rebuilding the field. */
+    removeEdit(editId: number): boolean;
     clear(): void;
 }
 export declare function carvableTerrain(base: TerrainField): CarvableField;

package/dist/world/carve.js

@@ -135,7 +135,8 @@ export class CarvableField {
     waterLevel;
     sampleNormal;
     base;
-    edits = [];
+    edits = new Map();
+    nextEditId = 1;
     constructor(base) {
         this.base = base;
         if (base.bounds !== undefined)
@@ -145,12 +146,11 @@ export class CarvableField {
         this.sampleNormal = withNormal((x, z) => this.sampleHeight(x, z));
     }
     get editCount() {
-        return this.edits.length;
+        return this.edits.size;
     }
     sampleHeight(x, z) {
         let h = this.base.sampleHeight(x, z);
-        for (let i = 0; i < this.edits.length; i += 1) {
-            const e = this.edits[i];
+        for (const e of this.edits.values()) {
             const dx = x - e.x;
             const dz = z - e.z;
             const d = Math.sqrt(dx * dx + dz * dz);
@@ -160,14 +160,24 @@ export class CarvableField {
         }
         return h;
     }
+    /** Digs a bowl; the returned id undoes just this crater via `removeEdit` (#284.7). */
     carve(op) {
-        this.edits.push({ x: op.x, z: op.z, radius: op.radius, delta: -op.depth });
+        const id = this.nextEditId++;
+        this.edits.set(id, { x: op.x, z: op.z, radius: op.radius, delta: -op.depth });
+        return id;
     }
+    /** Raises a mound; the returned id undoes just this mound via `removeEdit` (#284.7). */
     deposit(op) {
-        this.edits.push({ x: op.x, z: op.z, radius: op.radius, delta: op.height });
+        const id = this.nextEditId++;
+        this.edits.set(id, { x: op.x, z: op.z, radius: op.radius, delta: op.height });
+        return id;
+    }
+    /** Removes one edit by the id `carve`/`deposit` returned — capped-history destructibles evict without rebuilding the field. */
+    removeEdit(editId) {
+        return this.edits.delete(editId);
     }
     clear() {
-        this.edits.length = 0;
+        this.edits.clear();
     }
 }
 export function carvableTerrain(base) {

package/dist/world/cellStates.d.ts

@@ -0,0 +1,45 @@
+export interface CellStateGridConfig<TState extends string> {
+    cols: number;
+    rows: number;
+    /** The ordered escalation ladder; every cell starts at `states[0]`. */
+    states: readonly TState[];
+    /** World-space center of cell (0, 0), for `cellOf` world→cell mapping. Default `[0, 0]`. */
+    origin?: readonly [number, number];
+    /** World units per cell, for `cellOf`. Default `1`. */
+    cellSize?: number;
+}
+export interface CellRef {
+    col: number;
+    row: number;
+}
+/**
+ * A uniform world grid whose cells step through a discrete state ladder — pristine → cracked →
+ * burning → ruined — driven by whatever world events the game routes in (#284.8). Pure storage plus
+ * ladder mechanics; the game decides *when* to escalate, the grid guarantees ordered, clamped steps
+ * and cheap queries. `version()` bumps on every change for dirty-checked rendering.
+ */
+export interface CellStateGrid<TState extends string> {
+    readonly cols: number;
+    readonly rows: number;
+    readonly states: readonly TState[];
+    stateAt(col: number, row: number): TState | null;
+    /** Ladder index at a cell; `-1` outside the grid. */
+    indexAt(col: number, row: number): number;
+    /** Step a cell up the ladder (clamped at the last state); returns the new state or `null` outside the grid. */
+    escalate(col: number, row: number, steps?: number): TState | null;
+    /** Step a cell back down (clamped at the first state). */
+    regress(col: number, row: number, steps?: number): TState | null;
+    set(col: number, row: number, state: TState): boolean;
+    /** Escalate every cell the predicate matches; returns how many changed. */
+    escalateWhere(predicate: (col: number, row: number, state: TState) => boolean, steps?: number): number;
+    cellsIn(state: TState): CellRef[];
+    counts(): Record<TState, number>;
+    /** World position → cell, using `origin`/`cellSize`; `null` outside the grid. */
+    cellOf(x: number, z: number): CellRef | null;
+    /** World-space center of a cell. */
+    centerOf(col: number, row: number): readonly [number, number];
+    /** Bumps on every state change — key re-renders/dirty checks off it. */
+    version(): number;
+    reset(): void;
+}
+export declare function createCellStateGrid<TState extends string>(config: CellStateGridConfig<TState>): CellStateGrid<TState>;

package/dist/world/cellStates.js

@@ -0,0 +1,103 @@
+export function createCellStateGrid(config) {
+    if (config.states.length === 0)
+        throw new Error("cell state grid needs at least one state");
+    if (!(config.cols > 0) || !(config.rows > 0)) {
+        throw new Error(`cell state grid needs positive dimensions, got ${config.cols}x${config.rows}`);
+    }
+    const stateIndex = new Map();
+    config.states.forEach((state, index) => {
+        if (stateIndex.has(state))
+            throw new Error(`duplicate cell state: ${state}`);
+        stateIndex.set(state, index);
+    });
+    const [originX, originZ] = config.origin ?? [0, 0];
+    const cellSize = config.cellSize ?? 1;
+    const cells = new Int32Array(config.cols * config.rows);
+    let version = 0;
+    function inBounds(col, row) {
+        return Number.isInteger(col) && Number.isInteger(row) && col >= 0 && col < config.cols && row >= 0 && row < config.rows;
+    }
+    function indexOf(col, row) {
+        return row * config.cols + col;
+    }
+    function step(col, row, steps) {
+        if (!inBounds(col, row))
+            return null;
+        const at = indexOf(col, row);
+        const next = Math.max(0, Math.min(config.states.length - 1, cells[at] + steps));
+        if (next !== cells[at]) {
+            cells[at] = next;
+            version += 1;
+        }
+        return config.states[next];
+    }
+    return {
+        cols: config.cols,
+        rows: config.rows,
+        states: config.states,
+        stateAt: (col, row) => (inBounds(col, row) ? config.states[cells[indexOf(col, row)]] : null),
+        indexAt: (col, row) => (inBounds(col, row) ? cells[indexOf(col, row)] : -1),
+        escalate: (col, row, steps = 1) => step(col, row, Math.max(0, steps)),
+        regress: (col, row, steps = 1) => step(col, row, -Math.max(0, steps)),
+        set(col, row, state) {
+            const target = stateIndex.get(state);
+            if (target === undefined || !inBounds(col, row))
+                return false;
+            const at = indexOf(col, row);
+            if (cells[at] !== target) {
+                cells[at] = target;
+                version += 1;
+            }
+            return true;
+        },
+        escalateWhere(predicate, steps = 1) {
+            let changed = 0;
+            for (let row = 0; row < config.rows; row += 1) {
+                for (let col = 0; col < config.cols; col += 1) {
+                    const at = indexOf(col, row);
+                    if (!predicate(col, row, config.states[cells[at]]))
+                        continue;
+                    const next = Math.min(config.states.length - 1, cells[at] + Math.max(0, steps));
+                    if (next !== cells[at]) {
+                        cells[at] = next;
+                        changed += 1;
+                    }
+                }
+            }
+            if (changed > 0)
+                version += 1;
+            return changed;
+        },
+        cellsIn(state) {
+            const target = stateIndex.get(state);
+            const refs = [];
+            if (target === undefined)
+                return refs;
+            for (let row = 0; row < config.rows; row += 1) {
+                for (let col = 0; col < config.cols; col += 1) {
+                    if (cells[indexOf(col, row)] === target)
+                        refs.push({ col, row });
+                }
+            }
+            return refs;
+        },
+        counts() {
+            const result = Object.fromEntries(config.states.map((state) => [state, 0]));
+            for (let at = 0; at < cells.length; at += 1) {
+                result[config.states[cells[at]]] += 1;
+            }
+            return result;
+        },
+        cellOf(x, z) {
+            const col = Math.round((x - originX) / cellSize);
+            const row = Math.round((z - originZ) / cellSize);
+            return inBounds(col, row) ? { col, row } : null;
+        },
+        centerOf: (col, row) => [originX + col * cellSize, originZ + row * cellSize],
+        version: () => version,
+        reset() {
+            cells.fill(0);
+            version += 1;
+        },
+    };
+}

package/dist/world/environmentSummary.d.ts

@@ -1,6 +1,7 @@
-import { type GeneratedBuilding } from "./buildings.js";
+import { type BuildingPalette, type BuildingStyle, type GeneratedBuilding } from "./buildings.js";
 import type { BuildingEnvironmentDescriptor, EnvironmentWorldFeature, WorldBounds } from "./features.js";
 import type { Aabb } from "./geometry.js";
+import { type TerrainPalette } from "./terrain.js";
 export declare function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[];
 export interface TerrainHeightStats {
     min: number;
@@ -11,10 +12,12 @@ export interface TerrainHeightStats {
 export interface TerrainSummary {
     bounds: WorldBounds;
     height: TerrainHeightStats;
+    palette: TerrainPalette;
     waterLevel?: number;
 }
 export interface StructureSummary {
-    style: string;
+    style: BuildingStyle;
+    palette: BuildingPalette;
     requested: number;
     buildings: number;
     parts: number;
@@ -34,6 +37,7 @@ export interface WeatherSummary {
 }
 export interface EnvironmentCounts {
     terrain: number;
+    islands: number;
     structureGroups: number;
     buildings: number;
     buildingParts: number;
@@ -41,8 +45,12 @@ export interface EnvironmentCounts {
     waterBodies: number;
     weatherSystems: number;
 }
+export interface IslandSummary extends TerrainSummary {
+    origin: readonly [number, number];
+}
 export interface EnvironmentSummary {
     terrain?: TerrainSummary;
+    islands: readonly IslandSummary[];
     structures: readonly StructureSummary[];
     vegetation: readonly VegetationSummary[];
     water: readonly WaterSummary[];

package/dist/world/environmentSummary.js

@@ -1,5 +1,5 @@
-import { generateBuildingDistrict } from "./buildings.js";
-import { resolveTerrainField } from "./terrain.js";
+import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
     const rows = Math.max(1, Math.ceil(descriptor.count / columns));
@@ -74,6 +74,7 @@ function summarizeStructures(descriptor) {
     const buildings = resolveStructureBuildings(descriptor);
     return {
         style: descriptor.style,
+        palette: resolveBuildingPalette(descriptor.style, descriptor.palette),
         requested: descriptor.count,
         buildings: buildings.length,
         parts: buildings.reduce((sum, building) => sum + building.parts.length, 0),
@@ -84,11 +85,16 @@ function summarizeTerrain(descriptor) {
     return {
         bounds: descriptor.bounds,
         height: sampleTerrainHeights(descriptor),
+        palette: resolveTerrainPalette(descriptor),
         ...(descriptor.waterLevel === undefined ? {} : { waterLevel: descriptor.waterLevel }),
     };
 }
 export function summarizeEnvironment(feature) {
     const terrain = feature.terrain === undefined ? undefined : summarizeTerrain(feature.terrain);
+    const islands = (feature.islands ?? []).map((entry) => ({
+        ...summarizeTerrain({ ...entry, kind: "terrain" }),
+        origin: entry.origin,
+    }));
     const structures = (feature.structures ?? []).map(summarizeStructures);
     const vegetation = (feature.vegetation ?? []).map((entry) => ({
         area: entry.area,
@@ -105,6 +111,7 @@ export function summarizeEnvironment(feature) {
     const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
     const counts = {
         terrain: terrain === undefined ? 0 : 1,
+        islands: islands.length,
         structureGroups: structures.length,
         buildings,
         buildingParts: structures.reduce((sum, entry) => sum + entry.parts, 0),
@@ -113,12 +120,14 @@ export function summarizeEnvironment(feature) {
         weatherSystems: weather.length,
     };
     const isEmpty = counts.terrain === 0 &&
+        counts.islands === 0 &&
         buildings === 0 &&
         counts.vegetationFields === 0 &&
         counts.waterBodies === 0 &&
         counts.weatherSystems === 0;
     return {
         ...(terrain === undefined ? {} : { terrain }),
+        islands,
         structures,
         vegetation,
         water,

package/dist/world/features.d.ts

@@ -1,10 +1,14 @@
+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;
@@ -19,14 +23,32 @@ 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;
+    /** 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`. */
+    falloff?: number;
+}
 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[];
     segments?: number;
     seed?: string;
     frequency?: number;
@@ -55,7 +77,7 @@ export interface SnowEnvironmentConfig {
     color?: string;
 }
 export interface GrassEnvironmentConfig {
-    area?: WorldBounds;
+    area?: EnvironmentArea;
     density?: number;
     bladeHeight?: readonly [number, number];
     bladeWidth?: number;
@@ -67,7 +89,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 +124,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 +136,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 +147,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,13 +167,13 @@ 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">;
@@ -140,6 +184,8 @@ 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>;
@@ -151,6 +197,7 @@ export interface EnvironmentWorldConfig {
 export interface EnvironmentWorldFeature {
     kind: "environment";
     terrain?: TerrainEnvironmentDescriptor;
+    islands?: readonly TerrainIslandDescriptor[];
     sky?: SkyEnvironmentDescriptor;
     weather?: readonly WeatherEnvironmentDescriptor[];
     vegetation?: readonly VegetationEnvironmentDescriptor[];
@@ -206,7 +253,7 @@ 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[];
 export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
 export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
@@ -215,6 +262,7 @@ export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDes
 export declare function snow(config?: SnowEnvironmentConfig): SnowEnvironmentDescriptor;
 export declare function grass(config?: GrassEnvironmentConfig): GrassEnvironmentDescriptor;
 export declare function ocean(config?: OceanEnvironmentConfig): OceanEnvironmentDescriptor;
+export declare function island(config: TerrainIslandConfig): TerrainIslandDescriptor;
 export declare function building(config?: BuildingEnvironmentConfig): BuildingEnvironmentDescriptor;
 export declare function pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor;
 export declare function biomes(config: BiomesWorldConfig): WorldFeature;