@jgengine/core 0.6.0 → 0.8.0

package/dist/world/voxelField.js

@@ -0,0 +1,241 @@
+export const VOXEL_FACES = ["px", "nx", "py", "ny", "pz", "nz"];
+export const VOXEL_FACE_NORMALS = {
+    px: [1, 0, 0],
+    nx: [-1, 0, 0],
+    py: [0, 1, 0],
+    ny: [0, -1, 0],
+    pz: [0, 0, 1],
+    nz: [0, 0, -1],
+};
+function cellKey(x, y, z) {
+    return `${x},${y},${z}`;
+}
+function entryFace(dx, dy, dz) {
+    const ax = Math.abs(dx);
+    const ay = Math.abs(dy);
+    const az = Math.abs(dz);
+    if (ax >= ay && ax >= az && ax > 0)
+        return dx > 0 ? "nx" : "px";
+    if (az >= ay && az > 0)
+        return dz > 0 ? "nz" : "pz";
+    return dy > 0 ? "ny" : "py";
+}
+export function createVoxelField(config) {
+    const chunkSize = config?.chunkSize ?? 16;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error("createVoxelField: chunkSize must be a positive integer");
+    }
+    const cells = new Map();
+    const chunkVersions = new Map();
+    const listeners = new Set();
+    function chunkOf(x, y, z) {
+        return {
+            cx: Math.floor(x / chunkSize),
+            cy: Math.floor(y / chunkSize),
+            cz: Math.floor(z / chunkSize),
+        };
+    }
+    function bumpChunk(x, y, z) {
+        const { cx, cy, cz } = chunkOf(x, y, z);
+        const key = cellKey(cx, cy, cz);
+        chunkVersions.set(key, (chunkVersions.get(key) ?? 0) + 1);
+    }
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function setCell(x, y, z, type) {
+        const key = cellKey(x, y, z);
+        const existing = cells.get(key);
+        if (existing !== undefined && existing.type === type)
+            return false;
+        cells.set(key, { x, y, z, type });
+        bumpChunk(x, y, z);
+        return true;
+    }
+    function getCell(x, y, z) {
+        return cells.get(cellKey(x, y, z));
+    }
+    function computeBounds() {
+        if (cells.size === 0)
+            return null;
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let minZ = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        let maxZ = Number.NEGATIVE_INFINITY;
+        for (const cell of cells.values()) {
+            if (cell.x < minX)
+                minX = cell.x;
+            if (cell.y < minY)
+                minY = cell.y;
+            if (cell.z < minZ)
+                minZ = cell.z;
+            if (cell.x > maxX)
+                maxX = cell.x;
+            if (cell.y > maxY)
+                maxY = cell.y;
+            if (cell.z > maxZ)
+                maxZ = cell.z;
+        }
+        return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+    }
+    return {
+        set(x, y, z, type) {
+            const changed = setCell(x, y, z, type);
+            if (changed)
+                notify();
+            return changed;
+        },
+        remove(x, y, z) {
+            const removed = cells.delete(cellKey(x, y, z));
+            if (removed) {
+                bumpChunk(x, y, z);
+                notify();
+            }
+            return removed;
+        },
+        get(x, y, z) {
+            return getCell(x, y, z)?.type ?? null;
+        },
+        has(x, y, z) {
+            return cells.has(cellKey(x, y, z));
+        },
+        fill(min, max, type) {
+            let changed = 0;
+            for (let x = min[0]; x <= max[0]; x += 1) {
+                for (let y = min[1]; y <= max[1]; y += 1) {
+                    for (let z = min[2]; z <= max[2]; z += 1) {
+                        if (setCell(x, y, z, type))
+                            changed += 1;
+                    }
+                }
+            }
+            if (changed > 0)
+                notify();
+            return changed;
+        },
+        clear() {
+            if (cells.size === 0)
+                return;
+            for (const cell of cells.values())
+                bumpChunk(cell.x, cell.y, cell.z);
+            cells.clear();
+            notify();
+        },
+        count() {
+            return cells.size;
+        },
+        cells() {
+            return cells.values();
+        },
+        bounds() {
+            return computeBounds();
+        },
+        neighbors(x, y, z) {
+            const out = [];
+            for (const face of VOXEL_FACES) {
+                const [nx, ny, nz] = VOXEL_FACE_NORMALS[face];
+                const cell = getCell(x + nx, y + ny, z + nz);
+                if (cell !== undefined)
+                    out.push(cell);
+            }
+            return out;
+        },
+        exposedFaces(x, y, z) {
+            if (!cells.has(cellKey(x, y, z)))
+                return [];
+            return VOXEL_FACES.filter((face) => {
+                const [nx, ny, nz] = VOXEL_FACE_NORMALS[face];
+                return !cells.has(cellKey(x + nx, y + ny, z + nz));
+            });
+        },
+        raycast(origin, direction, maxDistance) {
+            const [ox, oy, oz] = origin;
+            const [dx, dy, dz] = direction;
+            let ix = Math.floor(ox);
+            let iy = Math.floor(oy);
+            let iz = Math.floor(oz);
+            const startCell = getCell(ix, iy, iz);
+            if (startCell !== undefined) {
+                return {
+                    x: ix,
+                    y: iy,
+                    z: iz,
+                    type: startCell.type,
+                    face: entryFace(dx, dy, dz),
+                    adjacent: [ix, iy, iz],
+                    distance: 0,
+                };
+            }
+            const stepX = dx > 0 ? 1 : dx < 0 ? -1 : 0;
+            const stepY = dy > 0 ? 1 : dy < 0 ? -1 : 0;
+            const stepZ = dz > 0 ? 1 : dz < 0 ? -1 : 0;
+            const tDeltaX = dx !== 0 ? Math.abs(1 / dx) : Number.POSITIVE_INFINITY;
+            const tDeltaY = dy !== 0 ? Math.abs(1 / dy) : Number.POSITIVE_INFINITY;
+            const tDeltaZ = dz !== 0 ? Math.abs(1 / dz) : Number.POSITIVE_INFINITY;
+            const boundary = (i, o, step) => (step > 0 ? i + 1 - o : o - i);
+            let tMaxX = dx !== 0 ? boundary(ix, ox, stepX) * tDeltaX : Number.POSITIVE_INFINITY;
+            let tMaxY = dy !== 0 ? boundary(iy, oy, stepY) * tDeltaY : Number.POSITIVE_INFINITY;
+            let tMaxZ = dz !== 0 ? boundary(iz, oz, stepZ) * tDeltaZ : Number.POSITIVE_INFINITY;
+            let face = "py";
+            let travelled = 0;
+            while (travelled <= maxDistance) {
+                let px = ix;
+                let py = iy;
+                let pz = iz;
+                if (tMaxX < tMaxY && tMaxX < tMaxZ) {
+                    ix += stepX;
+                    travelled = tMaxX;
+                    tMaxX += tDeltaX;
+                    face = stepX > 0 ? "nx" : "px";
+                }
+                else if (tMaxY < tMaxZ) {
+                    iy += stepY;
+                    travelled = tMaxY;
+                    tMaxY += tDeltaY;
+                    face = stepY > 0 ? "ny" : "py";
+                }
+                else {
+                    iz += stepZ;
+                    travelled = tMaxZ;
+                    tMaxZ += tDeltaZ;
+                    face = stepZ > 0 ? "nz" : "pz";
+                }
+                if (travelled > maxDistance)
+                    break;
+                const cell = getCell(ix, iy, iz);
+                if (cell !== undefined) {
+                    return {
+                        x: ix,
+                        y: iy,
+                        z: iz,
+                        type: cell.type,
+                        face,
+                        adjacent: [px, py, pz],
+                        distance: travelled,
+                    };
+                }
+            }
+            return null;
+        },
+        chunkOf,
+        chunkVersion(cx, cy, cz) {
+            return chunkVersions.get(cellKey(cx, cy, cz)) ?? 0;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        summary() {
+            const types = {};
+            for (const cell of cells.values()) {
+                types[cell.type] = (types[cell.type] ?? 0) + 1;
+            }
+            return { blocks: cells.size, types, bounds: computeBounds() };
+        },
+    };
+}

