@jgengine/core 0.7.0 → 0.9.0

package/dist/combat/resourcePool.d.ts

@@ -0,0 +1,20 @@
+export interface ResourcePoolConfig {
+    max: number;
+    initial?: number;
+    regenPerSecond?: number;
+    decayPerSecond?: number;
+}
+export interface ResourcePool {
+    current(): number;
+    max(): number;
+    setMax(value: number): void;
+    fraction(): number;
+    canSpend(amount: number): boolean;
+    spend(amount: number): boolean;
+    gain(amount: number): number;
+    set(value: number): void;
+    tick(dtSeconds: number): void;
+    isFull(): boolean;
+    isEmpty(): boolean;
+}
+export declare function createResourcePool(config: ResourcePoolConfig): ResourcePool;

package/dist/combat/resourcePool.js

@@ -0,0 +1,55 @@
+export function createResourcePool(config) {
+    let max = Math.max(0, config.max);
+    const regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);
+    const decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
+    let current = clamp(config.initial ?? max, max);
+    function clamp(value, ceiling) {
+        return Math.max(0, Math.min(ceiling, value));
+    }
+    return {
+        current() {
+            return current;
+        },
+        max() {
+            return max;
+        },
+        setMax(value) {
+            max = Math.max(0, value);
+            current = clamp(current, max);
+        },
+        fraction() {
+            return max <= 0 ? 0 : current / max;
+        },
+        canSpend(amount) {
+            return amount <= 0 || amount <= current;
+        },
+        spend(amount) {
+            if (amount <= 0)
+                return true;
+            if (amount > current)
+                return false;
+            current = clamp(current - amount, max);
+            return true;
+        },
+        gain(amount) {
+            if (amount > 0)
+                current = clamp(current + amount, max);
+            return current;
+        },
+        set(value) {
+            current = clamp(value, max);
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return;
+            const net = (regenPerSecond - decayPerSecond) * dtSeconds;
+            current = clamp(current + net, max);
+        },
+        isFull() {
+            return current >= max;
+        },
+        isEmpty() {
+            return current <= 0;
+        },
+    };
+}

package/dist/combat/shotOrigin.d.ts

@@ -0,0 +1,40 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import type { Aim } from "../scene/spatial.js";
+/**
+ * How a shot's world-space origin (and optional direction) is resolved before prediction/settlement.
+ * - `legacy` — `aim.origin` when present, else the shooter's entity position (pre-#431 default).
+ * - `entity` — always the shooter's entity position.
+ * - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model).
+ * - `camera` — explicit camera/reticle world origin (and optional direction override).
+ * - `world` — absolute world origin.
+ */
+export type ShotOriginPolicy = {
+    kind: "legacy";
+} | {
+    kind: "entity";
+} | {
+    kind: "entityOffset";
+    offset: EntityPosition;
+} | {
+    kind: "muzzle";
+    offset?: EntityPosition;
+} | {
+    kind: "camera";
+    origin: EntityPosition;
+    direction?: EntityPosition;
+} | {
+    kind: "world";
+    origin: EntityPosition;
+    direction?: EntityPosition;
+};
+export interface ResolvedShot {
+    origin: EntityPosition;
+    direction: EntityPosition;
+}
+export interface ShotOriginDeps {
+    positionOf(instanceId: string): EntityPosition | undefined;
+    rotationYOf?(instanceId: string): number | undefined;
+}
+export declare function aimDirection(aim: Aim): EntityPosition | null;
+export declare function aimSpreadDeg(aim: Aim): number;
+export declare function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy?: ShotOriginPolicy): ResolvedShot | null;

package/dist/combat/shotOrigin.js

