@adatechnology/game-items-goods 0.1.5 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@ Catalog of real-world items for [`@adatechnology/game-items`](../game-items): **
 melee reach and noise) and the texts in pt-BR (the team's own names) and en. It is data and a thin typed wrapper: no logic, no renderer, no game.
 
 The data is **generated** by `tools/items-catalog` from the Vale Cinzento delivery (Itens page, the game, the 3D house viewer) and the household items of the SDK; do not edit
-`src/data/*.json` by hand (except `src/data/locales/en.json`, the English translation, which is kept by hand). Run `pnpm --filter @adatechnology/items-catalog-tool catalog` after changing `decisions.json`.
+`src/data/*.json` by hand (except `src/data/locales/en.json`, the English translation, `kinds.json`, `item-contracts.json` and `known-gaps.json`, which are kept by hand; what the kinds add to each item lives in `tools/items-catalog/kinds-overlay.json`). Run `pnpm --filter @adatechnology/items-catalog-tool catalog` after changing `decisions.json`.
 
 ## Install
 
@@ -40,7 +40,8 @@ GOODS_STRINGS.en['place.pharmacy']             // 'Pharmacy'
 | `GOODS_TABLES` | rarities, storage, depletion, spawn numbers and melee stats as read (the `DEFAULT_RULES` of the engine are proven equal to them by test) |
 | `GOODS_ARSENAL_RECORDS` | ammo boxes, three firearms and two throwables of the game's `EXTRA`, for `itemsFromArsenal(arsenal, { records })` |
 | `GOODS_PROVENANCE` | per item: the team id, the household id, the viewer pool types, the game ids, and where the id and the measure come from |
-| `GOODS_STRINGS`, `goodsText(key, locale?)`, `pickGoodsLocale` | texts by key: `item.<id>`, `category.<id>`, `place.<id>`, `rarity.<id>`, `container.<id>`, `recipe.<id>` |
+| `GOODS_KINDS`, `createGoodsKinds(options?)`, `checkGoodsItems(options?)`, `ITEM_CONTRACTS`, `createItemContracts(options?)`, `GOODS_KNOWN_GAPS` | the tree of kinds, its registry, the validator over the catalog, the contract checkers and the allowed gaps |
+| `GOODS_STRINGS`, `goodsText(key, locale?)`, `pickGoodsLocale` | texts by key: `item.<id>`, `kind.<id>`, `kind.<id>.description`, `category.<id>`, `place.<id>`, `rarity.<id>`, `container.<id>`, `recipe.<id>` |
 
 ## Where the items come from
 
@@ -48,6 +49,36 @@ GOODS_STRINGS.en['place.pharmacy']             // 'Pharmacy'
 the sources lacked). 38 household items were merged with their team equivalent and keep the household id. Measures are the household's where it had one, the model box times a real scale for the 24
 modelled items, and a reference measure for the rest (`provenance.sizeSource`). Story items (diary, military map, evacuation order...) are not here: they live in the game's slice.
 
+## Adding an item
+
+Every item has a `kind` (`src/data/kinds.json`, a tree: `item > consumable > food_ready > canned_food`, `item > equipment > electronics`...). The kind carries the defaults (parts and
+materials, impact response, use animation and sounds, leftover, raw effect...) and the **contracts** the item must meet (`physical`, `destructible`, `impact`, `edible`, `use_animation`,
+`leftover`, `preparation`, `recipe_input`, `liquid_container`, `heat_resistant`, `weapon`, `wearable`, `battery`: see `src/contracts.ts`). An item declares only what differs from its kind.
+
+1. Pick the closest kind (`createGoodsKinds().ids()`; each has a name and description in the locales as `kind.<id>`). Tuning a kind (say `metal_can`) changes every item of it.
+2. Add the item the way `tools/items-catalog` says (an `extraItems` decision plus its `dimensions`), and give it a row in `tools/items-catalog/kinds-overlay.json`: `{ "kind": "canned_food", ...only what
+   differs }`. The generator refuses an item without a row. A real-world value you filled in for lack of a team number goes in the row's `"estimated": ["field", ...]` list: it means "estimated from the real world,
+   the teams may adjust it".
+3. Regenerate (`pnpm --filter @adatechnology/items-catalog-tool catalog`) and run **`pnpm check:items`**: it prints every problem (for example `"x" (canned_food): missing nutrition, required by food_ready`) and exits
+   non-zero. `known-gaps.json` lists the few gaps allowed so far; it only shrinks (a test fails when a gap stops applying, and caps its size), so a new item has to meet its kind.
+4. A new kind, or a parent inserted between two kinds, is data too, never a change of the engine:
+
+```ts
+import { checkGoodsItems, createGoodsKinds } from '@adatechnology/game-items-goods'
+
+const kinds = createGoodsKinds({
+  extra: [{ id: 'sealed_can', extends: 'food_ready', defaults: { impact: { response: 'dent', pushImpulse: true, shed: false } } }],   // a new kind...
+  patches: { canned_food: { extends: 'sealed_can' } },                                                                              // ...inserted above canned_food
+})
+const report = checkGoodsItems({ kinds, entries: myItems })    // { ok, problems, allowed }
+```
+
+## Português
+
+**Adicionando um item.** Todo item tem um `kind` (`src/data/kinds.json`, uma árvore). O kind traz os padrões (partes, impacto, animação de uso, sobra, efeito cru) e os contratos que o item tem de cumprir;
+o item só declara o que muda. Escolha o kind mais próximo, dê ao item uma linha em `tools/items-catalog/kinds-overlay.json` (`"estimated": [...]` marca o que foi estimado do mundo real e os times podem ajustar),
+regenere o catálogo e rode `pnpm check:items`: ele lista cada problema e sai com erro. Kind novo, ou um pai inserido no meio, é dado (`extra` e `patches` de `createGoodsKinds`), não mudança de motor.
+
 ## Tests
 
 `pnpm --filter @adatechnology/game-items-goods test`: the pack validates in `createItems`, ids are unique and English, every reference (category, place, rarity, pool, recipe, effect) exists, provenance covers

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ItemsOptions, ItemsCatalog, ItemPack, ArsenalItemRecord, CategoryDef, ContainerDef, PoolEntry, ItemDef, PlaceDef, RecipeDef, UseEffectDef, FindsProviderOptions, FindsProvider } from '@adatechnology/game-items';
+import { CategoryDef as CategoryDef$1, BodySlot, ContractChecker, CategoryRegistry, CategorizedReport, CategoryOptions } from '@adatechnology/game-contracts';
 
 /** The pack for `createItems({ packs })`: items, the three categories the game adds, 24 places, 17 containers, house pools, use effects and recipes. */
 declare const goodsPack: ItemPack;
