ChoiceScript Wiki
Advertisement

    The *choice command is the fundamental command of ChoiceScript, defining the options by which the player interacts with the story.

Usage

Ordinary (non-conditional) options should be preceded by the hash # symbol as in the following example:

Which would you prefer?
*choice
  #A horse.
    You have chosen a horse!
    *finish
  #A donkey.
    You have chosen a donkey!
    *finish
  #A pony.
    You have chosen a pony!
    *finish
  #None of these.
    You don't like any of these!
    *finish

There is no real limit to the number of #options included within a single *choice statement, but for a typical ChoiceScript game 2-4 options is most common.

For any #option to be considered valid it must ultimately end in either a *finish, *goto, *goto_scene or *ending command, and before the next #option in the list. However, it matters not whether this takes place immediately (as in the simple example above) or much later within your extended scripting for that particular #option. (In order to forgo having to use those ending commands, you must use a different command: *fake_choice.)

Nested choices

You can also use nested choices, where one *choice #option immediately leads on to yet another *choice, as in the following example:

Which would you prefer?
*choice
  #A horse.
    Which color do you want your horse to have?
    *choice
      #Yellow.
        Your horse is now yellow!
        *finish
      #Green.
        Your horse is now green!
        *finish
      #Red.
        Your horse is now red!
        *finish
  #A donkey.
    Which color do you want your donkey to have?
    *choice
      #Yellow.
        Your donkey is now yellow!
        *finish
      #Green.
        Your donkey is now green!
        *finish
      #Red.
        Your donkey is now red!
        *finish
  #A pony.
    Which color do you want your pony to have?
    *choice
      #Yellow.
        Your pony is now yellow!
        *finish
      #Green.
        Your pony is now green!
        *finish
      #Red.
        Your pony is now red!
        *finish
  #None of these.
    You don't like any of these!

Note that even with nested choices there is always a *finish, *goto, *goto_scene or *ending command before the next #option of the original *choice (i.e. before Donkey or Pony).