package/dist/world/walls.d.ts

@@ -0,0 +1,61 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+export type WallVec3 = readonly [number, number, number];
+export interface WallSegment {
+    from: Vec2;
+    to: Vec2;
+    length: number;
+    angle: number;
+}
+export interface EnclosedFootprint {
+    polygon: readonly Vec2[];
+    aabb: Aabb;
+    area: number;
+    perimeter: number;
+    closed: boolean;
+}
+export type RoofStyle = "hip" | "gable" | "flat";
+export interface RoofPlan {
+    style: RoofStyle;
+    ridge: readonly [Vec2, Vec2];
+    apexHeight: number;
+    eaveHeight: number;
+    faces: readonly (readonly WallVec3[])[];
+}
+export interface RoofConfig {
+    style?: RoofStyle;
+    eaveHeight?: number;
+    pitch?: number;
+    overhang?: number;
+}
+export declare function wallSegments(points: readonly Vec2[], closed: boolean): WallSegment[];
+export declare function isEnclosed(points: readonly Vec2[], tolerance?: number): boolean;
+export declare function enclosePath(points: readonly Vec2[], tolerance?: number): readonly Vec2[];
+export declare function polygonArea(polygon: readonly Vec2[]): number;
+export declare function footprintFromWalls(points: readonly Vec2[], tolerance?: number): EnclosedFootprint | null;
+export declare function autoRoof(footprint: EnclosedFootprint, config?: RoofConfig): RoofPlan;
+export type PaintTarget = "floor" | "wall";
+export interface SurfacePaintStore {
+    paint(target: PaintTarget, key: string, surface: string): void;
+    clear(target: PaintTarget, key: string): void;
+    get(target: PaintTarget, key: string): string | null;
+    entries(target: PaintTarget): readonly (readonly [string, string])[];
+    snapshot(): Record<PaintTarget, Record<string, string>>;
+    restore(snapshot: Record<PaintTarget, Record<string, string>>): void;
+}
+export declare function createSurfacePaint(): SurfacePaintStore;
+export interface WallDrawTool {
+    addPoint(point: Vec2, snap?: number): Vec2;
+    undo(): void;
+    close(): void;
+    clear(): void;
+    points(): readonly Vec2[];
+    segments(): WallSegment[];
+    isClosed(): boolean;
+    footprint(): EnclosedFootprint | null;
+    roof(config?: RoofConfig): RoofPlan | null;
+}
+export declare function createWallDrawTool(config?: {
+    snap?: number;
+    closeTolerance?: number;
+}): WallDrawTool;
+export declare function wallSegmentBounds(segment: WallSegment, thickness: number): Aabb;

