ChoiceScript Full Tutorial (finished!)

Link: ChoiceScript Interactive Tutorial

I’ve lashed together basically everything you could want from a ChoiceScript Tutorial. It has a guided page-by-page tutorial, as well as a “Chapter List” page for easy navigation. It has examples of all the different commands, along with appropriate ways to use them, and common mistakes that can end up breaking the game. There’s even pictures accompanying some examples. It has pages that help out with Quicktest and Randomtest. It also has higher level examples of design templates like the ones I’ve used in Creatures Such as We and my upcoming The Sea Eternal. There’s also a page with writing and testing tips.

The tutorial is fully interactive: you can click around to different examples and skip examples that aren’t relevant or useful to you, and you can get a sense of what not to do at a mere glance of the “break the games” titles. I really hope it’s useful and if anyone has anything to add, please give feedback!

Some screenshots of the tutorial in all its completed glory:

An example of a tutorial page explaining how variables work in ChoiceScript:

An example of Quicktest error explanations (with general description of Quicktest at the top)"

Some segments of the list of post-tutorial page navigation:


This is great! Wish I had had this when I was first learning (Wiki is a solid resource, but if you don’t know where to begin, it can be a little confusing to first sift through), but it looks like it will be very helpful for current and future users.

FYI, “Suggested additional programs” seems to link back to the “First-time ChoiceScript setup” page again for me. So, my apologies if it’s there and I couldn’t double check, but may I suggest adding the CS-IDE to helpful links or the compile section?

Anyway, fantastic job! So impressive and intuitive. :slight_smile:


Wow, I hadn’t even heard of the CS-IDE, @MizArtist33 . What a really cool tool. I added it in to the tools section (and made a clearer separation between First-time setup / Useful tools - thanks for pointing out that weakness!)


I love this! The visuals are incredibly helpful, and your explanations are very clear. I think the way you’ve built the tutorial, with the least complex commands and visuals first, is intuitive and will help new coders’ comprehension levels (and remembering how things work the next day, or the next month, as well).

The ‘break the game’ section is so useful, as well. Learning the most likely causes of my broken game was the hardest part of the ChoiceScript learning curve for me.

If I could make one tiny suggestion: At the bottom of the page, where there is ‘Go Back’ and ‘Next’ - would it be possible to make ‘Next’ into ‘Next Section’? Or at least some other way to indicate that the button takes you to a new topic (from ‘Paragraphs and Line Breaks’ to ‘Font Effects’, for instance), and not to the next page within the category (‘Writing in Paragraph Breaks’ to ‘Combining Content with Line Breaks’, in this case). At first, I thought that was how one skims through the pages, and didn’t realise I was skipping most of the tutorial for rather longer than I’m comfortable admitting.

Will absolutely make that change. Thanks for letting me know it a was a bit confusing!

Just curious, @Fiogan did you get how to use the up / down arrows? I’m a little worried those might be a bit obscure, too.

I’m also spending the day translating the templates into .txt files that can be downloaded (since right now you can’t copy-paste what’s there and use it.


Done! Changed them to “Next Section / Previous Section.” Thanks for the tip.

Also got the Templates page to give a link to downloadable versions.


Brilliant. And yes, I played with the up and down arrows. Those made sense to me immediately, partly because I’m used to seeing similar arrows in apps and such. And downloadable versions are a great addition!

Wow Lglasser, I think you deserve the hero badge. :sunglasses:

This tool is so clear - I enjoyed the ‘visualising choicescript’ section. Perhaps one day you could get some examples on there demonstrating cumulative increase (more choice = more writing). Then different graphics of the ways that choicescript authors cope.


Oh, I really like that suggestion, @nightcap . I’ll work on adding a section about cumulative increase and design philosophies to the page with design tips. I’ll definitely need a few days to mull it over and to get the drawings done.


Oh, this looks great! I haven’t used CS in ages and I’m gonna try and re-learn things I’ve forgotten. I’ll definitely try this out: good work!

1 Like

Followed through on @nightcap 's suggestion and added different types of design structures to the Design Strategies page. I tried to pull different types of structures from different guides, but if anyone has any other kinds of structures they’d like to throw into the ring, I’d be willing to diagram it as well.

Also, do you think it would be useful to give examples of the different types of games? I’m not sure if I want to look like I’m endorsing one game while ignoring another.


I don’t know what to say, this is Excellent @Lglasser

I am really impressed at how deeply you engaged with this topic and am learning from your tutorial as I speak. . .

First structures landing page -

A typo:
The examples shown represent of several scenes with tens of thousands of words.

Sentence structure:
How well the game has a satisfactory introduction


Thanks for pointing out those typos! Ironed them out (page might need a refresh to see them.)

And glad the tutorial was helpful! I’m definitely trying to wrangle all the info I can into this one accessible place.


Small update:

  • Added the *link command as its own page
  • Better described what’s on the templates page (strings of choices / larger choices / stat tests / choice hubs / handling pronouns / stat page example)
  • Added a break-the-game example to the numbers page
  • Tidied up one of the examples for text variables.

The *fake_choice page claims that you can’t use any *if or *selectable_if options in the selection lines. But in fact you can; it works exactly like a *choice block, except that you can’t nest *choice or *fake_choices, or use any terminal commands (*finish, *goto, *goto_scene, etc), within a *fake_choice. Of course, this last restriction is because game flow simply falls out of the *fake_choice to the next line.

Specifically, for both types of *choices:

  1. *if statements must get their own line, with their corresponding #option indented one level over below them;
  2. *selectable_if, *hide_reuse, and *disable_reuse modifier flags must appear on the same line as their corresponding #option; and
  3. *if statements’ tests don’t need to be enclosed in parentheses (but they can be), whereas *selectable_ifs’ must be enclosed in parentheses. Even if it’s just *selectable_if varname or *selectable_if not (varname), it needs to be *selectable_if (varname) or *selectable_if (not (varname)) instead.

I agree that *ifs are usable, but *selectable_ifs aren’t. They will break in live conditions.

1 Like

I’ve found that *selectable_if and *if statements can work on fake choices… until they don’t. I’ve had a lot of difficulty nailing down the exact conditions under which they do / don’t work, so I played it safe and said just not to use them. That seemed like the safest option.

However, should I include *if ? And is their needing their own line accurate?

That’s always been annoyingly inconsistent. *selectable_if does only ever work on the option’s own line, *if will always work on the above line, and will (sometimes) seem to work on the same line.

Hmm… I’ll see about adding that, although I think it’s too bad it muddies an otherwise simple rule to remember.

I almost feel like I need to add a new header to go along with “Basic Commands” and “Get Fancy” : “Use at Your Own Peril”.

Thanks for the additional info, @Chris_Conley and @CJW


Does this explain how to create an inventory?