@jgengine/core 0.5.0 → 0.7.0

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/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>;

package/dist/world/markers.js

@@ -0,0 +1,96 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+export const DEFAULT_MARKER_KINDS = {
+    player: { id: "player", color: "#4ade80", glyph: "◆", priority: 90 },
+    ally: { id: "ally", color: "#38bdf8", glyph: "▲", priority: 70 },
+    objective: { id: "objective", color: "#facc15", glyph: "★", priority: 100 },
+    location: { id: "location", color: "#e2e8f0", glyph: "⬡", priority: 40 },
+    loot: { id: "loot", color: "#c084fc", glyph: "◈", priority: 60 },
+    enemy: { id: "enemy", color: "#f87171", glyph: "✖", priority: 80 },
+    danger: { id: "danger", color: "#fb923c", glyph: "⚠", priority: 85 },
+    ping: { id: "ping", color: "#22d3ee", glyph: "◎", priority: 65 },
+};
+export function markerKindStyle(kind, styles = DEFAULT_MARKER_KINDS) {
+    return styles[kind] ?? { id: kind, color: "#e2e8f0", glyph: "•", priority: 30 };
+}
+function distanceXZ(a, b) {
+    return Math.hypot(a[0] - b[0], a[2] - b[2]);
+}
+export function createMarkerSet(now = Date.now) {
+    const store = createObservableKeyedStore();
+    let counter = 0;
+    function generateId() {
+        let id = `marker-${counter}`;
+        while (store.has(id)) {
+            counter += 1;
+            id = `marker-${counter}`;
+        }
+        counter += 1;
+        return id;
+    }
+    return {
+        add(input) {
+            const id = input.id ?? generateId();
+            const marker = {
+                id,
+                kind: input.kind,
+                position: input.position,
+                createdAt: input.createdAt ?? now(),
+            };
+            if (input.label !== undefined)
+                marker.label = input.label;
+            if (input.owner !== undefined)
+                marker.owner = input.owner;
+            if (input.expiresAt !== undefined)
+                marker.expiresAt = input.expiresAt;
+            if (input.meta !== undefined)
+                marker.meta = input.meta;
+            store.set(id, marker);
+            return id;
+        },
+        remove(id) {
+            const existed = store.has(id);
+            store.delete(id);
+            return existed;
+        },
+        get(id) {
+            return store.get(id) ?? null;
+        },
+        list() {
+            return store.arraySnapshot();
+        },
+        query(query) {
+            return store.arraySnapshot().filter((marker) => {
+                if (query.kind !== undefined && marker.kind !== query.kind)
+                    return false;
+                if (query.owner !== undefined && marker.owner !== query.owner)
+                    return false;
+                if (query.near !== undefined) {
+                    const radius = query.radius ?? Number.POSITIVE_INFINITY;
+                    if (distanceXZ(marker.position, query.near) > radius)
+                        return false;
+                }
+                return true;
+            });
+        },
+        prune(at) {
+            let removed = 0;
+            for (const marker of store.arraySnapshot()) {
+                if (marker.expiresAt !== undefined && marker.expiresAt <= at) {
+                    store.delete(marker.id);
+                    removed += 1;
+                }
+            }
+            return removed;
+        },
+        clear() {
+            for (const marker of store.arraySnapshot())
+                store.delete(marker.id);
+        },
+        subscribe(listener) {
+            return store.subscribe(listener);
+        },
+        snapshot() {
+            return store.arraySnapshot();
+        },
+    };
+}

package/dist/world/minimap.d.ts

@@ -0,0 +1,42 @@
+export type WorldXZ = readonly [number, number];
+/**
+ * Compass bearing (radians, 0 = map north = −Z, increasing clockwise toward +X
+ * = east) from one world XZ point to another. Feeds both the minimap direction
+ * and the compass strip.
+ */
+export declare function compassBearing(from: WorldXZ, to: WorldXZ): number;
+/** Bearing of an entity facing direction given its `rotationY` (yaw) in radians. */
+export declare function headingToBearing(yaw: number): number;
+export type Cardinal = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+export declare function bearingToCardinal(bearing: number): Cardinal;
+/** Signed offset of `bearing` from `reference`, wrapped into (−π, π]. */
+export declare function relativeBearing(bearing: number, reference: number): number;
+export interface MinimapView {
+    /** World XZ at the minimap center (usually the player position). */
+    center: WorldXZ;
+    /** World-unit distance from center to the minimap edge. */
+    worldRadius: number;
+    /** Pixel diameter of the minimap. */
+    size: number;
+    /** Rotate the projection so this facing bearing points up (rotating minimap). Omit for north-up. */
+    rotate?: number;
+}
+export interface MinimapPoint {
+    x: number;
+    y: number;
+    /** Radial distance in world units. */
+    distance: number;
+    /** True when within `worldRadius` of center. */
+    inside: boolean;
+}
+/**
+ * Project a world XZ (or XYZ) point into minimap pixel space. Origin is the
+ * top-left of the `size×size` box; north (−Z) maps to −Y (up). Pass
+ * `view.rotate` to spin the map under a fixed north-up player arrow.
+ */
+export declare function projectToMinimap(world: WorldXZ | readonly [number, number, number], view: MinimapView): MinimapPoint;
+/** Clamp a projected point to the minimap edge, preserving direction (edge markers). */
+export declare function clampToMinimapEdge(point: MinimapPoint, size: number): {
+    x: number;
+    y: number;
+};

