@jgengine/core 0.6.0 → 0.8.0

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,69 @@
+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;
+}
+/** A fixed buildable slot the placement controller snaps to instead of grid/free positioning. */
+export interface PlacementSlot {
+    id: string;
+    center: PlacementVec3;
+    /** Capture radius around `center`. Defaults to `config.slotRadius`, then `1.5`. */
+    radius?: number;
+    /** `false` hides the slot from hover resolution without releasing it. Default `true`. */
+    enabled?: boolean;
+}
+export interface PlacementControllerConfig {
+    footprint: Footprint;
+    rules?: PlacementRules;
+    snapMode?: SnapMode;
+    grid?: number;
+    quarterTurns?: number;
+    slots?: readonly PlacementSlot[];
+    /** Fallback capture radius for slots that don't set their own. Default `1.5`. */
+    slotRadius?: number;
+}
+export interface PlacementPreview {
+    center: Vec2;
+    y: number;
+    quarterTurns: number;
+    footprint: Footprint;
+    aabb: Aabb;
+    valid: boolean;
+    reason?: "out-of-bounds" | "overlap" | "no-slot";
+    snapMode: SnapMode;
+    normal: PlacementVec3;
+    /** Id of the resolved slot, when the controller is in slot mode and a slot matched. */
+    slotId?: string;
+}
+export interface PlacementCommit {
+    center: Vec2;
+    y: number;
+    rotationY: number;
+    quarterTurns: number;
+    footprint: Footprint;
+    aabb: Aabb;
+    /** Id of the slot this commit occupied, when the controller is in slot mode. */
+    slotId?: string;
+}
+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;
+    setSlots(slots: readonly PlacementSlot[]): void;
+    /** Id of the currently hovered slot, or `null` when idle, out of slot mode, or unmatched. */
+    hoveredSlotId(): string | null;
+    /** Frees a previously committed slot so it can match again. */
+    releaseSlot(id: string): void;
+    commit(): PlacementCommit | null;
+    reset(): void;
+}
+export declare function quarterTurnsToRotationY(quarterTurns: number): number;
+export declare function createPlacementController(config: PlacementControllerConfig): PlacementController;

package/dist/world/placementController.js

