@adatechnology/game-items-goods 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @adatechnology/game-items-goods
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Catalog of real-world items for [`@adatechnology/game-items`](../game-items): **327 items** with their true size (metres) and weight (kg), plus everything the engine needs to use them
+(17 categories, 24 places, 17 containers, 6 rarities, 7 storage kinds, 33 recipes, 9 use effects, the explicit pools of the house furniture, depletion and spawn numbers, ammo boxes,
+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`.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-items @adatechnology/game-items-goods
+```
+
+A plain `<script src=".../dist/index.global.js">` exposes the `GameItemsGoods` global (the engine bundled in).
+
+## Usage
+
+```ts
+import { createGoodsItems, goodsPack, GOODS_STRINGS, goodsText } from '@adatechnology/game-items-goods'
+import { createItems, createFindsProvider } from '@adatechnology/game-items'
+
+const items = createGoodsItems({ patch: { canned_beans: { weight: 0.5 } }, remove: ['dvd'] })   // goods first, then your packs and options
+// the same, by hand: createItems({ packs: [goodsPack, myPack], ... })
+items.get('hammer').size                       // [w, h, d] in metres
+createFindsProvider(items).findsFor({ place: 'house', container: 'fridge', state: 'normal', rng, day: 0 })
+
+goodsText('item.canned_beans', 'pt-BR')        // 'Feijão em lata'
+GOODS_STRINGS.en['place.pharmacy']             // 'Pharmacy'
+```
+
+## What is in it
+
+| Export | Content |
+|---|---|
+| `goodsPack`, `createGoodsItems(options?)` | the `ItemPack` (items, categories, places, containers, use effects, recipes, pools) and `createItems` with it first |
+| `GOODS_ITEMS`, `GOODS_CATEGORIES`, `GOODS_PLACES`, `GOODS_CONTAINERS`, `GOODS_RECIPES`, `GOODS_USE_EFFECTS` | the typed data |
+| `GOODS_HOUSE_POOLS` | explicit pools by the 3D viewer's furniture key, plus the keys that share a pool |
+| `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>` |
+
+## Where the items come from
+
+327 = 245 of the team (the other 12 team items are story items that belong to the game) + 54 household items with no team equivalent + 28 items the catalog needed (pool entries and recipe terms
+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.
+
+## 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
+every item, every key has a text in both languages. The tool's own tests prove the data against the team sources.

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { ItemsOptions, ItemsCatalog, ItemPack, ArsenalItemRecord, CategoryDef, ContainerDef, PoolEntry, ItemDef, PlaceDef, RecipeDef, UseEffectDef, FindsProviderOptions, FindsProvider } from '@adatechnology/game-items';
+
+/** 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;
+/** `createItems` with the goods pack first; the packs and options of the game come after and win. */
+declare const createGoodsItems: (options?: ItemsOptions) => ItemsCatalog;
+
+/** Where an item of the catalog comes from: the team's item, the household one, the pool types of the 3D house viewer and the game ids. */
+interface ItemProvenance {
+    /** The item exists only because `decisions.json` asked for it. */
+    created?: true;
+    ite?: string;
+    household?: string;
+    vc3?: readonly string[];
+    game?: readonly string[];
+    idSource: 'household' | 'merge' | 'decision';
+    sizeSource: 'household' | 'REF' | 'model' | 'derived';
+}
+interface RarityRow {
+    id: string;
+    weight: number;
+    isFixedOnly: boolean;
+}
+interface StorageRow {
+    id: string;
+    multiplier: number;
+    needsPower?: true;
+    limitDays?: number;
+    afterLimit?: number;
+    /** Line of the team's page the number was read from. */
+    line: number;
+}
+interface DepletionRow {
+    places: readonly string[];
+    perDay: number;
+    floor: number;
+}
+interface MeleeRow {
+    id: string;
+    reach: number;
+    noise: number;
+}
+interface HousePools {
+    /** Pools by the key of the 3D house viewer (`geladeira`, `pia`...), as `PoolEntry` of the catalog. */
+    pools: Readonly<Record<string, readonly PoolEntry[]>>;
+    /** Keys that share another key's pool. */
+    aliasOf: Readonly<Record<string, string>>;
+}
+declare const GOODS_ITEMS: readonly ItemDef[];
+declare const GOODS_CATEGORIES: readonly CategoryDef[];
+declare const GOODS_PLACES: readonly PlaceDef[];
+declare const GOODS_CONTAINERS: readonly ContainerDef[];
+declare const GOODS_RECIPES: readonly RecipeDef[];
+declare const GOODS_USE_EFFECTS: readonly UseEffectDef[];
+/** The explicit pools, cut to what `createItems` reads (the viewer's `type`, `name` and `viewerCategory` stay in `data/house-pools.json`). */
+declare const GOODS_HOUSE_POOLS: HousePools;
+/** The team's numbers and tables, as read. The rules in `DEFAULT_RULES` of `game-items` are proven equal to them by test. */
+declare const GOODS_TABLES: {
+    readonly rarities: readonly RarityRow[];
+    readonly storage: readonly StorageRow[];
+    readonly depletion: readonly DepletionRow[];
+    readonly spawn: {
+        rarityWeights: {
+            common: number;
+            uncommon: number;
+            rare: number;
+            very_rare: number;
+        };
+        fixedOnly: string[];
+        condition: {
+            common: number[];
+            uncommon: number[];
+            rare: number[];
+        };
+        ageShareOfShelfLife: number[];
+        batteryCharge: number[];
+        jerrycanFill: number[];
+        floorItemsPerCell: number;
+        gameRarityWeights: {
+            c: number;
+            i: number;
+            r: number;
+            mr: number;
+        };
+    };
+    readonly melee: readonly MeleeRow[];
+};
+/** 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>>;
+
+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. */
+type GoodsStrings = Readonly<Record<string, string>>;
+declare const GOODS_STRINGS: Readonly<Record<GoodsLocale, GoodsStrings>>;
+/** `pt`, `pt-BR` and `pt_br` give the Portuguese texts, anything else English. */
+declare const pickGoodsLocale: (locale?: string) => GoodsLocale;
+/** The text of `key`, or the key itself when it has none. */
+declare const goodsText: (key: string, locale?: string) => string;
+
+/**
+ * Which pool of the visor's `CONTEUDO` each furniture category of the floorplan packs draws from (the team's name on the right is the key of
+ * `GOODS_HOUSE_POOLS.pools`). The categories are the ones of the residential MIGRATION table (`geladeira` is `fridge`, `pia` is `kitchen_cabinet`, `aereo` is
+ * `overhead_cabinet`, `pia_b` is `washbasin`...). `sapateira` (shoe rack) has no category in the floorplan packs yet.
+ */
+declare const FLOORPLAN_POOL_KEYS: Readonly<Record<string, string>>;
+/** The place tags the floorplan templates use (`TemplateDef.place`) that the catalog names differently. */
+declare const FLOORPLAN_PLACES: Readonly<Record<string, string>>;
+/** The explicit pools describe dwellings (the visor draws them for houses); every other place uses the category roll of the container. */
+declare const POOL_PLACES: readonly string[];
+/** `poolAliases` for `createItems`: the furniture categories of the floorplan packs, as keys of the house pools. */
+declare const FLOORPLAN_POOL_ALIASES: Readonly<Record<string, string>>;
+/**
+ * The `FindsProvider` for `engine.registerFindsProvider` (`@adatechnology/game-floorplan`): the goods catalog (made with `createGoodsItems`) answers what a
+ * piece of furniture holds. The catalog must come from `createGoodsItems` (it carries the aliases of the floorplan categories). Fridges and freezers keep the
+ * spoiled food of the abandoned state under their floorplan ids too.
+ */
+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 };