The *label command is strictly used only as a reference for the *goto and *gosub commands and their variants. The exact usage is more fully explained within those two articles.
Naming labels
Labels are essentially named tags within your code, used by ChoiceScript to direct the program flow down a particular route. You can name labels just about anything you like, but all labels within the same scene file must be unique. In addition, when referenced by the *goto or *gosub commands, that reference must match exactly, including any use of Upper Case (capital) letters in the label name.
Label names also cannot contain spaces, but with the most recent versions of ChoiceScript any of the following name formats are acceptable. It is recommended that you choose your preferred format and use only that format throughout your code, this being good practice to avoid annoying "bad label" errors.
*label nextjump *label NextJump *label next_jump
Typically, you will find that you need to use many labels within a single scene file, and all must be unique for *goto or *gosub referencing to work correctly. Bear in mind that the following are, in fact, all unique (as are the above):
*label NextJump1 *label NextJump2 *label NextJump3
Additionally, there appears to be no limit to the length of a label name.
Usage
The following is a typical example of how a label is referenced by a *goto command.
What do you prefer?
*choice
#A donkey.
You prefer a donkey!
*goto Donkey
#A horse.
You prefer a horse!
*goto Horse
*label Donkey
What color do you want your donkey to be?
*choice
#Red.
You prefer a red donkey!
*finish
#Green.
You prefer a green donkey!
*finish
*label Horse
What color do you want your horse to be?
*choice
#Red.
You prefer a red horse!
*finish
#Green.
You prefer a green horse!
*finish
In the example above, when the player chooses between a Horse or Donkey, it will display the textual response and then jump, with the *goto command, to the line containing the *label of that exact name, skipping any other code in between.
It is also worth noting that labels can be either above or below any corresponding *goto or *gosub line; indeed, anywhere within the same scene file. The following code, for example, works just fine. Follow the *goto--*label jumps below, rather than reading it as you would ordinary text, each successive line in turn . . .
*goto ChooseMount
*label Donkey
What color do you want your donkey to be?
*choice
#Red.
You prefer a red donkey!
*finish
#Green.
You prefer a green donkey!
*finish
*label Horse
What color do you want your horse to be?
*choice
#Red.
You prefer a red horse!
*finish
#Green.
You prefer a green horse!
*finish
*label ChooseMount
What do you prefer?
*choice
#A donkey.
You prefer a donkey!
*goto Donkey
#A horse.
You prefer a horse!
*goto Horse
A label can also be called from another scene entirely, with the use of the *goto_scene command.
For example, in a chapter1.txt, you can write the following:
*goto_scene chapter5 horse
will send the player to the *label named "horse" in the chapter5.txt scene file.
| 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 |