Dialogue Basics

Dialogue Basics


How Dialogue Works
Creating Dialogue Packages
Dialogue Systems as a Scripting Engine

How Dialogue Works

Back to top

Dialogue Events

Dialogue events are individual pieces of dialogue that occur when some trigger is fulfilled. Broadly speaking, a dialogue event has three purposes:

  • Worldbuilding. Dialogue is used to deepen the lore of the game – whether it’s an idle conversation between two guards; a player inquiring about the locals; or some bar talk hinting at what’s going on in the world.
  • Roleplaying. Dialogue allows a player to initiate and engage in conversations, make choices, and express their opinion. It’s also important for (player) characters to express their opinions and immediate reactions to the game world. Idle conversation between PCs is one example; screaming in agony because it’s raining acid is another.
  • Reactive AI. Dialogue is used to round out and deepen an NPC’s AI. While the Goal-Oriented Action Planning (GOAP) system creates an AI framework with broad strokes, it’s the dialogue system that allows for complex decision-making.

Dialogue events range from simple throwaway lines to complex branching dialogue trees and – when used correctly – it’s a powerful toolbox of functions. The advanced dialogue chapter (pending) covers many important concepts, such as using empties, affecting world data, event jumping, dialogue passing, and more. It demonstrates the power of crowd triggers, interjectors, interrupts, and wordswaps when they’re used to their full potential.

The dialogue editor looks like this:

You’ll find a detailed breakdown of dialogue events, conditions, and effects here.

  • Each condition in the conditions box is added as an AND statement and may apply to anybody (speaker, target, interjectors)
  • Effects only occur if a dialogue line plays and isn’t empty. An empty line will passthrough to the next
  • The box in the top right corner references other game objects as conditions and effects
  • Each line of dialogue may have multiple assigned in the text fields. In which case, a random line is chosen


Each line of dialogue and each condition requires a speaker. The speakers are differentiated by their colour in the editor:

  • T_ME (black): The dialogue owner
  • T_TARGET (red): The target of the dialogue
  • T_TARGET_IF_PLAYER (red): The target of the dialogue only if it’s a player*
  • T_INTERJECTOR (blue/green): One of up to three interjectors from the owner’s squad
  • T_WHOLE_SQUAD (pink): Anybody from the owner’s squad
  • T_TARGET_WITH_RACE (red): A target with a race specified on the same line under “my race”. Searches for a specific race (see advanced dialogue)

*This is rarely used in vanilla and isn’t really needed as there’s already an “is player” condition.

Dialogue doesn’t have to be initiated by T_ME, though it usually is. Note that a character must be conscious to have a speaking line and dialogue will end if the dialogue owner becomes incapacitated.

Interjector Nodes

Interjector nodes add more characters frrom the speaker’s squad to the conversation. They can’t be used in talkto events but otherwise act as search functions returning a character with the conditions specified on an interjector node.

The nodes are covered in more detail in advanced dialogue, but note the following:

  • Nodes must be added before an interjector can speak
  • The same interjector node (e.g. Interjector 1) can be run multiple times to select different characters
  • Nodes using the “is character” condition can be used to force characters with the “dumb” trait (e.g. Agnu) to speak. This is the only time the “is character” condition applies to somebody other than T_ME.
  • Nodes can be run before any dialogue is spoken for advanced dialogue checks
  • Nodes won’t work if you change their speaker to a non-interjector (e.g. to T_TARGET)


Dialogue conditions are used to restrict when a line of dialogue can play. For instance, you might want a line of dialogue to play only when in combat. In which case, you’d use the condition,


A 1 means “true”, while a 0 means “false”.

Conditions that are added onto the dialogue root are assessed before the dialogue event plays. Be aware that if you have both conditions on the root and on the first line of dialogue, you might end up triggering the root timer even if the first line is false.

For example, imagine you have a dialogue event where the root condition is that the character is in combat. The root also has a dialogue timer. On the first line, there’s a condition that the character must be outnumbered. If the character isn’t outnumbered but the root condition is true, the root timer will trigger, like this:


You can see the score in square brackets at the start of a dialogue line. Score is used to weight particular lines. By default, interjector nodes have a higher score than other lines.

You can add an artificial score to a line to give it priority over others (e.g. for a line with lots of conditions). However, all conditions are weighed up before a line with no conditions is chosen. So, in the following example, the first line will always play if the character is female.

The “C” in square [] brackets denotes that a line has conditions, while an “E” denotes it has effects assigned to it.

When working with score, it’s generally recommended to use unambiguous values (i.e. “idiot proof”) to ensure you get your desired result. Use scores of 10, 20, 50, 100, and so on.

Linking to Another Line

To jump to another line of dialogue, shift + drag one line onto another. Make sure you don’t create infinite loops that can’t be broken out of. If it’s a player-chosen line (e.g. below) it’s fine.

Interrupts and Crowd Triggers

Interrupts and crowd triggers let you call another dialogue event.

Interrupts override a character’s talkto event until they stop speaking. When a player hovers over them with the mouse, they’ll see an orange speaking icon displayed instead of the regular white one.

Crowd triggers cancel the current dialogue and run a new event – but for all characters in a squad.

