ChoiceScript Wiki

    Choicescript has another handy feature called multireplace; it can be used to avoid long sections of *if for moments that would only contain different text. It can also keep it all in one line, improving code readability.


Multireplace is a function that lets you use a combination of the @{ | } characters to display different bits of flavor text linked to either Boolean (true/false) variables or numeric variables.

Boolean example: @{variable Text if true|Text if false}

Numeric example: @{variable Text if 1|Text if 2|Text if 3|Text if 4}

Numeric example: @{(variable+1) Text if 0|Text if 1|Text if 2|Text if 3}

Multireplace is most useful when you want:

  • short, varying flavor text
  • with no para breaks
  • without setting any variables
  • linked to a variable with a finite, discrete, and ideally small number of possible states.

If your variable always returns an identical range of text options, e.g. if "dragon_color" can only be "red," black," "gold," "green," or "purple," then it would be most efficient to set "dragon_color" as a string variable and display it as ${dragon_color}, rather than setting it as a numeric variable and displaying the text using multireplace.

Multireplace is better suited for when you want to use different text in different contexts.  For example, if the variable "dragon_attitude" could be set to one of four numbers (1-4) by the main character's choices in the game, you could then use it in several multireplace contexts:

The dragon Nzak regards you with @{dragon_attitude hate|scorn|indifference|affection}.

"We have to work together," says Nzak. @{dragon_attitude "But don't think I'll ever forget that you slew my mate."|"What a pathetic joke!"|It  gives the draconic equivalent of a shrug.|"But I want you to know that I'd choose to, even if circumstances hadn't forced us together."}

"You're wounded," Nzak observes @{dragon_attitude with relish|sneeringly|blandly|with concern}.

Uses like these are much more code- and time-efficient than typing out "*if dragon_attitude = 1, *if dragon_attitude = 2" etc. every time you want to have varying flavor text.

A multireplace can contain other variables:

"Who's that?" the other dragon asks Nzak curiously. 
 "@{dragon_attitude My arch-enemy, ${name}|Some idiot|Don't know, don't care|My beloved ${name}.  Don't touch ${them}}."

A multireplace can even contain line breaks, using the inline [n/] character.  But multireplace can't contain paragraph breaks (since using double-[n/] for para breaks is bad for screen-readers), can't contain commands or *set other variables, and can't include a second multireplace nested inside it.  For those, you'll still need *if.