@@ -88,6 +89,10 @@ declare const GOODS_TABLES: {
 /** Ammo boxes, three firearms and two throwables as items (the game's `EXTRA` table), for `itemsFromArsenal(arsenal, { records })`. */
 declare const GOODS_ARSENAL_RECORDS: readonly ArsenalItemRecord[];
 declare const GOODS_PROVENANCE: Readonly<Record<string, ItemProvenance>>;
+/** The tree of kinds (`kind` of each item): defaults and required contracts per kind, see `createGoodsKinds`. */
+declare const GOODS_KINDS: readonly CategoryDef$1[];
+/** Gaps of the catalog that are known and allowed, by item id: the problem prefixes `checkGoodsItems` lets through. It only shrinks: a test fails when a gap no longer applies. */
+declare const GOODS_KNOWN_GAPS: Readonly<Record<string, readonly string[]>>;
 
 type GoodsLocale = 'en' | 'pt-BR';
 /** Texts by key: `item.<id>`, `category.<id>`, `place.<id>`, `rarity.<id>`, `container.<id>`, `recipe.<id>`. The pt-BR names are the team's. */
@@ -117,4 +122,98 @@ declare const FLOORPLAN_POOL_ALIASES: Readonly<Record<string, string>>;
  */
 declare const createGoodsFindsProvider: (catalog: ItemsCatalog, options?: Omit<FindsProviderOptions, "unknownContainers">) => FindsProvider;
 
-export { type DepletionRow, FLOORPLAN_PLACES, FLOORPLAN_POOL_ALIASES, FLOORPLAN_POOL_KEYS, GOODS_ARSENAL_RECORDS, GOODS_CATEGORIES, GOODS_CONTAINERS, GOODS_HOUSE_POOLS, GOODS_ITEMS, GOODS_PLACES, GOODS_PROVENANCE, GOODS_RECIPES, GOODS_STRINGS, GOODS_TABLES, GOODS_USE_EFFECTS, type GoodsLocale, type GoodsStrings, type HousePools, type ItemProvenance, type MeleeRow, POOL_PLACES, type RarityRow, type StorageRow, createGoodsFindsProvider, createGoodsItems, goodsPack, goodsText, pickGoodsLocale };
+/**
+ * The fields the kinds add to `ItemDef`, as a catalog row after `resolveEntry` (the kind's defaults underneath the item's own fields).
+ * Every one is plain data: a kind sets it once and the items of the kind inherit it.
+ */
+interface KindedItem extends Omit<ItemDef, 'category' | 'rarity'> {
+    readonly category: string;
+    readonly kind: string;
+    /** The `category` values the kind's items may carry (the loot rolls read `category`): a kind default, never set on an item. */
+    readonly lootCategory?: readonly string[] | string;
+    /** Parts of the item for the destruction engine; a part may be a full `PartSpec` (shape and position) or only `{ id, material, thickness? }`. */
+    readonly parts?: readonly ItemPart[];
+    readonly impact?: ItemImpact;
+    readonly use?: {
+        readonly clip?: string;
+        readonly sounds?: readonly string[];
+    };
+    readonly leftover?: ItemLeftover;
+    /** What eating or drinking it raw does. `sickChance` is the chance of getting sick, 0..1. */
+    readonly rawEffect?: {
+        readonly sickChance?: number;
+    };
+    /** True when the item never spoils: the explicit form of a missing `shelfLife`. */
+    readonly nonPerishable?: boolean;
+    /** A container's capacity (an empty bucket); `fluid` is what it holds now. */
+    readonly container?: {
+        readonly capacityLiters?: number;
+    };
+    /** Names of the fields whose value was estimated from the real world, not given by a team: the teams may adjust them. */
+    readonly estimated?: readonly string[];
+    /** The arsenal caliber an ammunition item belongs to. */
+    readonly caliber?: string;
+}
+interface ItemPart {
+    readonly id: string;
+    readonly material: string;
+    readonly thickness?: number;
+    readonly shape?: unknown;
+    readonly position?: unknown;
+}
+/** How the item answers an impact: `response` is one of `IMPACT_RESPONSES`; `shed` says it throws off fragments. */
+interface ItemImpact {
+    readonly response?: string;
+    readonly pushImpulse?: boolean;
+    readonly shed?: boolean;
+}
+type ItemLeftover = 'none' | {
+    readonly item?: string;
+    readonly despawnSeconds?: number;
+};
+interface ItemContractOptions {
+    /** Ids of the destruction materials (`MATERIALS` of game-destruction). Without it the material names are not checked against the engine. */
+    readonly materials?: Iterable<string>;
+    /** Ids of the weapons of the arsenal (`WEAPONS` of game-weapons). Without it a `weapon` id is only checked to be a name. */
+    readonly weaponIds?: Iterable<string>;
+    /** Ids of the calibers of the arsenal (`CALIBERS` of game-weapons). */
+    readonly calibers?: Iterable<string>;
+    /** The catalog the leftovers and recipes are checked against (default: the goods catalog). */
+    readonly items?: readonly Pick<KindedItem, 'id' | 'kind' | 'category' | 'cookable'>[];
+    readonly recipes?: readonly RecipeDef[];
+    /** Kilograms per litre of the bounding box an item may have (default `densityKgPerLitre` of `data/item-contracts.json`). */
+    readonly density?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** Materials that take a flame (default `heatResistantMaterials` of `data/item-contracts.json`). */
+    readonly heatResistant?: readonly string[];
+}
+declare const IMPACT_RESPONSES: readonly string[];
+declare const HEAT_RESISTANT_MATERIALS: readonly string[];
+declare const DENSITY_KG_PER_LITRE: {
+    min: number;
+    max: number;
+};
+/** `BodySlot` of game-contracts, as a list. */
+declare const BODY_SLOTS: readonly BodySlot[];
+/** The checkers of the contracts the kinds of `kinds.json` require, built over the catalog and the engines they are given. */
+declare const createItemContracts: (options?: ItemContractOptions) => readonly ContractChecker<KindedItem>[];
+/** `createItemContracts()` over the goods catalog, without the engine lists (materials, arsenal): the CLI and the tests pass those. */
+declare const ITEM_CONTRACTS: readonly ContractChecker<KindedItem>[];
+
+/** The registry of the shipped kinds; `options` adds kinds, patches them by id or removes them (a game's own kinds go in `extra`). */
+declare const createGoodsKinds: (options?: CategoryOptions) => CategoryRegistry;
+interface CheckGoodsOptions extends ItemContractOptions {
+    readonly kinds?: CategoryRegistry;
+    /** The rows to check (default the goods catalog). */
+    readonly entries?: readonly KindedItem[];
+    /** Known gaps by item id (default `GOODS_KNOWN_GAPS`). */
+    readonly allow?: Readonly<Record<string, readonly string[]>>;
+}
+/** The `category` values a kind lets its items carry (`lootCategory` of its defaults); undefined when the kind declares none. */
+declare const lootCategoriesOf: (kinds: CategoryRegistry, kind: string) => readonly string[] | undefined;
+/** Runs the contracts of every item's kind over the catalog, and checks that `category` (read by the loot rolls) is one the kind declares. */
+declare const checkGoodsItems: (options?: CheckGoodsOptions) => CategorizedReport;
+
+export { BODY_SLOTS, type CheckGoodsOptions, DENSITY_KG_PER_LITRE, type DepletionRow, FLOORPLAN_PLACES, FLOORPLAN_POOL_ALIASES, FLOORPLAN_POOL_KEYS, GOODS_ARSENAL_RECORDS, GOODS_CATEGORIES, GOODS_CONTAINERS, GOODS_HOUSE_POOLS, GOODS_ITEMS, GOODS_KINDS, GOODS_KNOWN_GAPS, GOODS_PLACES, GOODS_PROVENANCE, GOODS_RECIPES, GOODS_STRINGS, GOODS_TABLES, GOODS_USE_EFFECTS, type GoodsLocale, type GoodsStrings, HEAT_RESISTANT_MATERIALS, type HousePools, IMPACT_RESPONSES, ITEM_CONTRACTS, type ItemContractOptions, type ItemImpact, type ItemLeftover, type ItemPart, type ItemProvenance, type KindedItem, type MeleeRow, POOL_PLACES, type RarityRow, type StorageRow, checkGoodsItems, createGoodsFindsProvider, createGoodsItems, createGoodsKinds, createItemContracts, goodsPack, goodsText, lootCategoriesOf, pickGoodsLocale };