Introduction to ChoiceScript

A basic guide to the ChoiceScript programming language. Please post on the ChoiceScript forum if you have questions about this document.

What is ChoiceScript?

ChoiceScript is a simple programming language for writing multiple-choice games (MCGs) like Choice of the Dragon. Writing games with ChoiceScript is easy and fun, even for authors with no programming experience.

Trying it out

To begin, download the ChoiceScript source from GitHub, extract the zip file, and open the web/index.html file in Firefox. (We strongly recommend using Firefox for this test; in particular, Google Chrome won’t work due to a security bug in Chrome.) The game will immediately begin.

(You can also use the ChoiceScript github page to browse our files, file bugs, or receive notifications when we update ChoiceScript.)

Your First Scene: *choice and *finish

Here’s a simple scene written in ChoiceScript. You can find it in web/mygame/startup.txt.

  Your majesty, your people are starving in the streets, and threaten revolution.
  Our enemies to the west are weak, but they threaten soon to invade.  What will you do?

  *choice
    #Make pre-emptive war on the western lands.
      If you can seize their territory, your kingdom will flourish.  But your army's
      morale is low and the kingdom's armory is empty.  How will you win the war?
      *choice
        #Drive the peasants like slaves; if we work hard enough, we'll win.
          Unfortunately, morale doesn't work like that.  Your army soon turns against you
          and the kingdom falls to the western barbarians.
          *finish
        #Appoint charismatic knights and give them land, peasants, and resources.
          Your majesty's people are eminently resourceful.  Your knights win the day,
          but take care: they may soon demand a convention of parliament.
          *finish
        #Steal food and weapons from the enemy in the dead of night.
          A cunning plan.  Soon your army is a match for the westerners; they choose
          not to invade for now, but how long can your majesty postpone the inevitable?
          *finish
    #Beat swords to plowshares and trade food to the westerners for protection.
      The westerners have you at the point of a sword.  They demand unfair terms
      from you.
      *choice
        #Accept the terms for now.
          Eventually, the barbarian westerners conquer you anyway, destroying their
          bread basket, and the entire region starves.
          *finish
        #Threaten to salt our fields if they don't offer better terms.
          They blink.  Your majesty gets a fair price for wheat.
          *finish
    #Abdicate the throne. I have clearly mismanaged this kingdom!
      The kingdom descends into chaos, but you manage to escape with your own hide.
      Perhaps in time you can return to restore order to this fair land.
      *finish

As you can see, the *choice command presents the user with a list of #options; the result of choosing each option appears indented right below the option (in an “indented block”).

If you go to play this scene, you’ll first be presented with three options:

  1. Make pre-emptive war on the western lands.
  2. Beat swords to plowshares and trade food to the westerners for protection.
  3. Abdicate the throne. I have clearly mismanaged this kingdom!

If you choose option #1, you get to choose how to win the war. If you choose option #2, you may decide how to negotiate with the westerners. If you choose option #3, the scene ends with no additional choices.

As you can see, there’s a lot you can do with just the *choice command and the *finish command. Indeed, using only these two commands and a lot of time, you could develop an entire “choose a path” style book!

Go On, Play with It!

Try opening up web/mygame/startup.txt in a simple text editor like Notepad or TextEdit. If you change the text, save the file, and refresh the web/mygame/index.html page in Firefox, you should be able to see the effect of your changes immediately.

NB: When you’re creating a new txt file for your game, make sure to save it with UTF encoding (UTF-8, for example), without BOM. If your encoding is ANSI, the game will mis-render certain extended-ASCII characters.

Indentation

Note that indentation in ChoiceScript is mandatory. Without those spaces for indentation, we would have no way to tell the difference between options nested within other choices and options on the main menu.

You can indent blocks using spaces or with the Tab character (but not both in the same file). You can use any number of spaces you want, but you must be consistent. Code like this is not allowed:

*choice
    #Hold 'em.
        He calls; you win!
        *finish
      #Fold 'em.
        Better luck next time.
        *finish

Option 1 has four spaces, but Option 2 has six spaces; since these don’t line up, ChoiceScript will display an error message if you try to write scenes like this.

Reusing Code: Goto and Label

ChoiceScript provides a way to jump around in a scene besides just making choices. You can use the *goto command to jump to any line in the scene, as long as you first put a *label on the line you want to reach.

  What kind of animal will you be?
  *choice
    #Lion
      *goto claws
    #Tiger
      *label claws
      In that case, you'll have powerful claws and a mighty roar!
      *finish
    #Elephant
      Well, elephants are interesting animals, too.
      *finish

