{"tab":"mechanics","section":"itemSettings","title":"Item Settings","summary":"Defines the equipment system: the name of your currency, the item categories that exist, the equipment slots characters have, and the `items` given to every player at the start of every game regardless of trait or story start.","kind":"schema","uiLocation":"Mechanics → Item Settings","uiSubtitle":"\"Item settings and their mechanics\"","editor":"JSON only","related":[{"section":"items","note":"items must be pre-defined there before being referenced here"},{"section":"storyStarts","note":"`startingItems` on starts and traits draw from the items catalog"},{"section":"traits","note":"traits can also grant `startingItems`"}],"wikiUrl":"/mechanics/itemSettings","schema":{"_type":"required","fields":{"currencyName":"string","itemCategories":{"_type":"array","of":"string"},"itemSlots":{"_type":"array","of":{"_type":"required","fields":{"slot":"string","category":"string","quantity":"number"}}},"startingItems":{"_type":"array","of":"(recursive)"}}},"sizeLimits":[{"id":"itemSettingsSection","group":"Mechanics Limits","label":"`itemSettings` (entire section)","measure":"prettyJson","enforced":5000,"display":5000,"sections":["mechanics/itemSettings"]},{"id":"itemCategoriesCount","group":"Settings Caps","label":"`itemSettings.itemCategories` (entry count)","measure":"count","unit":"entries","enforced":40,"display":40,"sections":["mechanics/itemSettings"]},{"id":"itemCategoryEntry","group":"Settings Caps","label":"`itemSettings.itemCategories.*` (each)","measure":"rawChars","enforced":60,"display":60,"sections":["mechanics/itemSettings"]},{"id":"itemSlotsCount","group":"Settings Caps","label":"`itemSettings.itemSlots` (slot count)","measure":"count","unit":"slots","enforced":60,"display":60,"sections":["mechanics/itemSettings"]},{"id":"itemSlotName","group":"Settings Caps","label":"`itemSettings.itemSlots.*.slot` (slot name)","measure":"rawChars","enforced":64,"display":64,"sections":["mechanics/itemSettings"]},{"id":"itemSlotCategory","group":"Settings Caps","label":"`itemSettings.itemSlots.*.category` (slot category)","measure":"rawChars","enforced":60,"display":60,"sections":["mechanics/itemSettings"]},{"id":"currencyName","group":"Settings Caps","label":"`itemSettings.currencyName`","measure":"rawChars","enforced":64,"display":64,"sections":["mechanics/itemSettings"]}],"blocks":[{"type":"example","lang":"json","code":"{\n  \"currencyName\": \"Gold\",\n  \"itemCategories\": [\"Armor\", \"Consumable\", \"Focus\", \"Helmet\", \"Offhand\", \"Tool\", \"Trinket\", \"Weapon\"],\n  \"itemSlots\": [\n    { \"slot\": \"Weapon\", \"category\": \"Weapon\", \"quantity\": 1 },\n    { \"slot\": \"chest\", \"category\": \"Armor\", \"quantity\": 1 },\n    { \"slot\": \"head\", \"category\": \"Helmet\", \"quantity\": 1 },\n    { \"slot\": \"offhand\", \"category\": \"Offhand\", \"quantity\": 1 },\n    { \"slot\": \"tool\", \"category\": \"Tool\", \"quantity\": 2 },\n    { \"slot\": \"Focus\", \"category\": \"Focus\", \"quantity\": 1 },\n    { \"slot\": \"trinket\", \"category\": \"Trinket\", \"quantity\": 2 },\n    { \"slot\": \"pouch\", \"category\": \"Consumable\", \"quantity\": 4 }\n  ],\n  \"startingItems\": [\n    { \"item\": \"Gold\", \"quantity\": 50 }\n  ]\n}"},{"type":"fields","fields":[{"name":"itemSlots","tooltip":"slot and category usually match.","md":"slot and category usually match. Exception: the `pouch` slot above uses `category: \"Consumable\"` - they diverge when a physical slot name (pouch, chest, head) maps to a logical item category."},{"name":"startingItems","tooltip":"items given to ALL players regardless of trait/start selection.","md":"items given to ALL players regardless of trait/start selection."}]},{"type":"prose","md":"## Authoring tips\n\n### Equipping items\n\n\"You don't have to equip an item to use it. There are 2 reasons to make an item equippable: (1) magic bonuses only apply when equipped; (2) NPCs comment on equipped items.\" A dedicated `Focus` or `Trinket` slot is useful for items you want NPCs to notice and react to.\n\n### Slot count\n\nCreative note: \"If you are making a game about being a spider that can put knives on its feet, you can let yourself have 8 weapon slots.\""},{"type":"prose","md":"## Behaviour\n\n### Slot eviction\n\nWhen equipping a new item into a slot whose `quantity` is full, the engine unequips the first item already in that slot (and removes its bonuses), then equips the new item. Categories must match the slot's `category`.\n\n### Currency stacking\n\nitems whose **`name`** matches `itemSettings.currencyName` stack on `name + category` only -- the engine ignores `bonuses` when deciding currency stacks. Non-currency items must match all properties (name, category, bonuses, effects) to stack."}],"body":"## Example\n\n```json\n{\n  \"currencyName\": \"Gold\",\n  \"itemCategories\": [\"Armor\", \"Consumable\", \"Focus\", \"Helmet\", \"Offhand\", \"Tool\", \"Trinket\", \"Weapon\"],\n  \"itemSlots\": [\n    { \"slot\": \"Weapon\", \"category\": \"Weapon\", \"quantity\": 1 },\n    { \"slot\": \"chest\", \"category\": \"Armor\", \"quantity\": 1 },\n    { \"slot\": \"head\", \"category\": \"Helmet\", \"quantity\": 1 },\n    { \"slot\": \"offhand\", \"category\": \"Offhand\", \"quantity\": 1 },\n    { \"slot\": \"tool\", \"category\": \"Tool\", \"quantity\": 2 },\n    { \"slot\": \"Focus\", \"category\": \"Focus\", \"quantity\": 1 },\n    { \"slot\": \"trinket\", \"category\": \"Trinket\", \"quantity\": 2 },\n    { \"slot\": \"pouch\", \"category\": \"Consumable\", \"quantity\": 4 }\n  ],\n  \"startingItems\": [\n    { \"item\": \"Gold\", \"quantity\": 50 }\n  ]\n}\n```\n\n## Fields\n\n### itemSlots\n\nslot and category usually match. Exception: the `pouch` slot above uses `category: \"Consumable\"` - they diverge when a physical slot name (pouch, chest, head) maps to a logical item category.\n\n### startingItems\n\nitems given to ALL players regardless of trait/start selection.\n\n## Authoring tips\n\n### Equipping items\n\n\"You don't have to equip an item to use it. There are 2 reasons to make an item equippable: (1) magic bonuses only apply when equipped; (2) NPCs comment on equipped items.\" A dedicated `Focus` or `Trinket` slot is useful for items you want NPCs to notice and react to.\n\n### Slot count\n\nCreative note: \"If you are making a game about being a spider that can put knives on its feet, you can let yourself have 8 weapon slots.\"\n\n## Behaviour\n\n### Slot eviction\n\nWhen equipping a new item into a slot whose `quantity` is full, the engine unequips the first item already in that slot (and removes its bonuses), then equips the new item. Categories must match the slot's `category`.\n\n### Currency stacking\n\nitems whose **`name`** matches `itemSettings.currencyName` stack on `name + category` only -- the engine ignores `bonuses` when deciding currency stacks. Non-currency items must match all properties (name, category, bonuses, effects) to stack."}