Countersong's Closet

Click here to edit subtitle

ChoiceScript Tutorial


ChoiceScript Tutorial Part 2: Starting Your Game

On to the fun stuff. Most of what you want to mess with is going to be in web/mygame/scenes, so let's go there.

The files that are already in here are for the tutorial game. You can open them up with notepad to see how some of the basic operations in ChoiceScript work, though it can be a little confusing if you're just starting out. This tutorial will cover what's in there, so don't fret too much about it. When you're ready to start, delete everything in the scenes folder except choicescript_stats.txt.

If you did delete choicescript_stats.txt, just open up notepad and save a blank file under that name. The contents of it aren't important right now.

Now, open up a plain text editor (such as notepad) and type up the first page of your game. Some people will start with an introductory paragraph to their game, others will jump right into the action. What you type is up to you.

  • Tip: Everytime you hit enter to go to the next line, ChoiceScript will simply add a space in the game and continue on in the same paragraph. In order to make a new paragraph, leave an empty line.

At this point, you want to save the file in your web/mygame/scenes folder under any name you want. Just make sure of these two things:

  • always use lowercase letters for file names
  • never put a space in the name of the file

You're well on your way to making a scene! However, it won't show up unless we tell ChoiceScript that we want it to, so let's do that now. Open web/mygame/mygame.js with your text editor and find the scene list.

The formatting from here on is tricky, so the easiest thing to do is replace what's already in the quotation marks. The first scene listed is "startup" so let's replace that with your scene's filename.

The rest of the scene names can be deleted, although it might be easier to simply change them as you go. Keep in mind that they will cause errors if you attempt to run the game with them still in place! Go ahead and save that file, but don't close it. You'll be using it again soon.

Congratulations! You have your first scene! It's pretty boring, though, so let's open up our first scene again and add to it.

If you want to add another page right after the one you just wrote, go to the next line and type in *page_break. Now you can begin on the next line to make your second page.

  • Tip: If you'd like to replace the default "Next Page" text with your own, write it in after *page_break

Adding Choices

Eventually, you're going to want to put in a choice, but before you do, you have to make a major choice of your own. ChoiceScript will accept any formatting indentation that you choose to use as long as it's consistant. Remember this decision because you're going to be using it throughout the entire file.

  • Will you use tabs or spaces?
  • How many tabs or spaces will you use?

For the purposes of this tutorial, I will be using four spaces everytime I indent, but use whatever's easiest for you.

To start a choice, type *choice on a new line. On the next line, indent the way you've chosen and type in #option1, where "option1" is the choice's text. Add as many choices as you like after that, each on it's own line to form a block of choices.

These choices all have to do something, so let's write in some effects. Go to a new line after your first choice and indent twice. This makes a block within your choice block. This new block has to end with either *finish, *goto_scene, or *goto. Otherwise, an error will occur in your game.

The *finish command will move the game to the next scene listed in your mygame.js file. Since you don't have another scene, this will simply end the game (or cause an error if you didn't remove the default scene names from the list).

The *goto_scene command works much like the *finish command, but it will move to a specified scene that you type in after the command. In my example, elsewhere_in_ocean.txt does not exist yet, and would cause an error.

The *goto command works like the *goto_scene command, but moves to a specified *label within the same scene. In my example, I added *label what_now after the choices so that it wouldn't cause an error.

For now, you probably want to stick with the *goto command, so make sure there's a *label to jump to after your *choice block that continues on with the story.

  • Tip: Most of your ChoiceScript game is going to be made out of these blocks (and blocks within blocks), which can make the indentation be a bit unruly if you're using notepad. I suggest using something like Notepad++, which keeps track of indentation and helps you track down errors with line numbers. In fact, I'll be switching to that for the rest of this tutorial.

Adding Stats

Now you've got a branching story in the works, but you probably want to use some stats pretty soon. The first thing you have to do is go back to your mygame.js file and declare these amazing stats. Find this section:

The rules for listing your stats are similar to the ones for listing your scenes, except it doesn't matter what order they're in and they must be listed here if you want them to apply to your entire game. Remember, no caps and no spaces when naming them! The basic format is

stat_name: value

There are several diferent values you can use for your stats.

  • Numerical: Great for many purposes, but especially useful for if you want to have varying degrees of the stat or are keeping a count. Just type in a number as the value.
  • True/False: Great for flagging events, or when stats can only have two states. Just type in true or false as the value
  • Named Values: If you have a very specific word, phrase, or sentance (like a name or a weapon) as your value, you need to put it in quotation marks. You can use either upper or lower case, since you can capitalize it within the scenes if needed. Also, if you don't have a default value for your stat yet, you can simply type in a set of qotation marks to be filled in later.

The next section of your mygame.js file asks for debug stats.

Either copy and paste the previous section with all of your starting stats, or erase the default stats and uncomment the last line by deleting the // and the space that follows it.

Congrats! Now your game has potential stats! In order for them to be of any use, however, you need alter them in your scene. In order to alter a stat, you use the *set command like this:

*set stat_name value

This will change the value to a new value. You can also try these to alter an existing numerical value:

*set stat_name +value

*set stat_name -value

*set stat_name stat_name2

*set stat_name /(stat_name2 *2)

It can get pretty complicated from there, but I'll go over those details once we're through with the basics. For most games, you probably won't need to do more than add or subtract values or enter a string of text within quotation marks.

*set stat_name "value"

Making A New Scene

While you could technically keep your entire game in a single scene, it's often easier to orgainize your work into different files (plus, it cuts down on the time it takes for your game to load).

To make another scene, just open up a new text document save it in the scenes folder.

Now, if you want it to load as soon as your first scene is done, go back to your mygame.js and list it right after your first scene.

Running Your Game

By now, you probably want to see the fruit of your labor. Easy enough. Just save everything that you've been working on and open the web/mygame folder. To run your game, open index.html with a web browser.

To run your game, open index.html with a web browser. Be aware

  • Google Chrome will not load your game from a local drive. Avoid testing with it unless your game is uploaded to the internet somewhere.
  • Safari will load it, but will not give you a proper error report if it encounters a problem. If you're testing your game after you uploaded it to the internet, Safari works perfectly fine.
  • Internet Explorer will load it, and gives you a proper error report. However, it reports a false error if you use *input_number in your game.
  • Mozilla Firefox will load it, and gives you a proper error report. It does not have the *input_number issue that IE has.

If you come across an error, don't worry. IE and Firefox will tell you exactly where it is in the popup dialogue box. 

With these few commands, you can do quite a bit with ChoiceScript. Try getting the hang of those before moving on to the next section.