{
  "tab": "world",
  "section": "npcTypes",
  "title": "NPC Types (Advanced)",
  "summary": "NPC types define behavior templates for categories of NPCs. Each type lists `vulnerabilities`, `resistances`, and `immunities` to `skills` and damage types.",
  "uiLocation": "World → Advanced → NPC Types",
  "uiSubtitle": "\"Optional pre-defined NPC types that the AI references for variety\"",
  "editor": "JSON + ADD ITEM",
  "sizeLimits": [
    {
      "field": "`npcTypes.*.description`",
      "limit": "8,000 chars",
      "sections": [
        "world/npcTypes"
      ]
    },
    {
      "field": "`npcTypes` (entire section)",
      "limit": "500,000 chars",
      "sections": [
        "world/npcTypes"
      ]
    }
  ],
  "related": "npcs - individual NPCs reference a type via `type`",
  "wikiUrl": "/world/npcTypes",
  "schema": {
    "_type": "record",
    "domain": "string",
    "codomain": {
      "_type": "required",
      "fields": {
        "name": "string",
        "vulnerabilities": {
          "_type": "array",
          "of": "string"
        },
        "resistances": {
          "_type": "array",
          "of": "string"
        },
        "immunities": {
          "_type": "array",
          "of": "string"
        },
        "description": "string"
      }
    }
  },
  "body": "## Example\r\n\r\n```json\r\n{\r\n  \"character\": {\r\n    \"name\": \"character\",\r\n    \"vulnerabilities\": [],\r\n    \"resistances\": [],\r\n    \"immunities\": [],\r\n    \"description\": \"A mortal being - human, elf, dwarf, or other standard species. Standard damage, social, and effect rules apply.\"\r\n  },\r\n  \"humanoid_enemy\": {\r\n    \"name\": \"humanoid_enemy\",\r\n    \"vulnerabilities\": [\"persuasion\", \"intimidation\", \"deception\"],\r\n    \"resistances\": [],\r\n    \"immunities\": [],\r\n    \"description\": \"Mortal adversaries - bandits, rogue soldiers, corrupt officials. Fully subject to social manipulation and fear. Standard combat tactics apply. Can be talked down, bribed, or scared off.\"\r\n  },\r\n  \"undead_shambling\": {\r\n    \"name\": \"undead_shambling\",\r\n    \"vulnerabilities\": [\"holy magic\", \"fire\"],\r\n    \"resistances\": [\"slashing\", \"bludgeoning\"],\r\n    \"immunities\": [\"intimidation\", \"persuasion\", \"deception\", \"medicine\"],\r\n    \"description\": \"Mindless undead - skeletons, zombies, revenants without will. Immune to social effects and fear. Vulnerable to consecrated attacks and fire. Cannot be reasoned with or bargained with.\"\r\n  },\r\n  \"humanoid_cultist\": {\r\n    \"name\": \"humanoid_cultist\",\r\n    \"vulnerabilities\": [\"arcana\", \"insight\"],\r\n    \"resistances\": [\"persuasion\"],\r\n    \"immunities\": [\"intimidation\"],\r\n    \"description\": \"Devoted fanatics. Their belief makes them immune to fear and resistant to conventional persuasion. Arcane knowledge can exploit gaps in their ritual understanding; Insight can expose internal doubts.\"\r\n  }\r\n}\r\n```\r\n\r\n## Fields\r\n\r\n### description\r\n\r\n`description` - baseline behavior summary: how this creature type behaves socially and in combat, what motivates it, and how it perceives the player. This is the template the narrator applies to every NPC of this type before the individual NPC's `basicInfo` supplements it.\r\n\r\n> **📋 Note (`npcType.description` as a `generateNPCDetails` instruction channel):** Because `npcType.description` is read by the narrator during `generateNPCDetails`, it functions as an instruction channel for that task across every NPC of the type. Directives embedded in the description -- such as formatting rules, required detail categories, or generation constraints -- apply consistently to all NPCs of that type without repeating them in each individual NPC's `basicInfo`. This is additive to the behavioral template role: the same field can describe how the type behaves and instruct how its detail generation should be structured.\r\n\r\n## Behaviour\r\n\r\n### When to create a type\r\n\r\n**Create an NPC type only when:**\r\n\r\n- Multiple NPCs share the same damage profile (vulnerabilities / resistances / immunities), or\r\n- The type represents a species, creature category, or profession that more than one NPC will inhabit\r\n\r\nNo baseline type is required. A world where every NPC is a unique individual (no shared damage profiles) is fine with zero `npcTypes` entries and `type: \"\"` on every NPC. The section is optional.\r\n\r\n### Damage multipliers\r\n\r\n| Category | Multiplier | Effect |\r\n|----------|------------|--------|\r\n| `vulnerabilities` | 1.5x | +50% damage taken |\r\n| `resistances` | 0.5x | -50% damage taken |\r\n| `immunities` | 0x | No damage taken |\r\n\r\n### Damage type inheritance\r\n\r\nAn NPC with `type: \"goblin\"` looks up `npcTypes.goblin` and receives the **union** of the type's damage arrays plus its own:\r\n\r\n- effective vulnerabilities = `npcType.vulnerabilities ∪ npc.vulnerabilities`\r\n- effective resistances = `npcType.resistances ∪ npc.resistances`\r\n- effective immunities = `npcType.immunities ∪ npc.immunities`\r\n\r\nNPCs with `type: \"\"` use only their own arrays -- no inheritance happens. Use a typed NPC for shared damage profiles, and a typeless NPC when a one-off character needs a unique profile.\r\n\r\n### Resistance stacking\r\n\r\nMultiple resistances against the same damage type **multiply** rather than add. A 0.5x resistance from the npcType combined with a 0.5x resistance on the NPC itself equals `0.5 × 0.5 = 0.25x` total damage taken (75% reduction). The same multiplicative rule applies to vulnerabilities and immunities.\r\n\r\n> **🐛 Common mistake:** Values in `vulnerabilities`, `resistances`, and `immunities` must match strings verbatim from `combatSettings.damageTypes`. Approximate matches do not work -- `\"poison\"` is not valid if `\"poisoning\"` is in the list; `\"frost\"` is not valid if only `\"ice\"` is defined. Always copy the exact strings from your `damageTypes` list. Entries that don't match are silently ignored.\r\n\r\n### Species ability inheritance\r\n\r\nWhen you define a creature species as both an `npcType` (so NPCs can be assigned to it via `type`) and a `trait` (so players can choose it at character creation), the species trait should include 3 abilities representing that species' innate capabilities. NPCs assigned that `type` should also have those same 3 abilities in their `abilities` array. This keeps species mechanics consistent between player and NPC versions of the same species - a player Elf and an NPC Elf both have access to the same innate abilities.\r\n\r\n> For guidance on populating vulnerabilities/resistances/immunities see [Authoring Guide > NPC Types](/world/npcTypes#npc-types-vulnerabilities-resistances-immunities).\r\n\r\n## Authoring tips\r\n\r\n### NPC Types - Vulnerabilities, Resistances, Immunities\r\n\r\nThe `vulnerabilities`, `resistances`, and `immunities` arrays on `npcTypes` are matched by the AI against two specific vocabularies during combat and challenge resolution:\r\n\r\n1. The **skill names** defined in your world's `skills` collection.\r\n2. The **damage type** strings listed in `combatSettings.damageTypes`.\r\n\r\nThe AI cannot infer custom categories. A value like `\"blade combat\"` or `\"ranged combat\"` will not match anything unless those exact strings exist as skill names or damage types -- the matching is literal, not semantic. **Populate these arrays with values that already exist in your skills or damage types, or the arrays will have no mechanical effect.**\r\n\r\nHow you stock those skills/damage types is entirely a world-design choice. A high-fantasy scenario will use a different skill vocabulary than a modern slice-of-life world, which uses a different one than a sci-fi or superhero scenario. Build the skill set that fits your scenario's genre first, then design NPC type vulnerabilities/resistances around it.\r\n\r\n**Example: a D&D-flavored fantasy skill set** (illustrative -- not the recommended default, just one workable configuration among many):\r\n\r\n| Type | Vulnerable to | Resistant to | Immune to |\r\n|---|---|---|---|\r\n| character | - | - | - |\r\n| beast | athletics, nature | - | arcana |\r\n| undead | religion, radiant | necrotic, cold | poison, persuasion |\r\n| construct | crafting, arcana | physical | charm, poison |\r\n| elemental | (element-specific) | (element-specific) | exhaustion |\r\n| spirit | arcana, religion | physical | poison, charm |\r\n| humanoid_enemy | intimidation, deception | - | - |\r\n| humanoid_cult | religion | arcana | - |\r\n\r\nA modern slice-of-life world might leave these arrays empty entirely (combat is rare or absent) or carry social vulnerabilities -- e.g. a celebrity NPC vulnerable to `social_media`, resistant to `intimidation`. A sci-fi world might have a `cybernetic_soldier` type vulnerable to `hacking` and resistant to `kinetic`. The pattern is the same; the vocabulary changes with the genre."
}