@jgengine/core 0.9.0 → 0.11.0

package/dist/inventory/shapedGrid.js

@@ -1,6 +1,7 @@
 function cellKey(cell) {
     return `${cell[0]},${cell[1]}`;
 }
+/** @internal */
 export function normalizeFootprint(footprint) {
     if (footprint.length === 0)
         return [];
@@ -25,6 +26,7 @@ export function normalizeFootprint(footprint) {
     }
     return out;
 }
+/** @internal */
 export function rotateFootprint(footprint, rotation) {
     const turns = ((rotation % 4) + 4) % 4;
     let cells = footprint.map(([c, r]) => [c, r]);
@@ -33,10 +35,17 @@ export function rotateFootprint(footprint, rotation) {
     }
     return normalizeFootprint(cells);
 }
+/** @internal */
 export function occupiedCells(footprint, origin, rotation) {
     const rotated = rotateFootprint(footprint, rotation);
     return rotated.map(([c, r]) => [c + origin[0], r + origin[1]]);
 }
+/**
+ * A spatial grid inventory that holds shaped multi-cell items, Resident-Evil/Tarkov style.
+ *
+ * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
+  * @internal
+  */
 export function createShapedGrid(width, height) {
     if (width <= 0 || height <= 0)
         throw new Error("shaped grid needs positive dimensions");
@@ -56,6 +65,7 @@ function occupancyMap(grid, ignoreId) {
     }
     return map;
 }
+/** @internal */
 export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     const cells = occupiedCells(footprint, origin, rotation);
     if (!inBounds(grid, cells))
@@ -67,6 +77,7 @@ export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     }
     return null;
 }
+/** @internal */
 export function placeShaped(grid, item, origin, rotation = 0) {
     if (grid.placements.some((p) => p.id === item.id)) {
         return { status: "rejected", reason: "duplicate-id", detail: item.id };
@@ -83,12 +94,14 @@ export function placeShaped(grid, item, origin, rotation = 0) {
     };
     return { status: "ok", grid: { ...grid, placements: [...grid.placements, placement] } };
 }
+/** @internal */
 export function removeShaped(grid, id) {
     if (!grid.placements.some((p) => p.id === id)) {
         return { status: "rejected", reason: "unknown-id", detail: id };
     }
     return { status: "ok", grid: { ...grid, placements: grid.placements.filter((p) => p.id !== id) } };
 }
+/** @internal */
 export function moveShaped(grid, id, origin, rotation) {
     const existing = grid.placements.find((p) => p.id === id);
     if (existing === undefined)
@@ -105,6 +118,7 @@ export function moveShaped(grid, id, origin, rotation) {
         },
     };
 }
+/** @internal */
 export function cellOccupant(grid, cell) {
     return occupancyMap(grid).get(cellKey(cell)) ?? null;
 }
@@ -120,6 +134,7 @@ const DIAGONAL = [
     [-1, 1],
     [-1, -1],
 ];
+/** @internal */
 export function gridAdjacencyQuery(grid, options = {}) {
     const directions = options.diagonal ? [...ORTHOGONAL, ...DIAGONAL] : ORTHOGONAL;
     const cellsById = new Map();
@@ -168,6 +183,7 @@ export function gridAdjacencyQuery(grid, options = {}) {
         },
     };
 }
