@jgengine/core 0.7.0 → 0.9.0

package/dist/world/features.d.ts

@@ -1,22 +1,63 @@
+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;
+}
+export interface TerrainFlattenMask {
+    center: EnvironmentVec2;
+    radius: number;
+    /** Target flat height; defaults to the noise field's height at `center`. */
+    height?: number;
+    /** 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;
-    material?: 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?: 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;
     octaves?: number;
     ridged?: boolean;
     baseHeight?: number;
     waterLevel?: number;
+    /** Flat pads carved into the noise field, e.g. for building pads or spawn circles. */
+    flatten?: readonly TerrainFlattenMask[];
 }
 export interface RainEnvironmentConfig {
     area?: EnvironmentArea;
@@ -36,7 +77,7 @@ export interface SnowEnvironmentConfig {
     color?: string;
 }
 export interface GrassEnvironmentConfig {
-    area?: WorldBounds;
+    area?: EnvironmentArea;
     density?: number;
     bladeHeight?: readonly [number, number];
     bladeWidth?: number;
@@ -46,24 +87,75 @@ export interface GrassEnvironmentConfig {
 }
 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;
 }
+export interface SkyEnvironmentConfig {
+    /** Fixed look used when `timeOfDay` is off (or no clock is available); default "day". */
+    preset?: "day" | "dusk" | "night";
+    /** Drive sun/sky from the world clock's `calendar().dayFraction` instead of the fixed `preset`. */
+    timeOfDay?: boolean;
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+    fog?: {
+        color?: string;
+        near?: number;
+        far?: number;
+    };
+}
 export interface BuildingEnvironmentConfig {
     count?: number;
+    position?: EnvironmentVec2;
     footprint?: WorldBounds;
     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] | {
+    radius: number;
+};
+export interface PadEnvironmentConfig {
+    center: EnvironmentVec2;
+    size: PadSize;
+    /** 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;
+}
 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">>;
@@ -75,10 +167,16 @@ 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">>;
+} & 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">;
+} & 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" | "elevation">;
+export type SkyEnvironmentDescriptor = {
+    kind: "sky";
+} & Required<Pick<SkyEnvironmentConfig, "preset" | "timeOfDay">> & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay">;
 export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
 export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;
 export type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor;
@@ -86,36 +184,62 @@ 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>;
+    /** 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[];
+    pads?: readonly PadEnvironmentDescriptor[];
+}
+export interface WorldGridCell {
+    x: number;
+    z: number;
+    /** Extruded box height for this cell; falls back to the config's `baseHeight`, then `1`. */
+    height?: number;
+    /** Per-cell tint; falls back to the config's `defaultColor`. */
+    color?: string;
+}
+/** Shared by `biomes()`/`voxel()`/`plots()`/`tilemap()` so the shell can render their declared content as instanced boxes without a hand-written renderer. */
+export interface WorldGridConfig {
+    cells?: readonly WorldGridCell[];
+    /** World-unit size of one grid cell. Default 1. */
+    cellSize?: number;
+    /** Height used for cells that omit their own `height`. Default 1. */
+    baseHeight?: number;
+    /** Color used for cells that omit their own `color`. */
+    defaultColor?: string;
 }
-export interface BiomesWorldConfig {
+export interface BiomesWorldConfig extends WorldGridConfig {
     map: string;
     zones: string;
     bounds?: WorldBounds;
 }
-export interface VoxelWorldConfig {
+export interface VoxelWorldConfig extends WorldGridConfig {
     seed: string;
     generate?: string;
     streaming?: {
         radius: number;
     };
 }
-export interface PlotsWorldConfig {
+export interface PlotsWorldConfig extends WorldGridConfig {
     city?: string;
     interiors?: string;
 }
-export interface TilemapWorldConfig {
+export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
 }
 export type WorldFeature = ({
@@ -129,13 +253,18 @@ export type WorldFeature = ({
 } & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
+/** 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;
+export declare function sky(config?: SkyEnvironmentConfig): SkyEnvironmentDescriptor;
 export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
 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;
 export declare function voxel(config: VoxelWorldConfig): WorldFeature;
 export declare function plots(config?: PlotsWorldConfig): WorldFeature;

package/dist/world/features.js

@@ -7,34 +7,82 @@ 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. Elevated pads (absolute `elevation`) float free and carve nothing. */
+export function padFlattenMasks(pads) {
+    return pads
+        .filter((padDescriptor) => padDescriptor.elevation === undefined)
+        .map((padDescriptor) => ({
+        center: padDescriptor.center,
+        radius: padHalfExtent(padDescriptor.size) * 1.2,
+    }));
+}
+function padHalfExtent(size) {
+    return "radius" in size ? size.radius : Math.max(size[0], size[1]) / 2;
+}
+function withPadFlatten(terrainDescriptor, pads) {
+    if (terrainDescriptor === undefined || pads === undefined || pads.length === 0)
+        return terrainDescriptor;
+    return {
+        ...terrainDescriptor,
+        flatten: [...(terrainDescriptor.flatten ?? []), ...padFlattenMasks(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 terrainDescriptor = withPadFlatten(config.terrain, config.pads);
     return {
         kind: "environment",
-        ...(config.terrain === undefined ? {} : { terrain: config.terrain }),
+        ...(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 }),
+        ...(config.pads === undefined ? {} : { pads: config.pads }),
     };
 }
 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.segments === undefined ? {} : { segments: config.segments }),
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.frequency === undefined ? {} : { frequency: config.frequency }),
         ...(config.octaves === undefined ? {} : { octaves: config.octaves }),
         ...(config.ridged === undefined ? {} : { ridged: config.ridged }),
         ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
+        ...(config.flatten === undefined ? {} : { flatten: config.flatten }),
+    });
+}
+export function sky(config = {}) {
+    return withOptional({
+        kind: "sky",
+        preset: config.preset ?? "day",
+        timeOfDay: config.timeOfDay ?? false,
+    }, {
+        ...(config.horizonColor === undefined ? {} : { horizonColor: config.horizonColor }),
+        ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
+        ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
+        ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.fog === undefined ? {} : { fog: config.fog }),
     });
 }
 export function rain(config = {}) {
@@ -80,8 +128,15 @@ export function ocean(config = {}) {
         waveScale: config.waveScale ?? 18,
         waveSpeed: config.waveSpeed ?? 0.55,
         color: config.color ?? "#1d7fa3",
+        ...(config.position === undefined ? {} : { position: config.position }),
+        ...(config.levelAt === undefined ? {} : { levelAt: config.levelAt }),
     };
 }
+export function island(config) {
+    const { origin, ...terrainConfig } = config;
+    const { kind: _kind, ...descriptor } = terrain(terrainConfig);
+    return { ...descriptor, kind: "island", origin };
+}
 export function building(config = {}) {
     return withOptional({
         kind: "building",
@@ -91,7 +146,23 @@ export function building(config = {}) {
         storyHeight: config.storyHeight ?? 3,
         spacing: config.spacing ?? 2,
         style: config.style ?? "generic",
-    }, config.seed === undefined ? undefined : { seed: config.seed });
+    }, {
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.position === undefined ? {} : { position: config.position }),
+        ...(config.palette === undefined ? {} : { palette: config.palette }),
+    });
+}
+export function pad(config) {
+    return withOptional({
+        kind: "pad",
+        center: config.center,
+        size: config.size,
+        height: config.height ?? 0.05,
+        color: config.color ?? "#8b8680",
+    }, {
+        ...(config.rotationY === undefined ? {} : { rotationY: config.rotationY }),
+        ...(config.elevation === undefined ? {} : { elevation: config.elevation }),
+    });
 }
 export function biomes(config) {
     return { kind: "biomes", ...config };

package/dist/world/gridInstances.d.ts

@@ -0,0 +1,12 @@
+import type { WorldFeature, WorldGridCell, WorldGridConfig } from "./features.js";
+export interface GridInstanceTransform {
+    position: readonly [number, number, number];
+    scale: readonly [number, number, number];
+    color: string;
+}
+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 {};

package/dist/world/gridInstances.js

@@ -0,0 +1,160 @@
+import { seedFrom, valueNoise } from "./terrain.js";
+const DEFAULT_CELL_SIZE = 1;
+const DEFAULT_BASE_HEIGHT = 1;
+const DEFAULT_GRID_COLOR = "#8a8f98";
+const DEFAULT_VOXEL_RADIUS = 4;
+function looksLikeAssetPath(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (/^(?:\.\/|\.\.\/|\/|[A-Za-z]:[\\/])/.test(trimmed))
+        return true;
+    if (/\.(?:ts|tsx|js|jsx|json|png|jpe?g|webp|gif|bmp)$/i.test(trimmed))
+        return true;
+    return false;
+}
+function parseZoneTable(zones) {
+    const trimmed = zones.trim();
+    if (trimmed.startsWith("{")) {
+        const parsed = JSON.parse(trimmed);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("biomes zones JSON must be an object keyed by map characters");
+        }
+        const table = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "string") {
+                table[key] = { color: value };
+                continue;
+            }
+            if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                const entry = value;
+                table[key] = {
+                    ...(typeof entry.height === "number" ? { height: entry.height } : {}),
+                    ...(typeof entry.color === "string" ? { color: entry.color } : {}),
+                };
+                continue;
+            }
+            throw new Error(`biomes zones entry "${key}" must be a color string or { height?, color? }`);
+        }
+        return table;
+    }
+    throw new Error(`biomes zones must be inline JSON (e.g. {"#":{"height":2,"color":"#4a7"}}); asset path "${zones}" is not auto-loaded`);
+}
+function parseAsciiGrid(map, resolveCell) {
+    if (looksLikeAssetPath(map)) {
+        throw new Error(`grid-world map "${map}" looks like an asset path and is not auto-loaded — provide inline ASCII or explicit cells`);
+    }
+    const rows = map
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((row) => row.trimEnd())
+        .filter((row, index, all) => row.length > 0 || (index > 0 && index < all.length - 1));
+    const solidRows = rows.filter((row) => row.trim().length > 0);
+    if (solidRows.length === 0) {
+        throw new Error("grid-world map is empty — provide ASCII rows or explicit cells");
+    }
+    const width = Math.max(...solidRows.map((row) => row.length));
+    const cells = [];
+    for (let rowIndex = 0; rowIndex < solidRows.length; rowIndex += 1) {
+        const row = solidRows[rowIndex].padEnd(width, " ");
+        const z = rowIndex - Math.floor((solidRows.length - 1) / 2);
+        for (let colIndex = 0; colIndex < width; colIndex += 1) {
+            const glyph = row[colIndex] ?? " ";
+            if (glyph === " " || glyph === ".")
+                continue;
+            const x = colIndex - Math.floor((width - 1) / 2);
+            const cell = resolveCell(glyph, x, z);
+            if (cell !== null)
+                cells.push(cell);
+        }
+    }
+    if (cells.length === 0) {
+        throw new Error("grid-world map produced no solid cells — use non-space/non-dot glyphs or explicit cells");
+    }
+    return cells;
+}
+function parseTilemapCells(config) {
+    return parseAsciiGrid(config.map, (glyph, x, z) => {
+        if (glyph >= "1" && glyph <= "9")
+            return { x, z, height: Number(glyph) };
+        return { x, z };
+    });
+}
+function parseBiomeCells(config) {
+    if (looksLikeAssetPath(config.zones)) {
+        throw new Error(`biomes zones "${config.zones}" looks like an asset path and is not auto-loaded — provide inline JSON zones or explicit cells`);
+    }
+    const zones = parseZoneTable(config.zones);
+    return parseAsciiGrid(config.map, (glyph, x, z) => {
+        const zone = zones[glyph];
+        if (zone === undefined) {
+            throw new Error(`biomes map glyph "${glyph}" is missing from zones`);
+        }
+        return {
+            x,
+            z,
+            ...(zone.height === undefined ? {} : { height: zone.height }),
+            ...(zone.color === undefined ? {} : { color: zone.color }),
+        };
+    });
+}
+function generateVoxelCells(config) {
+    const radius = config.streaming?.radius ?? DEFAULT_VOXEL_RADIUS;
+    const seed = seedFrom(config.seed, 1337);
+    const cells = [];
+    for (let z = -radius; z <= radius; z += 1) {
+        for (let x = -radius; x <= radius; x += 1) {
+            const n = valueNoise(x * 0.37, z * 0.37, seed);
+            if (n < -0.15)
+                continue;
+            const height = Math.max(1, Math.round(1 + (n + 1) * 1.5));
+            const tone = Math.round(120 + n * 40);
+            cells.push({
+                x,
+                z,
+                height,
+                color: `#${tone.toString(16).padStart(2, "0")}${tone.toString(16).padStart(2, "0")}${tone.toString(16).padStart(2, "0")}`,
+            });
+        }
+    }
+    if (cells.length === 0) {
+        cells.push({ x: 0, z: 0, height: 1 });
+    }
+    return cells;
+}
+function resolvePlotsCells(config) {
+    if (config.city !== undefined || config.interiors !== undefined) {
+        throw new Error(`plots source fields require explicit cells until asset loading is supported (city=${config.city ?? "—"}, interiors=${config.interiors ?? "—"})`);
+    }
+    return config.cells ?? [];
+}
+export function resolveGridCells(config) {
+    if (config.cells !== undefined && config.cells.length > 0)
+        return config.cells;
+    if ("kind" in config) {
+        switch (config.kind) {
+            case "tilemap":
+                return parseTilemapCells(config);
+            case "biomes":
+                return parseBiomeCells(config);
+            case "voxel":
+                return generateVoxelCells(config);
+            case "plots":
+                return resolvePlotsCells(config);
+        }
+    }
+    return config.cells ?? [];
+}
+export function resolveGridInstances(config) {
+    const cells = resolveGridCells(config);
+    const cellSize = config.cellSize ?? DEFAULT_CELL_SIZE;
+    const defaultColor = config.defaultColor ?? DEFAULT_GRID_COLOR;
+    return cells.map((cell) => {
+        const height = cell.height ?? config.baseHeight ?? DEFAULT_BASE_HEIGHT;
+        return {
+            position: [cell.x * cellSize, height / 2, cell.z * cellSize],
+            scale: [cellSize, height, cellSize],
+            color: cell.color ?? defaultColor,
+        };
+    });
+}

