Table of Contents

Game state

How a script reads from and writes to your game. A query asks the game a question; a command tells it to do something. Both are written as inline code spans, so a script stays readable Markdown.

Part of the script language specification.

Table of contents

Your game answers what a script asks of it and carries out what the script commands. The interface a game implements — the runtime's world read and effect handling — lands with the runtime, so this page describes what a script asks of your game rather than the C# shape of the answer. See the runtime architecture for the model it is settling on.

Queries

A query reads game state and inserts the returned value into speech.

Query = "`" , QuotedString , "`" ;

A game answers a query by its key: asked for Alice.FavoriteColor, it returns red. A key it does not know may return nothing, which the script reads as an empty value.

Script:

Bob: What's your favorite color?

Alice: My favorite color is `"Alice.FavoriteColor"`.

Actual speech after query resolution:

Bob: What's your favorite color?

Alice: My favorite color is red.
Tip

A query can also drive a random choice's odds — see Dynamic weights.

Where a query has no answer yet

Only a running game can say what a query is worth. Tools that show your script without running it — the compilation report's graph and its tables — write the query's key in braces instead:

Alice: My favorite color is {Alice.FavoriteColor}.

Read that as "a value goes here." It tells you which parts of a line change at play time, which is exactly what you cannot see by reading the words alone.

The braces are how a tool shows you an unanswered query. They are not script syntax, so typing {Alice.FavoriteColor} into a script writes those characters and nothing more — write the query as a code span to ask the game a question.

Commands

A command changes something in your game.

DefaultCommand = "`" , "(" , QuotedString , ")" , "`" ;
CustomCommand  = "`" , Identifier , "(" , [ Arguments ] , ")" , "`" ;
Command        = DefaultCommand | CustomCommand ;

Your game recognizes the command's text — JoinClub("Alice", "Kung Fu") — and carries it out.

Default command:

Bob: Of course. You can join. `("Alice joins Kung Fu")`

Alice: Thank you!

Custom command:

Bob: Of course. You can join. `JoinClub("Alice", "Kung Fu")`

Alice: Thank you!

Silent command:

Alice: Bob, do you have a minute?

Bob: Yes. What can I do for you?

Alice: I like Chinese martial arts. Can I join the Kung Fu Club?

Bob: Of course.

`JoinClub("Alice", "Kung Fu")`

Alice: Thank you!

A command in a line is carried out where you wrote it. The words before it are said, the command runs, and then the line carries on, so a stage direction in the middle of a sentence happens in the middle of that sentence:

Yuki: Then... `("Yuki hides a smile behind her sleeve")` I will not argue.

A query written after a command is read once the command has run, so it sees what the command changed. Here the game is asked about weapon.Attack before the line starts, and again once Polish() has run:

Smith: It was `"weapon.Attack"`. `Polish()` Now it is `"weapon.Attack"`.

The line still belongs to its speaker, even when a command opens it or is all it says, and the reader moves on from it as from any other line.

Under the hood, a silent command is an effect, not speech: it compiles to a command-only control line that has no speaker, so it is never attributed to a character or the default speaker. The runtime asks the host to perform it, and the execution contract belongs to the runtime, not to the script.

Quoting a key

Every key so far is written in straight double quotes. The quotes mark where the key begins and ends, so it can hold any characters — including spaces.

Two constructs put a sigil right after the key: a condition ends it with ?, and a dynamic weight ends it with %. There the sigil already marks where the key ends, so you may drop the quotes and write the key plainly:

`IsAngry?` => [The guard blocks your way](#blocked)

- `Bob.Affection%` Bob: ...good to see you.

The unquoted key is everything before the sigil, with surrounding spaces trimmed — so a natural phrase reads well, as in `Is Alice happy?`. Prefer this unquoted form; it is the one this guide uses by default.

Add the quotes back only to escape — when a key must end in a literal ? or %, or contain a ":

`"Rainy?"?` => [Wait out the storm](#the-inn)

Here the key is the literal Rainy?; the final ? is the condition. A value read has no sigil to mark its end, so it is always quoted.

Edit this page