A guide to more advanced features in the ChoiceScript programming language. Please post on the ChoiceScript google group if you have questions about this document.
Don’t Start Here!
Be sure to read our basic ChoiceScript Introduction page before reading this advanced documentation
More Commands
*comment: This command does nothing; any text you put after*commentwill 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!
*line_break: Put just one line break in your text, like a<br>in HTML. ChoiceScript automatically converts single line breaks to spaces, and double line breaks to paragraphs.So this is all one line. But this is a new paragraph. And this *line_break is two lines.
That code would display like this:
So this is all one line
But this is a new paragraph.
And this
is two lines*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}*fake_choice: This convenience command behaves exactly like*choice, but no commands are allowed in the body of the choice; thus no*goto/*finishis 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*rand: Set a variable to a random number. You set the minimum and maximum, we do the rest. For example, this would set the variabledie_rollto a value from 1 to 6 inclusive:*rand die_roll 1 6
Beware! It can be very hard to adequately test scenes that use randomness.
Advanced Techniques
- Labeled buttons: By default,
*finishbuttons say "Next Chapter" and*page_breakbuttons say "Next". You can make the button say something else, instead:*page_break On with the show! *finish The show is over!
- Conditional options: This advanced technique lets you show/hide some options based on the player's variables.
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. *finishIn this case, players have the option to abuse their presidential power only if they are president; if they are not president, then the option is completely hidden.
- Fairmath: ChoiceScript includes two rather strange operators specifically for use on variables that are percentages, called "%+" and "%-". You use them like this:
*set leadership 50 *set leadership %+ 20 *set leadership %- 40
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:
- Fair Addition:
(x %+ y) = (x + (100-x)*(y/100)) - Large scores are hard to increase:
(90 %+ 20) = (90 + 2) = 92 - Small scores are easy to increase:
(10 %+ 20) = (10 + 18) = 28 - Fair Subtraction:
(x %- y) = (x - x*(y/100))- Large scores are easy to decrease:
(90 %- 20) = (90 - 18) = 72 - Small scores are hard to decrease:
(10 %- 20) = (10 - 2) = 8
- Large scores are easy to decrease:
- 50 is equally easy to increase or decrease.
(50 %+ 20) = (50 + 10) = 60(50 %- 20) = (50 - 10) = 40
Fairmath is great in expressions like:
*set leadership %+ 20. The player will get anywhere from 0 to 20 more points of leadership, depending on how high leadership is currently. - Fair Addition:
- Advanced
*ifstatements: You can do a lot more with*ifstatements thanleadership > 15. Here's a few tricks:- Equality and Inequality
- Equal to:
leadership = 40(Is leadership equal to forty?) - Not equal to:
leadership != 40(Is leadership different from forty?) - Greater than:
leadership >40(Is leadership greater than forty?) - Less than:
leadership <40(Is leadership less than forty?) - Greater than OR equal to:
leadership >=50(Is leadership greater than or equal to fifty?) - Less than OR equal to:
leadership <=40(Is leadership less than or equal to forty?)
- Equal to:
- And/or (with mandatory parentheses)
- And:
(leadership > 30) and (strength > 40) - Or:
(leadership > 60) or (strength > 70) - Complex parentheses:
((leadership > 60) and (agility > 20)) or (strength > 80)
- And:
- Comparing text:
lover_name = "Jamie""2" = 2(this is true!)
- Setting variables to
trueorfalse:*set finished false*set correct guess = "blue"
- Equality and Inequality
- Text tricks:
- Capitalize first letter: You can capitalize just the first letter of a variable like this:
Behold! $!{He} is capitalized. - Concatenation: You can join text together like this:
*set murder "red"&"rum". You can use variables in the same way:*set title "Dr. " & last_name - Quotes: You can put quotes in your text by using backslashes, like this:
*set joke "she said it was \"ironic\"!"If you write
${joke}, you'll get:
she said it was "ironic"!
- Backslashes: You can put backslashes in your text by using even more backslashes, like this:
*set slashy "Here's one backslash: \\ and here's two backslashes: \\\\"If you write
${slashy}, you'll get:
Here's one backslash: \ and here's two backslashes: \\
*print: This command is no longer necessary; it just prints the value of the variable you specify. Use${}variable substitution instead.
- Capitalize first letter: You can capitalize just the first letter of a variable like this:
- Truly bizarre references: Probably only programmers will appreciate these. Beware! They add complexity without adding much value.
*setref: Set a variable by name, e.g.*setref "leadership" 30sets leadership to 30. Use it in crazy code like this:
*set virtue "courage" *setref virtue 30
This code would set
courageto 30. If this still doesn't seem useful, consider thatvirtuecould have been determined by earlier choices, so it might have sethonestyto 30 instead.Still not convinced? Don't worry about it; you'll probably never need it.
*gotoref: Goto a label by name, like this:
*temp superpower *set superpower "invisibility" Your super power is: *gotoref superpower flight! *finish *label invisibility invisibility.
- Curly parens: Put some text in curly braces and we'll turn it into the value of the named variable.
*set honesty 30 *set virtue "honesty" *set score {virtue} Your ${virtue} score is ${score}
Your honesty score is 30
Questions?
Please post on the ChoiceScript google group if you have questions about this document.