@@ -0,0 +1,57 @@
+import { worldOffset } from "../scene/colliders.js";
+const DEFAULT_MUZZLE_OFFSET = [0, 1.4, 0.35];
+function normalize(vector) {
+    const length = Math.sqrt(vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]);
+    if (length === 0)
+        return null;
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+export function aimDirection(aim) {
+    if ("origin" in aim)
+        return normalize(aim.direction);
+    const cosPitch = Math.cos(aim.pitch);
+    return [Math.sin(aim.yaw) * cosPitch, Math.sin(aim.pitch), Math.cos(aim.yaw) * cosPitch];
+}
+export function aimSpreadDeg(aim) {
+    return "origin" in aim ? 0 : aim.spread ?? 0;
+}
+export function resolveShot(deps, from, aim, policy = { kind: "legacy" }) {
+    const aimDir = aimDirection(aim);
+    if (aimDir === null && policy.kind !== "camera" && policy.kind !== "world")
+        return null;
+    switch (policy.kind) {
+        case "legacy": {
+            const origin = "origin" in aim ? aim.origin : deps.positionOf(from);
+            if (origin === undefined || aimDir === null)
+                return null;
+            return { origin, direction: aimDir };
+        }
+        case "entity": {
+            const origin = deps.positionOf(from);
+            if (origin === undefined || aimDir === null)
+                return null;
+            return { origin, direction: aimDir };
+        }
+        case "entityOffset":
+        case "muzzle": {
+            const position = deps.positionOf(from);
+            if (position === undefined || aimDir === null)
+                return null;
+            const rotationY = deps.rotationYOf?.(from) ?? 0;
+            const offset = policy.kind === "muzzle" ? (policy.offset ?? DEFAULT_MUZZLE_OFFSET) : policy.offset;
+            return { origin: worldOffset(offset, position, rotationY), direction: aimDir };
+        }
+        case "camera": {
+            const direction = policy.direction !== undefined ? normalize(policy.direction) : aimDir;
+            if (direction === null)
+                return null;
+            return { origin: policy.origin, direction };
+        }
+        case "world": {
+            const direction = policy.direction !== undefined ? normalize(policy.direction) : aimDir;
+            if (direction === null)
+                return null;
+            return { origin: policy.origin, direction };
+        }
+    }
+}

package/dist/combat/telegraph.d.ts

@@ -19,9 +19,38 @@ export interface TelegraphConfig {
     shape: TelegraphShape;
     at: EntityPosition;
     dir?: number;
-    windupMs: number;
+    windupMs?: number;
+    turns?: number;
     kind?: string;
 }
 export declare function telegraphProgress(windupMs: number, startedAtMs: number, nowMs: number): number;
+export interface HazardCycleConfig {
+    windupMs: number;
+    activeMs: number;
+    /** Rest between one activation's end and the next windup; default `0` (back-to-back). */
+    cooldownMs?: number;
+    /** Shifts the whole cycle — staggers identical hazards. */
+    offsetMs?: number;
+}
+export type HazardPhase = "windup" | "active" | "cooldown";
+export interface HazardCycleSample {
+    phase: HazardPhase;
+    /** Elapsed fraction of the current phase in `[0, 1]` — the windup fraction is the decal fill. */
+    fraction: number;
+    remainingMs: number;
+    /** How many full cycles have completed before this one. */
+    cycleIndex: number;
+}
+/**
+ * Deterministic repeating hazard timing — windup → active → cooldown as a pure function of absolute
+ * time, for recurring flame vents, crushers, lightning rings. Sample `hazardCycleAt` each tick: draw
+ * the telegraph during `windup`, apply the effect during `active`, rest through `cooldown`.
+ */
+export declare function hazardCycleAt(config: HazardCycleConfig, nowMs: number): HazardCycleSample;
+/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam. */
+export declare function nextHazardActiveAt(config: HazardCycleConfig, nowMs: number): number;
 export declare function telegraphFired(windupMs: number, startedAtMs: number, nowMs: number): boolean;
+export declare function telegraphTurnProgress(config: TelegraphConfig, startedTurn: number, currentTurn: number): number;
+export declare function telegraphFiredAtTurn(config: TelegraphConfig, startedTurn: number, currentTurn: number): boolean;
+export declare function telegraphTurnsRemaining(config: TelegraphConfig, startedTurn: number, currentTurn: number): number;
 export declare function pointInTelegraph(config: TelegraphConfig, point: EntityPosition): boolean;

package/dist/combat/telegraph.js

@@ -3,9 +3,70 @@ export function telegraphProgress(windupMs, startedAtMs, nowMs) {
         return 1;
     return Math.max(0, Math.min(1, (nowMs - startedAtMs) / windupMs));
 }
