Module dialogue 

Dialogue scripts (.dlg files): scenes of portraits, speech, narration, reply choices and music changes. parse_dlg turns a file into scenes, check_scene and check_duplicates validate them against the game’s SceneRules, and print_scene writes a scene back out. Every line that shows text has a LineId. Lines in an @if block play only while a character is there (Present).

A game adds directives of its own (a place behind the talk, a cut to a map) with a Directive type: the parser hands it every @name it doesn’t know, and a scene keeps the steps it makes in order.

As a format (ADR-0007), Dlg reads a file’s scenes (DialogueFile), and scripts_from_parsed checks them.

The format, for a game that adds no directive:

@scene gate_talk
@caption The east gate, dusk
@left mentor neutral
@right scout happy
mentor: Is the road clear?
scout[sad] (quietly, out of breath): Not since noon.
  Riders came over the hill.
> Rain begins to fall.
@delivery low, keeping out of sight
mentor: Then we go by the river.
@delivery clear
@music storm
@choice
* earnest: Then we wait.
  mentor: Agreed.
* wry: Then we get wet.
@endchoice
@if scout
scout: I'll keep watch.
@else
> Nobody keeps watch.
@endif
@end

Structs

CharacterId

String id of a named character, e.g. "guard_captain". Serialised as the bare string, so files name a character as "guard_captain".

ChoiceOption

One reply the player can pick: * <tone>: <text>, then its reaction.

DialogueFile

The scenes of one .dlg file as written, each with where it is: what the .dlg format (Dlg) reads. scripts_from_parsed checks them against the game’s rules, once its characters, names and music are loaded.

DialogueLimits

How much text a game’s dialogue box and reply menu hold: the limits the checks keep a script to, counted in cells (text_width).

DialogueTable

Every scene of every dialogue file, by id. Build it with DialogueTable::new or Default (ADR-0039).

Dlg

The .dlg format (dlg, .dlg) of a game whose own directives are D: a file’s scenes, with every syntax and structure error parse_dlg finds. The checks that need the game’s rules are scripts_from_parsed’s.

Line

One line that shows text, as Scene::lines lists it.

LineId

The id of one dialogue line: <scene id>_<8 hex>, with _2, _3… on repeats of the same speaker and text in one scene. Unique across every dialogue file. Empty on a step built by hand until Scene::assign_line_ids runs (the parser runs it).

Lines

Where the steps of one list of steps (a scene’s, a reaction’s, one part of an @if block) are in the file.

NoTokens

The tokens of a game that fills in nothing but names. Play its scenes with Named (or Plain if its text has no name tokens).

Parsed

What Directive::parse read from one line.

ParsedScene

A scene as written in a file, with the source lines the checks point at.

PartLines

Where one part of a block is: an option of a @choice, or one of the two parts of an @if block.

Scene

One scene: @scene <id> … @end.

Scripts

Every scene of every dialogue file, with where each was written: what checks that need more of the game’s data run on once that is loaded.

ScriptsCheck

scripts_from_parsed one scene at a time, for a game that must hand control back to its platform between them (a handheld’s update callback, which its OS ends when it runs too long): Self::new, then Self::check_next as many times as Self::unchecked says, then Self::finish. The scripts and the errors are the same.

Enums

MusicLine

What a @music line asks for.

NoDirective

The directives of a game that adds none: there are no such steps.

Present

Who is there when a scene plays.

Side

A side of the dialogue screen, where one portrait stands.

Step

One step of a scene, in script order. D is the game’s own directives.

Constants

NARRATION_SPEAKER

What stands for the speaker in a narration line’s hash and listing.

REPLY_SPEAKER

What stands for the speaker in a reply’s hash and listing.

Traits

Directive

A step a game adds to the format: @<name> <args>, for a name the engine’s own directives don’t use. The parser reads it with Directive::parse, a scene keeps it in order as Step::Directive, and the game plays it.

SceneRules

What check_scene checks a scene against: the game’s limits, tokens and names, and whatever it knows of its characters, portraits and music. A check the game has nothing for passes.

Tokens

The {tokens} a game fills in itself, besides the names table’s ({n:<id>}, Names): a player-named hero’s name, say.

Functions

bad_id

What an id that isn’t one (is_id) is told.

caption_key

The key a language pack translates the caption text of scene scene by: caption.<scene id>_<8 hex>, hashed like a line id. The same caption twice in a scene has one key.

char_problem

What is wrong with character c in dialogue text, if anything: text holds any character but a control character. Whether the font draws it is checked once the game’s text and its atlas load (crate::font::undrawn), not here.

check_duplicates

One error for each scene whose id an earlier scene (in any file) already has.

check_scene

Checks one scene against rules, replaying it to know who is on screen at each line.

is_id

Whether s is a valid scene, character or expression id: lowercase ASCII letters, digits and _, not empty.

line_hash

The hash part of a line id: the low 32 bits of FNV-1a 64 over speaker, a newline and text, as 8 lowercase hex digits.

lines_at_longest

Lines text takes in a box width cells wide (word_wrap, a wide character of widths two cells) once every token is filled in as its longest: each token is written out as that many Ws, with the tokens and names counted as in longest_width. A token is so a Latin run that is never broken, the worst case (a typed name of that length). A line that fits the box here fits it with any player’s name.

longest_width

Cells text can take once every token is filled in, at most (text_width, a wide character of widths two cells): the game’s tokens at their longest (Tokens::longest) and every name token as longest_name (the longest name in the table, so a rename can’t push the line over its limit). Unknown tokens, and name tokens without a table, count as written.

parse_dlg

Parses dialogue source (errors attributed to file) into its scenes, in file order, and every syntax error found. A scene with errors in it is still returned (without the broken lines), so later checks can run. A directive the engine doesn’t know is read by the game’s D.

print_scene

Writes scene in .dlg format (one line per step, reactions indented under their option, an @if block’s lines as far in as its @if), ending with @end and a newline. Parsing the result gives scene back.

scene_of

The id of the scene the line with id id is in, or None if id doesn’t end like a line id (_<8 hex>, then _<n> on a repeat).

scripts_from_files

Like scripts_from_sources, for files given as (file name, source) where a None source is a file that isn’t valid UTF-8 (an error).

scripts_from_parsed

Validates scenes already parsed (files, from the .dlg format Dlg, in file order) as scripts_from_sources does: each scene with check_scene and the game’s own SceneRules::scene_problems, then the scene ids across files.

scripts_from_sources

Parses and validates dialogue files given as (file name, source) pairs, each scene with check_scene and the game’s own SceneRules::scene_problems, then the scene ids across files. Reports every problem, ordered by file and line.

token_problems

What is wrong with the {...} of text, in order: each must be one of the game’s tokens or a name token with an id in names (any valid id without a table), and every { must close. The rule for a script and for every language pack’s dialogue text.