@jgengine/core 0.26.0 → 0.28.0

package/dist/inventory/shapedGrid.d.ts

@@ -79,6 +79,32 @@ export declare function findShapedPlacement<T>(grid: ShapedGrid<T>, footprint: F
  * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
  */
 export declare function placeShaped<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, origin: Cell, rotation?: Rotation): ShapedResult<T>;
+/**
+ * Why a first-fit placement failed: the footprint cannot fit an empty board at any offered rotation
+ * (`too-large`), the board is genuinely full (`no-space`), or the search hit its budget.
+ */
+export type ShapedFitRejection = "duplicate-id" | "invalid-footprint" | "too-large" | "no-space" | "budget-exceeded";
+/** A placed board, or a refusal that names why the item does not fit. */
+export type ShapedFitResult<T> = {
+    status: "ok";
+    grid: ShapedGrid<T>;
+    origin: Cell;
+    rotation: Rotation;
+    checks: number;
+} | {
+    status: "rejected";
+    reason: ShapedFitRejection;
+    detail: string;
+    checks: number;
+};
+/**
+ * Place a shaped item at the first legal spot, or say why it does not fit. Distinguishes an item that
+ * can never fit the board (`too-large`, with its footprint and the board size in `detail`) from a full
+ * board (`no-space`) and an exhausted search (`budget-exceeded`, not a full bag).
+ *
+ * @capability shaped-placement place a shaped item at its first fit and name why it does not fit
+ */
+export declare function fitShapedItem<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, options?: ShapedPlacementSearchOptions): ShapedFitResult<T>;
 /**
  * Remove one placement without mutating the source board.
  * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement

package/dist/inventory/shapedGrid.js

@@ -147,6 +147,53 @@ export function placeShaped(grid, item, origin, rotation = 0) {
     };
     return { status: "ok", grid: { ...grid, placements: [...grid.placements, placement] } };
 }
+function footprintBounds(footprint) {
+    let width = 0;
+    let height = 0;
+    for (const [c, r] of footprint) {
+        width = Math.max(width, c + 1);
+        height = Math.max(height, r + 1);
+    }
+    return { width, height };
+}
+/**
+ * Place a shaped item at the first legal spot, or say why it does not fit. Distinguishes an item that
+ * can never fit the board (`too-large`, with its footprint and the board size in `detail`) from a full
+ * board (`no-space`) and an exhausted search (`budget-exceeded`, not a full bag).
+ *
+ * @capability shaped-placement place a shaped item at its first fit and name why it does not fit
+ */
+export function fitShapedItem(grid, item, options = {}) {
+    if (grid.placements.some((placement) => placement.id === item.id)) {
+        return { status: "rejected", reason: "duplicate-id", detail: `"${item.id}" is already placed`, checks: 0 };
+    }
+    if (!validFootprint(item.footprint)) {
+        return { status: "rejected", reason: "invalid-footprint", detail: `footprint has ${item.footprint.length} cell(s)`, checks: 0 };
+    }
+    const rotations = options.rotations ?? [0, 1, 2, 3];
+    const candidates = rotations.map((rotation) => ({ rotation, bounds: footprintBounds(rotateFootprint(item.footprint, rotation)) }));
+    const fitsEmptyBoard = candidates.filter(({ bounds }) => bounds.width <= grid.width && bounds.height <= grid.height);
+    if (fitsEmptyBoard.length === 0) {
+        const bounds = footprintBounds(normalizeFootprint(item.footprint));
+        return {
+            status: "rejected",
+            reason: "too-large",
+            detail: `a ${bounds.width}×${bounds.height} item does not fit a ${grid.width}×${grid.height} board`,
+            checks: 0,
+        };
+    }
+    const fit = findShapedPlacement(grid, item.footprint, { ...options, rotations: fitsEmptyBoard.map((entry) => entry.rotation) });
+    if (fit.status !== "found") {
+        return fit.status === "budget-exceeded"
+            ? { status: "rejected", reason: "budget-exceeded", detail: `search stopped after ${fit.checks} placements`, checks: fit.checks }
+            : { status: "rejected", reason: "no-space", detail: `every position is covered after ${fit.checks} placements`, checks: fit.checks };
+    }
+    const placed = placeShaped(grid, item, fit.origin, fit.rotation);
+    if (placed.status === "rejected") {
+        return { status: "rejected", reason: "no-space", detail: placed.reason, checks: fit.checks };
+    }
+    return { status: "ok", grid: placed.grid, origin: fit.origin, rotation: fit.rotation, checks: fit.checks };
+}
 /**
  * Remove one placement without mutating the source board.
  * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement

package/dist/loot/lootGen.d.ts

@@ -0,0 +1,186 @@
+import type { AffixPool, ItemBaseDef, RarityTier, RolledAffix } from "../item/affix.js";
+import { type MountSlotDef, type PartDef } from "../item/modularItem.js";
+/** Cap on affixes one item may roll, so a bad catalog cannot make a drop cost unbounded work. */
+export declare const MAX_LOOT_AFFIXES = 8;
+/** A part a base can mount: its stats, a pick weight, and an optional word for the item name. */
+export interface LootPartDef extends PartDef {
+    /** Relative pick weight among parts eligible for the same slot (default `1`). */
+    weight?: number;
+    /** Word this part adds to the generated name, e.g. `"Riveted"`. */
+    namePart?: string;
+}
+/** A base family (frame, housing, chassis — caller nouns) with its slots, stats and affix pools. */
+export interface LootBaseDef extends ItemBaseDef {
+    /** Relative pick weight among bases a manufacturer can produce (default `1`). */
+    weight?: number;
+    /** Free-form tags for caller filters and UI. */
+    tags?: readonly string[];
+    /** Mount slots a roll fills; every declared slot receives one part. */
+    slots?: readonly MountSlotDef[];
+}
+/**
+ * A maker with a stat personality: its mark goes in the name, `bias` shifts stats additively,
+ * `scale` multiplies them, and favored affix pools weigh more when this maker rolls the item.
+ */
+export interface LootManufacturerDef {
+    id: string;
+    /** The maker's mark as it reads in the item name. */
+    name: string;
+    /** Relative pick weight among manufacturers (default `1`). */
+    weight?: number;
+    /** Base ids this maker produces; omitted means every base. */
+    bases?: readonly string[];
+    /** Flat stat shifts applied after level scaling and rarity scaling. */
+    bias?: Readonly<Record<string, number>>;
+    /** Per-stat multipliers applied after `bias`. */
+    scale?: Readonly<Record<string, number>>;
+    /** Affix pool ids this maker favors. */
+    favoredPools?: readonly string[];
+    /** Weight multiplier for an affix from a favored pool (default `3`). */
+    favoredWeight?: number;
+}
+/** Everything a roll reads: bases, parts, affixes, rarity odds, makers and the level curve. */
+export interface LootCatalog {
+    bases: readonly LootBaseDef[];
+    parts: readonly LootPartDef[];
+    pools: readonly AffixPool[];
+    rarities: readonly RarityTier[];
+    manufacturers: readonly LootManufacturerDef[];
+    /** `[level, multiplier]` points, linearly interpolated and clamped; omitted means no level scaling. */
+    levelScale?: readonly (readonly [number, number])[];
+}
+/** One part occupying one slot of a rolled item. */
+export interface LootInstalledPart {
+    slotId: string;
+    partId: string;
+    category: string;
+}
+/**
+ * One rolled item: the base, maker, rarity, level, composed name, chosen parts, rolled affixes and
+ * resolved stats. Plain JSON, so a save stores it and the instance registry can key it.
+ */
+export interface LootItem {
+    /** Base definition id; also the registry `baseId` a generated drop is stored under. */
+    baseId: string;
+    manufacturer: string;
+    rarity: string;
+    level: number;
+    name: string;
+    parts: readonly LootInstalledPart[];
+    affixes: readonly RolledAffix[];
+    stats: Readonly<Record<string, number>>;
+}
+/** Pin any part of a roll; omitted fields are drawn from the catalog. */
+export interface LootRollOptions {
+    /** Item level, integer `>= 1` (default `1`). */
+    level?: number;
+    baseId?: string;
+    manufacturer?: string;
+    rarity?: string;
+}
+/** A defect found by {@link validateLootItem}. */
+export type LootIssueCode = "invalid-level" | "unknown-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "empty-name";
+/** One reason a rolled item is not legal against its catalog, with the offending value named. */
+export interface LootValidationIssue {
+    code: LootIssueCode;
+    detail: string;
+}
+/** A per-stat comparison entry; `delta` is `b - a`, so positive means the second item is larger. */
+export interface LootStatDelta {
+    stat: string;
+    a: number;
+    b: number;
+    delta: number;
+}
+/** How two items compare: every stat delta plus one weighted score for each. */
+export interface LootComparison {
+    /** Union of both items' stats, sorted by stat id. Missing stats count as `0`. */
+    deltas: readonly LootStatDelta[];
+    scoreA: number;
+    scoreB: number;
+    /** `scoreB - scoreA`. */
+    scoreDelta: number;
+    better: "a" | "b" | "equal";
+}
+/** Caller policy for the comparison score. */
+export interface LootComparisonOptions {
+    /** Weight per stat in the score (default `1` each). */
+    weights?: Readonly<Record<string, number>>;
+    /** Stats where a smaller number is better, e.g. reload time; flips their score sign. */
+    lowerIsBetter?: readonly string[];
+    /** Score difference under which the items count as equal (default `1e-9`). */
+    tolerance?: number;
+}
+/** Saved counters of a {@link LootRoller}. */
+export interface LootRollerState {
+    rolls: number;
+    byRarity: Readonly<Record<string, number>>;
+}
+/** Options for {@link createLootRoller}. */
+export interface LootRollerOptions {
+    /** Register a devtools probe under this name reporting roll counts per rarity. */
+    devtoolsName?: string;
+}
+/**
+ * A roll counter over one catalog: every roll goes through {@link rollLoot}, and the handle keeps
+ * counters (a distribution readout in the debug overlay) that snapshot and restore as plain data.
+ */
+export interface LootRoller {
+    roll(rng: () => number, options?: LootRollOptions): LootItem;
+    stats(): LootRollerState;
+    snapshot(): LootRollerState;
+    /** Replace counters; returns false without mutation when the state is malformed. */
+    restore(next: LootRollerState): boolean;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/** Check a catalog before rolling; throws `RangeError` naming the offending entry. */
+export declare function assertLootCatalog(catalog: LootCatalog): void;
+/** Stat multiplier at `level` from the catalog's level curve; `1` when the catalog declares none. */
+export declare function lootLevelScale(catalog: LootCatalog, level: number): number;
+/**
+ * Roll one item from a catalog: a base and maker, a weighted rarity, one part per slot, rarity-count
+ * affixes, level-scaled stats and a name composed from maker, rarity, part, affix words and base.
+ * Deterministic for a given `rng`; every field it reads is caller data. Validate a catalog built
+ * outside {@link createLootRoller} once with {@link assertLootCatalog} before rolling from it.
+ *
+ * @capability loot-generation roll a named item from bases, parts, affixes, rarity weights, manufacturer personalities and level scaling
+ */
+export declare function rollLoot(catalog: LootCatalog, rng: () => number, options?: LootRollOptions): LootItem;
+/**
+ * Check one rolled item against its catalog: base, maker and rarity exist, every slot holds an
+ * eligible part, affixes belong to the base's pools, stats are finite and the item is named.
+ *
+ * @capability loot-validation check a rolled item against its catalog and report each defect with its code
+ */
+export declare function validateLootItem(item: LootItem, catalog: LootCatalog): LootValidationIssue[];
+/**
+ * Per-stat weighted contribution: `value × weight`, negated for stats listed in `lowerIsBetter`.
+ * This is the single weight policy behind {@link scoreLootStats}, {@link compareLootItems} and a
+ * gear score, so an item and a whole loadout are never ranked by different arithmetic.
+ *
+ * @capability loot-score split one stat block into per-stat weighted contributions
+ */
+export declare function lootStatContributions(stats: Readonly<Record<string, number>>, options?: Pick<LootComparisonOptions, "weights" | "lowerIsBetter">): Record<string, number>;
+/**
+ * One stat block's weighted score: the sum of `value × weight`, negated for stats listed in
+ * `lowerIsBetter`. Pair it with {@link lootStatContributions} when a caller also needs the split.
+ *
+ * @capability loot-score score one stat block with caller weights and lower-is-better stats
+ */
+export declare function scoreLootStats(stats: Readonly<Record<string, number>>, options?: Pick<LootComparisonOptions, "weights" | "lowerIsBetter">): number;
+/**
+ * Compare two rolled items: every stat delta plus one weighted score for each, with caller-named
+ * weights and which stats read better when small.
+ *
+ * @capability loot-comparison compare two rolled items with per-stat deltas and a weighted score
+ */
+export declare function compareLootItems(a: LootItem, b: LootItem, options?: LootComparisonOptions): LootComparison;
+/**
+ * Wrap a catalog in a roll counter: same results as {@link rollLoot}, plus counts by rarity for a
+ * debug overlay, snapshot/restore of those counts, and an optional devtools probe.
+ *
+ * @capability loot-roller roll items from one validated catalog while counting drops per rarity for a debug probe
+ */
+export declare function createLootRoller(catalog: LootCatalog, options?: LootRollerOptions): LootRoller;