@jgengine/core 0.6.0 → 0.8.0

package/dist/world/environmentSummary.js

@@ -0,0 +1,129 @@
+import { generateBuildingDistrict } from "./buildings.js";
+import { resolveTerrainField } 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));
+    const spacing = descriptor.spacing;
+    const [centerX, centerZ] = descriptor.position ?? [0, 0];
+    const origin = [
+        centerX - ((columns - 1) * (descriptor.footprint.w + spacing)) / 2,
+        centerZ - ((rows - 1) * (descriptor.footprint.d + spacing)) / 2,
+    ];
+    return generateBuildingDistrict({
+        rows,
+        columns,
+        origin,
+        lotSize: descriptor.footprint,
+        streetWidth: spacing,
+        floorRange: descriptor.stories,
+        base: { floorHeight: descriptor.storyHeight },
+        ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
+    }).slice(0, descriptor.count);
+}
+const TERRAIN_SAMPLE_RESOLUTION = 16;
+function sampleTerrainHeights(descriptor) {
+    const field = resolveTerrainField(descriptor);
+    const halfW = descriptor.bounds.w / 2;
+    const halfD = descriptor.bounds.d / 2;
+    const steps = TERRAIN_SAMPLE_RESOLUTION;
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    let finite = true;
+    for (let ix = 0; ix <= steps; ix += 1) {
+        for (let iz = 0; iz <= steps; iz += 1) {
+            const x = -halfW + (descriptor.bounds.w * ix) / steps;
+            const z = -halfD + (descriptor.bounds.d * iz) / steps;
+            const height = field.sampleHeight(x, z);
+            if (!Number.isFinite(height)) {
+                finite = false;
+                continue;
+            }
+            if (height < min)
+                min = height;
+            if (height > max)
+                max = height;
+            sum += height;
+        }
+    }
+    const count = (steps + 1) * (steps + 1);
+    if (!finite)
+        return { min: NaN, max: NaN, mean: NaN, finite: false };
+    return { min, max, mean: sum / count, finite: true };
+}
+function unionAabb(buildings) {
+    if (buildings.length === 0)
+        return { minX: 0, minZ: 0, maxX: 0, maxZ: 0 };
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const building of buildings) {
+        if (building.bounds.minX < minX)
+            minX = building.bounds.minX;
+        if (building.bounds.minZ < minZ)
+            minZ = building.bounds.minZ;
+        if (building.bounds.maxX > maxX)
+            maxX = building.bounds.maxX;
+        if (building.bounds.maxZ > maxZ)
+            maxZ = building.bounds.maxZ;
+    }
+    return { minX, minZ, maxX, maxZ };
+}
+function summarizeStructures(descriptor) {
+    const buildings = resolveStructureBuildings(descriptor);
+    return {
+        style: descriptor.style,
+        requested: descriptor.count,
+        buildings: buildings.length,
+        parts: buildings.reduce((sum, building) => sum + building.parts.length, 0),
+        bounds: unionAabb(buildings),
+    };
+}
+function summarizeTerrain(descriptor) {
+    return {
+        bounds: descriptor.bounds,
+        height: sampleTerrainHeights(descriptor),
+        ...(descriptor.waterLevel === undefined ? {} : { waterLevel: descriptor.waterLevel }),
+    };
+}
+export function summarizeEnvironment(feature) {
+    const terrain = feature.terrain === undefined ? undefined : summarizeTerrain(feature.terrain);
+    const structures = (feature.structures ?? []).map(summarizeStructures);
+    const vegetation = (feature.vegetation ?? []).map((entry) => ({
+        area: entry.area,
+        density: entry.density,
+    }));
+    const water = (feature.water ?? []).map((entry) => ({
+        level: entry.level,
+        bounds: entry.bounds,
+    }));
+    const weather = (feature.weather ?? []).map((entry) => ({
+        kind: entry.kind,
+        density: entry.density,
+    }));
+    const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
+    const counts = {
+        terrain: terrain === undefined ? 0 : 1,
+        structureGroups: structures.length,
+        buildings,
+        buildingParts: structures.reduce((sum, entry) => sum + entry.parts, 0),
+        vegetationFields: vegetation.length,
+        waterBodies: water.length,
+        weatherSystems: weather.length,
+    };
+    const isEmpty = counts.terrain === 0 &&
+        buildings === 0 &&
+        counts.vegetationFields === 0 &&
+        counts.waterBodies === 0 &&
+        counts.weatherSystems === 0;
+    return {
+        ...(terrain === undefined ? {} : { terrain }),
+        structures,
+        vegetation,
+        water,
+        weather,
+        counts,
+        isEmpty,
+    };
+}

package/dist/world/features.d.ts

@@ -6,17 +6,36 @@ export type EnvironmentVec2 = readonly [number, number];
 export interface EnvironmentArea extends WorldBounds {
     h?: number;
 }