package/dist/world/lod.d.ts

@@ -0,0 +1,17 @@
+export interface LodBand {
+    maxDistance: number;
+    interval: number;
+}
+export interface LodSchedulerConfig {
+    bands: readonly LodBand[];
+    beyondInterval?: number | null;
+    stagger?: boolean;
+}
+export interface LodScheduler {
+    bandIndex(distance: number): number;
+    step(id: string, distance: number, dtSeconds: number): number;
+    remove(id: string): void;
+    clear(): void;
+    size(): number;
+}
+export declare function createLodScheduler(config: LodSchedulerConfig): LodScheduler;

package/dist/world/lod.js

@@ -0,0 +1,66 @@
+const MAX_ACCUMULATED_SECONDS = 60;
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+export function createLodScheduler(config) {
+    const bands = [...config.bands].sort((a, b) => a.maxDistance - b.maxDistance);
+    const beyondInterval = config.beyondInterval ?? null;
+    const stagger = config.stagger ?? true;
+    const buckets = new Map();
+    function bandIndex(distance) {
+        for (let i = 0; i < bands.length; i++) {
+            if (distance <= bands[i].maxDistance)
+                return i;
+        }
+        return -1;
+    }
+    function effectiveInterval(band) {
+        return band === -1 ? beyondInterval : bands[band].interval;
+    }
+    function phaseOffset(id, interval) {
+        if (interval === null || interval <= 0)
+            return 0;
+        return (hashSeed(id) / 4294967296) * interval;
+    }
+    return {
+        bandIndex,
+        step(id, distance, dtSeconds) {
+            const interval = effectiveInterval(bandIndex(distance));
+            let bucket = buckets.get(id);
+            if (bucket === undefined) {
+                bucket = stagger ? phaseOffset(id, interval) : 0;
+            }
+            if (dtSeconds > 0) {
+                bucket = Math.min(MAX_ACCUMULATED_SECONDS, bucket + dtSeconds);
+            }
+            if (interval === null) {
+                buckets.set(id, bucket);
+                return 0;
+            }
+            if (interval <= 0) {
+                buckets.set(id, 0);
+                return bucket;
+            }
+            if (bucket >= interval) {
+                buckets.set(id, 0);
+                return bucket;
+            }
+            buckets.set(id, bucket);
+            return 0;
+        },
+        remove(id) {
+            buckets.delete(id);
+        },
+        clear() {
+            buckets.clear();
+        },
+        size() {
+            return buckets.size;
+        },
+    };
+}