Dialogue scripts
A conversation is a .qds text file. Drag it into the Content Browser and it becomes a dialogue
asset; right-click the asset and pick Reimport after editing the file. Because scripts are
plain text, they diff and merge in source control, and a writer can
work in any text editor.
A script runs from its first line down, one statement per line. A line that starts with # is a
comment; a # later in a line is part of it. Indentation and blank lines don’t matter. The
keywords (speaker, if, do and its actions, end, has, can start, is, and, not)
are lower case; quest names and states can be in any case.
# Bram, the gatekeeper
speaker Bram: Bram the Gatekeeper
if Gate is completed -> open
Bram: Halt. Nobody passes without the captain's word.
* {has Pass.Captain} I have it here. -> pass
* {can start Gate} Can I help? -> help
* Goodbye.
Bram: Move along, then.
end
== help
do start Gate
Bram: Clear the wolves from the road and I'll think about it. | voice=/Game/Voice/Bram_Wolves
end
== pass
do complete Gate
do event OpenGate
== open
Bram: Go on through.
Lines
Speaker: What they say.
Speaker: What they say. | voice=/Game/Voice/Line_01
- The speaker is an id: letters, digits and
_, not starting with a digit. It shows as the id with_turned into spaces unless aspeakerstatement names it. | voice=plays a sound asset with the line. The line moves on when the sound ends, unless options follow it; the player can skip it.- A line waits for the player to continue, with the dialogue box’s keys.
speaker Bram: Bram the Gatekeeper
speakergives an id the name shown for it:speaker Bram: Bram the Gatekeepershows Bram’s lines under “Bram the Gatekeeper”. Put it anywhere; it holds for the whole script.
Options
* Text of the option -> label
* {condition} Text shown only if the condition holds -> label
* Text of an option that carries on after the menu
- Options in a row make one menu, shown with the line directly before them. With a
door anifin between, the menu shows on its own, with no speaker or text. The player picks one with the mouse, a gamepad, or the number keys 1 to 9. - An option with
-> labelgoes to the label. One without goes on to the first statement after the menu. - An option whose condition fails isn’t shown. If no option shows, the menu is skipped.
Labels and jumps
== label
-> label
-> end
end
== labelnames the place where the next statement starts. Labels are letters, digits and_, not starting with a digit, and notend.-> labelgoes there.-> endandendend the conversation.- Without a jump, a script runs into the next label’s statements, the way
passruns intoopenabove. It ends at the end of the file. - A Speaker component or Start Dialogue can start a script at a label instead of the top.
Conditions
if condition -> label
if jumps when the condition holds and goes on to the next statement when it doesn’t. The same
conditions work in { } on an option.
| Condition | Holds when |
|---|---|
has Tag |
the player holds the gameplay tag, or a tag under it |
can start Quest |
the quest can start: not active, not done unless repeatable, its requirements met |
Quest is active |
the quest is in that state: inactive, active, completed, failed or abandoned |
Join conditions with and, and put not in front of one to turn it around:
if Gate is completed and not has Pass.Used -> again
There is no or: write two if lines to the same label.
On a client, conditions read the player’s quests as replicated, so a change made just before (a
do above, or the Talk Event Tag reported as talking starts) shows a round trip later. An if
right after a do still sees the old state there: jump on what the script just did instead.
Actions
do changes the player’s quests, or tells your Blueprints something.
| Action | Does |
|---|---|
do start Quest |
starts the quest if it can start |
do restart Quest |
starts it again from its first stage, whatever its state |
do complete Quest |
completes it, if it is active |
do complete Quest Objective |
completes one objective of its current stage |
do fail Quest |
fails it, if it is active |
do fail Quest Objective |
fails one objective; a required one fails the quest |
do abandon Quest |
abandons it, if it is active and its Can Abandon is ticked |
do advance Quest |
completes its current stage |
do track Quest |
makes it the tracked quest, if it is active |
do report Tag |
reports a quest event, as Report Quest Event does |
do report Tag 3 |
the same, counting 3 towards the objective’s Count |
do add Tag |
gives the player the gameplay tag |
do remove Tag |
takes it away |
do event Name |
fires On Dialogue Event with Name, on the speaker’s Speaker component and on the player’s dialogue subsystem |
do give |
the speaker hands the player something: both reach out, its hand to the player’s (gestures) |
do take |
the player hands the speaker something |
do event is how a script opens a door, gives an item or plays a sound: bind the event in your
Blueprint and check its name. do give and do take only show the hand-over; give or take the
item itself with a do event beside them.
Names
- Quests are named by their asset’s name, such as
Gatefor a quest asset calledGate. If two quest assets share a name, give the path:/Game/Quests/Gate. - Tags are gameplay tags that must exist in Project Settings > GameplayTags.
Errors
Import checks the whole script and names each problem’s line in the Message Log:
- an unknown label, quest, objective or gameplay tag, or a quest name more than one asset has;
- a label defined twice, or a label name that isn’t one;
- a voice path with no sound asset;
- a line or option with no text, or a
{without its}; - a condition,
doaction orspeakerstatement that isn’t one, anifwithout its-> label, or a count that isn’t above 0; - a line that isn’t a statement.
A script with errors still imports, but the dialogue asset fails validation until they are fixed. A line no path can reach, and a script with no statements, get a warning.
Localisation
All text in a script is localisable. Each line is keyed by its text under the namespace
QD.<AssetName>, so editing one line leaves the others’ translations alone, and lines with the
same text share one translation. Speaker names are keyed speaker_<Id>. Gather it with the
Localization Dashboard: add a gather from packages that covers the folder of your dialogue assets.