A guide of important techniques in the ChoiceScript programming language. Please post on the ChoiceScript forum if you have questions about this document.
Be sure to read our basic ChoiceScript Introduction page before reading these techniques.
*title
: This command sets the title of the game. It must be used at the top of startup.txt
, along with *create
and *scene_list
.
*title Choice of the Dragon
The Google Play Store for Android puts a limit of 30 characters on game titles. ChoiceScript will allow a title of any length, but if you’re planning to publish your game with us, you’ll need to come up with a name for your game that’s 30 characters or less, including spaces.
*author
: This command sets the author “by line” of the game. It must be used at the top of startup.txt
, along with *create
, *title
, and *scene_list
.
*author Dan Fabulich and Adam Strong-Morse
*temp
: This command is very much like *create
but it creates a temporary variable that only exists in the current file. Unlike *create
, you can use *temp
anywhere, and you’re not required to specify a starting value for a *temp
variable.
*temp conversation
*set conversation "a little less"
*temp action "a little more"
*comment
: This command does nothing; any text you put after *comment
will be ignored. It’s helpful to put remarks in the text that only the author should read.
*comment TODO We should make this scene more interesting!
*page_break
: Put in a “Next” button with no radio buttons. The game will continue on the subsequent page.
You turn the corner slowly. Blood rushes through your ears. As you open the door...
*page_break
... the masked murderer attacks!
*input_text
: Provides a text box for the user to specify the value of a variable, e.g. the user’s name.
Please enter your name.
*input_text name
Your name is ${name}, is that right?
ChoiceScript won’t allow the player to leave the input blank. If you want to allow that, you can use:
*input_text name allow_blank
*fake_choice
: This convenience command behaves exactly like *choice
, but no commands are allowed in the body of the choice; thus no *goto
/*finish
is required.
What color do you prefer?
*fake_choice
#Red
Red is the color of roses.
#Blue
Blue is the color of the sea.
#Green
Green is the color of spring.
What an excellent choice! And what flavor of ice cream would you like?
*fake_choice
#Vanilla
#Chocolate
#Strawberry
Mmm, delicious!
*finish
Stats that display on the stat screen usually range from 0 to 100. It can be difficult to guarantee that the player can never accidentally gains more than 100 points of leadership. To help with this, we’ve provided special commands that will keep stats in between 0 and 100.
*set leadership %+20 *set strength %-10
The “%+” and “%-” operators are called the “fairmath” operators. The idea is that as your leadership score gets higher, it becomes harder to increase, and easier to decrease. According to fairmath:
(x %+ y) = (x + (100-x)*(y/100))
(90 %+ 20) = (90 + 2) = 92
(10 %+ 20) = (10 + 18) = 28
(x %- y) = (x - x*(y/100))
(90 %- 20) = (90 - 18) = 72
(10 %- 20) = (10 - 2) = 8
(50 %+ 20) = (50 + 10) = 60
(50 %- 20) = (50 - 10) = 40
We recommend that you always/only use Fairmath to update percentages. If you’re having trouble deciding how many points to allocate using Fairmath, here are some guidelines:
%+ 20
usually only gives the player about 10 more points.%+10
. If you want a large boost, make it %+40
.*if
StatementsYou can do a lot more with *if
statements than leadership > 15
. Here’s a few tricks:
leadership = 40
(Is leadership equal to forty?)leadership != 40
(Is leadership different from forty?)leadership >40
(Is leadership greater than forty?)leadership <40
(Is leadership less than forty?)leadership >=50
(Is leadership greater than or equal to fifty?)leadership <=40
(Is leadership less than or equal to forty?)(leadership > 30) and (strength > 40)
(leadership > 60) or (strength > 70)
not(strength > 70)
((leadership > 60) and (agility > 20)) or (strength > 80)
lover_name = "Jamie"
"2" = 2
(this is true!)true
or false
:
*set finished false
*set correct guess = "blue"
@{}
Multireplace is a little bit like ${}
replacement, but you give it a variable and a list of options. The variable must be either a number or true
/false
(true
=1, false
=2). @{}
will insert the option corresponding to the number.
There @{count is one thing|are two things|are three things} here.
You are on the @{is_evil Dark|Light} Side of the Force.
Behold the dragon@{plural s|}!
Behold the dragon@{(dragons > 1) s|}!
Behold the dragon@{(dragons = 1) |s}!
The first word should be a variable name, followed by a space, and then a number of options separated by vertical pipes |
. Empty options are allowed. You can also use more complex expressions by wrapping them in parentheses.
Note that the first option is numbered #1. If you want the first option to be zero, add 1 to the variable in parentheses, like this:
There @{(count+1) are no things|is one thing|are two things} here.
You can nest ${}
replacements in @{}
but you can’t nest @{}
inside another @{}
.
Sometimes we want to show players that a choice is not available to them. We can do that like this:
How will you handle this?
*choice
#Try to talk them out of it.
They cannot be dissuaded.
*finish
#Force them to relent.
They back down, for now.
*finish
*selectable_if (president) #Abuse my presidential powers to silence them
This works; you will never hear from them again.
*finish
If you aren’t president, you’ll see the option to abuse presidential power, but it will appear in grey; it won’t highlight if you click on it. This gives players a hint that if they play the game again, they might be able to choose that option, by making different choices earlier on.
If we want to hide the option altogether, we can use *if
instead of *selectable_if
, like this:
How will you handle this?
*choice
#Try to talk them out of it.
They cannot be dissuaded.
*finish
#Force them to relent.
They back down, for now.
*finish
*if (president) #Abuse my presidential powers to silence them
This works; you will never hear from them again.
*finish
In this example, if you aren’t president, you won’t even see an option to abuse presidential power.
Sometimes we just want to revent certain options from being reused. We can do that with the *hide_reuse
and *disable_reuse
modifiers, like this:
*label start *choice *hide_reuse #One. The loneliest number that you'll ever do. *goto start *disable_reuse #Two. Two can be as bad as one. *goto start #I can't decide! Well, think it over. *goto start #Done. OK! *finish
If the player selects #One
, the option will be hidden; if the player selects #Two
, the option will be unselectable (greyed out).
Multiple-choice games written in ChoiceScript can be very hard to test, because each *choice
point can create new variations of the game that need testing. When testing by hand, it can be hard to be certain whether some path of choices can cause the game to crash, or whether some important part of the story can’t be reached at all.
To help with this, we’ve developed two tools that can make debugging ChoiceScript games considerably easier.
#option
in every *choice
, and both sides of every *if
statement. In order to do this quickly, Quicktest “cheats” by skipping lines that it has already tested.More information is available in our automated testing guide.
Please post on the ChoiceScript forum if you have questions about this document.
©2023 Choice of Games LLC Privacy Policy