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:
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.
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.
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!
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.
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.
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:
*if statements must get their own line, with their corresponding #option indented one level over below them;
*selectable_if, *hide_reuse, and *disable_reuse modifier flags must appear on the same line as their corresponding #option; and
*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_ifvarname or *selectable_ifnot (varname), it needs to be *selectable_if(varname) or *selectable_if(not (varname)) instead.
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.
