Dialog System Documentation

Introduction

All dialogs are created in Skald and stored in several DB tables.

Dialogs do not only hold the dialog texts and dialog structure, but also provide crucial means for scripting. They are, in fact, one of the 3 main places for content scripting along with (Quest) Flow Graph and MBT Trees.

Skald provides a human readable look at dialogs which slightly obscures the actual data structure. Skald provides the chapter-subchapter systems for purely organizational purposes. All dialogs are equal, and could theoretically be moved to another subchapter(=quest) without affecting the game in any way.

What happens when you initiate a dialog via Talk action

1. When you look at an NPC, the dialog system selects all dialogs where the player’s role and the NPC’s role are present, and evaluates validity of all their root sequences.
2. If it finds any such sequences, the Talk action (press E) is shown.
3. When you press E the dialog system selects the dialog (actually a topic) with highest priority to be played. If there are more dialogs with the same priority, the player gets to choose which one to start (you almost never want this to happen!). If there are no priority dialogs (=priority is higher than 0) the dialog system simply goes to dialog root without playing any sequence.
4. Dialog root lists all the valid root sequences from all the dialogs between you and the NPC. Additionally, the dialog system adds an auto-generated topic (End Dialog), but only in root.
5. You can select any of these sequences which takes you whichever dialog and its structure it belongs to.
6. If the dialog reaches a DECISION and more than one sub-sequence are valid, the player is again presented with a list of valid sequences. If there is NO valid sub-sequence the dialog abruptly ends (this is treated as an error). If only one sub-sequence is valid the dialog continues automatically.
7. If a sequence end with END TOPIC the dialog goes back to root. If the dialog ends with END DIALOG the dialog ends then and there. If there is no valid root sequence when the system goes back to root the dialog ends.

Dialog breakdown

A dialog typically looks like this

Roles

Each response (line of dialog) must belong to a role (see more in souls, roles...). A dialog may contain any number of roles. Roles are reusable across all dialogs, and are then ascribed to any number of souls, and subsequently a character and a voice. A soul can potentially engage in any dialog where their roles appear.

One role makes a monolog, 3 roles make a trialog, and so on. This particular dialog contains 2 roles which makes it a true dialog. The role JINDŘICH represents HENRY, the player character.

There is no technical difference between monologs, dialogs, trialogs, quadrialogs etc. They however do differ in their usage.

Roles array

A temporary Dialog Context array, with references to the participant entities, is created when the dialog starts. The participants are written in the array in the following order: [0] initiator, [1] first other appearing role, [2] second... etc.

1. In exit script you can refer to the entity via table reference dc.ROLE
   Example:
   Utils.GiveItem(player, dc['MILOMIR'], "money", 80) --gives 8 player’s groschen to entity with role MILOMIR
2. In the entry conditions you can refer to the entities via index number ([0],[1]...etc.) or directly via entity name. Entry conditions which require that contain the word Actor
   Examples:
   GetActorMoney()['Dude'] > 50 --True if player has more than 5.0 groschen GetActorMoney()[0] > 50 --True if dialog initiator (usually the player) has more than 5.0 groschen IsActorInside('q_skalitz_kunes_triggerArea2')[1] --True if second-role participant is inside area specified by area entity name

 

Types by role count

Monologs - utilize a more lightweight part of the dialog system (it skips some checks and synchronizations), which makes them faster but also somewhat limited. One of the downsides is that a monolog is not guaranteed to be played in their entirety and you SHOULD NEVER expect them to execute any critical logic.

Dialogs are further divided into forced and normal.

Forced dialogs – are initiated by an NPC via a special behavior script. They can happen between any 2 NPCs or an NPC can force it on the player. Both situations are somewhat dangerous and unguaranteed. A dialog forced on the player should always be preceded by some kind of fader situation (fast travel, cutscene, custom fader, jail etc.). A dialog forced on the player should always start with the NPCs role, not the player role, and vice versa.

Normal dialogs – are initiated by using the Talk action on the NPC and are the only safe dialogs. The Talk action is shown only if the soul has ANY valid dialog. A normal dialog should never start with the NPC speaking, unless you know what you are doing.

Polylog (Trialogs and up) – cannot be initiated by the Talk action; must be forced by an NPCs. Since automatic dialog cameras don’t work properly in trialogs (and up), they require hand-made custom camera and pre-determined positions for every participant. That, just like forced dialogs, requires a fader sequence prior to start, if only to hide the forced positioning. Dangerous trick: You can initiate a trialog via Talk action by enabling fake empty dialog(s), which immediately end but turn on a fader screen, which you use for trialog preparation, which then use one NPC to force the trialog.

Sequences

There are, in total, 15 responses (dialog lines). However the smallest logical unit of a dialog is a sequence. A dialog sequence is any uninterrupted sequence of responses (from start to END or from start to a DECISION). Entry conditions (validity conditions) are applied to sequences. An exit script or an objective actions can only be executed at the end of a sequence. Tip: If you need to run a script in the middle of a sequence, simply split it in two by adding a so-called fake DECISION, a decision which offers only one option and thus doesn’t pause the dialog.

This also means that you CANNOT resume a sequence in the middle. If a long monolog/dialog sequence is being played, and the script guarantees the dialog must finish, even of you save and load, the dialog, or at least the sequence, will start over after loading.

Topics

