About this FAQ

This FAQ is meant as a ressource to new developers. Questions in the ChoiceScript Google Group often repeat themselves and since there is no Wiki to record answers yet, I set up this FAQ to compensate. I am not associated with Choice of Games in any way, I just enjoy their scripting language. Please do not email them with questions or comments about this FAQ and do not email me with questions about ChoiceScript, that's what the Google group is for.

Note: You can download this FAQ for offline use using "Save Site As ..." (Ctrl+S).

Recent changes

  • 01/04/12: added section about errors in Firefox
  • 01/04/12: added *image to command overview

Command Overview

Below is a table with common commands and a short description of what they do.
*temp variableCreate a temporary variable (only usable in the scene it is created in)
*set variable valueSet a variable to a value*set name "Simski"
*set_ref variable_name valueSet a variable to a value by its name
*input_text variableSet a variable to the content of a text field*input_text name
*rand variable lower_limit upper_limitSet a variable to a value between an upper and lower limit*rand die_roll 1 6
*if conditionCommands for handling conditional code.
*elseif condition
*line_breakInsert a line break
*page_breakInsert a "Next" button before the game continues
*page_break captionInsert a captioned button before the game continues
*finishGo to the next chapter
*label nameDefine a label
*goto labelGo to a label
*goto_ref label_nameGo to a label by its name
*gosub / *returnGo to a label and return to the starting point once the *return command is reached.
*goto_sceneGo to a scene
*fake_choiceStarts a fake choice block
*choiceStarts a choice block
*selectable_if (condition) #choiceGreys out a choice if a condition isn't met
*hide_reuseHides a choice after it's been selected once
*image filenameInsert an image (use *image filename left or *image filename right for an alignment other than center.
*commentMark a line as a comment

How do I edit the ChoiceScript files? / What text editor should I use?

I am using Notepad++ (on Windows 7) for all my ChoiceScript editing needs. It works very well and there are some useful features for ChoiceScript authors. Here is the program's homepage: and a direct link to the download page:

If you are using Notepad++, you can profit from a syntax highlighting file I made: choicescript.xml (Rightclick->"Save Target As ..." to download).
To use it, click "View"->"User-Defined Dialogue ..." in Notepad++, then click "Import ..." and select the downloaded file.
The file is not complete, but you can customize it and add your own command highlighting through the Notepad++ User-Defined Dialogue. If you improve on the file, please send me the new version so I can update this site with it:

How do I track a variable and take action depending on its value?

A common example for this problem is the tracking of the player's health. Once the healthpoints drop below 0, the player dies. Before that happens, a warning for the player would be nice so she knows she's close to death.
To track a variable, its value has to be checked after every change that is made. Here is an example for health:

*temp health
*set health 50

You stub your toe.
*set health - 10
*if health <= 0
  *goto death
You hit your head.
*set health - 20
*if health <= 0
  *goto death

*label death
You have died.

To save lines of code, you can use *gosub:

*temp health
*set health 50

You stub your toe.
*set health - 10
*gosub check_health
You hit your head.
*set health - 20
*gosub check_health

*label check_health
*if health <= 0
  *goto death

*label death
You have died.

How can I use automated testing for my games?

Automated testing is a great way to debug your ChoiceScript games without clicking your way through them over and over. Here's how it works:
Locate the root folder for your game (this folder is what you get when you unzip the ChoiceScript engine. It should contain the "doc", "editor", "tests" and "web" folders as well as a bunch of other files).
Open the command line for this folder (in Windows, right-click on the folder and select "Open Command Window Here").
Depending on the test you want to run, enter "autotest.bat", "quicktest.bat" or "randomtest.bat".
Autotest and Quicktest (I'm not sure about the difference here, I think Quicktest skips more lines) go through the script line by line until they find an error or finish.
Randomtest plays the game like a player would, selecting random options to move through the game. When it reaches the end, it starts from the beginning and plays again, repeating until an error is found. While testing, Randomtest generates a text file in the folder it is being run in: randomtest-output.txt. It should look something like this:

prologue 19#1 (20)
prologue 33#2 (36)
prologue 124#4 (167)
prologue 175#1 (176)
prologue 264#2 (267)
prologue 598#2 (609)
prologue 632#3 (689)
chapter1 33#1 (34)
chapter1 99#1 (100)
chapter1 102#1 (103)
chapter1 314#1 (315)
chapter1 316#1 (317)

Each line of the file represents a choice the test made. For example, "prologue 19#1 (20)" means that there is a choice on line 19 of the prologue.txt file. The test randomly selected the first option (located on line 20). Using this file, you can recreate the path the test took through your game to recreate the error.

What kind of commands can I use on the stat screen?

The *stat_chart command is explained in detail on the official ChoiceScript site: It is not necessary to use this command, however. Think of the stat screen as just another scene to write (although using choices in the stat screen seems to cause problems).
Some examples:

Conditional stats
Combat Moves:
*if sneak_attack
  Sneak Attack
*if wrestle

Organic text
You are wielding a ${weapon} and wearing ${armor} bearing the crest of house ${house}.
*if (hp=10)
  You are unharmed.
*elseif (hp>=6)
  You are somewhat injured.
*elseif (hp>=3)
  You are in bad shape.
*elseif (hp>=0)
  You are near death.

I get a 'Syntax Error' in Firefox. What's wrong?

There seems to be a problem with displaying proper error messages in Firefox. Try using a different browser (like Google Chrome or Internet Explorer) for testing or use automated testing.
When posting in the Google Group, always include your full error message.


Choice of GamesHomepage of Choice of Games
Introductory Guide to ChoiceScriptStart here if you're a new developer
Advanced Guide to ChoiceScriptMore commands and advanced techniques
ChoiceScript Google GroupAsk any questions that remain unanswered after reading the Introductory Guide to ChoiceScript (link above) and this FAQ.