@adatechnology/game-items 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,755 @@
+import { BodySlot, DeepPartial } from '@adatechnology/game-contracts';
+export { BodySlot } from '@adatechnology/game-contracts';
+import { ItemDef as ItemDef$1, rng, ItemStack, SlotSpec, LootTables } from '@adatechnology/game-interactables';
+export { ItemDef as BaseItemDef } from '@adatechnology/game-interactables';
+
+/** Traits that pick any item of the catalog ("1 clothing" is any item of the category, "ingredients" is anything cookable). */
+interface RecipeMatch {
+    readonly category?: string;
+    readonly cookable?: true;
+}
+/**
+ * What a recipe consumes: one item, one of several (`any`), a fluid in `liters`, a thing of the world that is only near (`world`: furniture, ground) or any item
+ * with some traits (`match`). `qty` defaults to 1; `meters` marks a length taken from the item (the host measures it).
+ */
+interface RecipeInput {
+    item?: string;
+    any?: readonly string[];
+    fluid?: string;
+    world?: readonly string[];
+    match?: RecipeMatch;
+    qty?: number;
+    liters?: number;
+    meters?: number;
+    label?: string;
+}
+/** A tool requirement: one of `anyOf` must be in the inventory, and a station of `world` (a fire) must be near; both empty is bare hands. Tools are not consumed. */
+interface RecipeTool {
+    anyOf: readonly string[];
+    world?: readonly string[];
+    label?: string;
+}
+type RecipeOutput = {
+    item: string;
+    qty: readonly [number, number];
+    label?: string;
+    note?: string;
+} | {
+    effect: string;
+    params: Readonly<Record<string, unknown>>;
+    text?: string;
+};
+interface RecipeDef {
+    id: string;
+    inputs: readonly RecipeInput[];
+    tools: readonly RecipeTool[];
+    skill?: {
+        id: string;
+        level: number;
+    };
+    seconds: number;
+    /** Id of something the character must have unlocked first (a magazine read, a blueprint). Checked only when the host passes `unlocked`. */
+    unlockedBy?: string;
+    output: RecipeOutput;
+}
+
+/** One way of using an item, read from the team's `useItem`: which items or categories trigger it and what it does. */
+interface UseEffectDef {
+    id: string;
+    /** Id of the effect the host applies (`consume_nutrition`, `stop_bleeding`, `heal`, `calm`, `clean_wound`, `assemble_molotov`, `toggle_light`, `swap_bag`, `equip_melee`). */
+    effect: string;
+    params?: Readonly<Record<string, unknown>>;
+    /** The item is spent when used. */
+    consumes: boolean;
+    /** Items that trigger it, by id; wins over `category`. */
+    items?: readonly string[];
+    category?: readonly ItemCategory[];
+}
+
+/**
+ * Public types of @adatechnology/game-items.
+ *
+ * An `ItemDef` is a real-world thing (a can of beans, a hammer, a jacket) with its true size and weight; the rest of the fields are optional groups that
+ * only the categories that need them fill (nutrition for food, protection for clothing, carry for bags). Units: metres, kilograms, litres, days.
+ */
+
+declare const RARITIES: readonly ["common", "uncommon", "rare", "very_rare", "legendary", "unique"];
+type Rarity = (typeof RARITIES)[number];
+
+declare const BODY_SLOTS: readonly BodySlot[];
+declare const DURABILITY_KINDS: readonly ["uses", "portions", "doses", "hits", "cuts", "shots", "condition", "charges", "seconds", "days", "infinite", "container"];
+type DurabilityKind = (typeof DURABILITY_KINDS)[number];
+/** How long an item lasts, read from the source text ("10 uses", "4 portions", "300 hits", "infinite"). */
+interface Durability {
+    kind: DurabilityKind;
+    amount?: number;
+    /** Source qualifier when the amount alone is not enough (for example the voltage of a battery). */
+    per?: string;
+}
+/** Id of a place where items turn up (house, hospital, farm...). Places are a registry: a pack or the game declares the ones it uses. */
+type PlaceTag = string;
+/** Id of an item category. The 14 of `ITEM_CATEGORIES` are always present; a game adds its own through `createItems({ categories })`. */
+type ItemCategory = string;
+interface CategoryDef {
+    id: ItemCategory;
+    /** Display name in English; games translate by id. */
+    name?: string;
+}
+interface PlaceDef {
+    id: PlaceTag;
+    name?: string;
+}
+/**
+ * Where items are found inside a place (a fridge, a drawer, a locker): which categories it draws from and how many stacks. The finds roll reads `count`,
+ * `categories` (or `categoriesByPlace`, with `*` for any other place) and `places`; other fields of a pack's container are kept and ignored.
+ */
+interface ContainerDef {
+    id: string;
+    name?: string;
+    /** Places the container turns up in (`toLootTables` only); empty or missing means any. */
+    places?: readonly PlaceTag[];
+    /** Weight of each category when a stack is drawn for this container. */
+    categories?: Readonly<Record<ItemCategory, number>>;
+    /** When `categories` is missing: the weights by place (a shop shelf stocks what the shop sells). */
+    categoriesByPlace?: Readonly<Record<PlaceTag, Readonly<Record<ItemCategory, number>>>>;
+    /** Range of stacks a container holds when it is filled. */
+    count?: readonly [number, number];
+}
+/** One thing an explicit pool can hold (a fridge: water bottle, milk, eggs...): `item` is the catalog id, `weight` the odds, `qty` the range. */
+interface PoolEntry {
+    item: string;
+    weight: number;
+    qty: readonly [number, number];
+    /** Supplies (food, water, medicine, tools) are what a fortified house stocks up on. */
+    isSupply?: boolean;
+}
+interface ItemDef extends ItemDef$1 {
+    category: ItemCategory;
+    /** The old household category (`kitchen`, `hygiene`, `office`...), `perishable` or `craft_only`. */
+    tags?: readonly string[];
+    rarity: Rarity;
+    /** Litres. Derived from `size` when the pack does not give it. */
+    volume?: number;
+    durability?: Durability;
+    /** Days to spoil at room temperature. */
+    shelfLife?: number;
+    portions?: number;
+    cookable?: boolean;
+    nutrition?: {
+        satiety?: number;
+        hydration?: number;
+    };
+    /** Fractions 0..1 per attack, per body slot covered. */
+    protection?: {
+        slots: readonly BodySlot[];
+        bite?: number;
+        scratch?: number;
+        warmth?: number;
+        /** Against projectiles (read by game-characters): `resistance` in penetration units; a stopped projectile does `blunt` of its damage, one that goes through `pass`. */
+        ballistic?: {
+            resistance: number;
+            blunt?: number;
+            pass?: number;
+            consumable?: boolean;
+        };
+    };
+    carry?: {
+        capacityKg: number;
+        weightReduction: number;
+        quickSlots: number;
+        wheels?: boolean;
+    };
+    /** Id of the weapon in the arsenal when the item is also one. */
+    weapon?: string;
+    /** Id of the liquid (`game-fluids`) when the item holds one. */
+    fluid?: {
+        liquid: string;
+        liters: number;
+    };
+    uses?: readonly string[];
+    finds?: {
+        places: readonly PlaceTag[];
+    };
+    /** Battery-like items: share of the charge lost per month. */
+    charge?: {
+        lossPerMonth: number;
+    };
+    /** Fuel-like items: after `afterDays` each use fails with probability `chance`. */
+    agingFault?: {
+        afterDays: number;
+        chance: number;
+    };
+    /** Key of the 3D model in `game-items-three`; without it a simple shape from `shape` is drawn. */
+    model?: string;
+}
+/** A bundle of content: items plus the categories, places and containers they rely on. */
+interface ItemPack {
+    id: string;
+    items: readonly ItemDef[];
+    categories?: readonly CategoryDef[];
+    places?: readonly PlaceDef[];
+    containers?: readonly ContainerDef[];
+    /** What using an item does, in priority order (`resolveUse`). */
+    useEffects?: readonly UseEffectDef[];
+    recipes?: readonly RecipeDef[];
+    /** Explicit pools of what a kind of furniture holds, by key (`fridge`, `sink`...); they win over the category roll of a container. */
+    pools?: Readonly<Record<string, readonly PoolEntry[]>>;
+    /** Keys that share another key's pool (`garage_wardrobe` -> `wardrobe`). */
+    poolAliases?: Readonly<Record<string, string>>;
+}
+
+/** What a find is in: the plain world, a fortified house (stocked up) or an abandoned one (already picked over). */
+type FindState = 'normal' | 'fortified' | 'abandoned';
+/** Places whose stock falls with the days of the outbreak: `max(floor, 1 - perDay x days)` of the normal count, never below `floor`. */
+interface DepletionRule {
+    places: readonly PlaceTag[];
+    perDay: number;
+    floor: number;
+}
+/** Where an item is stored; ids of `StorageRules`. A game adds its own. */
+type StorageId = string;
+interface StorageRule {
+    /** How much faster (above 1) or slower (below 1) the item ages there. */
+    multiplier: number;
+    /** The multiplier only holds while the place has power (fridge, freezer); without it the item ages at the ambient rate. */
+    needsPower?: boolean;
+    /** The multiplier holds for this many days only, then `afterLimit` applies (a cooler with ice). */
+    limitDays?: number;
+    afterLimit?: number;
+}
+type StorageRules = Readonly<Record<StorageId, StorageRule>>;
+/** What eating food does once it is past its best; one entry per freshness state after `fresh`. */
+interface FreshnessEffect {
+    /** Multiplies the satiety and hydration the food gives. */
+    satietyFactor: number;
+    /** Chance of food poisoning. */
+    poisonChance: number;
+    /** Morale change (negative hurts). */
+    morale: number;
+    /** False when the food cannot be eaten at all. */
+    isEdible: boolean;
+}
+interface ItemRules {
+    rarity: {
+        /** Draw weight of each rarity when a stack is rolled. */
+        weights: Readonly<Record<Rarity, number>>;
+        /** Rarities that only turn up at fixed spots, never in a roll. */
+        fixedOnly: readonly Rarity[];
+    };
+    /** Where `fresh` ends and `stale`, `spoiled` and `rotten` begin, as fractions of `shelfLife`. */
+    freshness: {
+        stale: number;
+        spoiled: number;
+        rotten: number;
+    };
+    storage: StorageRules;
+    carry: {
+        /** `(baseKg + perStrengthKg × strength) × factor`. */
+        baseKg: number;
+        perStrengthKg: number;
+        factor: number;
+        /** Fractions of the maximum load: above `encumbered` the carrier is slowed, above `overloaded` it cannot run. */
+        encumbered: number;
+        overloaded: number;
+    };
+    protection: {
+        /** Highest share of an attack clothing can block: there is always some risk. */
+        cap: number;
+        /** Condition a blocked attack costs the piece. */
+        wear: {
+            bite: number;
+            scratch: number;
+        };
+        /** Share of its value a torn piece (condition 0) still protects. */
+        tornShare: number;
+        /** A repair kit restores up to the maximum condition minus this. */
+        repairMargin: number;
+    };
+    aging: {
+        /** Storage with power -> days of shelf life a food keeps when the power fails (a thawed freezer counts as fresh with 2 days to go). */
+        thawShelfDays: Readonly<Record<StorageId, number>>;
+    };
+    inventory: {
+        /** Slots of a character's bag when no bag item says otherwise. */
+        defaultSlots: number;
+        /** Running speed and breath multiplier while carrying more than `carry.encumbered` of the maximum. */
+        encumberedRunFactor: number;
+    };
+    use: {
+        freshness: Readonly<Record<'stale' | 'spoiled' | 'rotten', FreshnessEffect>>;
+        /** Cooking the food leaves this share of its poison chance. */
+        cookedPoisonFactor: number;
+    };
+    spawn: {
+        /** On day 0 of the outbreak, stock on shelves in these places appears brand new (condition 100) instead of in the team's ranges. */
+        retailNew: boolean;
+        retailPlaces: readonly PlaceTag[];
+        /** Containers that count as shelf or stock room inside a retail place; empty means every container of the place. */
+        retailContainers: readonly string[];
+        /** Condition (0..100) of a found item with wear, by rarity: `[low, high]`. */
+        condition: Readonly<Record<Rarity, readonly [number, number]>>;
+        /** Found food is already old: the days since the outbreak plus this share of its shelf life, `[low, high]`. */
+        ageShare: readonly [number, number];
+        /** Charge (0..1) of found batteries. */
+        charge: readonly [number, number];
+        /** Items found partly filled (a jerrycan) and how full, 0..1. */
+        fillable: readonly string[];
+        fill: readonly [number, number];
+    };
+    finds: {
+        /** The container whose table a container unknown to the catalog uses (the team's game falls back to a corpse). */
+        fallbackContainer: string;
+        /** Ids left out of the roll by category (the game never rolls the 7.62x39 box). */
+        rollExcluded: readonly string[];
+        depletion: readonly DepletionRule[];
+        /** Multiplies the count of a place, by region id. */
+        regionMultiplier: Readonly<Record<string, number>>;
+        /** Maps the state a host passes to one of the three the finds know. */
+        states: Readonly<Record<string, FindState>>;
+        /** The numbers of the explicit house pools (the 3D viewer's `sorteiaConteudo`). */
+        pool: {
+            /** Footprint (m²) used when the query gives none. */
+            defaultFootprint: number;
+            /** Count of a normal container: `clamp(round(offset + footprint x perSquareMetre + random x jitter), min, max)`. */
+            offset: number;
+            perSquareMetre: number;
+            jitter: number;
+            min: number;
+            max: number;
+            /** Fortified: this many more entries (up to the pool size), supplies weigh `supplyWeight` times and give `supplyExtraQty` more. */
+            fortifiedExtra: number;
+            supplyWeight: number;
+            supplyExtraQty: number;
+            /** Abandoned: this chance of being empty, otherwise `abandonedKept` entries. */
+            abandonedEmptyChance: number;
+            abandonedKept: number;
+            /** Abandoned and empty: this chance of leaving a bit of junk. */
+            junkChance: number;
+            junkItem: string;
+            /** Abandoned fridges and freezers also hold this, gone bad. */
+            spoiledFoodItem: string;
+            coldContainers: readonly string[];
+        };
+    };
+}
+
+interface ItemsOptions {
+    /** Content bundles, merged in order (a later item replaces one with the same id). */
+    packs?: readonly ItemPack[];
+    /** Changes to items, by id, applied after the packs are merged; `size`, `nutrition`, `protection`... merge field by field, arrays replace. */
+    patch?: Readonly<Record<string, DeepPartial<Omit<ItemDef, 'id'>>>>;
+    /** Ids to take out after the patches. */
+    remove?: readonly string[];
+    /** Keeps only the items it returns true for, after `remove`. */
+    include?: (item: ItemDef) => boolean;
+    /** Extra categories, places and containers, added to those of the packs (by id). */
+    categories?: readonly CategoryDef[];
+    places?: readonly PlaceDef[];
+    containers?: readonly ContainerDef[];
+    useEffects?: readonly UseEffectDef[];
+    recipes?: readonly RecipeDef[];
+    pools?: ItemPack['pools'];
+    poolAliases?: ItemPack['poolAliases'];
+    rules?: DeepPartial<ItemRules>;
+}
+interface ItemsCatalog {
+    readonly items: ReadonlyMap<string, ItemDef>;
+    readonly categories: ReadonlyMap<ItemCategory, CategoryDef>;
+    readonly places: ReadonlyMap<PlaceTag, PlaceDef>;
+    readonly containers: ReadonlyMap<string, ContainerDef>;
+    /** Explicit pools by key, with the aliases already resolved. */
+    readonly pools: ReadonlyMap<string, readonly PoolEntry[]>;
+    readonly useEffects: readonly UseEffectDef[];
+    readonly recipes: ReadonlyMap<string, RecipeDef>;
+    readonly rules: ItemRules;
+    has(id: string): boolean;
+    /** Throws on an unknown id. */
+    get(id: string): ItemDef;
+    list(): ItemDef[];
+    byCategory(category: ItemCategory): ItemDef[];
+    /** Items that can be found in `place` (`finds.places`). */
+    byPlace(place: PlaceTag): ItemDef[];
+    byTag(tag: string): ItemDef[];
+}
+
+/**
+ * Create the catalog. Order: the packs in order (added or replaced by id), then `patch`, then `remove`, then `include`; categories, places and
+ * containers are those of the packs plus the options, by id. Every inconsistency found is reported in one error.
+ */
+declare const createItems: (options?: ItemsOptions) => ItemsCatalog;
+
+interface ItemsParts {
+    readonly items: ReadonlyMap<string, ItemDef>;
+    readonly categories: ReadonlyMap<string, CategoryDef>;
+    readonly places: ReadonlyMap<string, PlaceDef>;
+    readonly containers: ReadonlyMap<string, ContainerDef>;
+    readonly rules: ItemRules;
+}
+/** Every inconsistency of a catalog, one line each; empty when it is sound. */
+declare const checkItems: (parts: ItemsParts) => string[];
+
+/** The 14 categories of the team's catalog; always registered. */
+declare const ITEM_CATEGORIES: readonly CategoryDef[];
+
+/**
+ * The numbers of the rules, from the team's Vale Cinzento delivery. `storage` was read by hand from its table (Validade e apodrecimento) so the
+ * skeleton runs; the source test of the catalog tool proves it against the HTML (legendary and unique are never rolled: L276). Every field is an option of `createItems({ rules })`.
+ */
+declare const DEFAULT_RULES: ItemRules;
+
+type Freshness = 'fresh' | 'stale' | 'spoiled' | 'rotten';
+/**
+ * What an item remembers about its age. Nothing ticks: the account is closed lazily, when the item moves or someone looks at it.
+ * Times are in days on the host's clock.
+ */
+interface AgeState {
+    /** Effective age: days at room temperature. */
+    ageDays: number;
+    /** Time at which `ageDays` was last closed. */
+    since: number;
+    storage: StorageId;
+    /** Time at which the item entered `storage` (a cooler only helps for its first days). */
+    storedAt: number;
+    /** Replaces the item's shelf life (a thawed freezer leaves 2 days). */
+    shelfLife?: number;
+}
+interface AgeOptions {
+    /** Whether the storage has power right now (fridge, freezer). Default true. */
+    powered?: boolean;
+    rules?: ItemRules;
+}
+/** The multiplier of the age at one instant: `heldDays` is how long the item has been in `storage`. */
+declare const storageMultiplier: (storage: StorageId, options?: AgeOptions & {
+    heldDays?: number;
+}) => number;
+/** Closes the account up to `now`: `ageDays += (now - since) x multiplier`. Pure: returns the new state. */
+declare const advanceAge: (state: AgeState, now: number, options?: AgeOptions) => AgeState;
+/** Moves the item to another storage: closes the account in the old one, then the new multiplier applies from `now`. */
+declare const moveToStorage: (state: AgeState, now: number, storage: StorageId, options?: AgeOptions) => AgeState;
+/** Age as a share of the shelf life; 0 for an item that does not spoil. */
+declare const shelfRatio: (item: ItemDef, state: AgeState) => number;
+/** `fresh`, `stale`, `spoiled` or `rotten` at 0.5, 1 and 1.5 of the shelf life (the rule's `freshness`). Closes the account up to `now` first. */
+declare const freshness: (item: ItemDef, state: AgeState, now: number, options?: AgeOptions) => Freshness;
+/** Charge left (0..1) of a battery-like item: it loses `charge.lossPerMonth` of the full charge per 30 days of effective age. */
+declare const chargeLevel: (item: ItemDef, initialCharge: number, ageDays: number) => number;
+/** True when one use of an old fuel-like item fails: past `agingFault.afterDays` each use fails with probability `chance`. Draws once, only when it can fail. */
+declare const failsToStart: (item: ItemDef, ageDays: number, random: () => number) => boolean;
+
+type AttackKind = 'bite' | 'scratch';
+/** A piece of clothing on a body: the item and its condition, 0 (torn) to 100 (new). */
+interface WornPiece {
+    item: ItemDef;
+    condition: number;
+}
+/** What one piece blocks of an attack: its value times its condition; a torn piece (condition 0) keeps `tornShare` of the value. */
+declare const pieceBlock: (piece: WornPiece, attack: AttackKind, rules?: ItemRules) => number;
+/** Share of an attack on `slot` that clothing blocks: `1 - PROD(1 - value x condition)`, never above the cap (there is always some risk). */
+declare const blockChance: (pieces: readonly WornPiece[], slot: BodySlot, attack: AttackKind, rules?: ItemRules) => number;
+/** A blocked attack wears every piece that covers the slot and blocks something: bite -8, scratch -3 (never below 0). */
+declare const wearBlocked: (pieces: readonly WornPiece[], slot: BodySlot, attack: AttackKind, rules?: ItemRules) => WornPiece[];
+/** A repair kit restores up to the maximum condition minus the margin (10); a piece already better is left alone. */
+declare const repairPiece: (piece: WornPiece, rules?: ItemRules, maxCondition?: number) => WornPiece;
+
+interface CarryEntry {
+    item: ItemDef;
+    count: number;
+}
+type LoadLevel = 'normal' | 'encumbered' | 'overloaded';
+interface LoadState {
+    /** Load as a share of the maximum. */
+    ratio: number;
+    level: LoadLevel;
+    /** Multiplier of running speed and breath. */
+    runFactor: number;
+    canRun: boolean;
+}
+/** What a character can carry, kg: `(8 + 2.5 x strength) x 1.2` with the default rules. */
+declare const maxLoadKg: (strength: number, rules?: ItemRules) => number;
+/** Weight carried: what is outside the bag counts in full, what is inside counts times `(1 - weightReduction)`. */
+declare const carriedKg: (parts: {
+    loose: readonly CarryEntry[];
+    packed?: readonly CarryEntry[];
+    weightReduction?: number;
+}) => number;
+/** Above 100% of the maximum, running and breath drop 25%; above 150% the character cannot run. */
+declare const loadState: (loadKg: number, maxKg: number, rules?: ItemRules) => LoadState;
+/** The bag of a character: how many item slots it has and how much it holds. */
+interface BagOption {
+    slots: number;
+    capacityKg: number;
+}
+/** The bag a bag item gives: its `carry.capacityKg` is the slot count the team's game reads from `cap`; the weight limit is the character's. */
+declare const bagOption: (bag: ItemDef | undefined, characterMaxKg: number, rules?: ItemRules) => BagOption;
+type TakeResult = 'ok' | 'bag_full' | 'too_heavy';
+/** Whether `item` can go into the bag now: first the slots, then the weight. */
+declare const canTake: (item: ItemDef, bag: BagOption, used: {
+    slots: number;
+    loadKg: number;
+}) => TakeResult;
+
+interface UseContext {
+    /** State of the food, from `freshness()`. Default `fresh`. */
+    freshness?: Freshness;
+    /** The food was cooked: it keeps only `cookedPoisonFactor` of its poison chance. */
+    isCooked?: boolean;
+}
+interface NutritionResult {
+    satiety: number;
+    hydration: number;
+    morale: number;
+    poisonChance: number;
+    isEdible: boolean;
+}
+interface UseResult {
+    useId: string;
+    effect: string;
+    params: Readonly<Record<string, unknown>>;
+    /** The item is spent (false for food too rotten to eat). */
+    consumes: boolean;
+    /** Only for `consume_nutrition`. */
+    nutrition?: NutritionResult;
+}
+/**
+ * What using `item` does, as data: the host applies it (the player, the needs, the world). Pure. The first effect that lists the item wins, then the first
+ * that lists its category; `undefined` when nothing happens. Food past its best follows `rules.use.freshness`.
+ */
+declare const resolveUse: (item: ItemDef, effects: readonly UseEffectDef[], context?: UseContext, rules?: ItemRules) => UseResult | undefined;
+
+interface CraftContext {
+    catalog: ItemsCatalog;
+    /** Count of each item the character has, by id. */
+    inventory: ReadonlyMap<string, number>;
+    /** Litres of each fluid at hand, by fluid id. */
+    fluids?: Readonly<Record<string, number>>;
+    /** Stations and things of the world that are near (`fire`, `table`, `soil`). */
+    world?: ReadonlySet<string>;
+    /** Skill levels by id. Without it the skill requirement is ignored. */
+    skills?: Readonly<Record<string, number>>;
+    /** Ids unlocked so far. Without it `unlockedBy` is ignored. */
+    unlocked?: ReadonlySet<string>;
+}
+interface CraftCheck {
+    isPossible: boolean;
+    /** One entry per unmet requirement: `item:nails`, `any:salt|sugar`, `match:cookable`, `fluid:water`, `world:fire`, `tool:hammer|axe`, `skill:carpentry:2`, `unlock:magazine`. */
+    missing: string[];
+}
+type Consumption = {
+    item: string;
+    count: number;
+    meters?: number;
+} | {
+    fluid: string;
+    liters: number;
+};
+type CraftOutcome = {
+    item: string;
+    count: number;
+} | {
+    effect: string;
+    params: Readonly<Record<string, unknown>>;
+    text?: string;
+};
+type CraftResult = {
+    isCrafted: true;
+    seconds: number;
+    consumed: Consumption[];
+    output: CraftOutcome;
+} | {
+    isCrafted: false;
+    missing: string[];
+};
+/** Whether the character can make the recipe now, and what is missing when not. Skill and `unlockedBy` are ignored when the host does not pass `skills` or `unlocked`. */
+declare const canCraft: (recipe: RecipeDef, context: CraftContext) => CraftCheck;
+/**
+ * Makes the recipe: what is consumed and what comes out. Pure: the host takes the consumed things from its inventory and applies the output (an item is
+ * added, an effect such as "window with 200 life" is the host's to handle). Draws one number only when the output quantity is a range.
+ */
+declare const craft: (recipe: RecipeDef, context: CraftContext, random: () => number) => CraftResult;
+
+/** The seeded generator of the SDK: a function returning floats in [0, 1). */
+type Rng = ReturnType<typeof rng>;
+/** Per-instance state of a found item. */
+interface FindData {
+    /** Effective age in days (food). */
+    readonly ageDays?: number;
+    /** Condition 0..100 (clothing, weapons, tools). */
+    readonly condition?: number;
+    /** Charge 0..1 (batteries). */
+    readonly charge?: number;
+    /** How full 0..1 (a jerrycan). */
+    readonly fill?: number;
+}
+/** The shape of the floorplan's `FindStack`; structurally the same, so a provider plugs in without either package importing the other. */
+interface FindStack {
+    readonly itemId: string;
+    readonly count: number;
+    readonly data?: FindData;
+}
+/** The shape of the floorplan's `FindsQuery`. */
+interface FindsQuery {
+    /** Kind of place (`house`, `supermarket`...). */
+    place: string;
+    /** Kind of container (a catalog container id such as `fridge`, or a furniture category). */
+    container: string;
+    /** `normal`, `fortified` or `abandoned` (or a name the rules map to one of them). */
+    state: string;
+    rng: Rng;
+    /** Outbreak days; 0 is the normal world. */
+    day?: number;
+    region?: string;
+    /** Footprint of the furniture in m²: sets the count of an explicit pool. */
+    footprint?: number;
+    /** Key of the explicit pool when it differs from `container`. */
+    key?: string;
+}
+/** The shape of the floorplan's `FindsProvider`: answers what a container holds; `null` says it does not know the container. */
+interface FindsProvider {
+    findsFor(query: FindsQuery): readonly FindStack[] | null;
+}
+
+/**
+ * Port of the team game's `rollItems` (jogo.js L68796-68812) on the container table (`CONT_TAB`) and the rarity weights (`RAR_W`).
+ *
+ * Order of the random draws, the contract the golden test holds: one for the count; then for each stack one to pick the category, and (unless the category
+ * has nothing to draw) one to pick the item among those of the place, by rarity weight. Nothing else draws. The count is scaled by the day and the region
+ * after it is drawn, so day 0 gives exactly the game's rolls. Returns the item ids, one per stack.
+ */
+declare const rollByCategory: (catalog: ItemsCatalog, query: FindsQuery) => string[];
+
+/** Share of the normal stock a place still has `day` days into the outbreak: `max(floor, 1 - perDay x day)`; 1 on day 0 and where no rule names the place. */
+declare const depletionFactor: (place: PlaceTag, day: number, rules: ItemRules) => number;
+/** The count of stacks after the days of the outbreak and the region: the roll is drawn first, so day 0 and an unknown region leave it as it was. */
+declare const scaleCount: (count: number, scale: {
+    place: PlaceTag;
+    day: number;
+    region?: string;
+}, rules: ItemRules) => number;
+
+interface PoolPick {
+    itemId: string;
+    count: number;
+    /** The pool entry it came from; none for the junk an abandoned container leaves. */
+    entry?: PoolEntry;
+}
+/**
+ * Port of the 3D house viewer's `sorteiaConteudo` (visor-casas-3d.js L10837-10863) over a pool of what a kind of furniture holds.
+ *
+ * Order of the random draws, the contract the golden test holds: one for the count (`base`); for an abandoned container one more (empty or not); then a full
+ * weighted order of the pool (one draw per entry, before the cut to the count); then one per kept entry for its quantity; and only for an abandoned and empty
+ * container one last draw for the junk. Fortified: more entries, supplies weigh x2.5 and give +1. Abandoned: 40% empty, otherwise one entry, plus junk and,
+ * in a fridge or freezer, spoiled food.
+ */
+declare const rollExplicitPool: (pool: readonly PoolEntry[], state: FindState, query: FindsQuery, rules: ItemRules) => PoolPick[];
+
+interface FindsProviderOptions {
+    /** `team` (default): a container with an explicit pool in the catalog uses it; `none`: always the category roll. */
+    pools?: 'team' | 'none';
+    /** Changes to the `finds` and `spawn` rules for this provider. */
+    rules?: DeepPartial<Pick<ItemRules, 'finds' | 'spawn'>>;
+    /** Names a host uses for a place, mapped to the place tags of the catalog (a floorplan `cabin` is a `lodge`). */
+    placeAliases?: Readonly<Record<string, string>>;
+    /** Places where the explicit pools apply (the viewer's pools describe dwellings); the others use the category roll. Default: every place. */
+    poolPlaces?: readonly string[];
+    /** A container with neither a pool nor a table: `fallback` (default) uses the table of `rules.finds.fallbackContainer`, like the game; `pass` answers `null` so the host's own default applies. */
+    unknownContainers?: 'fallback' | 'pass';
+}
+/**
+ * What a container holds, as the floorplan's `FindsProvider` asks it. A container with an explicit pool (`query.key` or the container id) draws from it
+ * (port of the viewer); otherwise the category roll of the game draws on the container table. Every stack is chosen first, in the order of the sources, and
+ * only then each gets its state (age, condition, charge, fill) from the same generator. Items the catalog no longer has (removed by a game) are dropped
+ * after the draws, so the others do not change.
+ */
+declare function createFindsProvider(catalog: ItemsCatalog, options: FindsProviderOptions & {
+    unknownContainers: 'pass';
+}): FindsProvider;
+declare function createFindsProvider(catalog: ItemsCatalog, options?: FindsProviderOptions): {
+    findsFor(query: FindsQuery): readonly FindStack[];
+};
+
+interface PlacedFinds {
+    /** One entry per slot, in the order of `slots`; null is empty. */
+    contents: Array<ItemStack | null>;
+    /** Stacks that fit no free slot. */
+    leftover: FindStack[];
+}
+/**
+ * Puts the stacks in the slots of a container: each in the first free slot its item fits (`fitsSize`, width and depth may swap), a stack larger than the
+ * item's `stack` splits over several slots. Pure and in order, so the same finds always land in the same slots. The result is the floorplan's `contents`.
+ */
+declare const placeFinds: (stacks: readonly FindStack[], slots: readonly SlotSpec[], catalog: ItemsCatalog) => PlacedFinds;
+
+interface LootTablesQuery {
+    place: string;
+    /** Outbreak days; 0 is the normal world. */
+    day?: number;
+    region?: string;
+}
+/**
+ * The finds as the loot tables of `game-interactables`, for worlds that have no floorplan: one table per container of the place, named by the container id.
+ * A table has one entry per rollable item, weighted by the container's category weight and the rarity (60/28/9/2.5). A slot is filled with probability
+ * `fill` = expected count / most stacks, taking the container to have as many slots as its largest count; the day and the region scale the expected count.
+ */
+declare const toLootTables: (catalog: ItemsCatalog, query: LootTablesQuery) => LootTables;
+
+/** Age of food when it turns up: the days since the outbreak plus 0 to 60% of the shelf life. On day 0 that is the normal turnover of the shelf. One draw. */
+declare const spawnAgeDays: (item: ItemDef, outbreakDays: number, random: () => number, catalog: ItemsCatalog) => number | undefined;
+/**
+ * The state an item has when it turns up, drawn after all the stacks of a container were chosen (so the choice itself matches the sources): food age, condition
+ * by rarity (100 for shop stock on day 0), battery charge and how full a jerrycan is. Draws in that order, only what applies.
+ */
+declare const spawnData: (item: ItemDef, query: FindsQuery, catalog: ItemsCatalog) => FindData | undefined;
+
+/** The part of a weapon definition the bridge reads; `WeaponDef` of `@adatechnology/game-weapons` fits it without importing the package. */
+interface ArsenalWeaponLike {
+    readonly id: string;
+    readonly mass: number;
+    readonly action: {
+        readonly kind: string;
+        readonly explosive?: string;
+    };
+    readonly dimensions?: {
+        readonly length: number;
+    };
+}
+/** The part of a calibre definition the bridge reads; `CaliberDef` fits it. */
+interface ArsenalCaliberLike {
+    readonly id: string;
+    readonly bulletGrams: number;
+    readonly pellets?: number;
+    readonly caseType?: string;
+    readonly cartridge?: {
+        readonly caseDiameter: number;
+        readonly overallLength: number;
+    };
+}
+/** The part of an `Arsenal` the bridge reads. */
+interface ArsenalLike {
+    readonly weapons: ReadonlyMap<string, ArsenalWeaponLike>;
+    readonly calibers: ReadonlyMap<string, ArsenalCaliberLike>;
+}
+/** What the team's game says of a box or an arsenal item (`ammo-boxes.json`, from its `EXTRA` table); it wins over the estimates below. */
+interface ArsenalItemRecord {
+    /** Id of the item; without it the bridge uses `ammo_<caliber>`, `firearm_<weapon>` or `throwable_<weapon>`. */
+    id?: string;
+    kind: 'ammo_box' | 'firearm' | 'throwable';
+    /** Calibre id of a box. */
+    caliber?: string;
+    /** Weapon id of a firearm or throwable; for a throwable also the explosive it uses. */
+    weapon?: string;
+    rounds?: number;
+    weight: number;
+    rarity: Rarity;
+}
+interface ArsenalItemsOptions {
+    records?: readonly ArsenalItemRecord[];
+}
+declare const ARSENAL_CATEGORIES: readonly CategoryDef[];
+/**
+ * The arsenal as items, so a bag can carry it: a box `ammo_<caliber>` for every calibre, `firearm_<id>` for every firearm and `throwable_<id>` for every
+ * throwable, with the mass and the real dimensions of the `WeaponDef` (`mass`, `dimensions.length`). A record from the team's game (`records`) gives the rounds
+ * per box, the weight and the rarity of what it listed (9x19: 20 rounds, 0.24 kg); the rest are estimated from the calibre (REF): rounds by case type,
+ * weight from the bullet. Returns a pack (with the `ammo`, `firearms` and `throwables` categories) for `createItems({ packs })`.
+ */
+declare const itemsFromArsenal: (arsenal: ArsenalLike, options?: ArsenalItemsOptions) => ItemPack;
+
+export { ARSENAL_CATEGORIES, type AgeOptions, type AgeState, type ArsenalCaliberLike, type ArsenalItemRecord, type ArsenalItemsOptions, type ArsenalLike, type ArsenalWeaponLike, type AttackKind, BODY_SLOTS, type BagOption, type CarryEntry, type CategoryDef, type Consumption, type ContainerDef, type CraftCheck, type CraftContext, type CraftOutcome, type CraftResult, DEFAULT_RULES, DURABILITY_KINDS, type DepletionRule, type Durability, type DurabilityKind, type FindData, type FindStack, type FindState, type FindsProvider, type FindsProviderOptions, type FindsQuery, type Freshness, type FreshnessEffect, ITEM_CATEGORIES, type ItemCategory, type ItemDef, type ItemPack, type ItemRules, type ItemsCatalog, type ItemsOptions, type LoadLevel, type LoadState, type LootTablesQuery, type NutritionResult, type PlaceDef, type PlaceTag, type PlacedFinds, type PoolEntry, type PoolPick, RARITIES, type Rarity, type RecipeDef, type RecipeInput, type RecipeMatch, type RecipeOutput, type RecipeTool, type Rng, type StorageId, type StorageRule, type StorageRules, type TakeResult, type UseContext, type UseEffectDef, type UseResult, type WornPiece, advanceAge, bagOption, blockChance, canCraft, canTake, carriedKg, chargeLevel, checkItems, craft, createFindsProvider, createItems, depletionFactor, failsToStart, freshness, itemsFromArsenal, loadState, maxLoadKg, moveToStorage, pieceBlock, placeFinds, repairPiece, resolveUse, rollByCategory, rollExplicitPool, scaleCount, shelfRatio, spawnAgeDays, spawnData, storageMultiplier, toLootTables, wearBlocked };