+/**
+ * Deterministic repeating hazard timing — windup → active → cooldown as a pure function of absolute
+ * time, for recurring flame vents, crushers, lightning rings. Sample `hazardCycleAt` each tick: draw
+ * the telegraph during `windup`, apply the effect during `active`, rest through `cooldown`.
+ */
+export function hazardCycleAt(config, nowMs) {
+    const cooldownMs = Math.max(0, config.cooldownMs ?? 0);
+    const cycleMs = config.windupMs + config.activeMs + cooldownMs;
+    if (cycleMs <= 0)
+        return { phase: "active", fraction: 1, remainingMs: 0, cycleIndex: 0 };
+    const shifted = nowMs + (config.offsetMs ?? 0);
+    const local = ((shifted % cycleMs) + cycleMs) % cycleMs;
+    const cycleIndex = Math.floor((shifted - local) / cycleMs);
+    if (local < config.windupMs) {
+        return {
+            phase: "windup",
+            fraction: config.windupMs <= 0 ? 1 : local / config.windupMs,
+            remainingMs: config.windupMs - local,
+            cycleIndex,
+        };
+    }
+    const intoActive = local - config.windupMs;
+    if (intoActive < config.activeMs) {
+        return {
+            phase: "active",
+            fraction: config.activeMs <= 0 ? 1 : intoActive / config.activeMs,
+            remainingMs: config.activeMs - intoActive,
+            cycleIndex,
+        };
+    }
+    const intoCooldown = intoActive - config.activeMs;
+    return {
+        phase: "cooldown",
+        fraction: cooldownMs <= 0 ? 1 : intoCooldown / cooldownMs,
+        remainingMs: cooldownMs - intoCooldown,
+        cycleIndex,
+    };
+}
+/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam. */
+export function nextHazardActiveAt(config, nowMs) {
+    const sample = hazardCycleAt(config, nowMs);
+    if (sample.phase === "windup")
+        return nowMs + sample.remainingMs;
+    const cooldownMs = Math.max(0, config.cooldownMs ?? 0);
+    const restMs = sample.phase === "active" ? sample.remainingMs + cooldownMs : sample.remainingMs;
+    return nowMs + restMs + config.windupMs;
+}
 export function telegraphFired(windupMs, startedAtMs, nowMs) {
     return nowMs - startedAtMs >= windupMs;
 }
+export function telegraphTurnProgress(config, startedTurn, currentTurn) {
+    const turns = config.turns ?? 0;
+    if (turns <= 0)
+        return 1;
+    return Math.max(0, Math.min(1, (currentTurn - startedTurn) / turns));
+}
+export function telegraphFiredAtTurn(config, startedTurn, currentTurn) {
+    const turns = config.turns ?? 0;
+    return currentTurn - startedTurn >= turns;
+}
+export function telegraphTurnsRemaining(config, startedTurn, currentTurn) {
+    const turns = config.turns ?? 0;
+    return Math.max(0, turns - (currentTurn - startedTurn));
+}
 function planarDelta(config, point) {
     return { dx: point[0] - config.at[0], dz: point[2] - config.at[2] };
 }

package/dist/commands/commandRegistry.d.ts

@@ -3,7 +3,7 @@ export interface CommandRejection {
 }
 export interface CommandDefinition<TState, TInput> {
     validate?(state: TState, input: TInput): CommandRejection | null;
-    apply(state: TState, input: TInput): TState;
+    apply(state: TState, input: TInput): TState | void;
 }
 export type CommandResult<TState> = {
     status: "applied";

package/dist/commands/commandRegistry.js

@@ -20,7 +20,8 @@ export function createCommandRegistry() {
             const rejection = definition.validate?.(state, input) ?? null;
             if (rejection)
                 return { status: "rejected", reason: rejection.reason };
-            return { status: "applied", state: definition.apply(state, input) };
+            const next = definition.apply(state, input);
+            return { status: "applied", state: next === undefined ? state : next };
         },
     };
 }

package/dist/crafting/recipe.js

