@jgengine/core 0.7.0 → 0.8.0

package/dist/combat/projectiles.js

@@ -2,6 +2,38 @@ const DEFAULT_RANGE = 100;
 const DEFAULT_PROJECTILE_SPEED = 15;
 const GRAVITY = 9.8;
 const BASE_HIT_RADIUS = 0.5;
+const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+function isEntityHit(hit) {
+    return hit.kind === "entity";
+}
+function isObjectHit(hit) {
+    return hit.kind === "object";
+}
+function raySegmentAabbDistance(origin, direction, range, min, max) {
+    let tMin = 0;
+    let tMax = range;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const o = origin[axis];
+        const d = direction[axis];
+        const lo = min[axis];
+        const hi = max[axis];
+        if (Math.abs(d) < 1e-9) {
+            if (o < lo || o > hi)
+                return null;
+            continue;
+        }
+        const inv = 1 / d;
+        let t1 = (lo - o) * inv;
+        let t2 = (hi - o) * inv;
+        if (t1 > t2)
+            [t1, t2] = [t2, t1];
+        tMin = Math.max(tMin, t1);
+        tMax = Math.min(tMax, t2);
+        if (tMin > tMax)
+            return null;
+    }
+    return tMin;
+}
 function normalize(vector) {
     const length = Math.sqrt(vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]);
     if (length === 0)