To pass ChoiceScript's automatic testers, multireplace needs to cover every value of a numeric variable that is achievable in your game.  For example, let's say your game has a variable, "stan_trust," which can be set to 1 (you trust Stan), 2 (you distrust Stan without any reason), or 3 (Stan has betrayed you and you'll never trust them again).  Even before Stan betrays you, i.e. before it's possible for the variable to actually be set to 3, any use of "stan_trust" in a multireplace needs to have a third term, or it will fail Quicktest.

So you might write:

@{stan_trust "Hey, buddy!"|"Stay away from me."|!!This is a bug, Stan can't have betrayed me yet!!}

or just

@{stan_trust "Hey, buddy!"|"Stay away from me."|x}

or even

@{stan_trust "Hey, buddy!"|"Stay away from me."|}

--you don't need to fill all the spaces around/between pipes with text, but if you don't include at least a blank option corresponding to every possible value of the variable, your game won't pass Quicktest.

Because multireplace needs to include a potential response for every game-achievable value of a variable, it is poorly suited to many uses of numeric variables, e.g. any numeric variables that change incrementally (where you'd want the flavor text to correspond to a range of values rather than being different for each value), that have gaps or jumps, or that just go on for too long. Don't expect to use multireplace and fairmath on the same variable!


Code using multireplace is generally more condensed than the alternatives.  Compare:

You reply
*if noble
  in fluent High Court Latin. 
*if not(noble)
  in the common tongue. 

You reply @{noble in fluent High Court Latin|in the common tongue}.


"I also want to stay and fight. But
*if noble
  forgive me, your Excellency, 
there's no time."

"I also want to stay and fight. But @{noble forgive me, your Excellency,|} there's no time."

Having all your flavor text variation in one line can make the code more readable, especially with relatively simple Booleans. 

However, as the number of terms in a numeric variable increases, the readability of a multireplace arguably decreases, and the odds of a mistake definitely increase.

"In some of my worst dreams, I'm stuck in a memory of @{trauma the children of our band being dragged off to the Harrower|the children of our band starving last winter|a dying child|my followers, when…when I failed them|my followers dying|an old comrade dying|someone I had to kill|an old friend trying to kill me|a friend being Harrowed|a helot girl being Harrowed|being inside a Harrower|Plektoi coming for me|Theurges raining fire down on us|being locked in a dungeon|being poisoned|being speared in this arm}."

While this is much shorter than writing out a list of all sixteen potential Choice of Rebels traumas with *if checks, it's unlikely that you or anyone checking your code will catch the mistake if you happened to confuse trauma number 12 with trauma number 13.

Multireplace is great with Booleans.  If a key character is present or absent, it's easy to use a Boolean like "ayla_here" to give them a dialogue tag or a reaction that would otherwise go to someone else:

"Here we are," @{ayla_here Ayla|another NPC} says. 

@{ayla_here Ayla stares|You stare} grimly out across the glacier.

If you have Booleans for whether a character is in love with you, or injured, or whether a particular event happened, you can use multireplace for simple in-line variations on the game text to take those differences into account.

Watch your punctuation, though - it's easy to end up missing a full stop or quotation marks, or to have them double up, if you're not consistent in using them either inside or outside the curly brackets.

Finally, it's possible to use a multireplace instead of a paired *if and *else statement. This is similar to using a Boolean variable, with the first section being selected if the *if statement would succeed and the second if it would fail. So instead of writing out this:

*if health < 50
  Coughing, you stagger weakly toward the door.
  *goto next
  You charge boldly forward.
  *goto next
*label next

you could just have:

@{(health < 50) Coughing, you stagger weakly toward the door.|You charge boldly forward.}

This can make code simpler, as it requires fewer *goto and *label statements than the equivalent *if/*else statement. It also allows you to use multireplace on variables that have a much wider range of values, e.g. a 1-100 fairmath percentage variable. But it only works in cases of flavor text -- if you want any variables to change, or the story to branch, you'll still need to use *if . And for a case where you want to include more than two options (e.g. one text snippet if health < 50, a different one if it's 50-89, and yet another one if its >=90) then you still need *if/*elseif/*else, not multireplace.

Managing Verbs for Singular They[]

In April 2016, ChoiceScript author Lynnea Glasser wrote here about the challenge of coding for a character who might prefer either a traditional singular pronoun or the pronoun "they." The differences in verb conjugations can be tricky to manage with a typical ${variable} code; compare "he flies," with "they fly"; "she is," with "they are"; "xe doesn't," with "they don't." In some cases, managing it took multiple lines of code:

*if plural = true
  *if plural = false

The multireplace function, introduced a year or so after Glasser's blog post, now makes it possible to code this more efficiently.

Here's one way to do it. In startup.txt, create a string variable for the character's pronoun (which may later be set to e.g. "he," "she," "they," or a neopronoun) as well as a Boolean variable for whether the pronoun is plural.

*create pronoun ""
*create plural false

When the character's gender is set, if the character uses the pronoun "they," (or for that matter any other plural pronoun--maybe they prefer the royal we?) the variable plural should be set to true.

*set pronoun "they"
*set plural true

From that point on, multireplace can be used to select the right verb conjugation:

$!{pronoun} @{plural don't|doesn't} want to go.

This could display as "They don't want to go." or "She doesn't want to go." depending on the pronoun.

More commands / functions
Choice *choice, *fake_choice, *disable_reuse, *hide_reuse, *allow_reuse, *selectable_if
Variable *create, *temp, *set, Arithmetic operators, *delete, *input_number, *input_text, *print, *rand
Conditional *if, *elseif, *else, Multireplace
Goto *label, *goto, *goto_scene, *goto_random_scene, *gosub, *gosub_scene, *finish
Formatting Bold text, Italic text, *image, *line_break, *page_break, *link, *stat_chart
Miscellaneous *comment, *scene_list, *title, *author, *achieve, *achievement, *check_achievements, *bug, *ending, *more_games, *share_this_game, *show_password, *script, Implicit Control Flow