There are no decisions in the DB dialog data model. Instead there are the following tables: topic, topic2sequence, and sequence. All sequences below the same “decision” have the same topic ID. A forced dialog always forces a topic, never a sequence, so always have to pay extra attention to properly defining entry conditions. Sequence table holds the exit scripts and a reference to the following topic. Topic2sequence table ties sequences to topics and contains entry conditions. Topic holds a textual alias for the topic ID, topic priority, and a deciding role (if defined, it is the NPC who chooses, not the player).

In essence, the dialog system is unaware of the concepts of a chapter, a quest, a decision, and a dialog. All content of all dialogs is simply a set of topics with one or more sub-sequences where each sequence defines the following topic. If the next topic is 0, the dialog ends. Chapters, subchapters (quests), decisions, and dialogs only serve the purpose of content organization and human readability.

Monologs can also look like this

This is just an alternative limited tool used for writing simple linear monologs in-line in the cutscene and gameplay sections. It does NOT differ from its equal definition in Br. Dialog section in any way.

Decisions and dialog choice

Decisions (merely a visual syntactic sugar, see Topics) mark a point where a sequence ends, and the dialog can continue through one or more options.

The player is provided with a dialog choice when there are at least 2 valid sub-sequences after a Decision. No matter what the roles are there. That means that, by default, even if you intended the NPC to continue one way or another, but the conditions say that both options are valid, it is the player who chooses. The only 2 ways to prevent player choice in such cases are:

• guaranteed exclusiveness of the entry conditions (usually a condition and its negation)
• setting the NPC’s role as a Topic Role to that topic. This will result in random selection from the valid set of options.

GOTOs

A GOTO (“next” in DB table sequence) defines where the dialog continues, if the sequence doesn’t end with an END or a DECISION. GOTO 0 is equal to END TOPIC, that is jumping back to dialog root.

Dialogue Type

Each dialog, or rather the its root topic, can have a “Dialogue type”

Normal = If the dialog features 2 roles the dialog is a standard one. Dialog cameras are generated, and dialog choices are possible

Greeting = a special type which defines this dialog as a possible generic greeting the NPC says prior to starting a player-NPC dialog

Ending = the same, but a farewell

Monolog = optimization option which tell the Dialog System to not even attempt any non-monolog operations (cameras, multi-role dialog evaluations etc.)

InGame = tells the Dialog system to not start the cameras. Does not allow dialog choices.

InGame monolog = a monolog that is forced to be in-game

Dialog scripting

Beside the inherent logic created by the dialog structure itself, you can use the 3 major following means of scripting – entry conditions, exit scripts, and objective actions.

Entry conditions

Entry conditions apply to sequences, and defines the validity of a sequence. If it’s true, the dialog is valid and thus selectable. If it’ invalid the dialog sequence cannot be played nor selected.

Entry conditions Expression Evaluator functions.

Empty entry conditions in root topic sequences are implicitly FALSE.

Empty entry condition in any other sequence is TRUE.

That means that in terms of dialogs (their root topics) all dialogs are disabled by default and must be explicitly enabled.

Expression aliases (compound conditions)

Expression aliases (Exp. aliases) are compound entry conditions stored in DB and referred to via a custom alias name. They are useful when a complex condition needs to be reused, or when you want to easily negate a complex condition.

Exit scripts

Exit scripts are LUA scripts executed at the end of a sequence.

Objective actions

executed at the end of a sequence and are synchronized (=the operations are guaranteed to be finished before the next sequence starts). You can set ANY objective from the entire game to a desired state. Objective state-transition limitation rules apply (see Quest System)

Objective action can also feature a condition under which it is applied. Same as entry conditions.

Additional scripting tools

Skill Checks

Skill checks can be considered a sort of conditioning tool. The tool is more general and simply adds a predefined icon appears next to the sequence it is set to. The only special options whic do something more are: Threaten
Persuade
Impress
Bribe

Based on the type and difficulty they fill a temporary local variable “success” with value ranging from -1 to 1 which you have to then test for in subsequent decision. The actual tests are protected via self-explanatory Expression Aliases skillCheckSuccess and skillCheckFail you are advised to use.

Additionally, the Bribe option requires:

•  !Include=bribe_man! or !Include=bribe_woman!
• The NPC to have the role VYJEDNAVANI_(MUZ) for men or VYJEDNAVANI_(ZENA) for women
• Exit script SetupBribe(100) to setup the starting bribe value, prior to inclusion

Cooldown

A sequence can have a cooldown set. Cooldown defines for how many seconds, in GameTime, is this particular sequence invalid (despite the entry condition). Cooldown = -1 is auto-disable, which disables the sequence forever after it is played for the first time.

 

Advanced tricks

Sequence splitting and fake decisions = adding decisions with only one option for the purpose of splitting a sequence in two or for a GOTO to be linked there.

Empty responses = a response with no dialog line

Dialog inclusion = using the exclamation operator (!) you can include a topic (by alias) from another dialog. The included dialog will play, and if ending with END TOPIC, the includer will take over and continue.

Playing around with topic priorities over multiple dialogs.

Forcing a non-root topic = dialogs are forced via topic. You force any subtopic which may start the dialog from somewhere in the middle of its structure.

Stealth dialog = Creating a hidden dialog structure by hiding it under an invalid empty sequence.

!addRole command = can create a dialog with no response form one if the participant (the added role). It looks like a monolog but is technically a dialog.

InGame type dialogs = is technically a dialog but doesn’t start the cameras and doesn’t allow dialog choices. Useful for dialog rejection in-game “barks”