@@ -19,6 +19,9 @@ export function stationSatisfied(recipe, context) {
         return true;
     const range = recipe.stationRange !== undefined && recipe.stationRange > 0 ? recipe.stationRange : Infinity;
     const origin = context.origin;
+    if (range !== Infinity && origin === undefined) {
+        throw new Error(`recipe "${recipe.id}" sets stationRange=${recipe.stationRange} but CraftContext.origin is missing`);
+    }
     const stations = context.stations ?? [];
     for (const station of stations) {
         if (station.catalogId !== recipe.station)
@@ -37,7 +40,7 @@ function lockedRequirements(recipe, context) {
         return [];
     const unlocked = context.unlocked;
     if (unlocked === undefined)
-        return [];
+        return recipe.requires;
     return recipe.requires.filter((id) => !unlocked(id));
 }
 function outputsFit(state, layout, traits, recipe) {

package/dist/data/dataSource.d.ts

@@ -0,0 +1,26 @@
+export type DataSourceStatus = "idle" | "loading" | "ready" | "error";
+export interface DataSourceState<T> {
+    readonly status: DataSourceStatus;
+    readonly data: T | undefined;
+    readonly error: Error | undefined;
+}
+export interface DataSourceClock {
+    setInterval(handler: () => void, intervalMs: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface DataSourceOptions {
+    intervalMs?: number;
+    clock?: DataSourceClock;
+}
+export interface RefreshOptions {
+    force?: boolean;
+}
+export interface DataSource<T> {
+    getState(): DataSourceState<T>;
+    subscribe(listener: (state: DataSourceState<T>) => void): () => void;
+    refresh(options?: RefreshOptions): Promise<void>;
+    startPolling(intervalMs?: number): void;
+    stopPolling(): void;
+    dispose(): void;
+}
+export declare function createDataSource<T>(load: (signal: AbortSignal) => Promise<T>, options?: DataSourceOptions): DataSource<T>;

package/dist/data/dataSource.js

@@ -0,0 +1,93 @@
+const defaultClock = {
+    setInterval: (handler, intervalMs) => globalThis.setInterval(handler, intervalMs),
+    clearInterval: (handle) => globalThis.clearInterval(handle),
+};
+export function createDataSource(load, options = {}) {
+    const clock = options.clock ?? defaultClock;
+    const listeners = new Set();
+    let state = { status: "idle", data: undefined, error: undefined };
+    let controller;
+    let inFlight;
+    let pollHandle;
+    let disposed = false;
+    function setState(next) {
+        state = next;
+        for (const listener of listeners)
+            listener(state);
+    }
+    async function run() {
+        const ownController = new AbortController();
+        controller = ownController;
+        setState({ status: "loading", data: state.data, error: undefined });
+        try {
+            const data = await load(ownController.signal);
+            if (ownController.signal.aborted)
+                return;
+            setState({ status: "ready", data, error: undefined });
+        }
+        catch (error) {
+            if (ownController.signal.aborted)
+                return;
+            setState({
+                status: "error",
+                data: state.data,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+        finally {
+            if (controller === ownController)
+                controller = undefined;
+        }
+    }
+    function refresh(refreshOptions = {}) {
+        if (disposed)
+            return Promise.resolve();
+        if (inFlight !== undefined) {
+            if (!refreshOptions.force)
+                return inFlight;
+            controller?.abort();
+        }
+        const promise = run().finally(() => {
+            if (inFlight === promise)
+                inFlight = undefined;
+        });
+        inFlight = promise;
+        return promise;
+    }
+    function stopPolling() {
+        if (pollHandle !== undefined) {
+            clock.clearInterval(pollHandle);
+            pollHandle = undefined;
+        }
+    }
+    function startPolling(intervalMs) {
+        stopPolling();
+        const resolvedInterval = intervalMs ?? options.intervalMs;
+        if (resolvedInterval === undefined) {
+            throw new Error("startPolling requires an intervalMs (pass one, or set options.intervalMs at creation)");
+        }
+        void refresh();
+        pollHandle = clock.setInterval(() => {
+            void refresh();
+        }, resolvedInterval);
+    }
+    function dispose() {
+        disposed = true;
+        stopPolling();
+        controller?.abort();
+        listeners.clear();
+    }
+    if (options.intervalMs !== undefined)
+        startPolling(options.intervalMs);
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refresh,
+        startPolling,
+        stopPolling,
+        dispose,
+    };
+}

package/dist/data/devProxy.d.ts

@@ -0,0 +1,11 @@
+export interface DevProxyTable {
+    readonly [routeName: string]: string;
+}
+export interface ProxiedUrlOptions {
+    dev?: boolean;
+    table?: DevProxyTable;
+    prefix?: string;
+}
+export declare function parseDevProxyTable(raw: string | undefined): DevProxyTable;
+export declare const DEFAULT_DEV_PROXY_PREFIX = "/proxy";
+export declare function proxiedUrl(target: string, options?: ProxiedUrlOptions): string;

package/dist/data/devProxy.js

@@ -0,0 +1,38 @@
+function readImportMetaEnv() {
+    try {
+        const meta = import.meta;
+        return meta.env ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+export function parseDevProxyTable(raw) {
+    if (raw === undefined || raw.length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const entries = Object.entries(parsed).filter((entry) => typeof entry[1] === "string");
+        return Object.fromEntries(entries);
+    }
+    catch {
+        return {};
+    }
+}
+export const DEFAULT_DEV_PROXY_PREFIX = "/proxy";
+export function proxiedUrl(target, options = {}) {
+    const env = readImportMetaEnv();
+    const dev = options.dev ?? env.DEV === true;
+    if (!dev)
+        return target;
+    const table = options.table ?? parseDevProxyTable(env.VITE_JGENGINE_DEV_PROXY);
+    const prefix = options.prefix ?? DEFAULT_DEV_PROXY_PREFIX;
+    for (const [routeName, base] of Object.entries(table)) {
+        if (target.startsWith(base)) {
+            return `${prefix}/${routeName}${target.slice(base.length)}`;
+        }
+    }
+    return target;
+}

package/dist/data/fetchJson.d.ts

@@ -0,0 +1,20 @@
+export type FetchImpl = typeof fetch;
+export interface FetchJsonOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    fetchImpl?: FetchImpl;
+}
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    constructor(status: number, statusText: string, url: string);
+}
+export declare class JsonParseError extends Error {
+    readonly url: string;
+    readonly cause: unknown;
+    constructor(url: string, cause: unknown);
+}
+export declare function fetchJson<T>(url: string, options?: FetchJsonOptions): Promise<T>;

package/dist/data/fetchJson.js

@@ -0,0 +1,43 @@
+export class HttpStatusError extends Error {
+    status;
+    statusText;
+    url;
+    constructor(status, statusText, url) {
+        super(`HTTP ${status} ${statusText} for ${url}`);
+        this.name = "HttpStatusError";
+        this.status = status;
+        this.statusText = statusText;
+        this.url = url;
+    }
+}
+export class JsonParseError extends Error {
+    url;
+    cause;
+    constructor(url, cause) {
+        super(`failed to parse JSON response from ${url}`);
+        this.name = "JsonParseError";
+        this.url = url;
+        this.cause = cause;
+    }
+}
+export async function fetchJson(url, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchImpl(url, {
+        method: options.method,
+        headers: options.headers,
+        body: options.body,
+        signal: options.signal,
+    });
+    if (!response.ok) {
+        throw new HttpStatusError(response.status, response.statusText, url);
+    }
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new JsonParseError(url, cause);
+    }
+}

package/dist/data/jsonDataSource.d.ts

@@ -0,0 +1,4 @@
+import { type DataSource, type DataSourceOptions } from "./dataSource.js";
+import { type FetchJsonOptions } from "./fetchJson.js";
+export type JsonDataSourceOptions = DataSourceOptions & Omit<FetchJsonOptions, "signal">;
+export declare function createJsonDataSource<T>(url: string, options?: JsonDataSourceOptions): DataSource<T>;

package/dist/data/jsonDataSource.js

@@ -0,0 +1,6 @@
+import { createDataSource } from "./dataSource.js";
+import { fetchJson } from "./fetchJson.js";
+export function createJsonDataSource(url, options = {}) {
+    const { intervalMs, clock, ...fetchOptions } = options;
+    return createDataSource((signal) => fetchJson(url, { ...fetchOptions, signal }), { intervalMs, clock });
+}