+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;
+}
 export interface TerrainEnvironmentConfig {
     bounds?: WorldBounds;
     height?: number;
     heightMap?: string;
+    /** Named palette preset (see `TERRAIN_MATERIAL_PALETTES` in `world/terrain`); default "grass". Overridden field-by-field by `colors`. */
     material?: string;
+    /** Explicit low/high/waterline hex colors; any field left unset falls back to the resolved `material` preset. */
+    colors?: TerrainColors;
+    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;
@@ -46,14 +65,31 @@ export interface GrassEnvironmentConfig {
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
+    position?: EnvironmentVec2;
     level?: number;
     waveHeight?: number;
     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;
@@ -61,6 +97,18 @@ export interface BuildingEnvironmentConfig {
     style?: string;
     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. */
+    height?: 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">;
@@ -75,10 +123,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">;
 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">;
+export type PadEnvironmentDescriptor = {
+    kind: "pad";
+} & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY">;
+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 +140,59 @@ export type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor;
 export type EnvironmentDescriptorList<T> = T | readonly T[];
 export interface EnvironmentWorldConfig {
     terrain?: TerrainEnvironmentDescriptor;
+    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;
+    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 +206,17 @@ export type WorldFeature = ({
 } & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
+/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. */
+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 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,18 +7,39 @@ 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. */
+export function padFlattenMasks(pads) {
+    return pads.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.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 = {}) {
@@ -29,12 +50,28 @@ export function terrain(config = {}) {
     }, {
         ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
         ...(config.material === undefined ? {} : { material: config.material }),
+        ...(config.colors === undefined ? {} : { colors: config.colors }),
+        ...(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,6 +117,7 @@ export function ocean(config = {}) {
         waveScale: config.waveScale ?? 18,
         waveSpeed: config.waveSpeed ?? 0.55,
         color: config.color ?? "#1d7fa3",
+        ...(config.position === undefined ? {} : { position: config.position }),
     };
 }
 export function building(config = {}) {
@@ -91,7 +129,19 @@ 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 }),
+    });
+}
+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 ? undefined : { rotationY: config.rotationY });
 }
 export function biomes(config) {
     return { kind: "biomes", ...config };

package/dist/world/fog.d.ts

@@ -0,0 +1,40 @@
+export interface FogBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+export interface FogConfig {
+    bounds: FogBounds;
+    cellSize: number;
+    /** Cells revealed on construction (start-of-run known area). */
+    revealed?: readonly number[];
+}
+export interface FogCells {
+    cols: number;
+    rows: number;
+    minX: number;
+    minZ: number;
+    cellSize: number;
+    /** Row-major flags; index = row * cols + col. */
+    revealed: readonly boolean[];
+    revealedCount: number;
+}
+/**
+ * Reveal-on-event fog of war over a fixed grid. Walking (`revealAlong`) and
+ * digging/acting (`reveal`) clear cells; once revealed a cell stays revealed.
+ * Pure and renderer-free — the shell/react map draws `cells()`.
+ */
+export interface FogField {
+    reveal(x: number, z: number, radius?: number): number;
+    revealAlong(from: readonly [number, number], to: readonly [number, number], radius?: number): number;
+    isRevealed(x: number, z: number): boolean;
+    isRevealedCell(col: number, row: number): boolean;
+    revealedCount(): number;
+    cellCount(): number;
+    fraction(): number;
+    cells(): FogCells;
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createFogField(config: FogConfig): FogField;

package/dist/world/fog.js

@@ -0,0 +1,137 @@
+function clampInt(value, min, max) {
+    const rounded = Math.floor(value);
+    return rounded < min ? min : rounded > max ? max : rounded;
+}
+export function createFogField(config) {
+    const { minX, minZ, maxX, maxZ } = config.bounds;
+    const cellSize = config.cellSize;
+    if (cellSize <= 0)
+        throw new Error("createFogField: cellSize must be positive");
+    const cols = Math.max(1, Math.ceil((maxX - minX) / cellSize));
+    const rows = Math.max(1, Math.ceil((maxZ - minZ) / cellSize));
+    const total = cols * rows;
+    const revealed = new Array(total).fill(false);
+    let revealedCount = 0;
+    const listeners = new Set();
+    let snapshotCache = null;
+    function colOf(x) {
+        return clampInt((x - minX) / cellSize, 0, cols - 1);
+    }
+    function rowOf(z) {
+        return clampInt((z - minZ) / cellSize, 0, rows - 1);
+    }
+    function markCell(col, row) {
+        if (col < 0 || col >= cols || row < 0 || row >= rows)
+            return false;
+        const index = row * cols + col;
+        if (revealed[index])
+            return false;
+        revealed[index] = true;
+        revealedCount += 1;
+        return true;
+    }
+    function notify(changed) {
+        if (changed === 0)
+            return;
+        snapshotCache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function revealAt(x, z, radius) {
+        const centerCol = colOf(x);
+        const centerRow = rowOf(z);
+        let changed = markCell(centerCol, centerRow) ? 1 : 0;
+        if (radius <= 0)
+            return changed;
+        const span = Math.ceil(radius / cellSize);
+        const radiusSq = radius * radius;
+        for (let dr = -span; dr <= span; dr += 1) {
+            for (let dc = -span; dc <= span; dc += 1) {
+                if (dc === 0 && dr === 0)
+                    continue;
+                const cellX = minX + (centerCol + dc + 0.5) * cellSize;
+                const cellZ = minZ + (centerRow + dr + 0.5) * cellSize;
+                const dx = cellX - x;
+                const dz = cellZ - z;
+                if (dx * dx + dz * dz > radiusSq)
+                    continue;
+                if (markCell(centerCol + dc, centerRow + dr))
+                    changed += 1;
+            }
+        }
+        return changed;
+    }
+    if (config.revealed !== undefined) {
+        for (const index of config.revealed) {
+            if (index >= 0 && index < total && !revealed[index]) {
+                revealed[index] = true;
+                revealedCount += 1;
+            }
+        }
+        snapshotCache = null;
+    }
+    return {
+        reveal(x, z, radius = 0) {
+            const changed = revealAt(x, z, radius);
+            notify(changed);
+            return changed;
+        },
+        revealAlong(from, to, radius = cellSize) {
+            const dx = to[0] - from[0];
+            const dz = to[1] - from[1];
+            const distance = Math.hypot(dx, dz);
+            const steps = Math.max(1, Math.ceil(distance / cellSize));
+            let changed = 0;
+            for (let step = 0; step <= steps; step += 1) {
+                const t = step / steps;
+                changed += revealAt(from[0] + dx * t, from[1] + dz * t, radius);
+            }
+            notify(changed);
+            return changed;
+        },
+        isRevealed(x, z) {
+            return revealed[rowOf(z) * cols + colOf(x)] === true;
+        },
+        isRevealedCell(col, row) {
+            if (col < 0 || col >= cols || row < 0 || row >= rows)
+                return false;
+            return revealed[row * cols + col] === true;
+        },
+        revealedCount() {
+            return revealedCount;
+        },
+        cellCount() {
+            return total;
+        },
+        fraction() {
+            return total === 0 ? 0 : revealedCount / total;
+        },
+        cells() {
+            if (snapshotCache === null) {
+                snapshotCache = {
+                    cols,
+                    rows,
+                    minX,
+                    minZ,
+                    cellSize,
+                    revealed: revealed.slice(),
+                    revealedCount,
+                };
+            }
+            return snapshotCache;
+        },
+        reset() {
+            if (revealedCount === 0)
+                return;
+            revealed.fill(false);
+            revealedCount = 0;
+            notify(1);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/world/gridInstances.d.ts

@@ -0,0 +1,13 @@
+import type { 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[];

package/dist/world/gridInstances.js

@@ -0,0 +1,22 @@
+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.
+ */
+export function resolveGridInstances(config) {
+    const cells = config.cells ?? [];
+    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/markers.d.ts

@@ -0,0 +1,52 @@
+export type MarkerPosition = readonly [number, number, number];
+export interface MapMarker<TMeta = unknown> {
+    id: string;
+    kind: string;
+    position: MarkerPosition;
+    label?: string;
+    owner?: string;
+    createdAt: number;
+    expiresAt?: number;
+    meta?: TMeta;
+}
+export interface MarkerInput<TMeta = unknown> {
+    id?: string;
+    kind: string;
+    position: MarkerPosition;
+    label?: string;
+    owner?: string;
+    createdAt?: number;
+    expiresAt?: number;
+    meta?: TMeta;
+}
+export interface MarkerQuery {
+    kind?: string;
+    owner?: string;
+    near?: MarkerPosition;
+    radius?: number;
+}
+/**
+ * Visual descriptor for a marker kind. Games supply their own palette; the
+ * engine ships `DEFAULT_MARKER_KINDS` as a content-agnostic starting set that
+ * the react minimap/compass read for colors and glyphs.
+ */
+export interface MarkerKindStyle {
+    id: string;
+    color: string;
+    glyph: string;
+    priority: number;
+}
+export declare const DEFAULT_MARKER_KINDS: Record<string, MarkerKindStyle>;
+export declare function markerKindStyle(kind: string, styles?: Record<string, MarkerKindStyle>): MarkerKindStyle;
+export interface MarkerSet<TMeta = unknown> {
+    add(marker: MarkerInput<TMeta>): string;
+    remove(id: string): boolean;
+    get(id: string): MapMarker<TMeta> | null;
+    list(): readonly MapMarker<TMeta>[];
+    query(query: MarkerQuery): MapMarker<TMeta>[];
+    prune(now: number): number;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): readonly MapMarker<TMeta>[];
+}
+export declare function createMarkerSet<TMeta = unknown>(now?: () => number): MarkerSet<TMeta>;