NPC dialogue

⚠️ Partial

NPCs speak through a data-driven dialogue bank. Each line is authored as plain JSON, grouped by the NPC’s personality and by a category (idle chatter, capture taunts, command replies, and so on). At runtime the game looks up a dialogue id for the speaker’s personality, filters the matching entries by context, then picks one weighted variant to display.

This page documents every field the game actually reads when loading the dialogue bank.

Two hard locks — read this first

The dialogue system is only partly open to add-ons:

1. The namespace is locked to tiedup. The game only ever looks under data/tiedup/dialogue/… — it never scans your own namespace. A third-party pack can therefore only override files that ship there; it cannot register a brand-new dialogue namespace.
2. The personality types and category names are fixed lists. Adding a data/tiedup/dialogue/en_us/myvibe/ folder or a myevent.json file does nothing — neither name is in the scan list, so the file is never opened. You author inside the existing folders.

In practice your dialogue files go under data/tiedup/dialogue/... in your addon pack, with paths that exactly match the built-in ones to replace or extend the shipped lines. See Packaging for the full pack structure.

File layout

data/tiedup/dialogue/<lang>/<personality>/<category>.json
                     ^^^^^^ ^^^^^^^^^^^^^  ^^^^^^^^^^^
                     locked  fixed list    fixed list

Segment	Allowed values	Notes
<lang>	en_us	Only en_us is ever read. Other lang folders are ignored.
<personality>	one of the 11 personalities, or default	See Personalities. default is the fallback bank merged into every personality.
<category>	one of the fixed category names	See Categories. A filename not on the list is silently skipped.

Speaker-type folders are a second scan

Besides the personality folders, the game also reads a fixed set of speaker-type folders — master, kidnapper, maid, trader, guard, kidnapper_archer, kidnapper_elite, merchant — from a nested default sub-folder:

data/tiedup/dialogue/en_us/<speaker>/default/<category>.json

These lines are added to all personalities (no personality condition), so role-specific barks like a trader’s greeting are available regardless of the NPC’s temperament.

File shape

A category file is one JSON object with an entries list. Each entry has an id, optional conditions, and a list of weighted variants:

{
  "category": "idle",
  "personality": "TIMID",
  "description": "Timid idle behaviors and greetings",
  "entries": [
    {
      "id": "idle.greeting",
      "variants": [
        { "text": "*waves shyly*", "weight": 10, "is_action": true },
        { "text": "H-hello...", "weight": 10 },
        { "text": "*avoids eye contact* Oh, um, hi...", "weight": 8 }
      ]
    }
  ]
}

Top-level fields

Field	Type	Read?	Notes
entries	array	yes	The only field the game consumes. A file with no entries array loads zero lines.
category	string	no	Metadata / human label only. The real category is the filename — this key is never read. Keep it accurate for your own sanity.
personality	string	no	Metadata. The real personality comes from the folder name, applied automatically as a condition.
description	string	no	Free-text comment for authors.

Folder = condition, filename = category

You don’t set the personality or category inside the file — they come from the path. A line in …/timid/idle.json is automatically a TIMID-only idle line. The top-level personality / category keys are descriptive labels the game ignores.

Entry fields

Field	Type	Req?	Notes
id	string	yes	The lookup key the game asks for, e.g. idle.greeting, command.follow.accept. An entry with no id is dropped.
variants	array	yes	At least one valid variant, or the entry is dropped.
conditions	object	optional	Extra context filter on top of the folder’s personality. See Conditions.

An entry with the same id may appear in several files. Personality-specific entries take priority over the default bank — when a personality folder defines an id, its variants are tried first, with the default bank as fallback.

Variant fields

Field	Type	Default	Notes
text	string	—	Required. The line shown (after variable substitution). A variant with no text is skipped.
weight	int	10	Relative weight in the weighted-random pick. Higher = more frequent.
is_action	bool	false	If true, the line is treated as a roleplay action: it is wrapped in *asterisks* and is exempt from gag muffling.

is_action and gags

When the speaker is gagged, ordinary speech variants are passed through a muffling filter (e.g. “Help!” → “Mmph!”). Action variants are not muffled — a *struggles against the ropes* line reads the same gagged or not. Author physical reactions as is_action: true so they survive a gag. If you author your own asterisk-wrapped action text and set is_action: false, the muffler leaves it alone too (it skips anything already wrapped in *…*), but you then lose the automatic wrapping — prefer the flag.

Conditions

conditions narrows when an entry is eligible, in addition to the personality implied by the folder. Only three keys actually filter — the rest are accepted for backward compatibility but have no effect.