@@ -0,0 +1,153 @@
+import { footprintAabb, snapToGrid } from "./geometry.js";
+import { validatePlacement } from "./placement.js";
+const SNAP_ORDER = ["grid", "free", "surface"];
+const DEFAULT_SLOT_RADIUS = 1.5;
+function distanceVec3(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+export function quarterTurnsToRotationY(quarterTurns) {
+    const turns = ((quarterTurns % 4) + 4) % 4;
+    return turns === 0 ? 0 : -turns * (Math.PI / 2);
+}
+export function createPlacementController(config) {
+    let footprint = config.footprint;
+    let rules = config.rules ?? {};
+    let snapMode = config.snapMode ?? "grid";
+    let grid = config.grid ?? rules.snap ?? 1;
+    let quarterTurns = ((config.quarterTurns ?? 0) % 4 + 4) % 4;
+    let slots = config.slots;
+    const slotRadius = config.slotRadius ?? DEFAULT_SLOT_RADIUS;
+    const occupiedSlots = new Set();
+    let lastHit = null;
+    let preview = null;
+    function snapCenter(raw) {
+        if (snapMode === "grid")
+            return snapToGrid(raw, grid);
+        return raw;
+    }
+    function nearestSlot(hit) {
+        let best = null;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const slot of slots ?? []) {
+            if (slot.enabled === false || occupiedSlots.has(slot.id))
+                continue;
+            const distance = distanceVec3(hit.point, slot.center);
+            if (distance <= (slot.radius ?? slotRadius) && distance < bestDistance) {
+                best = slot;
+                bestDistance = distance;
+            }
+        }
+        return best;
+    }
+    function computeSlotPreview(hit) {
+        const slot = nearestSlot(hit);
+        const center = slot === null ? [hit.point[0], hit.point[2]] : [slot.center[0], slot.center[2]];
+        const next = {
+            center,
+            y: slot === null ? hit.point[1] : slot.center[1],
+            quarterTurns,
+            footprint,
+            aabb: footprintAabb(center, footprint, quarterTurns),
+            valid: slot !== null,
+            snapMode,
+            normal: hit.normal,
+            ...(slot === null ? { reason: "no-slot" } : { slotId: slot.id }),
+        };
+        preview = next;
+        return next;
+    }
+    function compute(hit) {
+        if (slots !== undefined)
+            return computeSlotPreview(hit);
+        const raw = [hit.point[0], hit.point[2]];
+        const center = snapCenter(raw);
+        const rulesWithoutSnap = snapMode === "grid" ? { ...rules, snap: undefined } : rules;
+        const result = validatePlacement({ center, footprint, quarterTurns }, rulesWithoutSnap);
+        const aabb = result.status === "ok" ? result.aabb : footprintAabb(center, footprint, quarterTurns);
+        const next = {
+            center: result.status === "ok" ? result.center : center,
+            y: hit.point[1],
+            quarterTurns,
+            footprint,
+            aabb,
+            valid: result.status === "ok",
+            snapMode,
+            normal: hit.normal,
+            ...(result.status === "rejected" ? { reason: result.reason } : {}),
+        };
+        preview = next;
+        return next;
+    }
+    return {
+        hover(hit) {
+            lastHit = hit;
+            return compute(hit);
+        },
+        current() {
+            return preview;
+        },
+        rotate(steps = 1) {
+            quarterTurns = ((quarterTurns + steps) % 4 + 4) % 4;
+            return lastHit === null ? null : compute(lastHit);
+        },
+        setSnapMode(mode) {
+            snapMode = mode;
+            return lastHit === null ? null : compute(lastHit);
+        },
+        cycleSnapMode() {
+            const index = SNAP_ORDER.indexOf(snapMode);
+            snapMode = SNAP_ORDER[(index + 1) % SNAP_ORDER.length];
+            if (lastHit !== null)
+                compute(lastHit);
+            return snapMode;
+        },
+        setFootprint(next) {
+            footprint = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        setRules(next) {
+            rules = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        setGrid(next) {
+            grid = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        setSlots(next) {
+            slots = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        hoveredSlotId() {
+            return preview?.slotId ?? null;
+        },
+        releaseSlot(id) {
+            occupiedSlots.delete(id);
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        commit() {
+            if (preview === null || !preview.valid)
+                return null;
+            if (preview.slotId !== undefined)
+                occupiedSlots.add(preview.slotId);
+            return {
+                center: preview.center,
+                y: preview.y,
+                rotationY: quarterTurnsToRotationY(quarterTurns),
+                quarterTurns,
+                footprint: preview.footprint,
+                aabb: preview.aabb,
+                ...(preview.slotId !== undefined ? { slotId: preview.slotId } : {}),
+            };
+        },
+        reset() {
+            lastHit = null;
+            preview = null;
+            quarterTurns = ((config.quarterTurns ?? 0) % 4 + 4) % 4;
+        },
+    };
+}

package/dist/world/realm.d.ts

@@ -0,0 +1,61 @@
+import { type EnvironmentField, type EnvironmentFieldConfig } from "./envField.js";
+import type { WeatherState } from "./weather.js";
+/** The recomposable environment parameters a realm card can override. */
+export interface RealmEnvironmentParams {
+    baseTemperature: number;
+    nightDrop: number;
+    altitudeLapse: number;
+    /** Game-seconds per day (a "long night" minor card shortens the day cycle). */
+    dayLength: number;
+    /** Ambient rain intensity 0..1. */
+    rain: number;
+    /** Ambient light floor 0..1 (moonlight). */
+    ambientFloor: number;
+}
+export declare const DEFAULT_REALM_ENVIRONMENT: RealmEnvironmentParams;
+/** Spawn-table edits a card layers on: replace weights, add/scale, or remove ids. */
+export interface SpawnTableOverride {
+    set?: Record<string, number>;
+    add?: Record<string, number>;
+    scale?: Record<string, number>;
+    remove?: readonly string[];
+}
+export interface RealmCard {
+    id: string;
+    /** A major card sets the biome base; minors layer weather/day-length/aesthetic on top. */
+    kind: "major" | "minor";
+    /** Environment param overrides (last write wins across the ordered deck). */
+    environment?: Partial<RealmEnvironmentParams>;
+    /** Weather state overrides (kind/intensity/wind). */
+    weather?: Partial<WeatherState>;
+    /** Spawn-table edits applied in deck order. */
+    spawn?: SpawnTableOverride;
+    /** Opaque aesthetic tag (skybox, palette) the renderer maps — engine never inspects it. */
+    aesthetic?: string;
+}
+export interface RealmBase {
+    environment?: Partial<RealmEnvironmentParams>;
+    weather?: WeatherState;
+    spawn?: Record<string, number>;
+}
+export interface ComposedRealm {
+    params: RealmEnvironmentParams;
+    weather: WeatherState;
+    spawnTable: Record<string, number>;
+    aesthetics: readonly string[];
+    cards: readonly RealmCard[];
+    /**
+     * Build an environment field (#91) from the composed params, wired to the composed
+     * weather's rain intensity. Extra config (terrain, occluders, heat sources) merges on top.
+     */
+    environmentField(extra?: Omit<EnvironmentFieldConfig, "baseTemperature" | "nightDrop" | "altitudeLapse" | "dayLength" | "rain" | "ambientFloor">): EnvironmentField;
+}
+/**
+ * Assemble a played realm instance at runtime from a deck of modifier cards — the
+ * Nightingale "realm card" model. A major card is the biome base; minor cards layer
+ * weather, day length, and spawn edits. The result recomposes both the environment
+ * (into a sampleable field via `environmentField()`) and the spawn table, and it depends
+ * on the weather hooks in this group (#92) to turn its `weather` into gameplay modifiers.
+ * Cards apply in array order; sort your deck (majors first) before composing.
+ */
+export declare function composeRealm(base: RealmBase, cards: readonly RealmCard[]): ComposedRealm;