@jgengine/core 0.8.0 → 0.10.0

package/dist/combat/regenShield.d.ts

@@ -0,0 +1,35 @@
+/** Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period. */
+export interface RegenShieldConfig {
+    max: number;
+    /** Points restored per second once the post-damage grace period has elapsed. */
+    regenPerSecond: number;
+    /** Grace period after the last damage before regen resumes. */
+    regenDelayMs: number;
+    /** Starting value; defaults to `max` (full). */
+    current?: number;
+}
+/**
+ * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
+ * `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per
+ * tick to detect "damage taken" (#536.3). `damage` resets the grace timer; `tick` counts it down and
+ * regenerates once it elapses.
+ */
+export interface RegenShield {
+    current(): number;
+    max(): number;
+    setMax(value: number): void;
+    fraction(): number;
+    isFull(): boolean;
+    isBroken(): boolean;
+    /** True while the post-damage grace period is suppressing regen. */
+    suppressed(): boolean;
+    /** Absorb `amount` and reset the regen grace timer; returns damage that got through (0 while the shield holds). */
+    damage(amount: number): number;
+    /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
+    restore(amount: number): void;
+    set(value: number): void;
+    /** Advance time: count down the grace period, then regenerate once it has elapsed. */
+    tick(dtSeconds: number): void;
+}
+/** Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit. */
+export declare function createRegenShield(config: RegenShieldConfig): RegenShield;

package/dist/combat/regenShield.js

@@ -0,0 +1,45 @@
+/** Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit. */
+export function createRegenShield(config) {
+    let max = Math.max(0, config.max);
+    const regenPerSecond = Math.max(0, config.regenPerSecond);
+    const regenDelayMs = Math.max(0, config.regenDelayMs);
+    function clamp(value, ceiling) {
+        return Math.max(0, Math.min(ceiling, value));
+    }
+    let current = clamp(config.current ?? max, max);
+    let sinceDamageMs = regenDelayMs;
+    return {
+        current: () => current,
+        max: () => max,
+        setMax(value) {
+            max = Math.max(0, value);
+            current = clamp(current, max);
+        },
+        fraction: () => (max <= 0 ? 0 : current / max),
+        isFull: () => current >= max,
+        isBroken: () => current <= 0,
+        suppressed: () => sinceDamageMs < regenDelayMs,
+        damage(amount) {
+            if (amount <= 0)
+                return 0;
+            sinceDamageMs = 0;
+            const overflow = Math.max(0, amount - current);
+            current = clamp(current - amount, max);
+            return overflow;
+        },
+        restore(amount) {
+            if (amount > 0)
+                current = clamp(current + amount, max);
+        },
+        set(value) {
+            current = clamp(value, max);
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return;
+            sinceDamageMs += dtSeconds * 1000;
+            if (sinceDamageMs >= regenDelayMs)
+                current = clamp(current + regenPerSecond * dtSeconds, max);
+        },
+    };
+}

package/dist/combat/resistance.d.ts

@@ -1,13 +1,25 @@
 export type ResistVerdict = "immune" | "resist" | "normal" | "vulnerable";
