Mods are a feature of the full game, not the demo. They open when the full game launches, and details may change before then.

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 attach to 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:

data/dialogue.json
[
  {
    "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#

FieldRange and meaning
id (required)Your own name for it, same rules as other tables. An answer's next is this
attachWho says it: { "roles": [jobs...] }, { "npcs": [villagers...] }, both together, or "all" (every job). A line with attach is an opening line by default
startfalse 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
priority1 to 200, default 40. When several lines could be said, the higher number goes first
weight0.1 to 10. How strongly this line is favoured when it is picked
cooldownDays0 to 30 days, default 1. How long before it can be said again
oncenever (default, can repeat), per_player (once per player) or per_world (once in the whole world)
conditionsUp to 12 conditions, all must hold for the line to be said. See "Conditions"
onEnterEffects that happen the moment the line is said, up to 8. See "Effects"
choicesThe player's answers, up to 6

Answers#

FieldRange and meaning
id (required)A name unique within this line
text, texts (required)What the player picks, up to 200 characters
toneTone: honest, kind, formal, bold, threatening, deceptive, humorous, dismissive
nextWhich line to go to after choosing (that line's id). Leave out to end the conversation
effectsEffects when chosen, up to 8
showIfConditions, up to 12. The answer is only shown when they hold
checkA 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, failureUsed 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` valueJob
MERCHANTMerchant
GUARDGuard
BLACKSMITHBlacksmith
INNKEEPERInnkeeper
ELDERElder
FARMERFarmer
ADVENTURERAdventurer
FERRYMANFerryman
HEALERHealer
HUNTERHunter
FISHERFisher
MINERMiner
SCHOLARScholar
BARDBard
STOREKEEPERStorekeeper
STABLEMASTERStablemaster
`npcs` valueVillagerJob
bailuBai LuBard
haishengHai ShengFisher
luqiLu QiHunter
tanweiTan WeiScholar
yanshuYan ShuMiner
qingwuQing WuHealer
zhuoyingZhuo YingBlacksmith
lingboElder LingElder
luochuanLuo ChuanGuard
henanHenanMerchant
miraMiraBlacksmith
sukuiSu KuiInnkeeper

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 fieldsMeaning
relation_gte, relation_ltefield, 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_isstageThe relationship stage is exactly: hostile, wary, stranger, acquaintance, friend, trusted, confidant
player_stat_gtestat, value (0 to 100)The player's social skill is at least that: persuasion, insight, intimidation, etiquette, deception, leadership
player_has_itemitem, count (1 to 999, default 1)The player is carrying this item (built-in or modded)
player_has_tagtagThe player has this identity tag
memory_exists, memory_missingtag; memory_exists also takes minConfidence (0 to 1)The villager remembers (or does not remember) something with this tag
world_flagflag, equals (default true)A world flag equals a value (true, false, a number or text)
time_rangefrom, to (0 to 24)The in-game time is within this window (0 to 24 hours)
day_modmodulo (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_isroleThe speaker has this job
all, anyconditions (up to 12)All hold / at least one holds
notconditionThe condition does not hold

Effects#

onEnter and an answer's effects use these. Each effect is an object with a type:

`type`Other fieldsMeaning
relation_deltadelta: affinity, trust, respect, fear, debt, intimacy, each -20 to 20Change the relationship with this villager
add_memorytags (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_flagflag, 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_tagtagGive the player an identity tag, same naming rules as flags
give_itemitem, count (1 to 99)Give the player items
take_itemitem, count (1 to 999)Take items from the player
change_currencyamount (-1000 to 1000)Add or remove gold
offer_quest, turn_in_questquestOffer or hand in a quest. Use an id from your own Quests table, or @othermod/id
adjust_villagefield, delta (-15 to 15)Change a village number: security, prosperity, foodSupply, morale, outsiderTrust, corruption
close_conversationnoneEnd 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:

data/dialogue.json
[
  {
    "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": false on a follow-up line, or giving a follow-up an attach. A follow-up has no attach and is only entered through another line's next.
  • A next that 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 effects or next on an answer that has a check. They belong inside success and failure.
  • 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_quest that your quests table does not define.
  • A line that comes up too often. Raise cooldownDays or add once.
  • Quests: use giver to add the offer dialogue for you, or hand out quests yourself with offer_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.