package/dist/world/minimap.js

@@ -0,0 +1,72 @@
+const TWO_PI = Math.PI * 2;
+function normalizeAngle(angle) {
+    let value = angle % TWO_PI;
+    if (value < 0)
+        value += TWO_PI;
+    return value;
+}
+/**
+ * Compass bearing (radians, 0 = map north = −Z, increasing clockwise toward +X
+ * = east) from one world XZ point to another. Feeds both the minimap direction
+ * and the compass strip.
+ */
+export function compassBearing(from, to) {
+    return normalizeAngle(Math.atan2(to[0] - from[0], -(to[1] - from[1])));
+}
+/** Bearing of an entity facing direction given its `rotationY` (yaw) in radians. */
+export function headingToBearing(yaw) {
+    return normalizeAngle(Math.atan2(Math.sin(yaw), -Math.cos(yaw)));
+}
+const CARDINALS = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"];
+export function bearingToCardinal(bearing) {
+    const index = Math.round(normalizeAngle(bearing) / (Math.PI / 4)) % 8;
+    return CARDINALS[index];
+}
+/** Signed offset of `bearing` from `reference`, wrapped into (−π, π]. */
+export function relativeBearing(bearing, reference) {
+    let delta = normalizeAngle(bearing) - normalizeAngle(reference);
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    if (delta <= -Math.PI)
+        delta += TWO_PI;
+    return delta;
+}
+/**
+ * Project a world XZ (or XYZ) point into minimap pixel space. Origin is the
+ * top-left of the `size×size` box; north (−Z) maps to −Y (up). Pass
+ * `view.rotate` to spin the map under a fixed north-up player arrow.
+ */
+export function projectToMinimap(world, view) {
+    const worldX = world[0];
+    const worldZ = world.length === 3 ? world[2] : world[1];
+    let dx = worldX - view.center[0];
+    let dz = worldZ - view.center[1];
+    if (view.rotate !== undefined && view.rotate !== 0) {
+        const cos = Math.cos(view.rotate);
+        const sin = Math.sin(view.rotate);
+        const rx = dx * cos - dz * sin;
+        const rz = dx * sin + dz * cos;
+        dx = rx;
+        dz = rz;
+    }
+    const distance = Math.hypot(dx, dz);
+    const half = view.size / 2;
+    const scale = view.worldRadius === 0 ? 0 : half / view.worldRadius;
+    return {
+        x: half + dx * scale,
+        y: half + dz * scale,
+        distance,
+        inside: distance <= view.worldRadius,
+    };
+}
+/** Clamp a projected point to the minimap edge, preserving direction (edge markers). */
+export function clampToMinimapEdge(point, size) {
+    const half = size / 2;
+    const dx = point.x - half;
+    const dy = point.y - half;
+    const length = Math.hypot(dx, dy);
+    if (length <= half || length === 0)
+        return { x: point.x, y: point.y };
+    const scale = half / length;
+    return { x: half + dx * scale, y: half + dy * scale };
+}

package/dist/world/placedStructureStore.d.ts