Both of these effect types are powerful and covered in detail in the advanced dialogue chapter.

Player Talktos

Talktos are those events where the game is paused, a dialogue window displays, and the player can choose options. The top item in a character’s dialogue package, talkto events work a little differently:

  • Talkto dialogue is between the speaker (T_ME) and the player (T_TARGET)
  • Each line must link only to lines spoken by one of these characters, i.e. don’t put both player and NPC lines after a line
  • The player sees all available options at once and can choose freely
  • The final line spoken by an NPC (T_ME) is displayed above the character’s head. You can use talktos to play idle one-liners this way.
Because line 1 is followed by both player and NPC lines, the NPC will keep speaking, able to pick any line, and things will get confusing

You can use conditions on player lines, too. For instance, you might wish to only have a line display if the player has enough money, else display a line where they can’t afford something.

All dialogue effects will default to the NPC’s perspective in a talkto, even if it’s on a player line.

Dialogue Repeat Timers

Any dialogue line or event may use a repeat timer. Once triggered, these timers apply to all instances of a line, so if character A triggers a timer, character B won’t be able to use that line/event until the timer runs out.

  • DR_NO_LIMIT: The default. No timer.
  • DR_SHORT_2: Two in-game hours.
  • DR_MEDIUM_6: Six in-game hours.
  • DR_LONG_48: Two in-game days.
  • DR_LONG_1WEEK: Seven in-game days.
  • DR_ONCE_ONLY: Once, only, ever.
  • DR_VSHORT_020: Twenty in-game minutes.

Twenty minutes is the shortest timer, and also the amount of time an AI contract runs for if its timer is set to 0.

Unlock Events

Any dialogue event may be “locked” by default. In which case, it requires the speaker to play another dialogue event that unlocks it. Similarly, dialogue can be locked by another event to using the “lock dialogue” effect:

Dialogue Packages

Dialogue events are wrapped up in packages, and dialogue packages are assigned to NPCs. They can use inheritance – so you don’t have to remake every package for every character. For example, you might have a “soldier” and “officer” dialogue package, where the officer type reuses the soldier’s package but with an additional talkto event.

Dialogue packages are assigned either to characters directly or in squads, and you can assign as many packages as you want instead of using inheritance. Any packages that are assigned to a squad override character-set dialogue, which is lost.

See the “mercenary” dialogue package for an example.

In addition to packages, a leader may have additional dialogue talkto events assigned through a squad. This won’t override anything but add more. In general, it’s better to design your packages by hand and assign them to characters.


Wordswaps are a special kind of dialogue that’s covered in more detail in the writing better dialogue and advanced dialogue chapters.

Put simply, wordswaps allow you to substitute a word, phrase, or dialogue fragment:

  • Wordswaps can be used for random variation
  • Wordswaps can be used for conditional alterations
  • Wordswaps can be nested (i.e. reference other wordswaps)
  • Wordswaps follow all “regular” dialogue rules

A wordswap can’t use dialogue effects – so it can’t make an NPC attack, give the player an item, or affect the AI. Otherwise, all regular rules of dialogue apply: Repeat timers and conditions still work.

A simple example of a conditional wordswap are the “HE”, “HIM”, and “CHARGE” swaps, while an example of a procedural wordswap is the “RACISTBABBLE” swap.

Wordswaps are referenced between / / brackets, like this: “Get /HIM/!”. The error log will flag any wordswap that hasn’t been terminated with a second slash.

In rare cases, you may wish to enable the persistent use tag. This is helpful for procedurally generating things like character catchphrases – a character will use the same line each time they play the swap.

Creating Dialogue Packages

Back to top

Dialogue packages are where all the dialogue events are hooked up. They dictate what trigger cause what dialogue to play. By default, player characters are assigned the “player character default” dialogue package even if they don’t have any dialogue assigned.

Player vs. NPC Dialogue

Characters have two sets of dialogue assigned:

Should an NPC ever become a player character, their existing dialogue packages will be erased and replaced with their player packages. Notably, they’ll retain their player dialogue if they’re ever dismissed.

Player dialogue packages work as NPC packages, with a few caveats:

  • PCs can’t have talkto events
  • Many events no longer trigger, such as the “looting” or “crime” dialogue events


Dialogue packages can inherit from other packages. For example, most NPCs in vanilla inherit from a very basic package to give them base functionality:

Similarly, package inheritance can be nested. If a character inherits the dialogue package above, they’ll also get the default “imprisoned” and “bought from slavery” reactions, allowing them to respond intelligently to those events.

Dialogue Systems as a Scripting Engine

Back to top

Kenshi’s dialogue system can be used to do a lot more than have NPCs talk.

You can use it to craft complex, reactive AI. It can make player characters react dynamically to events around them. Harnessed correctly, you can create a living, breathing world that changes and evolves – and all sorts of quests and procedural events are possible with it.

Head on over to one of these two chapters to learn more:

  • Advanced dialogue covers dialogue systems in-depth
  • Writing dialogue that works is a thinkpiece about outlier events, reactive AI, and strategies for procedural dialogue design

When they’re done I’ll add links. Either Feb or March idk.