@jgengine/core 0.8.0 → 0.9.0

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,
     }));
@@ -34,6 +36,7 @@ export function environment(config = {}) {
     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 }),
@@ -43,14 +46,22 @@ export function environment(config = {}) {
     };
 }
 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 }),
@@ -118,8 +129,14 @@ 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 }),
     };
 }
+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",
@@ -132,6 +149,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,7 +159,10 @@ 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 }),
+    });
 }
 export function biomes(config) {
     return { kind: "biomes", ...config };

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 {};

package/dist/world/gridInstances.js

@@ -1,14 +1,152 @@
+import { seedFrom, valueNoise } from "./terrain.js";
 const DEFAULT_CELL_SIZE = 1;
 const DEFAULT_BASE_HEIGHT = 1;
 const DEFAULT_GRID_COLOR = "#8a8f98";
-/**
- * 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.
- */
+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 = config.cells ?? [];
+    const cells = resolveGridCells(config);
     const cellSize = config.cellSize ?? DEFAULT_CELL_SIZE;
     const defaultColor = config.defaultColor ?? DEFAULT_GRID_COLOR;
     return cells.map((cell) => {

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;
+        },
+    };
+}

package/dist/world/mapLayers.d.ts

@@ -0,0 +1,60 @@
+export type MapXZ = readonly [number, number];
+export type MapLayerTone = "danger" | "warning" | "info" | "safe" | "neutral";
+export interface MapRoute {
+    id: string;
+    /** World-XZ polyline. */
+    points: readonly MapXZ[];
+    tone?: MapLayerTone;
+    /** Dashed rendering — a planned/forecast route rather than a live one. */
+    forecast?: boolean;
+    /** Line width in map pixels; default `2`. */
+    width?: number;
+    /** Close the polyline back to its first point (patrol loops). */
+    closed?: boolean;
+}
+export type MapZoneShape = {
+    kind: "circle";
+    center: MapXZ;
+    radius: number;
+} | {
+    kind: "rect";
+    center: MapXZ;
+    w: number;
+    d: number;
+    rotate?: number;
+} | {
+    kind: "polygon";
+    points: readonly MapXZ[];
+};
+export interface MapZone {
+    id: string;
+    shape: MapZoneShape;
+    tone?: MapLayerTone;
+    /** Fill opacity in `[0, 1]`; default `0.25`. */
+    opacity?: number;
+    /** Dashed outline + no fill — the previewed future state (storm's next ring, incoming hazard band). */
+    forecast?: boolean;
+    label?: string;
+}
+export interface MapCellStates {
+    id: string;
+    /** World-space center of cell (0, 0). */
+    origin: MapXZ;
+    cellSize: number;
+    /** Sparse cell statuses — pair with `world/cellStates`' `cellsIn`/`counts` output. */
+    cells: readonly {
+        col: number;
+        row: number;
+        tone: MapLayerTone;
+        opacity?: number;
+    }[];
+}
+/**
+ * Renderer-free overlay data for map surfaces (#285.1-2): zones with live + forecast states,
+ * route polylines, and per-cell status heatmaps. `@jgengine/react/map`'s `Minimap`/`WorldMap`
+ * take these straight in; `pointInMapZone` answers gameplay queries against the same data,
+ * so the HUD and the rules can never disagree about where the storm is.
+ */
+export declare function pointInMapZone(zone: MapZoneShape, x: number, z: number): boolean;
+export declare const MAP_LAYER_TONE_COLORS: Record<MapLayerTone, string>;
+export declare function mapLayerColor(tone: MapLayerTone | undefined): string;

package/dist/world/mapLayers.js

@@ -0,0 +1,44 @@
+/**
+ * Renderer-free overlay data for map surfaces (#285.1-2): zones with live + forecast states,
+ * route polylines, and per-cell status heatmaps. `@jgengine/react/map`'s `Minimap`/`WorldMap`
+ * take these straight in; `pointInMapZone` answers gameplay queries against the same data,
+ * so the HUD and the rules can never disagree about where the storm is.
+ */
+export function pointInMapZone(zone, x, z) {
+    if (zone.kind === "circle") {
+        return Math.hypot(x - zone.center[0], z - zone.center[1]) <= zone.radius;
+    }
+    if (zone.kind === "rect") {
+        let dx = x - zone.center[0];
+        let dz = z - zone.center[1];
+        if (zone.rotate !== undefined && zone.rotate !== 0) {
+            const cos = Math.cos(-zone.rotate);
+            const sin = Math.sin(-zone.rotate);
+            const rx = dx * cos - dz * sin;
+            const rz = dx * sin + dz * cos;
+            dx = rx;
+            dz = rz;
+        }
+        return Math.abs(dx) <= zone.w / 2 && Math.abs(dz) <= zone.d / 2;
+    }
+    const points = zone.points;
+    let inside = false;
+    for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+        const [xi, zi] = points[i];
+        const [xj, zj] = points[j];
+        const crosses = zi > z !== zj > z && x < ((xj - xi) * (z - zi)) / (zj - zi) + xi;
+        if (crosses)
+            inside = !inside;
+    }
+    return inside;
+}
+export const MAP_LAYER_TONE_COLORS = {
+    danger: "#ef4444",
+    warning: "#f59e0b",
+    info: "#38bdf8",
+    safe: "#4ade80",
+    neutral: "#a1a1aa",
+};
+export function mapLayerColor(tone) {
+    return MAP_LAYER_TONE_COLORS[tone ?? "neutral"];
+}

package/dist/world/massing.d.ts

@@ -0,0 +1,45 @@
+export type MassingComposition = "bar" | "split" | "cluster" | "stack" | "court" | "bridge" | "ring" | "capsule" | "megastructure";
+export declare const MASSING_COMPOSITIONS: readonly MassingComposition[];
+export type MassingProfile = "straight" | "stepped" | "tapered" | "top-heavy" | "offset" | "twisted";
+export declare const MASSING_PROFILES: readonly MassingProfile[];
+export type MassingSpec = {
+    seed: string;
+    width: number;
+    height: number;
+    depth: number;
+    floorHeight: number;
+    baySpacing: number;
+    pilotis: number;
+    podiumHeight: number;
+    cores: number;
+    terraces: number;
+    cantilever: number;
+    voids: number;
+    taper: number;
+    articulation: number;
+    crown: number;
+    moduleDensity: number;
+    branches: number;
+    composition: MassingComposition;
+    profile: MassingProfile;
+};
+export type MassingBodyRole = "mass" | "core" | "transfer";
+export type MassingBody = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    h: number;
+    d: number;
+    ry?: number;
+    facade?: boolean;
+    kind?: "box" | "capsule";
+    role?: MassingBodyRole;
+    branch?: boolean;
+    crown?: boolean;
+};
+export declare const hashMassingSeed: (text: string) => number;
+export declare const massingBase: (spec: Pick<MassingSpec, "pilotis" | "height">, cap?: number) => number;
+export declare const isVillageMassing: (spec: Pick<MassingSpec, "composition" | "height" | "articulation" | "moduleDensity">) => boolean;
+export declare function massingFloorCount(spec: Pick<MassingSpec, "pilotis" | "height" | "floorHeight">): number;
+export declare function composeMassing(b: MassingSpec): MassingBody[];