-export interface ResistanceMatrix {
-    categories: Record<string, Record<string, ResistVerdict>>;
+export declare class UnknownResistanceCategoryError extends Error {
+    readonly category: string;
+    constructor(category: string);
+}
+export declare class UnknownResistancePropertyError extends Error {
+    readonly category: string;
+    readonly property: string;
+    constructor(category: string, property: string);
+}
+export interface ResistanceMatrix<TCategory extends string = string, TProperty extends string = string> {
+    categories: Partial<Record<TCategory, Partial<Record<TProperty, ResistVerdict>>>>;
+    categoryIds?: readonly TCategory[];
+    propertyIds?: readonly TProperty[];
     multipliers?: Partial<Record<ResistVerdict, number>>;
     default?: ResistVerdict;
+    unknownCategory?: ResistVerdict;
 }
 export interface ResistanceResult {
     verdict: ResistVerdict;
     multiplier: number;
     immune: boolean;
 }
-export declare function resolveResistance(matrix: ResistanceMatrix, category: string, targetProperties: readonly string[]): ResistanceResult;
-export declare function resistanceScale(matrix: ResistanceMatrix, category: string, targetProperties: readonly string[]): number;
+export declare function resolveResistance<TCategory extends string = string, TProperty extends string = string>(matrix: ResistanceMatrix<TCategory, TProperty>, category: TCategory | string, targetProperties: readonly (TProperty | string)[]): ResistanceResult;
+export declare function resistanceScale<TCategory extends string = string, TProperty extends string = string>(matrix: ResistanceMatrix<TCategory, TProperty>, category: TCategory | string, targetProperties: readonly (TProperty | string)[]): number;

package/dist/combat/resistance.js

@@ -1,3 +1,21 @@
+export class UnknownResistanceCategoryError extends Error {
+    category;
+    constructor(category) {
+        super(`Unknown resistance category: ${category}`);
+        this.name = "UnknownResistanceCategoryError";
+        this.category = category;
+    }
+}
+export class UnknownResistancePropertyError extends Error {
+    category;
+    property;
+    constructor(category, property) {
+        super(`Unknown resistance property "${property}" for category "${category}"`);
+        this.name = "UnknownResistancePropertyError";
+        this.category = category;
+        this.property = property;
+    }
+}
 const DEFAULT_MULTIPLIERS = {
     immune: 0,
     resist: 0.5,
@@ -17,13 +35,35 @@ function summaryVerdict(matrix, immune, net) {
         return "resist";
     return "normal";
 }
+function fromVerdict(matrix, verdict) {
+    if (verdict === "immune")
+        return { verdict: "immune", multiplier: 0, immune: true };
+    const multiplier = multiplierFor(matrix, verdict);
+    return { verdict, multiplier, immune: false };
+}
+function categoryTable(matrix, category) {
+    return matrix.categories[category];
+}
 export function resolveResistance(matrix, category, targetProperties) {
-    const byProperty = matrix.categories[category] ?? {};
+    const byProperty = categoryTable(matrix, category);
+    if (byProperty === undefined) {
+        if (matrix.unknownCategory !== undefined)
+            return fromVerdict(matrix, matrix.unknownCategory);
+        const catalog = matrix.categoryIds ?? Object.keys(matrix.categories);
+        if (catalog.length === 0 && matrix.default !== undefined) {
+            return fromVerdict(matrix, matrix.default);
+        }
+        throw new UnknownResistanceCategoryError(category);
+    }
+    const propertyCatalog = matrix.propertyIds !== undefined ? new Set(matrix.propertyIds) : null;
     const fallback = matrix.default ?? "normal";
     let net = 1;
     let matched = false;
     let immune = false;
     for (const property of targetProperties) {
+        if (propertyCatalog !== null && !propertyCatalog.has(property)) {
+            throw new UnknownResistancePropertyError(category, property);
+        }
         const verdict = byProperty[property];
         if (verdict === undefined)
             continue;
@@ -32,12 +72,8 @@ export function resolveResistance(matrix, category, targetProperties) {
             immune = true;
         net *= multiplierFor(matrix, verdict);
     }
-    if (!matched) {
-        if (fallback === "immune")
-            return { verdict: "immune", multiplier: 0, immune: true };
-        const multiplier = multiplierFor(matrix, fallback);
-        return { verdict: fallback, multiplier, immune: false };
-    }
+    if (!matched)
+        return fromVerdict(matrix, fallback);
     const multiplier = immune ? 0 : net;
     return { verdict: summaryVerdict(matrix, immune, multiplier), multiplier, immune };
 }

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,52 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
+import type { Aim } from "../scene/spatial.js";
+/**
+ * How a shot's world-space origin (and optional direction) is resolved before prediction/settlement.
+ * - `eye` — `aim.origin` when present, else the shooter's entity position raised to eye height; the
+ *   shot traces the shooter's sightline, so what the crosshair covers is what gets hit (the default).
+ * - `legacy` — `aim.origin` when present, else the shooter's raw entity position (feet).
+ * - `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: "eye";
+    height?: number;
+} | {
+    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;
+    /** When provided, the `eye` policy sizes its height from the shooter's own hitbox instead of the humanoid default. */
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+}
+/** Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top. */
+export declare const DEFAULT_EYE_HEIGHT: number;
+/** Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown. */
+export declare function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number;
+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,86 @@
+import { resolveColliders, worldOffset } from "../scene/colliders.js";
+const DEFAULT_MUZZLE_OFFSET = [0, 1.4, 0.35];
+const EYE_HEIGHT_RATIO = 0.9;
+/** Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top. */
+export const DEFAULT_EYE_HEIGHT = EYE_HEIGHT_RATIO * 1.8;
+/** Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown. */
+export function eyeHeightFromColliders(set) {
+    const colliders = resolveColliders(set);
+    let top = 0;
+    for (const collider of colliders) {
+        const offsetY = collider.shape.offset?.[1] ?? 0;
+        const halfHeight = collider.shape.kind === "sphere" ? collider.shape.radius : collider.shape.halfExtents[1];
+        top = Math.max(top, offsetY + halfHeight);
+    }
+    return top > 0 ? top * EYE_HEIGHT_RATIO : DEFAULT_EYE_HEIGHT;
+}
+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: "eye" }) {
+    const aimDir = aimDirection(aim);
+    if (aimDir === null && policy.kind !== "camera" && policy.kind !== "world")
+        return null;
+    switch (policy.kind) {
+        case "eye": {
+            if ("origin" in aim) {
+                if (aimDir === null)
+                    return null;
+                return { origin: aim.origin, direction: aimDir };
+            }
+            const position = deps.positionOf(from);
+            if (position === undefined || aimDir === null)
+                return null;
+            const height = policy.height ??
+                (deps.collidersOf !== undefined
+                    ? eyeHeightFromColliders(deps.collidersOf(from))
+                    : DEFAULT_EYE_HEIGHT);
+            return { origin: [position[0], position[1] + height, position[2]], direction: aimDir };
+        }
+        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) {