package/dist/world/walls.js

@@ -0,0 +1,221 @@
+import { footprintAabb } from "./geometry.js";
+export function wallSegments(points, closed) {
+    const segments = [];
+    const count = closed ? points.length : points.length - 1;
+    for (let index = 0; index < count; index += 1) {
+        const from = points[index];
+        const to = points[(index + 1) % points.length];
+        const dx = to[0] - from[0];
+        const dz = to[1] - from[1];
+        segments.push({ from, to, length: Math.hypot(dx, dz), angle: Math.atan2(dz, dx) });
+    }
+    return segments;
+}
+export function isEnclosed(points, tolerance = 0.5) {
+    if (points.length < 3)
+        return false;
+    const first = points[0];
+    const last = points[points.length - 1];
+    return Math.hypot(first[0] - last[0], first[1] - last[1]) <= tolerance;
+}
+export function enclosePath(points, tolerance = 0.5) {
+    if (points.length < 3)
+        return points;
+    if (!isEnclosed(points, tolerance))
+        return points;
+    return points.slice(0, points.length - 1);
+}
+export function polygonArea(polygon) {
+    let sum = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        sum += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(sum) / 2;
+}
+export function footprintFromWalls(points, tolerance = 0.5) {
+    const closed = isEnclosed(points, tolerance);
+    const polygon = enclosePath(points, tolerance);
+    if (polygon.length < 3)
+        return null;
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    let perimeter = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const point = polygon[index];
+        if (point[0] < minX)
+            minX = point[0];
+        if (point[0] > maxX)
+            maxX = point[0];
+        if (point[1] < minZ)
+            minZ = point[1];
+        if (point[1] > maxZ)
+            maxZ = point[1];
+        const next = polygon[(index + 1) % polygon.length];
+        perimeter += Math.hypot(next[0] - point[0], next[1] - point[1]);
+    }
+    return {
+        polygon,
+        aabb: { minX, minZ, maxX, maxZ },
+        area: polygonArea(polygon),
+        perimeter,
+        closed,
+    };
+}
+export function autoRoof(footprint, config = {}) {
+    const style = config.style ?? "hip";
+    const eaveHeight = config.eaveHeight ?? 3;
+    const pitch = config.pitch ?? 0.5;
+    const overhang = config.overhang ?? 0.4;
+    const aabb = footprint.aabb;
+    const minX = aabb.minX - overhang;
+    const maxX = aabb.maxX + overhang;
+    const minZ = aabb.minZ - overhang;
+    const maxZ = aabb.maxZ + overhang;
+    const width = maxX - minX;
+    const depth = maxZ - minZ;
+    const cx = (minX + maxX) / 2;
+    const cz = (minZ + maxZ) / 2;
+    const ridgeAlongX = width >= depth;
+    const halfSpan = (ridgeAlongX ? depth : width) / 2;
+    const apexHeight = style === "flat" ? eaveHeight : eaveHeight + halfSpan * pitch;
+    if (style === "flat") {
+        const face = [
+            [minX, eaveHeight, minZ],
+            [maxX, eaveHeight, minZ],
+            [maxX, eaveHeight, maxZ],
+            [minX, eaveHeight, maxZ],
+        ];
+        const flatRidge = [
+            [minX, cz],
+            [maxX, cz],
+        ];
+        return { style, ridge: flatRidge, apexHeight, eaveHeight, faces: [face] };
+    }
+    const ridge = ridgeAlongX
+        ? [
+            [minX + (style === "hip" ? halfSpan : 0), cz],
+            [maxX - (style === "hip" ? halfSpan : 0), cz],
+        ]
+        : [
+            [cx, minZ + (style === "hip" ? halfSpan : 0)],
+            [cx, maxZ - (style === "hip" ? halfSpan : 0)],
+        ];
+    const r0 = [ridge[0][0], apexHeight, ridge[0][1]];
+    const r1 = [ridge[1][0], apexHeight, ridge[1][1]];
+    const corners = {
+        nw: [minX, eaveHeight, minZ],
+        ne: [maxX, eaveHeight, minZ],
+        se: [maxX, eaveHeight, maxZ],
+        sw: [minX, eaveHeight, maxZ],
+    };
+    const faces = ridgeAlongX
+        ? [
+            [corners.nw, corners.ne, r1, r0],
+            [corners.se, corners.sw, r0, r1],
+        ]
+        : [
+            [corners.ne, corners.se, r1, r0],
+            [corners.sw, corners.nw, r0, r1],
+        ];
+    if (style === "hip") {
+        faces.push(ridgeAlongX
+            ? [corners.sw, corners.nw, r0]
+            : [corners.nw, corners.ne, r0]);
+        faces.push(ridgeAlongX
+            ? [corners.ne, corners.se, r1]
+            : [corners.se, corners.sw, r1]);
+    }
+    return { style, ridge, apexHeight, eaveHeight, faces };
+}
+export function createSurfacePaint() {
+    const maps = {
+        floor: new Map(),
+        wall: new Map(),
+    };
+    return {
+        paint(target, key, surface) {
+            maps[target].set(key, surface);
+        },
+        clear(target, key) {
+            maps[target].delete(key);
+        },
+        get(target, key) {
+            return maps[target].get(key) ?? null;
+        },
+        entries(target) {
+            return Array.from(maps[target].entries());
+        },
+        snapshot() {
+            return {
+                floor: Object.fromEntries(maps.floor),
+                wall: Object.fromEntries(maps.wall),
+            };
+        },
+        restore(snapshot) {
+            maps.floor = new Map(Object.entries(snapshot.floor ?? {}));
+            maps.wall = new Map(Object.entries(snapshot.wall ?? {}));
+        },
+    };
+}
+function snapPoint(point, grid) {
+    if (!(grid > 0))
+        return point;
+    return [Math.round(point[0] / grid) * grid, Math.round(point[1] / grid) * grid];
+}
+export function createWallDrawTool(config = {}) {
+    const defaultSnap = config.snap ?? 0;
+    const closeTolerance = config.closeTolerance ?? 0.5;
+    let pts = [];
+    let closed = false;
+    return {
+        addPoint(point, snap) {
+            const grid = snap ?? defaultSnap;
+            const next = snapPoint(point, grid);
+            if (pts.length >= 3 && Math.hypot(next[0] - pts[0][0], next[1] - pts[0][1]) <= closeTolerance) {
+                closed = true;
+                return pts[0];
+            }
+            pts.push(next);
+            return next;
+        },
+        undo() {
+            pts.pop();
+            closed = false;
+        },
+        close() {
+            if (pts.length >= 3)
+                closed = true;
+        },
+        clear() {
+            pts = [];
+            closed = false;
+        },
+        points() {
+            return pts;
+        },
+        segments() {
+            return wallSegments(pts, closed);
+        },
+        isClosed() {
+            return closed;
+        },
+        footprint() {
+            if (!closed && !isEnclosed(pts, closeTolerance))
+                return null;
+            return footprintFromWalls(pts, closeTolerance);
+        },
+        roof(roofConfig) {
+            const fp = this.footprint();
+            return fp === null ? null : autoRoof(fp, roofConfig);
+        },
+    };
+}
+export function wallSegmentBounds(segment, thickness) {
+    const center = [(segment.from[0] + segment.to[0]) / 2, (segment.from[1] + segment.to[1]) / 2];
+    const quarterTurns = Math.abs(Math.round(segment.angle / (Math.PI / 2))) % 2;
+    return footprintAabb(center, { w: segment.length, d: thickness }, quarterTurns);
+}