@@ -42,7 +74,7 @@ export function createProjectileSystem(deps) {
             if (direction === null)
                 return [];
             const spreadRad = (aimSpreadDeg(aim) * Math.PI) / 180;
-            const hits = [];
+            const entityHits = [];
             for (const instanceId of deps.spatial.inRadius(origin, range)) {
                 if (instanceId === from)
                     continue;
@@ -61,8 +93,42 @@ export function createProjectileSystem(deps) {
                 const perpendicular = Math.sqrt(px * px + py * py + pz * pz);
                 if (perpendicular > BASE_HIT_RADIUS + Math.tan(spreadRad) * along)
                     continue;
-                hits.push({ instanceId, distance: along, at: position });
+                entityHits.push({ kind: "entity", instanceId, distance: along, at: position });
             }
+            let nearestObject = null;
+            for (const object of deps.objects?.list() ?? []) {
+                const half = deps.objects?.halfExtents?.(object.catalogId) ?? DEFAULT_OBJECT_HALF_EXTENTS;
+                const min = [
+                    object.position[0] - half[0],
+                    object.position[1] - half[1],
+                    object.position[2] - half[2],
+                ];
+                const max = [
+                    object.position[0] + half[0],
+                    object.position[1] + half[1],
+                    object.position[2] + half[2],
+                ];
+                const distance = raySegmentAabbDistance(origin, direction, range, min, max);
+                if (distance === null)
+                    continue;
+                if (nearestObject === null || distance < nearestObject.distance) {
+                    nearestObject = {
+                        kind: "object",
+                        instanceId: object.instanceId,
+                        catalogId: object.catalogId,
+                        distance,
+                        at: [
+                            origin[0] + direction[0] * distance,
+                            origin[1] + direction[1] * distance,
+                            origin[2] + direction[2] * distance,
+                        ],
+                    };
+                }
+            }
+            const blockDistance = nearestObject?.distance ?? Infinity;
+            const hits = entityHits.filter((hit) => hit.distance <= blockDistance);
+            if (nearestObject !== null)
+                hits.push(nearestObject);
             return hits.sort((a, b) => a.distance - b.distance);
         });
     function resolveRange(via) {
@@ -71,7 +137,7 @@ export function createProjectileSystem(deps) {
     function isBallistic(via) {
         return itemStat(via, "projectile.fuseTime") !== null || itemStat(via, "explosion.radius") !== null;
     }
-    function ballisticSettlePoint(input) {
+    function ballisticArc(input) {
         const origin = shotOrigin(input.from, input.aim) ?? [0, 0, 0];
         const direction = aimDirection(input.aim) ?? [0, 0, 1];
         const speed = itemStat(input.via, "projectile.speed") ?? DEFAULT_PROJECTILE_SPEED;
@@ -85,16 +151,32 @@ export function createProjectileSystem(deps) {
             : flightCap;
         const flightTime = Math.min(impactTime, flightCap);
         const settledY = Math.max(0, origin[1] + verticalSpeed * flightTime - 0.5 * gravity * flightTime * flightTime);
-        return [
-            origin[0] + direction[0] * speed * flightTime,
-            settledY,
-            origin[2] + direction[2] * speed * flightTime,
-        ];
+        return {
+            origin,
+            velocity: [direction[0] * speed, verticalSpeed, direction[2] * speed],
+            gravity,
+            flightTime,
+            landing: [
+                origin[0] + direction[0] * speed * flightTime,
+                settledY,
+                origin[2] + direction[2] * speed * flightTime,
+            ],
+        };
+    }
+    function ballisticSettlePoint(input) {
+        const arc = ballisticArc(input);
+        const sweep = deps.sweepBallistic;
+        if (sweep !== undefined) {
+            const impact = sweep(arc.origin, arc.velocity, arc.gravity, arc.flightTime);
+            if (impact !== null)
+                return impact.point;
+        }
+        return arc.landing;
     }
     function predictHits(input) {
         const aim = withWeaponSpread(input.via, input.aim);
         const rawHits = raycast(input.from, aim, resolveRange(input.via));
-        const visible = rawHits.filter((hit) => deps.spatial.hasLineOfSight(input.from, hit.instanceId));
+        const visible = rawHits.filter((hit) => isObjectHit(hit) || deps.spatial.hasLineOfSight(input.from, hit.instanceId));
         return { rawHits, visible };
     }
     function settledAt(input, hits) {
@@ -112,7 +194,9 @@ export function createProjectileSystem(deps) {
         willHitProjectile(input) {
             const { rawHits, visible } = predictHits(input);
             const prediction = {
-                hits: visible.map(({ instanceId, distance }) => ({ instanceId, distance })),
+                hits: visible.map((hit) => isObjectHit(hit)
+                    ? { kind: "object", instanceId: hit.instanceId, catalogId: hit.catalogId, distance: hit.distance }
+                    : { kind: "entity", instanceId: hit.instanceId, distance: hit.distance }),
             };
             if (rawHits.length > 0 && visible.length === 0)
                 prediction.blocked = true;
@@ -139,7 +223,9 @@ export function createProjectileSystem(deps) {
                 return { status: "settled", shotId, at, hits: [] };
             }
             const { visible } = predictHits(input);
-            const receivable = visible.filter((hit) => deps.effects.canReceive(hit.instanceId, input.effect) === null);
+            const entityHits = visible.filter(isEntityHit);
+            const objectHits = visible.filter(isObjectHit);
+            const receivable = entityHits.filter((hit) => deps.effects.canReceive(hit.instanceId, input.effect) === null);
             const pellets = Math.max(1, Math.round(itemStat(input.via, "pellets") ?? 1));
             const hits = [];
             if (receivable.length > 0) {
@@ -153,7 +239,7 @@ export function createProjectileSystem(deps) {
                     }));
                 }
             }
-            const at = settledAt(input, receivable);
+            const at = settledAt(input, receivable.length > 0 ? receivable : objectHits);
             deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: receivable.length > 0 });
             return { status: "settled", shotId, at, hits };
         },

package/dist/combat/telegraph.d.ts

@@ -19,9 +19,13 @@ 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 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

@@ -6,6 +6,20 @@ export function telegraphProgress(windupMs, startedAtMs, nowMs) {
 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/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 });
+}

package/dist/devtools/devtools.d.ts

