104 lines
6.2 KiB
Markdown
104 lines
6.2 KiB
Markdown
# 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`):
|
|
|
|
```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:
|
|
|
|
```scenario
|
|
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:
|
|
|
|
```scenario
|
|
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
|
|
|
|
1. **A scenario never plays.** Its `scene:` name is wrong, its `condition` is false, or it has `is_one_run` and has already played.
|
|
2. **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.
|
|
3. **An answer leads nowhere.** The label after `->` must exist in the same file, written with a colon (`:bar`).
|
|
4. **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.
|
|
|
|
## Shared expressions
|
|
|
|
Numeric expressions are supplied by `expressions_base`. Use `set money=rnd(3,5)` or `cset total "1+2+${money}"`; reuse `${money}` in localized text and action parameters. `set name value` still stores a literal string. See the [Expression Engine guide](../../expressions_base/docs/en.md) for syntax, strict assignments and mod-defined strategies.
|