Dialogue
Make villagers say something new, offer the player a few answers, and let those answers change friendship, hand out items, start quests or lead to the next line.
What this lets you make#
Each entry in this table is one line a villager says (the game calls it a "node"), optionally with answers for the player. An answer can lead to another line, which gives you a short conversation. You choose who says it: every villager with a certain job (all the innkeepers, say) or one named villager. You can also add conditions: only if friendship is high enough, only at night, only if the player is carrying something.
There are two kinds of line:
- Opening lines: the first thing a villager might say when the player talks to them. Use
attachto say who says it. - Follow-up lines: reached only through another line's answer
next, and marked"start": false. A follow-up never starts a conversation by itself. If nothing points to it, the load check tells you nobody will ever say it.
In the editor#
Open the Dialogue tab under Story in the left column (if it is not there, add it from Add new content at the bottom) and press Add. One entry is one line a villager says. A new entry is spoken by the innkeeper and has one Goodbye. answer.
This kind has its own form. From top to bottom:
- How this line appears: pick Opening line: a villager starts it and then Every villager or Pick roles or villagers; or pick Follow-up: reached from an answer, which never starts a talk and has to be linked from an answer on another line. There is also a Can start a conversation switch.
- The line: What the villager says, up to 600 characters.
- When it appears (leave it if unsure): Priority, Weight, Days before repeating and Say only once.
- When it can be said: condition cards, added with Add a condition. They include Relationship at least, Player carries an item, Something happened in the world, During a time of day and Speaker has a role, and you can combine them with All of these, Any of these and None of these (not). Add none and the line can be said any time.
- What happens when it is said: effect cards, added with Add an effect, for example Change relationship, Make the villager remember, Give an item, Offer a quest and End the conversation.
- Player answers: up to 6. Each answer has Answer text and Tone, and can have When this answer shows. An answer is a Plain answer or Needs a skill check (fill in Which skill, Difficulty and Luck range, and send success and failure to different lines). Leads to picks an existing line, (ends the talk), or New line, linked, which grows the next line for you.
The form shows a Conversation tree: green-edged lines open a conversation, below them are the lines each answer leads to, and a click on any line jumps to it. A line that nothing leads to and that is not an opening line is flagged, because it never shows up in the game.
The right column is the Conversation preview. It plays from the selected line, you click answers to move on, and Start over begins again. The preview does not check conditions, so every answer shows.
Advanced: writing the JSON by hand#
This is the same content as it is written in the file. The editor saves exactly this format. You can also press Open folder at the top of the editor and edit the file in an outside text editor; when you save, the editor picks up the change. Fields the form does not have are kept as they are. Where the file goes and how it is listed: Mod folder and mod.json.
The file is data/dialogue.json, and mod.json points to it with "dialogue": "data/dialogue.json" under content.
A minimal working example#
An innkeeper passes on a rumour. The player can ask for more, which gives +1 friendship, or just say goodbye:
[
{
"id": "wolf_rumor",
"attach": { "roles": ["INNKEEPER"] },
"text": "Travellers say wolves with frost on their backs roam the snowfields to the north.",
"texts": { "zh-TW": "旅人們都說,北邊的雪地有狼群出沒,牠們背上帶著霜。" },
"priority": 40,
"cooldownDays": 1,
"choices": [
{ "id": "more", "text": "Any other news?", "tone": "kind", "next": "wolf_rumor_more" },
{ "id": "bye", "text": "Thanks, I will be careful." }
]
},
{
"id": "wolf_rumor_more",
"start": false,
"text": "They say the wolves hardly dare come near unless you are alone at night.",
"onEnter": [ { "type": "relation_delta", "delta": { "affinity": 1 } } ],
"choices": [ { "id": "thanks", "text": "Good to know, thanks." } ]
}
]text is the main-language text and texts adds other languages (en, zh-TW, zh-CN). The text of an answer works the same way and can also have texts. A language you leave out borrows the text from another one.
Fields of a line#
| Field | Range and meaning |
|---|---|
id (required) | Your own name for it, same rules as other tables. An answer's next is this |
attach | Who says it: { "roles": [jobs...] }, { "npcs": [villagers...] }, both together, or "all" (every job). A line with attach is an opening line by default |
start | false marks a follow-up line that can only be reached through an answer. Required whenever there is no attach |
text, texts (required) | The spoken line, up to 600 characters |
priority | 1 to 200, default 40. When several lines could be said, the higher number goes first |
weight | 0.1 to 10. How strongly this line is favoured when it is picked |
cooldownDays | 0 to 30 days, default 1. How long before it can be said again |
once | never (default, can repeat), per_player (once per player) or per_world (once in the whole world) |
conditions | Up to 12 conditions, all must hold for the line to be said. See "Conditions" |
onEnter | Effects that happen the moment the line is said, up to 8. See "Effects" |
choices | The player's answers, up to 6 |
Answers#
| Field | Range and meaning |
|---|---|
id (required) | A name unique within this line |
text, texts (required) | What the player picks, up to 200 characters |
tone | Tone: honest, kind, formal, bold, threatening, deceptive, humorous, dismissive |
next | Which line to go to after choosing (that line's id). Leave out to end the conversation |
effects | Effects when chosen, up to 8 |
showIf | Conditions, up to 12. The answer is only shown when they hold |
check | A speech check: { "kind": kind, "difficulty": 0 to 60, "random": 0 to 20 }. kind is one of persuasion, insight, intimidation, deception, etiquette, leadership. random is how much luck can swing it, default 6 |
success, failure | Used with check: { "next": line, "effects": [...] }, what happens when the check succeeds and when it fails |
Who can say it: jobs and named villagers#
roles takes jobs. Every villager with that job says the line, including the named one. npcs only targets the named villager.
| `roles` value | Job |
|---|---|
MERCHANT | Merchant |
GUARD | Guard |
BLACKSMITH | Blacksmith |
INNKEEPER | Innkeeper |
ELDER | Elder |
FARMER | Farmer |
ADVENTURER | Adventurer |
FERRYMAN | Ferryman |
HEALER | Healer |
HUNTER | Hunter |
FISHER | Fisher |
MINER | Miner |
SCHOLAR | Scholar |
BARD | Bard |
STOREKEEPER | Storekeeper |
STABLEMASTER | Stablemaster |
| `npcs` value | Villager | Job |
|---|---|---|
bailu | Bai Lu | Bard |
haisheng | Hai Sheng | Fisher |
luqi | Lu Qi | Hunter |
tanwei | Tan Wei | Scholar |
yanshu | Yan Shu | Miner |
qingwu | Qing Wu | Healer |
zhuoying | Zhuo Ying | Blacksmith |
lingbo | Elder Ling | Elder |
luochuan | Luo Chuan | Guard |
henan | Henan | Merchant |
mira | Mira | Blacksmith |
sukui | Su Kui | Innkeeper |
Conditions#
Each condition in conditions and showIf is an object with an op. Nesting (all, any, not) can go at most 4 levels deep.
| `op` | Other fields | Meaning |
|---|---|---|
relation_gte, relation_lte | field, value (-100 to 100) | This villager's feeling towards the player is at least / at most that. field is affinity, trust, respect, fear, debt or intimacy |
stage_is | stage | The relationship stage is exactly: hostile, wary, stranger, acquaintance, friend, trusted, confidant |
player_stat_gte | stat, value (0 to 100) | The player's social skill is at least that: persuasion, insight, intimidation, etiquette, deception, leadership |
player_has_item | item, count (1 to 999, default 1) | The player is carrying this item (built-in or modded) |
player_has_tag | tag | The player has this identity tag |
memory_exists, memory_missing | tag; memory_exists also takes minConfidence (0 to 1) | The villager remembers (or does not remember) something with this tag |
world_flag | flag, equals (default true) | A world flag equals a value (true, false, a number or text) |
time_range | from, to (0 to 24) | The in-game time is within this window (0 to 24 hours) |
day_mod | modulo (1 to 30), equals (0 to 29) | The in-game day number divided by modulo leaves a remainder of equals, for example once every 7 days |
role_is | role | The speaker has this job |
all, any | conditions (up to 12) | All hold / at least one holds |
not | condition | The condition does not hold |
Effects#
onEnter and an answer's effects use these. Each effect is an object with a type:
| `type` | Other fields | Meaning |
|---|---|---|
relation_delta | delta: affinity, trust, respect, fear, debt, intimacy, each -20 to 20 | Change the relationship with this villager |
add_memory | tags (up to 6), salience (0 to 100, default 20), valence (-100 to 100, default 0), privacy (public, personal, secret) | Make the villager remember this. Later conditions can test it with memory_exists |
set_world_flag | flag, value (default true) | Set a world flag. Names use only lowercase letters, digits and underscores, and the game adds your mod id automatically |
add_identity_tag | tag | Give the player an identity tag, same naming rules as flags |
give_item | item, count (1 to 99) | Give the player items |
take_item | item, count (1 to 999) | Take items from the player |
change_currency | amount (-1000 to 1000) | Add or remove gold |
offer_quest, turn_in_quest | quest | Offer or hand in a quest. Use an id from your own Quests table, or @othermod/id |
adjust_village | field, delta (-15 to 15) | Change a village number: security, prosperity, foodSupply, morale, outsiderTrust, corruption |
close_conversation | none | End the conversation |
An example with a speech check#
Luo Chuan the guard watches the gate. The player can show proof (the answer only appears when they carry iron ore) or try to talk their way through. Success and failure lead to different next lines:
[
{
"id": "gate_toll",
"attach": { "npcs": ["luochuan"] },
"text": "I need to inspect your goods. Anything that proves who you are?",
"texts": { "zh-TW": "過關要查驗貨物。你有什麼可以證明身分的東西嗎?" },
"priority": 50,
"once": "per_player",
"conditions": [ { "op": "relation_gte", "field": "trust", "value": -10 } ],
"choices": [
{
"id": "show_ore",
"text": "I am a miner. This is my ore.",
"tone": "honest",
"showIf": [ { "op": "player_has_item", "item": "iron_ore", "count": 1 } ],
"effects": [ { "type": "set_world_flag", "flag": "gate_open" } ],
"next": "gate_pass"
},
{
"id": "talk_around",
"text": "Come on, bend the rules a little. I am in a hurry.",
"tone": "bold",
"check": { "kind": "persuasion", "difficulty": 25 },
"success": { "next": "gate_pass", "effects": [ { "type": "relation_delta", "delta": { "respect": 2 } } ] },
"failure": { "next": "gate_refuse" }
},
{ "id": "leave", "text": "Never mind, I will come back later." }
]
},
{
"id": "gate_pass",
"start": false,
"text": "All right, go through. Safe travels.",
"choices": [ { "id": "thanks", "text": "Thank you." } ]
},
{
"id": "gate_refuse",
"start": false,
"text": "No. Rules are rules.",
"onEnter": [ { "type": "relation_delta", "delta": { "respect": -1 } } ],
"choices": [ { "id": "fine", "text": "Fine." } ]
}
]Common mistakes#
- Forgetting
"start": falseon a follow-up line, or giving a follow-up anattach. A follow-up has noattachand is only entered through another line'snext. - A
nextthat points at a line that does not exist (or was skipped because it has its own error). The line holding that answer is then blocked, and the load check names the missing line. - Putting
effectsornexton an answer that has acheck. They belong insidesuccessandfailure. - More than 6 answers on a line, or more than 8 effects.
- Using capitals or spaces in a flag name. Flags and tags use lowercase letters, digits and underscores only.
- Writing a name in
offer_questthat your quests table does not define. - A line that comes up too often. Raise
cooldownDaysor addonce.
Related pages#
- Quests: use
giverto add the offer dialogue for you, or hand out quests yourself withoffer_quest. - Director events: the
evt_<event id>flag lets villagers speak while an event runs. - Species
- The mod editor: build this kind of content with forms and test it in the game.