When we reach the line *goto claws, we automatically jump to the line *label claws. You may create as many labels as you like, and use *goto to reach any of them.

Note that every indented (nested) block must conclude with either a *finish command (which ends the scene) or a *goto line which jumps to another line in the scene.

(You can also reuse code with the *goto_scene command, described later in this document.)

Setting and Checking Variables (aka “Stats”)

In ChoiceScript, you can use variables to make scenes and decisions more interesting than a “choose a path” style book.

To use a variable, you must begin by defining it with *create and modifying it with *set, like this:

  *create leadership 20
  *set leadership 30

Note that *create is only allowed to appear at the top of startup.txt. You can use *set anywhere you like. For example:

What do you prefer?
*choice
  #Leadership
    *set leadership +10
    *goto action
  #Strength
    *set strength +10

Once a variable has been set, you can check the value of the variable like this:

  #Run for class president
    *if leadership > 15
      You win the election.
      *finish
    You lose the election.
    *finish

Using variables, the player’s earlier leadership choices can have an effect on the story later in the game.

You can also add leadership points to the current number of leadership points, like this:

  *set leadership +20

This would add 20 points to the player’s current leadership score. It’s the same thing as writing *set leadership leadership+20. You can also subtract points with “-”, multiply with “*” or divide with “/”.

If you need to use multiple operators at once (e.g. you need to do both division and addition), you must use parentheses, like this: *set honesty (leadership + manners)*2. You may not omit the paretheses, even though it’s perfectly understandable arithmetic: *set honesty leadership + manners / 2.

You can also show the player’s current leadership score by using ${} (a dollar sign followed by curly braces), like this:

  Your leadership score is: ${leadership}

You can also display variables on the stats screen, available when you click the “Show Stats” button. There’s a lot to discuss there, so we’ve pulled it out into a separate page: Customizing the ChoiceScript Stats Screen

By the way, variables aren’t just for numbers. You can also put text in a variable by using quotation marks:

  *set lover_name "Jamie"

And you can also set true/false “boolean” variables, which are useful because they can make your *if statements nice and short.

*create lover true
*if lover
  I'm a lover, not a fighter.

Using *else and *elseif to Improve Readability

We can rewrite the leadership example above to use the *else command; this will make it easier to read.

  #Run for class president
    *if leadership > 15
      You win the election.
      *finish
    *else
      You lose the election.
      *finish

This does exactly the same thing as before, but using *else makes it clearer that only one of these two options is possible, just by indenting the code.

You can also use the *elseif command to define three possible branches, like this:

  #Run for class president
    *if leadership > 25
      You win the election by a landslide!
      *finish
    *elseif leadership > 15
      You win the election, but just barely.
      *finish
    *else
      You lose the election.
      *finish

What Happens When We *finish?

When we *finish, we move on to the next scene in the game. This is defined using the *scene_list command at the top of startup.txt. Here’s an example:

*scene_list
  startup
  animal
  variables
  ending
  death

If you *finish in the “startup” scene, we’ll move right ahead to the “animal” scene, then the “variables” scene. Finally, we reach the ending scene. Here’s an example ending scene:

  This is the last scene!  The game is over!

  *ending

That final *ending command instructs the game to insert a “Play Again” menu at the end of the scene. If you choose to “Play Again”, the game will begin again at the “startup” scene. If you *finish in a scene that doesn’t appear in the *scene_list or if you *finish in the last scene of the game, the game will automatically insert a “Play Again” menu as if you had used the *ending command instead.

You’re not required to use *scene_list and *finish to move on to the next scene; you can also jump to any scene in the game using *goto_scene. Here’s an example:

  #Lift weights
    *if strength > 15
      You lift the weights.
      *finish
    You drop the weights and hurt yourself badly.  You never recover.

    *goto_scene death

When this happens, we jump directly to the death.txt file. This allows you to provide a standard “death” message without copying and pasting all over the game.

Examples

Here some example scenes from Choice of the Dragon. Please don’t copy their code without explicit permission from Choice of Games.

Let Us Host Your ChoiceScript Games

Have you finished writing a game? Choice of Games encourages you to submit your finished ChoiceScript game to us so that we can host it for you publicly; we’ll give you a share of the revenue your game produces.

Next: Other Important Commands and Techniques

Questions?

Please post on the ChoiceScript forum if you have questions about this document.