@@ -0,0 +1,39 @@
+export type StructureVec3 = readonly [number, number, number];
+export interface PlacedStructure {
+    id: string;
+    catalogId: string;
+    position: StructureVec3;
+    rotationY: number;
+    plotId?: string;
+    data?: Readonly<Record<string, unknown>>;
+}
+export interface AddStructureInput {
+    id?: string;
+    catalogId: string;
+    position: StructureVec3;
+    rotationY?: number;
+    plotId?: string;
+    data?: Readonly<Record<string, unknown>>;
+}
+export interface StructureFilter {
+    plotId?: string;
+    catalogId?: string;
+}
+export interface PlacedStructureSnapshot {
+    structures: readonly PlacedStructure[];
+}
+export interface PlacedStructureStore {
+    add(input: AddStructureInput): PlacedStructure;
+    move(id: string, position: StructureVec3): boolean;
+    rotate(id: string, rotationY: number): boolean;
+    remove(id: string): boolean;
+    get(id: string): PlacedStructure | null;
+    list(filter?: StructureFilter): readonly PlacedStructure[];
+    clear(): void;
+    select(id: string | null): boolean;
+    selected(): PlacedStructure | null;
+    snapshot(): PlacedStructureSnapshot;
+    load(snapshot: PlacedStructureSnapshot): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createPlacedStructureStore(): PlacedStructureStore;

package/dist/world/placedStructureStore.js

@@ -0,0 +1,95 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+export function createPlacedStructureStore() {
+    const store = createObservableKeyedStore();
+    let counter = 1;
+    let selectedId = null;
+    function generateId() {
+        let id = `structure-${counter}`;
+        while (store.has(id)) {
+            counter += 1;
+            id = `structure-${counter}`;
+        }
+        counter += 1;
+        return id;
+    }
+    return {
+        add(input) {
+            if (input.id !== undefined && store.has(input.id)) {
+                throw new Error(`Structure id "${input.id}" already exists.`);
+            }
+            const id = input.id ?? generateId();
+            const structure = {
+                id,
+                catalogId: input.catalogId,
+                position: input.position,
+                rotationY: input.rotationY ?? 0,
+                ...(input.plotId === undefined ? {} : { plotId: input.plotId }),
+                ...(input.data === undefined ? {} : { data: input.data }),
+            };
+            store.set(id, structure);
+            return structure;
+        },
+        move(id, position) {
+            const current = store.get(id);
+            if (current === undefined)
+                return false;
+            store.set(id, { ...current, position });
+            return true;
+        },
+        rotate(id, rotationY) {
+            const current = store.get(id);
+            if (current === undefined)
+                return false;
+            store.set(id, { ...current, rotationY });
+            return true;
+        },
+        remove(id) {
+            const existed = store.has(id);
+            store.delete(id);
+            if (selectedId === id)
+                selectedId = null;
+            return existed;
+        },
+        get(id) {
+            return store.get(id) ?? null;
+        },
+        list(filter) {
+            const all = store.arraySnapshot();
+            if (filter === undefined)
+                return all;
+            return all.filter((structure) => (filter.plotId === undefined || structure.plotId === filter.plotId) &&
+                (filter.catalogId === undefined || structure.catalogId === filter.catalogId));
+        },
+        clear() {
+            for (const structure of store.arraySnapshot())
+                store.delete(structure.id);
+            selectedId = null;
+        },
+        select(id) {
+            if (id === null) {
+                selectedId = null;
+                return true;
+            }
+            if (!store.has(id))
+                return false;
+            selectedId = id;
+            return true;
+        },
+        selected() {
+            return selectedId === null ? null : store.get(selectedId) ?? null;
+        },
+        snapshot() {
+            return { structures: store.arraySnapshot() };
+        },
+        load(snapshot) {
+            for (const structure of store.arraySnapshot())
+                store.delete(structure.id);
+            selectedId = null;
+            for (const structure of snapshot.structures)
+                store.set(structure.id, structure);
+        },
+        subscribe(listener) {
+            return store.subscribe(listener);
+        },
+    };
+}

package/dist/world/placementController.d.ts

@@ -0,0 +1,48 @@
+import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
+import { type PlacementRules } from "./placement.js";
+export type SnapMode = "grid" | "free" | "surface";
+export type PlacementVec3 = readonly [number, number, number];
+export interface PlacementHit {
+    point: PlacementVec3;
+    normal: PlacementVec3;
+}
+export interface PlacementControllerConfig {
+    footprint: Footprint;
+    rules?: PlacementRules;
+    snapMode?: SnapMode;
+    grid?: number;
+    quarterTurns?: number;
+}
+export interface PlacementPreview {
+    center: Vec2;
+    y: number;
+    quarterTurns: number;
+    footprint: Footprint;
+    aabb: Aabb;
+    valid: boolean;
+    reason?: "out-of-bounds" | "overlap";
+    snapMode: SnapMode;
+    normal: PlacementVec3;
+}
+export interface PlacementCommit {
+    center: Vec2;
+    y: number;
+    rotationY: number;
+    quarterTurns: number;
+    footprint: Footprint;
+    aabb: Aabb;
+}
+export interface PlacementController {
+    hover(hit: PlacementHit): PlacementPreview;
+    current(): PlacementPreview | null;
+    rotate(steps?: number): PlacementPreview | null;
+    setSnapMode(mode: SnapMode): PlacementPreview | null;
+    cycleSnapMode(): SnapMode;
+    setFootprint(footprint: Footprint): void;
+    setRules(rules: PlacementRules): void;
+    setGrid(grid: number): void;
+    commit(): PlacementCommit | null;
+    reset(): void;
+}
+export declare function quarterTurnsToRotationY(quarterTurns: number): number;
+export declare function createPlacementController(config: PlacementControllerConfig): PlacementController;