package/dist/world/weather.d.ts

@@ -0,0 +1,92 @@
+import type { WindVector } from "./wind.js";
+export type WeatherKind = string;
+export interface WeatherState {
+    /** Game-defined kind: "clear", "rain", "storm", "snow", "fog", "sandstorm". */
+    kind: WeatherKind;
+    /** 0..1 severity — scales every modifier. */
+    intensity: number;
+    wind?: WindVector;
+}
+/** Per-kind gameplay effect values at full intensity. Intensity interpolates from neutral. */
+export interface WeatherModifier {
+    /** Movement traction multiplier at full intensity — <1 = mud/ice slows, 1 = normal. */
+    grip?: number;
+    /** View distance multiplier at full intensity — 0..1, 1 = clear. */
+    visibility?: number;
+    /** Structure HP lost per game-second at full intensity (hail, storm). */
+    structureDamage?: number;
+    /** Temperature delta at full intensity (a blizzard chills). */
+    chill?: number;
+    /** Lightning ignition chance per game-second at full intensity. */
+    ignition?: number;
+    /** Fire spread-rate multiplier at full intensity — rain suppresses (<1). Default neutral 1. */
+    spread?: number;
+}
+export type WeatherModifierTable = Record<WeatherKind, WeatherModifier>;
+export interface ResolvedWeather {
+    grip: number;
+    visibility: number;
+    structureDamage: number;
+    chill: number;
+    ignition: number;
+    spread: number;
+}
+/**
+ * Resolve a weather state against a game-owned modifier table into concrete gameplay
+ * numbers. Multiplier-style effects (grip, visibility, spread) interpolate from the
+ * neutral 1 by intensity; rate-style effects (structureDamage, ignition, chill) scale
+ * linearly. Games read `grip`/`visibility` in movement and AI, `structureDamage` on a
+ * building tick, and `spread`/`ignition` feed the fire grid.
+ */
+export declare function resolveWeather(state: WeatherState, table: WeatherModifierTable): ResolvedWeather;
+export type FireCellState = "unburnt" | "burning" | "burnt";
+export interface FireCell {
+    fuel: number;
+    heat: number;
+    state: FireCellState;
+}
+export interface FireGridConfig {
+    cols: number;
+    rows: number;
+    cellSize: number;
+    /** World x,z of the center of cell (0,0). Default [0,0]. */
+    origin?: readonly [number, number];
+    /** Initial fuel 0..1 per cell; default 1 everywhere. */
+    fuelAt?: (col: number, row: number) => number;
+    /** Accumulated heat needed to ignite a fuelled cell. Default 1. */
+    ignitionThreshold?: number;
+    /** Heat pushed to each neighbour per second from a burning cell. Default 0.6. */
+    spreadRate?: number;
+    /** Fuel consumed per second while burning. Default 0.25. */
+    burnRate?: number;
+    /** Prevailing wind biasing spread direction. */
+    wind?: WindVector;
+    /** How strongly wind biases downwind vs upwind spread, 0..1. Default 0.6. */
+    windBias?: number;
+}
+export interface FireStepOptions {
+    /** Global spread multiplier this step (rain suppression from resolveWeather().spread). Default 1. */
+    spread?: number;
+    /** Per-cell wetness 0..1 that resists ignition — from an environment field. */
+    wetnessAt?: (col: number, row: number) => number;
+}
+export interface FireGrid {
+    readonly cols: number;
+    readonly rows: number;
+    /** Advance the cellular propagation by game-time `dt`. */
+    step(dt: number, options?: FireStepOptions): void;
+    igniteCell(col: number, row: number): void;
+    /** Ignite the cell under a world position; no-op if outside the grid. */
+    ignite(x: number, z: number): boolean;
+    cell(col: number, row: number): FireCell;
+    cellAt(x: number, z: number): FireCell | null;
+    cellCoord(x: number, z: number): {
+        col: number;
+        row: number;
+    } | null;
+    /** Count of currently burning cells. */
+    readonly burning: number;
+    /** Flat snapshot (row-major) for rendering. */
+    snapshot(): FireCell[];
+}
+export declare function createFireGrid(config: FireGridConfig): FireGrid;