+/** @internal */
 export function cellFromPoint(point, cellSize, gridOrigin = { x: 0, y: 0 }) {
     return [
         Math.floor((point.x - gridOrigin.x) / cellSize),

package/dist/inventory/slotModel.d.ts

@@ -7,13 +7,23 @@ export type SlotResult<T> = {
     status: "rejected";
     reason: "invalid-slot" | "slot-occupied" | "empty-slot";
 };
+/** @internal */
 export declare function createSlots<T>(size: number): Slot<T>[];
+/** @internal */
 export declare function normalizeSlots<T>(values: SlotGrid<T>, size: number): Slot<T>[];
+/** @internal */
 export declare function placeAt<T>(grid: SlotGrid<T>, index: number, value: T): SlotResult<T>;
+/** @internal */
 export declare function removeAt<T>(grid: SlotGrid<T>, index: number): SlotResult<T>;
+/** @internal */
 export declare function moveSlot<T>(grid: SlotGrid<T>, from: number, to: number): SlotResult<T>;
+/** @internal */
 export declare function firstEmpty<T>(grid: SlotGrid<T>): number | null;
+/** @internal */
 export declare function insertFirst<T>(grid: SlotGrid<T>, value: T): SlotResult<T>;
+/** @internal */
 export declare function compactSlots<T>(grid: SlotGrid<T>): Slot<T>[];
+/** @internal */
 export declare function countFilled<T>(grid: SlotGrid<T>): number;
+/** @internal */
 export declare function indexOfSlot<T>(grid: SlotGrid<T>, match: (value: T, index: number) => boolean): number | null;

package/dist/inventory/slotModel.js

@@ -1,6 +1,8 @@
+/** @internal */
 export function createSlots(size) {
     return new Array(Math.max(0, size)).fill(null);
 }
+/** @internal */
 export function normalizeSlots(values, size) {
     const grid = createSlots(size);
     for (let index = 0; index < size; index++)
@@ -10,6 +12,7 @@ export function normalizeSlots(values, size) {
 function inRange(grid, index) {
     return Number.isInteger(index) && index >= 0 && index < grid.length;
 }
+/** @internal */
 export function placeAt(grid, index, value) {
     if (!inRange(grid, index))
         return { status: "rejected", reason: "invalid-slot" };
@@ -19,6 +22,7 @@ export function placeAt(grid, index, value) {
     next[index] = value;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function removeAt(grid, index) {
     if (!inRange(grid, index))
         return { status: "rejected", reason: "invalid-slot" };
@@ -28,6 +32,7 @@ export function removeAt(grid, index) {
     next[index] = null;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function moveSlot(grid, from, to) {
     if (!inRange(grid, from) || !inRange(grid, to))
         return { status: "rejected", reason: "invalid-slot" };
@@ -39,6 +44,7 @@ export function moveSlot(grid, from, to) {
     next[to] = moved;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function firstEmpty(grid) {
     for (let index = 0; index < grid.length; index++) {
         if (grid[index] === null)
@@ -46,12 +52,14 @@ export function firstEmpty(grid) {
     }
     return null;
 }
+/** @internal */
 export function insertFirst(grid, value) {
     const index = firstEmpty(grid);
     if (index === null)
         return { status: "rejected", reason: "slot-occupied" };
     return placeAt(grid, index, value);
 }
+/** @internal */
 export function compactSlots(grid) {
     const filled = grid.filter((slot) => slot !== null);
     const next = createSlots(grid.length);
@@ -59,6 +67,7 @@ export function compactSlots(grid) {
         next[index] = filled[index];
     return next;
 }
+/** @internal */
 export function countFilled(grid) {
     let count = 0;
     for (const slot of grid)
@@ -66,6 +75,7 @@ export function countFilled(grid) {
             count += 1;
     return count;
 }
+/** @internal */
 export function indexOfSlot(grid, match) {
     for (let index = 0; index < grid.length; index++) {
         const slot = grid[index];

package/dist/item/durability.d.ts

@@ -33,6 +33,11 @@ export declare function durabilityFraction(state: DurabilityState): number;
 export declare function isBroken(state: DurabilityState): boolean;
 export declare function isDisabled(spec: DurabilitySpec, state: DurabilityState): boolean;
 export declare function wearAmount(spec: DurabilitySpec, kind: WearKind): number;
+/**
+ * Apply wear to an item, tracking breakage and repair eligibility.
+ *
+ * @capability durability track item wear, breakage, and repair
+ */
 export declare function applyWear(state: DurabilityState, amount: number): DurabilityState;
 export declare function wear(spec: DurabilitySpec, state: DurabilityState, kind: WearKind, times?: number): DurabilityState;
 export declare function canRepairAt(spec: DurabilitySpec, stationId?: string): boolean;

package/dist/item/durability.js

@@ -17,6 +17,11 @@ export function isDisabled(spec, state) {
 export function wearAmount(spec, kind) {
     return kind === "use" ? spec.wearPerUse ?? 0 : spec.wearPerHit ?? 0;
 }
+/**
+ * Apply wear to an item, tracking breakage and repair eligibility.
+ *
+ * @capability durability track item wear, breakage, and repair
+ */
 export function applyWear(state, amount) {
     if (amount <= 0)
         return state;

package/dist/item/itemIdentity.d.ts

@@ -0,0 +1,171 @@
+import type { InstalledPart, PartDef } from "./modularItem.js";
+/**
+ * The declarative identity of a built modular item: a caller-named family, its
+ * provenance tags, and the parts occupying its slots. This is the "what an item
+ * is" layer above the raw stat rollup in ./modularItem — a plain, serializable
+ * value with no game noun baked in ("gun", "manufacturer", "potion" are all
+ * caller data in `family`/`tags`).
+ */
+export interface ItemIdentity {
+    family: string;
+    tags: readonly string[];
+    parts: readonly InstalledPart[];
+}
+/**
+ * A predicate over an {@link ItemIdentity}, expressed as data so a whole rule
+ * set round-trips through JSON. An empty query matches every identity; each
+ * present field narrows the match and all present fields must hold (AND).
+ */
+export interface IdentityQuery {
+    /** Match only this family id; omit to match any family. */
+    family?: string;
+    /** Every listed tag must be present on the identity. */
+    allTags?: readonly string[];
+    /** At least one listed tag must be present on the identity. */
+    anyTags?: readonly string[];
+    /** A part of this category must occupy some slot. */
+    hasCategory?: string;
+    /** A part with this id must occupy some slot. */
+    hasPart?: string;
+}
+/**
+ * A rule that requires a second condition to hold whenever the first matches —
+ * e.g. "a scoped rifle requires a stock". Checked at completeness time, not
+ * during incremental placement, because the `then` side may be satisfied by a
+ * part chosen later in a generation pass.
+ */
+export interface RequireRule {
+    id: string;
+    kind: "require";
+    when: IdentityQuery;
+    then: IdentityQuery;
+    message?: string;
+}
+/**
+ * A rule that forbids a combination — e.g. "an incendiary barrel cannot pair
+ * with a cryo core". A forbid rule can never become satisfiable by adding more
+ * parts, so it is the check a backtracking generator runs on each candidate.
+ */
+export interface ForbidRule {
+    id: string;
+    kind: "forbid";
+    when: IdentityQuery;
+    forbid: IdentityQuery;
+    message?: string;
+}
+/**
+ * A cross-slot compatibility rule constraining which part/tag/family
+ * combinations a modular item may hold.
+ */
+export type CompatibilityRule = RequireRule | ForbidRule;
+/**
+ * A match/set bonus: extra stats granted when enough parts (or a tag) of a
+ * given kind are present — e.g. "3 Blackwood parts grant +recoil control".
+ * Counting is declarative (`countBy`/`value`) so the whole catalog is data.
+ */
+export interface SetBonus {
+    id: string;
+    /** Dimension counted for membership: a part category, a part id, or an identity tag. */
+    countBy: "category" | "partId" | "tag";
+    /** The value counted; membership is the number of matching parts (or 0/1 for a tag). */
+    value: string;
+    /** Minimum matching count for the bonus to activate. */
+    min: number;
+    /** Additive stat deltas applied when the bonus is active. */
+    stats: Record<string, number>;
+    /** Optional name fragment recorded in provenance/UI when active. */
+    namePart?: string;
+}
+/**
+ * One failed {@link CompatibilityRule}, carrying the rule id, its kind, and a
+ * human-readable message for UI or generator diagnostics.
+ */
+export interface ConstraintViolation {
+    ruleId: string;
+    kind: "require" | "forbid";
+    message: string;
+}
+/**
+ * A part proposed for a slot during generation, before it is committed to an
+ * identity. Used by the backtracking contract to test a placement in isolation.
+ */
+export interface CandidatePlacement {
+    slotId: string;
+    part: PartDef;
+}
+/**
+ * The serializable record of how an item was generated: its family, tags,
+ * per-slot part selection, applied set-bonus ids, and the deterministic seed.
+ * Enough for UI provenance display and byte-exact regeneration.
+ */
+export interface ItemProvenance {
+    family: string;
+    tags: readonly string[];
+    /** slotId -> partId of the selected parts. */
+    parts: Readonly<Record<string, string>>;
+    /** Ids of the set bonuses that were active, for display and re-derivation. */
+    bonuses: readonly string[];
+    /** Seed of the roll that produced this item; omit for hand-authored items. */
+    seed?: number;
+}
+/**
+ * Assemble an {@link ItemIdentity} from a family, tags, and installed parts.
+ *
+ * @capability item-identity assemble a serializable modular-item identity from family, tags, and installed parts
+ */
+export declare function identityOf(family: string, tags: readonly string[], parts: readonly InstalledPart[]): ItemIdentity;
+/**
+ * Test whether an identity satisfies a declarative {@link IdentityQuery}.
+ *
+ * @capability item-identity evaluate a data-defined compatibility query against a modular-item identity
+ */
+export declare function matchesQuery(identity: ItemIdentity, query: IdentityQuery): boolean;
+/**
+ * Collect every compatibility rule a completed identity violates. An empty
+ * result means the identity is legal.
+ *
+ * @capability item-identity validate a completed modular item against its compatibility rule set
+ */
+export declare function validateIdentity(identity: ItemIdentity, rules: readonly CompatibilityRule[]): ConstraintViolation[];
+/**
+ * Convenience predicate: true when {@link validateIdentity} finds no violations.
+ *
+ * @capability item-identity check whether a completed modular item is compatibility-valid
+ */
+export declare function isIdentityValid(identity: ItemIdentity, rules: readonly CompatibilityRule[]): boolean;
+/**
+ * The generic backtracking contract for procedural generation (see #908): given
+ * a partial identity and a candidate part, return the first forbid rule the
+ * placement would violate, or null if it stays viable. Require rules are ignored
+ * here because they may still be satisfied by a later placement.
+ *
+ * @capability item-identity test a candidate part placement against forbid rules for generation backtracking
+ */
+export declare function candidateViolatesForbid(partial: ItemIdentity, candidate: CandidatePlacement, rules: readonly CompatibilityRule[]): ForbidRule | null;
+/**
+ * Count how many parts (or tags) contribute to a set bonus on an identity.
+ *
+ * @capability item-identity count set-bonus membership across an item's parts and tags
+ */
+export declare function countSetMembers(identity: ItemIdentity, bonus: SetBonus): number;
+/**
+ * Select the set bonuses whose membership count meets their threshold, in the
+ * order they were declared.
+ *
+ * @capability item-identity resolve which match/set bonuses an item qualifies for
+ */
+export declare function activeSetBonuses(identity: ItemIdentity, bonuses: readonly SetBonus[]): SetBonus[];
+/**
+ * Fold a set of active bonuses' additive stats onto a stat map, returning a new
+ * map (the input is not mutated).
+ *
+ * @capability item-identity apply active set-bonus stats onto an item's resolved stats
+ */
+export declare function applySetBonuses(stats: Record<string, number>, bonuses: readonly SetBonus[]): Record<string, number>;
+/**
+ * Capture the provenance of a generated item — family, tags, per-slot parts,
+ * active bonus ids, and optional seed — as a JSON-safe record.
+ *
+ * @capability item-identity capture serializable provenance for UI display and deterministic regeneration
+ */
+export declare function captureProvenance(identity: ItemIdentity, activeBonuses: readonly SetBonus[], seed?: number): ItemProvenance;

package/dist/item/itemIdentity.js

@@ -0,0 +1,138 @@
+/**
+ * Assemble an {@link ItemIdentity} from a family, tags, and installed parts.
+ *
+ * @capability item-identity assemble a serializable modular-item identity from family, tags, and installed parts
+ */
+export function identityOf(family, tags, parts) {
+    return { family, tags, parts };
+}
+function hasCategory(identity, category) {
+    return identity.parts.some((installed) => installed.part.category === category);
+}
+function hasPart(identity, partId) {
+    return identity.parts.some((installed) => installed.part.id === partId);
+}
+/**
+ * Test whether an identity satisfies a declarative {@link IdentityQuery}.
+ *
+ * @capability item-identity evaluate a data-defined compatibility query against a modular-item identity
+ */
+export function matchesQuery(identity, query) {
+    if (query.family !== undefined && query.family !== identity.family)
+        return false;
+    if (query.allTags !== undefined && !query.allTags.every((tag) => identity.tags.includes(tag)))
+        return false;
+    if (query.anyTags !== undefined && !query.anyTags.some((tag) => identity.tags.includes(tag)))
+        return false;
+    if (query.hasCategory !== undefined && !hasCategory(identity, query.hasCategory))
+        return false;
+    if (query.hasPart !== undefined && !hasPart(identity, query.hasPart))
+        return false;
+    return true;
+}
+function ruleFails(identity, rule) {
+    if (!matchesQuery(identity, rule.when))
+        return false;
+    return rule.kind === "require" ? !matchesQuery(identity, rule.then) : matchesQuery(identity, rule.forbid);
+}
+function defaultMessage(rule) {
+    return rule.message ?? (rule.kind === "require" ? `${rule.id}: required combination missing` : `${rule.id}: forbidden combination`);
+}
+/**
+ * Collect every compatibility rule a completed identity violates. An empty
+ * result means the identity is legal.
+ *
+ * @capability item-identity validate a completed modular item against its compatibility rule set
+ */
+export function validateIdentity(identity, rules) {
+    const violations = [];
+    for (const rule of rules) {
+        if (ruleFails(identity, rule))
+            violations.push({ ruleId: rule.id, kind: rule.kind, message: defaultMessage(rule) });
+    }
+    return violations;
+}
+/**
+ * Convenience predicate: true when {@link validateIdentity} finds no violations.
+ *
+ * @capability item-identity check whether a completed modular item is compatibility-valid
+ */
+export function isIdentityValid(identity, rules) {
+    return validateIdentity(identity, rules).length === 0;
+}
+/**
+ * The generic backtracking contract for procedural generation (see #908): given
+ * a partial identity and a candidate part, return the first forbid rule the
+ * placement would violate, or null if it stays viable. Require rules are ignored
+ * here because they may still be satisfied by a later placement.
+ *
+ * @capability item-identity test a candidate part placement against forbid rules for generation backtracking
+ */
+export function candidateViolatesForbid(partial, candidate, rules) {
+    const projected = {
+        family: partial.family,
+        tags: partial.tags,
+        parts: [...partial.parts, { slotId: candidate.slotId, part: candidate.part }],
+    };
+    for (const rule of rules) {
+        if (rule.kind === "forbid" && ruleFails(projected, rule))
+            return rule;
+    }
+    return null;
+}
+/**
+ * Count how many parts (or tags) contribute to a set bonus on an identity.
+ *
+ * @capability item-identity count set-bonus membership across an item's parts and tags
+ */
+export function countSetMembers(identity, bonus) {
+    switch (bonus.countBy) {
+        case "category":
+            return identity.parts.filter((installed) => installed.part.category === bonus.value).length;
+        case "partId":
+            return identity.parts.filter((installed) => installed.part.id === bonus.value).length;
+        case "tag":
+            return identity.tags.includes(bonus.value) ? 1 : 0;
+    }
+}
+/**
+ * Select the set bonuses whose membership count meets their threshold, in the
+ * order they were declared.
+ *
+ * @capability item-identity resolve which match/set bonuses an item qualifies for
+ */
+export function activeSetBonuses(identity, bonuses) {
+    return bonuses.filter((bonus) => countSetMembers(identity, bonus) >= bonus.min);
+}
+/**
+ * Fold a set of active bonuses' additive stats onto a stat map, returning a new
+ * map (the input is not mutated).
+ *
+ * @capability item-identity apply active set-bonus stats onto an item's resolved stats
+ */
+export function applySetBonuses(stats, bonuses) {
+    const out = { ...stats };
+    for (const bonus of bonuses) {
+        for (const [key, delta] of Object.entries(bonus.stats))
+            out[key] = (out[key] ?? 0) + delta;
+    }
+    return out;
+}
+/**
+ * Capture the provenance of a generated item — family, tags, per-slot parts,
+ * active bonus ids, and optional seed — as a JSON-safe record.
+ *
+ * @capability item-identity capture serializable provenance for UI display and deterministic regeneration
+ */
+export function captureProvenance(identity, activeBonuses, seed) {
+    const parts = {};
+    for (const installed of identity.parts)
+        parts[installed.slotId] = installed.part.id;
+    return {
+        family: identity.family,
+        tags: [...identity.tags],
+        parts,
+        bonuses: activeBonuses.map((bonus) => bonus.id),
+        ...(seed === undefined ? {} : { seed }),
+    };
+}

package/dist/item/itemInstanceRegistry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A runtime store for procedurally generated item instances — a rolled unique gun, a rolled
+ * affixed relic — keyed by a generated id distinct from any static catalog id. The counterpart a
+ * game's `content.itemById` consults for ids `lootTable`'s `generate` entries hand back, so runtime
+ * rolls never need a hand-rolled parallel registry (#536.1).
+ */
+export interface ItemInstanceRegistry<TDef> {
+    /** Stores `def` under a fresh generated id derived from `baseId`; returns that id. */
+    register(baseId: string, def: TDef): string;
+    get(id: string): TDef | undefined;
+    has(id: string): boolean;
+    /** Drop a generated instance once nothing references it (consumed, destroyed, sold). */
+    release(id: string): void;
+    count(): number;
+}
+/**
+ * Builds an {@link ItemInstanceRegistry}; generated ids are `"<prefix>:<baseId>:<n>"`, unique per
+ * registry instance.
+ *
+ * @capability item-instance-registry a runtime store for procedurally generated item instances
+ */
+export declare function createItemInstanceRegistry<TDef>(prefix?: string): ItemInstanceRegistry<TDef>;
+/**
+ * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
+ * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.
+ *
+ * @capability item-instance-registry roll and register a procedural item as a loot-table drop
+ */
+export declare function proceduralLootEntry<TDef>(registry: ItemInstanceRegistry<TDef>, roll: (rng: () => number) => {
+    baseId: string;
+    def: TDef;
+}): (rng: () => number) => string;

package/dist/item/itemInstanceRegistry.js

@@ -0,0 +1,34 @@
+/**
+ * Builds an {@link ItemInstanceRegistry}; generated ids are `"<prefix>:<baseId>:<n>"`, unique per
+ * registry instance.
+ *
+ * @capability item-instance-registry a runtime store for procedurally generated item instances
+ */
+export function createItemInstanceRegistry(prefix = "item") {
+    let seq = 0;
+    const store = new Map();
+    return {
+        register(baseId, def) {
+            seq += 1;
+            const id = `${prefix}:${baseId}:${seq}`;
+            store.set(id, def);
+            return id;
+        },
+        get: (id) => store.get(id),
+        has: (id) => store.has(id),
+        release: (id) => void store.delete(id),
+        count: () => store.size,
+    };
+}
+/**
+ * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
+ * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.
+ *
+ * @capability item-instance-registry roll and register a procedural item as a loot-table drop
+ */
+export function proceduralLootEntry(registry, roll) {
+    return (rng) => {
+        const rolled = roll(rng);
+        return registry.register(rolled.baseId, rolled.def);
+    };
+}