UnofficialWIKI
Builder
Edit / Suggest changeSuggest deletion

New NPC

generateNewNPC

Generates new NPCs during play. Use custom for what kinds of NPCs your world should produce and how they are named; fuller details come from generateNPCDetails.

In the editor

"Runs when the story introduces an improvised NPC who is not already defined. Use it to shape the character’s first-pass name, role, appearance, social signals, affiliation, and power level before fuller details are generated."

Editor location
Files → AI → Advanced → New NPC
Editor type
Edit in Studio + View JSON
API endpoint
/sections/generateNewNPC.json/sections/generateNewNPC.md
Size limits
  • Each string leaf under a task (aiInstructions.<task>.<key>) — 5,000
Related

Schema

json
{
  "aiInstructions": {
    "generateNewNPC": {
      "<key>": "string"
    }
  }
}

Example

json
{
  "aiInstructions": {
    "generateNewNPC": {
      "custom": "## MANDATORY FIELDS\nEvery improvised NPC must declare:\n- **Role** (specific occupation, not a vague label): 'dockside cooper', 'mountain guide', 'cartel courier'.\n- **Origin / culture** (anchors name + speech register): which region, clan, or tradition they come from.\n- **Rank or skill tier** (chooses one from your world's authority ladder): which rung they sit at and how they behave toward those above and below.\n- **One behavioral hook** (one thing they do or want, not a trait list).\n- **One short-term goal** the current scene can engage with.\n\n## NAMING RULES BY ORIGIN\n[Replace with your world's geographic or cultural groups and their phonetic registers.]\n- Central territories: short, grounded names — Edric, Mara, Owen, Holt.\n- Northern frontier: harder consonants, longer names — Halvard, Sigrun, Brekt.\n- Coastal cities: Latinate surnames — Varano, Crell, Senne.\nAvoid generic fantasy names (Theron, Aldric, Zara, Mira).\n\n## VISUAL DESCRIPTION FORMAT\nvisualDescription is a comma-separated tag list, not prose. No sentences, no pronouns, no exposition.\n- Humanoid example tags: Athletic Build, Cropped Hair, Cyan Eyes, Leather Tunic, Arm Guards, Sigil-Marked Cloak.\n- Non-humanoid example tags: Six-Horned, Cobalt Scales, Tattered Wings, Two Tails, Crystalline Spines, Tree-Bark Hide.\nAlways full-body, grounded in a specific location (city street, training hall, sacred grove, battlefield).\n\n## TIER + LEVEL\nMatch authored NPC conventions: trivial / weak / average / strong / elite / boss / mythic. New improvised NPCs default to average or weak unless the scene demands otherwise."
    }
  }
}

A worked pattern — replace world-specific tokens with your own:

Fields

custom

The only key — free-form rules for first-pass creation of improvised NPCs: mandatory fields, naming by origin, visualDescription tag format, and tier defaults.

Authoring pattern

  • List the fields every new NPC must have, one line per field with its rule, rather than describing them in a paragraph.
  • Naming rules organised by origin or culture. Group names by region or species, each with its own sound and example names, so a generated NPC's name matches where it comes from. Community naming instructions also ask the AI to read the world background and current location first, match the sound of names already in the world, keep minor NPCs' names plain, and stay distinct from the player characters' names.
  • Separate visualDescription tag guidance for people and for creatures, as two short example lists side by side.
  • Anchor tier to authored NPCs. Improvised NPCs should match the tier scale your authored set uses, rather than jumping to elite without a reason.

Note: To prevent specific NPC types, species, or categories from being generated ambiently (while still allowing them at authored locations), see Restricted spawn lists in the Advanced AI Techniques appendix.