@jgengine/core 0.8.0 → 0.10.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 { BuildingEnvironmentDescriptor, EnvironmentWorldFeature, WorldBounds } from "./features.js";
+import { type BuildingPalette, type BuildingStyle, type GeneratedBuilding } from "./buildings.js";
+import type { BuildingEnvironmentDescriptor, EnvironmentArea, EnvironmentWorldFeature, WorldBounds } from "./features.js";
 import type { Aabb } from "./geometry.js";
+import { type TerrainPalette } from "./terrain.js";
 export declare function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[];
 export interface TerrainHeightStats {
     min: number;
@@ -11,17 +12,19 @@ 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;
     bounds: Aabb;
 }
 export interface VegetationSummary {
-    area: WorldBounds;
+    area: EnvironmentArea;
     density: number;
 }
 export interface WaterSummary {
@@ -30,23 +33,37 @@ export interface WaterSummary {
 }
 export interface WeatherSummary {
     kind: "rain" | "snow";
+    area: EnvironmentArea;
     density: number;
 }
+/** One road descriptor's resolved footprint: vertex count, width, and total centerline length. */
+export interface RoadSummary {
+    points: number;
+    width: number;
+    length: number;
+}
 export interface EnvironmentCounts {
     terrain: number;
+    islands: number;
     structureGroups: number;
     buildings: number;
     buildingParts: number;
     vegetationFields: number;
     waterBodies: number;
     weatherSystems: number;
+    roads: 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[];
     weather: readonly WeatherSummary[];
+    roads: readonly RoadSummary[];
     counts: EnvironmentCounts;
     isEmpty: boolean;
 }

package/dist/world/environmentSummary.js

@@ -1,5 +1,6 @@
-import { generateBuildingDistrict } from "./buildings.js";
-import { resolveTerrainField } from "./terrain.js";
+import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { pathLength } from "./roads.js";
+import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
     const rows = Math.max(1, Math.ceil(descriptor.count / columns));
@@ -74,6 +75,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 +86,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,
@@ -100,29 +107,41 @@ export function summarizeEnvironment(feature) {
     }));
     const weather = (feature.weather ?? []).map((entry) => ({
         kind: entry.kind,
+        area: entry.area,
         density: entry.density,
     }));
+    const roads = (feature.roads ?? []).map((entry) => ({
+        points: entry.path.length,
+        width: entry.width,
+        length: pathLength(entry.path),
+    }));
     const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
     const counts = {
         terrain: terrain === undefined ? 0 : 1,
+        islands: islands.length,
         structureGroups: structures.length,
         buildings,
         buildingParts: structures.reduce((sum, entry) => sum + entry.parts, 0),
         vegetationFields: vegetation.length,
         waterBodies: water.length,
         weatherSystems: weather.length,
+        roads: roads.length,
     };
     const isEmpty = counts.terrain === 0 &&
+        counts.islands === 0 &&
         buildings === 0 &&
         counts.vegetationFields === 0 &&
         counts.waterBodies === 0 &&
-        counts.weatherSystems === 0;
+        counts.weatherSystems === 0 &&
+        counts.roads === 0;
     return {
         ...(terrain === undefined ? {} : { terrain }),
+        islands,
         structures,
         vegetation,
         water,
         weather,
+        roads,
         counts,
         isEmpty,
     };