If new to ChoiceScript, instead of using nested choices (for which it's harder to get the indentation exactly right) you can keep things simpler by using the *goto and *label commands more, as in the following example:

Which would you prefer?
*choice
  #A horse.
    *goto HorseColor
  #A donkey.
    *goto DonkeyColor
  #A pony.
    *goto PonyColor
  #None of these.
    You don't like any of these!
    *finish

*label HorseColor
Which color do you want your horse to have?
*choice
  #Yellow.
    Your horse is now yellow!
    *finish
  #Green.
    Your horse is now green!
    *finish
  #Red.
    Your horse is now red!
    *finish

*label DonkeyColor
Which color do you want your donkey to have?
*choice
  #Yellow.
    Your donkey is now yellow!
    *finish
  #Green.
    Your donkey is now green!
    *finish
  #Red.
    Your donkey is now red!
    *finish

*label PonyColor
Which color do you want your pony to have?
*choice
  #Yellow.
    Your pony is now yellow!
    *finish
  #Green.
    Your pony is now green!
    *finish
  #Red.
    Your pony is now red!
    *finish

*finish

In the example above, the original *choice statement uses the *goto command to simply jump to a new *label section below, using the label name (e.g. "HorseColor") for referencing.

Multiple *choice

A little-known feature of ChoiceScript is the ability to offer the player multiple choices on a single page, each with two or more options. This is by no means easy to explain so, using a tie-in to the ChoiceScript IDE, all you have to do is click Result below to see how this code would actually appear in-game.

There are however two main restrictions to bear in mind when employing this type of multiple choice in your own game:

1. Each entry on the *choice line must be a single word only, and note that these words are displayed in-game.

2. All second and subsequent #options must be identical (in the above example, the names of 'Sash' and 'Emblem' groups respectively). Only the first level of #option text may vary in wording ('Order' type in the above example).

Advanced *choice

Although ordinary #options will suffice in most instances, the *choice command is one of the most flexible of all ChoiceScript commands, allowing the use of *if, *selectable_if and *hide_reuse, *allow_reuse and *disable_reuse conditional options.

The following example should serve to give you a better idea of the real flexibility of the *choice command and complex conditional #options, in particular showing how such as *if can be used to assign pre-conditions to the likes of *selectable_if, *hide_reuse and ordinary #options alike. Note also the versatility of *selectable_if.

We have included the *temp commands and following *labels in this example so you may, if you wish, just copy the entire thing and paste it into a scene .txt file to display in-game. Then change the default values accordingly to see the varying effect on the options displayed in each case, adjusting the various conditions between true & false.

*temp shadowwalk 31
*temp infravision 31
*temp agility 51
*temp lit_torch_held false

*label throne_room
*choice
  #Cross the throne room and exit through the doorway at the far side
    *if shadowwalk > 20
      You tip-toe across the throne room and head into a damp passageway.
      *goto damp_passage
    *else
      You clumsily trip over the dragon's tail and promptly get eaten.
      *ending
  *if (shadowwalk > 30) and ((infravision > 30) or (lit_torch_held = true))
    *hide_reuse #Search every nook and cranny of the throne room.
      You search every nook and cranny . . . pointlessly.
      *goto throne_room
  *if (shadowwalk < 31) and ((infravision < 31) and (lit_torch_held = false))
    #Search the throne room, avoiding the sleeping dragon.
      You trip over the dragon's tail. She awakens and gobbles you up... Burp!
      *ending
  *selectable_if ((agility > 50) and (shadowwalk < 31)) #Leap for the balcony.
    You reach the balcony, grab the treasure, and leave via an open window.
    *goto castle_grounds
  *if shadowwalk > 30
    *selectable_if (agility < 51) #Quietly leap up to the crumbling balcony.
      You fail to reach the balcony but land softly, without waking the dragon.
      *goto throne_room
    *selectable_if (agility > 50) #Use the chandalier to reach the balcony.
      You reach the balcony, grab the treasure, and leave via an open window.
      *goto castle_grounds
  *hide_reuse #Dance a jig around the sleeping dragon . . . quietly!
    You (somewhat pointlessly) dance a silent jig around the dragon. Zzzzzzz.
    *goto throne_room
  #Hack the head off the slumbering dragon.
    Nice try . . . You succeed only in annoying her. Charred adventurer! Yummy!
    *ending

*label damp_passage
You head down the damp passageway.
*ending
*label castle_grounds
You enter the castle grounds.
*ending

Notes

Combining *selectable_if, *hide_reuse and *disable_reuse

Note that *selectable_if can be combined with *hide_reuse, *disable_reuse or *allow_reuse, provided that the reuse command precedes it, as in:

*temp money 5

*label Home

You have $${money} to spend. What will you buy?

*choice

    *hide_reuse *selectable_if (money >= 2) #A popsickle for $2.

        Great choice, the popsickle is delicious!

        *goto Home

    *disable_reuse *selectable_if (money >= 4) #A chocolate waffle for $4.

         A little overpriced, but it's worth every penny.

         *goto Home

    #Done shopping.

        You leave the candy store.

        *finish

Here, the options to buy a popsickle and a waffle will be visible but disabled ("greyed out") if they don't have enough money (as insured by the *selectable_if commands). Further, the popsickle option will become hidden if it has previously been picked (thanks to *hide_reuse), whereas the waffle option will be grayed out after it has been picked before (thanks to *disable_reuse). Otherwise, the options will be selectable.


When is not... not -- A ChoiceScript Quirk

The following code, using a boolean condition, is perfectly valid:

*choice
  *if (var) #This option 1
    *goto next

So you may be wondering why, within the Wiki (as in the long example above), we tend to use the following format:

*choice
  *if (var)
    #This option 1
      *goto next

Which is also equally valid. The reason for this strange mannerism is that, when checking to see if a particular boolean is not true (i.e. is false), this format is perfectly valid and will work as intended / expected:

*choice
  *if not (var)
    #This option 1
      *goto next

Whereas this format:

*choice
  *if not (var) #This option 1
    *goto next

Will in fact completely ignore that particular 'not' and will instead treat the code as a check for true, not false.

For this reason we advocate always placing an *if condition on a separate line of its own, whether checking true or false, to avoid confusing the issue by using a different format for each.

Another way to resolve this issue is with the addition of another set of parentheses encompassing the "not", which allows the option to be on the same line, as in:

*choice
  *if (not (var)) #This option 1
    *goto next


Similarly, note that:

*choice
  *selectable_if not (var)#This option 1
     *goto next

Will also simply ignore that 'not', treating that line as a check for true, not false. Furthermore, because:

*choice
  *selectable_if (var)
    #This option 1
      *goto next

Is actually invalid for a *selectable_if (resulting in a "parsing error", although is perfectly fine for an ordinary *if).

There are two ways to check for a false boolean with *selectable_if, the first is:

*choice
  *selectable_if (var = false)#This option 1
     *goto next

The second is:

*choice
  *selectable_if (not (var))#This option 1
     *goto next


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
Advertisement