{"tab":"mechanics","section":"traitCategories","title":"Trait Categories","summary":"Categories group `traits` together and control how many the player can pick from each group. Each category must be defined before `traits` can be assigned to it - the `traits` array lists which trait names belong to this category.","kind":"schema","uiLocation":"Mechanics → Trait Categories","uiSubtitle":"\"Trait categories\"","editor":"JSON + ADD ITEM","related":[{"section":"traits","note":"traits are assigned to categories via `category`"}],"wikiUrl":"/mechanics/traitCategories","schema":{"_type":"record","domain":"string","codomain":{"_type":"required","fields":{"name":"string","maxSelections":"number","traits":{"_type":"array","of":"string"}}}},"sizeLimits":[{"id":"traitCategoriesSection","group":"Mechanics Limits","label":"`traitCategories` (entire section)","measure":"prettyJson","enforced":100000,"display":100000,"sections":["mechanics/traitCategories"]}],"blocks":[{"type":"example","lang":"json","code":"{\n  \"Race\": {\n    \"name\": \"Race\",\n    \"description\": \"Your ancestral heritage. Shapes base capabilities and how the world sees you.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Human\", \"Elf\", \"Dwarf\", \"Halfling\"]\n  },\n  \"Class\": {\n    \"name\": \"Class\",\n    \"description\": \"Your trained vocation. Determines starting equipment and which abilities are most readily available.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Soldier\", \"Scholar\", \"Scout\", \"Healer\", \"Merchant\"]\n  },\n  \"Background\": {\n    \"name\": \"Background\",\n    \"description\": \"Where you come from and what shaped you before adventuring. Adjusts base skills and gives one starting item.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Noble Household\", \"Working Family\", \"Frontier Town\", \"Coastal Port\"]\n  },\n  \"Perks\": {\n    \"name\": \"Perks\",\n    \"description\": \"Edge traits — small advantages from biology, habit, or hard-won experience. Pick up to two.\",\n    \"maxSelections\": 2,\n    \"traits\": [\"Iron Stomach\", \"Light Sleeper\", \"Sharp-Eyed\", \"Quick Learner\", \"Bookish\", \"Patient\", \"Cool Head\", \"Lucky\"]\n  }\n}"},{"type":"fields","fields":[{"name":"name","tooltip":"Display name of the trait category, and must be byte-identical to the outer map key — the engine matches entries by key, so the key and name have to be…","md":"Display name of the trait category, and **must be byte-identical to the outer map key** — the engine matches entries by key, so the key and `name` have to be exactly equal (same case, same spaces). A mismatch is a validation error. Build the map as `{ category[\"name\"]: category }`."},{"name":"maxSelections","tooltip":"how many traits from this category the player can choose.","md":"how many traits from this category the player can choose. Set to `1` for mutually exclusive categories or to the desired multi-select cap. **`0` is empirically broken in the live UI -- the category renders 'Selected 0/0' and no traits can be picked.** For \"pick everything that applies\" categories, set `maxSelections` equal to the number of traits in the category. Typical values: `1` (single-pick), `3-N` (multi-select)."},{"name":"traits","tooltip":"required Array<string.","md":"**required** `Array<string>`. Lists all trait names in this category. Validator errors if absent.\n\n> **📋 Note:** The validator checks `name`, `maxSelections`, and `traits` on traitCategory entries.\n\n> See [Authoring Guide > Traits](/mechanics/traits#traits-character-creation-depth-and-clarity) for the pattern on hiding trigger-only system traits from the character creator."}]}],"body":"## Example\n\n```json\n{\n  \"Race\": {\n    \"name\": \"Race\",\n    \"description\": \"Your ancestral heritage. Shapes base capabilities and how the world sees you.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Human\", \"Elf\", \"Dwarf\", \"Halfling\"]\n  },\n  \"Class\": {\n    \"name\": \"Class\",\n    \"description\": \"Your trained vocation. Determines starting equipment and which abilities are most readily available.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Soldier\", \"Scholar\", \"Scout\", \"Healer\", \"Merchant\"]\n  },\n  \"Background\": {\n    \"name\": \"Background\",\n    \"description\": \"Where you come from and what shaped you before adventuring. Adjusts base skills and gives one starting item.\",\n    \"maxSelections\": 1,\n    \"traits\": [\"Noble Household\", \"Working Family\", \"Frontier Town\", \"Coastal Port\"]\n  },\n  \"Perks\": {\n    \"name\": \"Perks\",\n    \"description\": \"Edge traits — small advantages from biology, habit, or hard-won experience. Pick up to two.\",\n    \"maxSelections\": 2,\n    \"traits\": [\"Iron Stomach\", \"Light Sleeper\", \"Sharp-Eyed\", \"Quick Learner\", \"Bookish\", \"Patient\", \"Cool Head\", \"Lucky\"]\n  }\n}\n```\n\n## Fields\n\n### name\n\nDisplay name of the trait category, and **must be byte-identical to the outer map key** — the engine matches entries by key, so the key and `name` have to be exactly equal (same case, same spaces). A mismatch is a validation error. Build the map as `{ category[\"name\"]: category }`.\n\n### maxSelections\n\nhow many traits from this category the player can choose. Set to `1` for mutually exclusive categories or to the desired multi-select cap. **`0` is empirically broken in the live UI -- the category renders 'Selected 0/0' and no traits can be picked.** For \"pick everything that applies\" categories, set `maxSelections` equal to the number of traits in the category. Typical values: `1` (single-pick), `3-N` (multi-select).\n\n### traits\n\n**required** `Array<string>`. Lists all trait names in this category. Validator errors if absent.\n\n> **📋 Note:** The validator checks `name`, `maxSelections`, and `traits` on traitCategory entries.\n\n> See [Authoring Guide > Traits](/mechanics/traits#traits-character-creation-depth-and-clarity) for the pattern on hiding trigger-only system traits from the character creator."}