@@ -0,0 +1,157 @@
+import { type ChangeSignal } from "../store/changeSignal.js";
+export type DevtoolsControlKind = "slider" | "toggle" | "color" | "select" | "text";
+export interface TunableOptions<T> {
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly T[];
+    label?: string;
+    group?: string;
+    onChange?: (value: T) => void;
+}
+export interface DevtoolsControl {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly label: string;
+    readonly group: string;
+    readonly initial: unknown;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly options?: readonly unknown[];
+    read(): unknown;
+    write(value: unknown): void;
+    reset(): void;
+}
+export interface Tunable<T> {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: T;
+    readonly value: T;
+    set(value: T): void;
+    reset(): void;
+    subscribe(listener: (value: T) => void): () => void;
+}
+export interface FrameStats {
+    fps: number;
+    avgFrameMs: number;
+    p95FrameMs: number;
+    maxFrameMs: number;
+    avgSimMs: number;
+    maxSimMs: number;
+    longFrames: number;
+    samples: number;
+    recentFrameMs: readonly number[];
+}
+export interface RenderSample {
+    drawCalls: number;
+    triangles: number;
+    geometries: number;
+    textures: number;
+}
+export interface LatencyStats {
+    lastMs: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    samples: number;
+}
+export type DevtoolsLogLevel = "log" | "info" | "warn" | "error";
+export interface DevtoolsLogEntry {
+    at: number;
+    level: DevtoolsLogLevel;
+    message: string;
+}
+export interface DiscoveredEntry {
+    readonly id: string;
+    readonly table: string;
+    readonly key: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: unknown;
+    readonly enabled: boolean;
+    read(): unknown;
+}
+export interface TunableAccessor {
+    initial: unknown;
+    get(): unknown;
+    set(value: unknown): void;
+}
+export interface DevtoolsOverrides {
+    enabled: string[];
+    values: Record<string, unknown>;
+}
+export interface DevtoolsSnapshot {
+    at: number;
+    frame: FrameStats | null;
+    render: RenderSample | null;
+    latency: LatencyStats | null;
+    logs: readonly DevtoolsLogEntry[];
+    probes: Record<string, unknown>;
+    controls: readonly {
+        name: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        initial: unknown;
+    }[];
+    discovered: readonly {
+        id: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        enabled: boolean;
+    }[];
+}
+export interface Devtools {
+    frame: {
+        record(sample: {
+            frameMs: number;
+            simMs: number;
+        }): void;
+        stats(): FrameStats | null;
+    };
+    render: {
+        record(sample: RenderSample): void;
+        latest(): RenderSample | null;
+    };
+    logs: {
+        push(level: DevtoolsLogLevel, message: string): void;
+        captureConsole(): void;
+        list(): readonly DevtoolsLogEntry[];
+        clear(): void;
+    };
+    latency: {
+        record(ms: number): void;
+        stats(): LatencyStats | null;
+    };
+    controls: {
+        register<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
+        list(): readonly DevtoolsControl[];
+        get(name: string): DevtoolsControl | null;
+        remove(name: string): void;
+        resetAll(): void;
+    };
+    discover: {
+        bind(table: string, key: string, accessor: TunableAccessor): void;
+        scanTable(table: string, candidate: unknown): number;
+        scanModule(exports: Record<string, unknown>): number;
+        list(): readonly DiscoveredEntry[];
+        enable(id: string): void;
+        disable(id: string): void;
+        clear(): void;
+    };
+    overrides: {
+        export(): DevtoolsOverrides;
+        apply(overrides: DevtoolsOverrides): void;
+    };
+    probes: {
+        register(name: string, read: () => unknown): () => void;
+        read(): Record<string, unknown>;
+    };
+    signal: ChangeSignal;
+    snapshot(): DevtoolsSnapshot;
+}
+export declare function formatLogMessage(args: readonly unknown[]): string;
+export declare function createDevtools(): Devtools;
+export declare const devtools: Devtools;
+export declare function tunable<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
+export declare function snapshotDevtools(): DevtoolsSnapshot;
+export declare function instrumentLatency<T extends object>(target: T, methods: readonly (keyof T)[], record?: (ms: number) => void): T;