Npcs

NPCs

Edit tabs/npcs.json.

Required Fields

Conditional Fields

Never Include

Omit these fields (auto-set or unused):

• visualDescription, visualTags
• detailType, hpCurrent, activeBuffs
• currentCoordinates, embeddingId, embedding, portraitUrl
• status, lastSeenTick
• lastSeenLocation, lastSeenArea, playerNotes
• needsDetailGeneration, deathXPAwarded
• healthMultiplier

status is reset to "" by the engine. Near death, dying, and dead are a runtime incapacitation counter (1 = near death, 2 = dying, 3 = dead) that creators never set. To spawn an NPC already down, use hpMax: 0 with hpCurrent: 0 instead.

Naming

Avoid naming an NPC (key, name, or properName) allSceneNPCs, anySceneNPC, allPartyNPCs, or anyPartyNPC: these are reserved trigger selector tokens. Keys and display names match interchangeably (case-insensitively) and display names are not unique, so keep names unique when triggers or effects need precise targeting.

basicInfo Format

Three sentences covering role, appearance, and dress:

1. One sentence about what they are
2. One elaborate sentence about their appearance and species features in detail
3. One short sentence about their clothes/equipment

Format: "A [gender] [species] [role]. [Build] with [hair], [eyes], [species features in detail]. Wears [X]."

personality Format

Four traits in this order, drawing from personality psychology trait vocabulary:

1. Positive trait - a strength or virtue
2. Neutral trait - a characteristic that's neither good nor bad
3. Negative trait - a flaw or weakness
4. Speaking style - how they talk (verbal patterns, tone, word choice)

Format: "Label: Explanation in under 10 words"

abilities Format

At least five appropriate abilities plus a fighting style summary.

Ability Descriptions

Format: "Ability Name: 3 sentence description of what it is and how it can be used."

Describe what the ability is, then list possibilities for how it can be used. Stay vague enough for creative interpretation but elaborate enough to inspire varied usage. Show flexibility - most abilities can be used offensively, defensively, or for utility depending on the situation.

fighting style Summary

The final entry summarizes their overall combat approach - longer and more detailed than individual abilities. Important: Include a literal \n before "fighting style" so it appears on its own line when displayed.

Format: "\nfighting style: [5 sentences covering how they fight]"

Include:

• How they combine and synergize their abilities
• Tactical preferences and engagement patterns
• Emotional tone and attitude in combat
• How their personality manifests when fighting
• How they adapt to different situations or opponents

level & hpMax Calculation

Players start with 100 HP and deal ~16 damage on success.

• level: Determines NPC damage. Each level adds +2 to base damage. Rough hits to down a 100 HP player: 100 ÷ (baseHit + 2 × level)
• hpMax: Determines NPC survivability. Calculate hits to down NPC: hpMax ÷ 16

hiddenInfo Guidelines

Write a full paragraph with maximum variety. No formula - be creative.

Mix different types of secrets:

• Personal history and backstory
• Fears, desires, and contradictions
• Connections to other NPCs or factions
• Knowledge of locations, treasures, or dangers
• Skills or abilities not immediately apparent
• Plans, schemes, or hidden agendas

Both narrative depth AND gameplay-useful information should be included.

Schema

interface NPC {
  name: string
  properName?: string
  type: string
  currentLocation: string
  currentArea: string
  tier?: 'trivial' | 'weak' | 'average' | 'strong' | 'elite' | 'boss' | 'mythic'
  gender?: string
  faction?: string
  relationship?: number
  basicInfo?: string
  hiddenInfo?: string
  personality?: string[]
  abilities?: string[]
  aliases?: string[]
  level?: number
  hpMax?: number
  healthMultiplier?: number
  known?: boolean
  voiceTag?: string
  worldVoiceId?: string
  portraitFocusX?: number
  portraitFocusY?: number
  portraitZoom?: number
  vulnerabilities?: string[]
  resistances?: string[]
  immunities?: string[]
  successBonus?: number
  damageModifier?: number
  damageReductionModifier?: number
}

Species Ability Inheritance

When creating an NPC with a species type, the NPC should inherit the 3 species skills from the corresponding trait as abilities:

1. Look up the species in tabs/traits.json
2. Copy those skill names and descriptions into the NPC's abilities array
3. Add additional unique abilities specific to that individual
4. Add the \nfighting style: summary

See Species Consistency Rules for the full requirements.

Reference

For detailed documentation, see npcs-reference.md.