@jgengine/core 0.8.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

@@ -24,6 +24,31 @@ export interface TelegraphConfig {
     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;

package/dist/combat/telegraph.js

@@ -3,6 +3,53 @@ 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;
 }

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/devtools/devtools.d.ts

@@ -1,14 +1,7 @@
 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;
-}
+import { type AngleUnit, type DevtoolsControlKind, type DevtoolsOverrides, type DiscoverySkip, type OverrideApplyDiagnostic, type ScanMeta, type TunableChoice, type TunableOptions } from "./tunableSchema.js";
+export type { AngleUnit, DevtoolsControlKind, DevtoolsOverrides, DiscoverySkip, OverrideApplyDiagnostic, TunableChoice, TunableInterval, TunableOptions, TunableVec2, TunableVec3, TunableVec4, ScanMeta, ScanFieldMeta, NormalizedColor, } from "./tunableSchema.js";
+export { CONTROL_SCHEMA_VERSION, OVERRIDES_FORMAT_VERSION, convertAngle, escapePathSegment, formatColor, joinTunablePath, normalizeAngle, normalizeColorValue, parseColor, parseOverridesPayload, splitTunablePath, unescapePathSegment, validateControlValue, } from "./tunableSchema.js";
 export interface DevtoolsControl {
     readonly name: string;
     readonly kind: DevtoolsControlKind;
@@ -19,8 +12,19 @@ export interface DevtoolsControl {
     readonly max?: number;
     readonly step?: number;
     readonly options?: readonly unknown[];
+    readonly choices?: readonly TunableChoice[];
+    readonly unit?: AngleUnit;
+    readonly displayUnit?: AngleUnit;
+    readonly wrap?: boolean;
+    readonly integer?: boolean;
+    readonly axisLabels?: readonly string[];
+    readonly axisMin?: readonly number[];
+    readonly axisMax?: readonly number[];
+    readonly axisStep?: readonly number[];
+    readonly hasAlpha?: boolean;
+    readonly schemaVersion: number;
     read(): unknown;
-    write(value: unknown): void;
+    write(value: unknown): boolean;
     reset(): void;
 }
 export interface Tunable<T> {
@@ -28,10 +32,15 @@ export interface Tunable<T> {
     readonly kind: DevtoolsControlKind;
     readonly initial: T;
     readonly value: T;
-    set(value: T): void;
+    set(value: T): boolean;
     reset(): void;
     subscribe(listener: (value: T) => void): () => void;
 }
+export interface OverrideApplyResult {
+    applied: number;
+    skipped: readonly OverrideApplyDiagnostic[];
+    diagnostics: readonly string[];
+}
 export interface FrameStats {
     fps: number;
     avgFrameMs: number;
@@ -39,9 +48,36 @@ export interface FrameStats {
     maxFrameMs: number;
     avgSimMs: number;
     maxSimMs: number;
+    avgOutsideMs: number;
+    maxOutsideMs: number;
     longFrames: number;
     samples: number;
     recentFrameMs: readonly number[];
+    phases: readonly PhaseStats[];
+}
+export interface PhaseStats {
+    name: string;
+    avgMs: number;
+    maxMs: number;
+    lastMs: number;
+    samples: number;
+    pctOfSim: number;
+}
+export interface LongFrameEvent {
+    at: number;
+    frameMs: number;
+    simMs: number;
+    outsideMs: number;
+    phases: readonly {
+        name: string;
+        ms: number;
+        pct: number;
+    }[];
+    topPhase: string | null;
+    culprit: string;
+    reason: string;
+    probes: Record<string, unknown>;
+    render: RenderSample | null;
 }
 export interface RenderSample {
     drawCalls: number;
@@ -76,15 +112,12 @@ export interface TunableAccessor {
     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;
+    longFrames: readonly LongFrameEvent[];
     logs: readonly DevtoolsLogEntry[];
     probes: Record<string, unknown>;
     controls: readonly {
@@ -99,14 +132,26 @@ export interface DevtoolsSnapshot {
         value: unknown;
         enabled: boolean;
     }[];
+    skipped: readonly DiscoverySkip[];
+}
+export interface FrameRecordSample {
+    frameMs: number;
+    simMs: number;
+    phases?: Readonly<Record<string, number>>;
 }
 export interface Devtools {
     frame: {
-        record(sample: {
-            frameMs: number;
-            simMs: number;
-        }): void;
+        record(sample: FrameRecordSample): void;
         stats(): FrameStats | null;
+        longFrames(): readonly LongFrameEvent[];
+        clearLongFrames(): void;
+    };
+    profile: {
+        begin(name: string): () => void;
+        measure<T>(name: string, fn: () => T): T;
+        add(name: string, ms: number): void;
+        current(): Record<string, number>;
+        reset(): void;
     };
     render: {
         record(sample: RenderSample): void;
@@ -130,17 +175,18 @@ export interface Devtools {
         resetAll(): void;
     };
     discover: {
-        bind(table: string, key: string, accessor: TunableAccessor): void;
-        scanTable(table: string, candidate: unknown): number;
-        scanModule(exports: Record<string, unknown>): number;
+        bind(table: string, key: string, accessor: TunableAccessor, options?: TunableOptions): void;
+        scanTable(table: string, candidate: unknown, meta?: ScanMeta): number;
+        scanModule(exports: Record<string, unknown>, meta?: ScanMeta): number;
         list(): readonly DiscoveredEntry[];
+        skipped(): readonly DiscoverySkip[];
         enable(id: string): void;
         disable(id: string): void;
         clear(): void;
     };
     overrides: {
         export(): DevtoolsOverrides;
-        apply(overrides: DevtoolsOverrides): void;
+        apply(overrides: DevtoolsOverrides | unknown): OverrideApplyResult;
     };
     probes: {
         register(name: string, read: () => unknown): () => void;
@@ -149,9 +195,11 @@ export interface Devtools {
     signal: ChangeSignal;
     snapshot(): DevtoolsSnapshot;
 }
+export declare const LONG_FRAME_MS = 33.4;
 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 measureProfile<T>(name: string, fn: () => T): T;
 export declare function instrumentLatency<T extends object>(target: T, methods: readonly (keyof T)[], record?: (ms: number) => void): T;