Dialog Engine — the dialog box and the scenario language

Dialog Engine is what the player reads and clicks: the dialog box with its lines, portraits and answers. Behind it is the scenario language — small .scenario text files in which a story is written line by line: what is said, which answers there are, where each answer leads, and what happens in the game (a new background, music, an item, a quest step, another scene). Every game in the collection, from the novel template to RPG Plus, tells its story with it.

What the player sees

A scene's scenario starts by itself when the player enters the scene. Lines appear in the box at the bottom; a click shows the next one:

When the story asks something, the answers appear on the right. The story waits until one is chosen:

"Go into the bar" takes the player to the bar scene, which starts its own scenario:

The scenario behind these pictures

This is the whole town scenario of the novel template (my_novel_game/scenarios/my_novel_town.scenario):

scene: my_novel_town
priority: 10
---
# The town is the hub: every visit shows the same choice.
text "Evening town. The street lamps are already lit and a cool draught runs along the cobbles." key=my_novel/town/intro
select "Where to go?" key=my_novel/town/prompt
option "Go into the bar" key=my_novel/town/opt_bar -> :bar
option "Go back home" key=my_novel/town/opt_home -> :home

:bar
switch_scene my_novel_bar
end

:home
switch_scene my_novel_home
end

The header above --- says when the scenario plays: scene: names the scene, priority: orders several scenarios of one scene (lower plays first). More header lines are below.
text "…" shows a line and waits for a click. key= is the translation key of the line; the quoted text is what is shown when no translation is found.
select asks a question, and each option is an answer that jumps to a label (-> :bar).
:bar is a label; switch_scene goes to another scene; end finishes the scenario.
A line starting with # is a note for the author.

To add a story to a scene, put a .scenario file anywhere in your mod's scenarios/ folder and name the scene in its header.

Writing a story

Lines and portraits. text "…" first=marao/sad shows a portrait in the first place, second=… in the second (see Characters Engine). ptext is the same as text, and also replaces ${name} with the value of a variable. title "…" shows a chapter title.

Choices and jumps. An answer can be shown only when a condition holds: option "Pay" "if=item('money/coin') >= 5" -> :pay (a condition with spaces is quoted together with if=). goto -> :label jumps without asking. when "<condition>" -> :label jumps if the condition holds at that moment:

when "rpg_wolf_dead == 1" -> :lantern

Remembering things. flag rpg_quest_taken 1 sets a story flag that is saved with the game; conditions read it as rpg_quest_taken == 1. set name value sets a variable of the running dialog; ptext shows it as ${name} and actions can read it.

Conditions are one shared language: flags, item('id') from Items Base, quest checks from Quests Engine, stats and equipment from their mods, joined with &&, || and !.

The scene. background, foreground, background_color, music, sound, effect, delay, light_set, hide_dialog/show_dialog, interactive_add/interactive_remove, notify.

Game actions. action <name> key=value … runs an action of another mod, for example action item.add id=money/coin count=3 or action quest.set_status quest_id=woodland_ward status=Progress. The schema files of the mods list the actions, and Editor Tools offers them in its scenario editor and command palette.

When a scenario plays

The header decides it:

scene: prolog_alley
priority: 15
condition: AwakeningQuest.notHasTag("cloak_taken")
is_one_run: true
save_allowed: true
---

scene: — the scene where it plays when the player arrives.
priority: — order among scenarios of the same scene; the lowest number that may play goes first, and the next one starts when the dialog ends.
condition: — it plays only while the condition holds; when a flag or quest changes, the scene checks again.
is_one_run: true — it plays only once per game.
after: — it waits until the named scenario has played.
save_allowed: true — the player may save in this scene.

A scenario without a scene: header is not started by a scene; it is run by something else, such as a click on an interactive object or a map event.

Other mods add and replace scenarios

Scenarios of all mods are collected together. A mod adds a story to someone else's scene simply by naming that scene. A mod that depends on another and ships a scenario with the same file name replaces it.

If something goes wrong

A scenario never plays. Its scene: name is wrong, its condition is false, or it has is_one_run and has already played.
The line is shown in the wrong language. The key= is missing from the mod's locale files for that language; the quoted text is shown instead.
An answer leads nowhere. The label after -> must exist in the same file, written with a colon (:bar).
An action does nothing. The mod that owns the action is not part of the game (the log says the action "is not registered"), or a parameter name is wrong — compare it with the action in the scenario editor of Editor Tools.

5.8 KiB Raw Blame History