Text directives

Player-facing text can contain a text directive. The runtime resolves each @{...} directive when it displays the text, using the current game state.

Directives support these uses:

• insert a variable value into a sentence
• select wording based on a variable or count
• change a dialogue line after repeat visits

Use a directive to keep related text variants in one string. Localization then receives one unit with all its variants in context.

Interpolate with @{VarName}

@{VarName} inserts the variable's current value. Use a variable name without spaces, dots, or expressions.

Welcome back, @{PlayerName}. You carry @{Gold} gold.

Text values appear unchanged. Numbers use compact formatting, so 1.5 doesn't become 1.500000. True or false values appear as true or false.

For an option set value, the directive displays the player-facing label instead of the entry key. For an entity reference, it displays the entity name.

If Narratyr can't find the variable, the output retains the complete directive. Seeing @{VarName} in the game helps you find a missing or misspelled variable.

Select wording with @{select ...}

@{select Subject, Label {text} Label {text} other {text} } checks labels in order. It displays the text for the first label that matches the subject variable. Include other as a fallback because a directive without a match displays an empty string.

@{select Gender, Male {He} Female {She} other {They} } readies for battle.

You return to town. @{select JarlState,
  Dead  {The throne sits empty.}
  Alive {The Jarl greets you with a nod.}
  other {No one will say where the Jarl has gone.} }

Labels compare with the variable's underlying value. An option set uses its key, such as Dead. Display labels such as "Deceased" don't affect matching. A true or false variable uses the labels true and false.

Select counts with @{plural ...}

@{plural CountVar, ... } selects text for a number. A label such as =0 checks an exact count first. The one label matches 1, and other matches remaining values. Within the selected text, # inserts the count.

@{plural ArrowCount,
  =0    {You are out of arrows.}
  one   {You have # arrow left.}
  other {You have # arrows left, @{PlayerName}.} }

Narratyr currently supports one and other. Other language-specific plural categories, including zero, two, few, and many, aren't available yet.

Change text after repeat visits

Within a dialogue node's full Text, @{visited, ...} selects text from the node's one-based visit count. The first entry matches visit 1, and the next entry matches visit 2.

@{visited,
  once  {Hello.}
  twice {Hello again.}
  many  {Chatty today, aren't we?} }

Use exact labels such as =1, =2, and =3, or use once for =1 and twice for =2. The many label is another name for the other fallback. It can match any visit count that an earlier label didn't match.

The runtime checks exact labels and aliases in their written order, then uses the first other or many fallback. Within the selected text, # inserts the visit count and ## inserts a literal #.

Only a dialogue node's full Text supports visited. Short Text, choice labels, and other fields don't have a dialogue-node visit count.

Syntax rules

• The subject of select or plural must be a variable name. Store a calculated result in a variable before using it in a directive.
• Directives can nest inside selected text.
• Add an other fallback to select and plural. Add other or many to visited.
• Write @@{ to display a literal @{. Individual @ and { characters don't require an escape.
• The runtime doesn't scan an inserted variable value for more directives.

Next

Dialogues describes the text fields that support directives. Variables explains their source values. Expressions covers the language for conditions and instructions.