1 unstable release
0.1.0 | Apr 28, 2023 |
---|
#24 in #marker
39KB
721 lines
Dialogue Script - A language for writing interactable dialogue
Dialogue Script is a language for writing dialogue that is both human-readable and easy to parse. The dialogue can be thought of as a state machine, where each line of dialogue is a state and each indented block is a transition to a sub-state.
Example
%START%
ZELDA |SAY| "Hey there!"
ZELDA |SAY| "How are you?"
YOU |SAY| "I'm doing well, thanks!"
ZELDA |SAY| "Glad to hear it!"
%END%
More example scripts are located in the example_scripts/
directory.
Syntax
The syntax of a script consists of lines, blocks, and comments. Lines are the main component of a script, and blocks and comments are used to organize and annotate the script.
Lines in a script are either Markers or Commands. They can include any letters or symbols, except for pipes ( | ), as those are used to delimit commands.
Markers
A script must start with a %START%
marker and end with a %END%
marker which determine the start and
end of the script, respectively. Markers are written in ALL-CAPS-KEBAB-CASE and delimited by percent
symbols. By using the [|GOTO| command], the flow of dialogue can be
redirected to just after a marker.
Commands
Commands are written in ALL-CAPS-KEBAB-CASE and delimited by pipes. Commands can have 'prefixes' and 'suffixes'. Several built-in commands are supported, and (in most cases) it's easy to extend the language with custom commands.
PREFIX |COMMAND| SUFFIX
SAY
The |SAY|
command is used to display dialogue. When an optional prefix is supplied, it represents the
speaker. A suffix is required, and it represents the dialogue to be displayed.
ZELDA |SAY| "Hey there!"
The above command would display the text "Hey there!"
in a dialogue box with the speaker ZELDA
.
Quotes around text are interpreted as text, and aren't required.
|SAY| It was a dark and stormy night...
The above command would display the text It was a dark and stormy night...
in a dialogue box with no speaker.
CHOICE
The |CHOICE|
command is used to declare a list of choices. A suffix is required, and it represents a choice
that the player could make. A prefix is not allowed.
|CHOICE| "Yes"
PLAYER |SAY| "Yes"
|GOTO| %CONTINUE%
|CHOICE| "No"
PLAYER |SAY| "No"
|GOTO| %GO-BACK%
The above command would display a list of choices with the text "Yes"
and "No"
. If the player chose
"Yes"
, PLAYER - "Yes"
would be printed and the dialogue would continue at the %CONTINUE%
marker. If the player chose "No"
, PLAYER - "No"
would be printed and the dialogue would continue at the %GO-BACK%
marker.
GOTO
The |GOTO|
command is used to redirect the flow of dialogue to a marker. A suffix is required, and it
must be a valid marker. A prefix is not allowed.
|GOTO| %START%
The above command would redirect the flow of dialogue back to the %START%
marker. Used in concert with the
|CHOICE|
command, branching dialogue is possible. Below is an example of branching dialogue using |GOTO|
.
%START%
Zelda |SAY| "This is a test."
Zelda |SAY| "You got that?"
|CHOICE| What?
You |SAY| "Come again?"
|GOTO| %START%
|CHOICE| Yes
You |SAY| "Ah, yes. Thank you."
Zelda |SAY| "You're welcome."
%END%
In the above dialogue, if the player chose What?
, the dialogue would loop back to the start.
If the player chose Yes
, the dialogue would continue to the end.
Blocks
Blocks are used to organize dialogue. They are indented by 4 spaces and can contain any number of lines or inner blocks. Blocks can be nested to any depth, though you should avoid nesting deeply, as it makes scripts difficult to read. The |CHOICE| and |GOTO| commands show examples of how blocks can be used. When a block is entered, dialogue will continue from the first line of the block. When a block is exited, dialogue will continue from the first line after the block.
%START%
|SAY| 1
|SAY| 2
|SAY| 3
|SAY| 4
|SAY| 5
%END%
is equivalent to
%START%
|SAY| 1
|SAY| 2
|SAY| 3
|SAY| 4
|SAY| 5
%END%
Blocks should always be used to organize choices, and commands that result from a choice should be in a block after that choice.
Comments
Comments start with a //
and continue until the end of the line. They can be used to annotate a script.
// This is a comment
License
This project is licensed under the MIT License.
Dependencies
~4MB
~73K SLoC