{
  "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.",
  "uiLocation": "Mechanics → Item Settings",
  "uiSubtitle": "\"Item settings and their mechanics\"",
  "editor": "JSON only",
  "sizeLimits": [
    {
      "field": "`itemSettings` (entire section)",
      "limit": "5,000 chars",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.itemCategories` (entry count)",
      "limit": "40 entries",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.itemCategories.*` (each)",
      "limit": "60 chars",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.itemSlots` (slot count)",
      "limit": "60 slots",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.itemSlots.*.slot` (slot name)",
      "limit": "64 chars",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.itemSlots.*.category` (slot category)",
      "limit": "60 chars",
      "sections": [
        "mechanics/itemSettings"
      ]
    },
    {
      "field": "`itemSettings.currencyName`",
      "limit": "64 chars",
      "sections": [
        "mechanics/itemSettings"
      ]
    }
  ],
  "related": "items - items must be pre-defined there before being referenced here; storyStarts - `startingItems` on starts and traits draw from the items catalog; traits - 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)"
      }
    }
  },
  "body": "## Example\r\n\r\n```json\r\n{\r\n  \"currencyName\": \"Gold\",\r\n  \"itemCategories\": [\"Armor\", \"Consumable\", \"Focus\", \"Helmet\", \"Offhand\", \"Tool\", \"Trinket\", \"Weapon\"],\r\n  \"itemSlots\": [\r\n    { \"slot\": \"Weapon\", \"category\": \"Weapon\", \"quantity\": 1 },\r\n    { \"slot\": \"chest\", \"category\": \"Armor\", \"quantity\": 1 },\r\n    { \"slot\": \"head\", \"category\": \"Helmet\", \"quantity\": 1 },\r\n    { \"slot\": \"offhand\", \"category\": \"Offhand\", \"quantity\": 1 },\r\n    { \"slot\": \"tool\", \"category\": \"Tool\", \"quantity\": 2 },\r\n    { \"slot\": \"Focus\", \"category\": \"Focus\", \"quantity\": 1 },\r\n    { \"slot\": \"trinket\", \"category\": \"Trinket\", \"quantity\": 2 },\r\n    { \"slot\": \"pouch\", \"category\": \"Consumable\", \"quantity\": 4 }\r\n  ],\r\n  \"startingItems\": [\r\n    { \"item\": \"Gold\", \"quantity\": 50 }\r\n  ]\r\n}\r\n```\r\n\r\n## Fields\r\n\r\n### itemSlots\r\n\r\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.\r\n\r\n### startingItems\r\n\r\nitems given to ALL players regardless of trait/start selection.\r\n\r\n## Authoring tips\r\n\r\n### Equipping items\r\n\r\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.\r\n\r\n### Slot count\r\n\r\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.\"\r\n\r\n## Behaviour\r\n\r\n### Slot eviction\r\n\r\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`.\r\n\r\n### Currency stacking\r\n\r\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."
}