{
  "id": "mood.sad",
  "conditions": { "mood_max": -20 },
  "variants": [
    { "text": "*sighs heavily*", "weight": 10, "is_action": true },
    { "text": "I miss being free...", "weight": 10 }
  ]
}

Key	Type	Effect
personality	string[]	Restrict to these personalities (names case-insensitive). Ignored inside a personality folder — the folder already pins the personality; it only matters in the default / speaker-type folders. Unknown names are skipped — you’ll see a warning in the log.
mood_min	int	Entry eligible only when the speaker’s mood ≥ this. Mood ranges roughly -100…100.
mood_max	int	Entry eligible only when the speaker’s mood ≤ this.

Inert condition keys — silent no-ops

❌ Planned These keys still appear in some shipped files and parse without error, but the systems behind them were removed — they do nothing:

training_min, training_max (training system removed) · relationship (relationship system removed) · resentment_min, resentment_max, resentment (no runtime consumer).

An entry whose only condition is one of these effectively has no condition — it always matches. Don’t rely on them to gate a line.

Personalities

The 11 personality folders are a fixed list you cannot extend. Folder names are the lowercased personality names:

timid   gentle   submissive   calm   curious   proud
fierce  defiant  playful      masochist   sadist

Plus the special default folder, whose lines are merged into every personality as a fallback. You cannot add a 12th personality from a pack — a folder named anything else is never scanned.

Tip

Authoring a new line for an existing personality is the supported workflow: drop a file at data/tiedup/dialogue/en_us/<personality>/<category>.json (matching a built-in path to override, or adding new ids within an existing category file).

Categories

The category is the filename (without .json). There is one fixed set of valid category names, and any of them is scanned in every personality folder and every speaker-type default/ folder — there is no separate “speaker-only” list. Anything not in this set is ignored:

commands   capture   struggle   jobs    mood     combat
needs      idle      actions    fear    reaction environment
discipline home      leash      resentment        personality
conversation         punishment purchase inspection petplay
guard_labor maid_labor          guard    dogwalk
patrol     punish

So data/tiedup/dialogue/en_us/timid/punishment.json and data/tiedup/dialogue/en_us/master/default/idle.json are both scanned — the same names apply everywhere.

ids are namespaced by convention, not by the file

The category does not prefix the id automatically. Convention is to prefix the id to match — command.follow.accept lives in commands.json, idle.greeting in idle.json — but the game looks lines up by the raw id string you write, so the prefix is yours to keep consistent. Built-in lookups expect patterns like command.<name>.accept, capture.<phase>, mood.<mood>, needs.<need>, and idle.*.

A line only ever shows when some code path asks for its id. Writing a brand-new id that no built-in lookup requests means the line is loaded but never displayed — stick to the patterns above unless you also drive the lookup yourself.

How selection works

1. The game asks for a dialogue id (e.g. idle.greeting) for a speaker with a known personality.
2. It gathers every entry registered under that id for that personality — personality-specific first, then the merged default bank.
3. It drops entries whose conditions don’t match the current context (personality + mood).
4. From the first matching entry it picks one variant by weighted random.
5. Variables in the text are substituted, action text is wrapped in *…*, and if the speaker is gagged, non-action speech is muffled.

If no entry matches, the bark is skipped (the caller may supply its own hard-coded fallback).

Worked example: a defiant capture taunt

1. Create the file at the right path — defiant personality, capture category:

   data/tiedup/dialogue/en_us/defiant/capture.json

2. Write the entry. The folder already pins DEFIANT, so no personality condition is needed:

   {
     "category": "capture",
     "personality": "DEFIANT",
     "description": "Defiant reactions while being captured",
     "entries": [
       {
         "id": "capture.start",
         "variants": [
           { "text": "You'll regret this!", "weight": 10 },
           { "text": "*thrashes against your grip*", "weight": 10, "is_action": true },
           { "text": "I will NOT go quietly!", "weight": 8 },
           { "text": "*spits* Coward.", "weight": 4 }
         ]
       }
     ]
   }

3. Run /reload. The log reports how many dialogue ids loaded. A malformed file is skipped — you’ll see a warning in the log, and the rest still load.

Reload is server-side and full-bank

/reload re-reads the whole bank. There is no hot-swap of a single file; edit, then /reload. On a dedicated server the bank loads server-side, so your pack must be installed on the server, not just a client.

See also

• Item JSON reference — the bondage-item schema (the items NPCs react to).
• Animations — pose clips; pair an is_action bark with a struggle pose for a richer reaction.
• Body regions & bones — naming reference for the rest of the system.