The Beginners Guide to ChoiceScript

So, any long time member may know that I made a ChoiceScript Guide. Well after so long and so many iterations, I’m closing in on completing it. My intentions with this guide is to create something that, no matter your level of skill or computer knowledge, it can teach you the basics of ChoiceScript. For me to consider it truly ‘done’ though, I want to make sure it includes every thing that any aspiring ChoiceScript writer may want. So if you don’t know what to do with ChoiceScript, try checking out this guide, and see if I can’t help you get started on making your own game.

The guide can be viewed online here.

Now while this guide has everything you’ll need to get started with ChoiceScript, there are still a few missing features, noted below:

  • Incomplete Feature: Advanced Walkthrough.
  • Incomplete Feature: Tips Section
  • Feedback Requested: Images to the unzipping/opening txt (is it clear enough/is there anyone having trouble with after reading this guide?)
  • Feedback Requested: Are the colors confusing?

@Reaperoa i’m so grateful for this! I can’t wait to try this out. One question though: can Notepad be used on Apple devices or is there a another text editor that needs to be used?

1 Like

Notepad itself can’t be used on mobile devices, but there are a number of options available that you might try. You just need something that doesn’t try to format your text for you, like word processors. You might try Nebulous Notes Lite, since it’s free and has dropbox sync capabilities.

1 Like

I’m sorry, but I haven’t used a mac since the very tail end of the 90s. Sublime seems to be the general recommendation with a bit of googling, and it looks fine at a glance, but I personally have never used it. If you do your own checking and find a really good free mac alternative though, please do let me know. My recommendations are currently only based on what I’ve used, but I’m happy to include things to make it more inclusive.

thanks. I think I may stick to windows for now and try coding on that. However, if I do decide to use my Mac and I do find a decent text editor, I’ll be sure to let you know.

I would really like some pictures for the unzipping section. That was actually the most difficult part for me when I was first learning choicescript. I found unzipping the files and then having an overwhelming amount of them, and not knowing what to do next, was one of the worst steps. I had a look at CS_Closet’s tutorial though (which is now out-dated) and just seeing things in images helped a lot.

We’ve got users using Sublime instead of Notepad++. Sublime isn’t free though which is something that should be noted.

I use DroidEdit for my android, but just to view the code, I don’t do any actual coding there so I can’t tell you if it’s any good or not…

@addicted Thanks.

@FairyGodfeather I’ll see about adding in images for the unzipping. I think I considered it at one point, but backed off on that idea because I wanted universality, and images have to come from one OS or another (specifically they’ll be coming from Win8, but that’s neither here nor there) (plus I think I first considered it when images were pretty new and Dan put up the caveat about needing testing across platforms).

I’m surprised that zip files seem to be a common problem, but computers have been a staple of my life since I was like eight or ten, so it’s hard to know what is simple because it’s intuitive, and what is simple because I’ve done it a million times. Is there anything else that the guide fails to cover clearly enough, or anything else anyone found particularly difficult they think could be covered in more detail?

Regarding Sublime 2: It is technically not free, but it does have “[…]no enforced time limit for the evaluation.” I’ll lean against including it because part of the design philosophy for the guide is nothing overwhelming (it’s why I’m actually updating the links so that they are inline with the text and you can’t see the actual addresses, not to mention so they can easily open in new windows), and IMO any talk of paying for anything breaks that, but I may reevaluate though, IDK.

1 Like

I actually understood how to unzip. It’s the process afterwards that is difficult.

I was expecting there to be an executable file once everything was unzipped but there wasn’t one. Or just more support in the downloaded stuff, and there wasn’t.

And having all of those files and not knowing what any of them did was so overwhelming. While text instructions are great for almost everything, to begin with I really needed those pictures just to hold my hand and tell me I was doing right. I tried the website, I tried the wiki, I tried the forums, I tried to make sense of it all, but it was CS_Closet’s tutorial that made it click.

I haven’t had the chance to read over the guide in depth. But if I do I’ll certainly make some more suggestions.

Randomizers beware:
There’s a known issue where going to the stat screen and back can cause a random variable to reset to something else. This can change your game in unexpected ways even if you think it should already have taken effect, e.g. have gone to a different scene determined by the random variable.

The easiest solution is to use the random number to immediately set another variable, at some point before the variable is actually needed. Example:

*rand room 1 3
*if room=1
   *set room_name "kitchen"
*if room=2
   *set room_name "bedroom"
*if room=3
   *set room_name "attic"

Then later when you refer to the variable room_name, it won’t matter if the random variable changes.

^ Anyone see anything wrong with this? If not, here’s Coding Tip #1.

1 Like


I’m not sure if I understand what you’re trying to do/explain.

Jason’s method works for circumventing the issues with the random command though.

Actually the guide seems to tackle the subject too. (Although you didn’t mention how I use this method in order to cheat.) :slight_smile:

Second, there is a significant unresolved problem with *rand, in that if a player goes to the stats screen and returns, the *rand is re-rolled, and additionally this may cause other commands to refire (such as *set commands), doubling their affects. For this reason, it is recommended that *rand only be used where it will not run at the same time as any other commands, and that it be run at least one page before it is to be used (so that it has no visible affect on the story).

Can you provide an example of this, @Reaperoa ? Sometimes I find examples of code helps me best. (Although that said /I/ don’t need one in this case.)

Also, I believe Choice of Games philosophy is not to rely too much on the randomness. Would mentioning that be appropriate?

1 Like

I’m referring back to this:

Is the exact explanation that *page_break will fix it, but goto_scene does not? The method of using a random variable to set a different variable fixed that problem, which is why I wrote the tip about that method of avoiding random variable bugs.

If the variable was used to tell the main scene which other scene to go to, using goto_scene, testers in that particular scene would be re-routed to a different scene if they clicked to the stats and back during that scene.

Have you spoken directly to Dan about this? I’d suggest messaging him, sending him an email. Because that seems like a really strange bug. I know he posted on your thread but he didn’t seem able to recreate the bug. If things are happening the way you say, for the reasons you’re saying, it sounds like something’s really broken. But it’s not actually something I’ve come across or seen anyone else mention in the forums.

Yikes… if that’s the case, I’ve twice been guilty of posting about something that I thought was a known issue or an error on my part, and is odder than I portrayed it to be. I’ll get together some proper documentation on it.

@FairyGodfeather I’ll be including an example of what not to do with *rand (ie, not put it where it can affect a scene visibly) in the actual walkthrough, because understanding that is pretty important (and because I don’t have a good plan for *rand in the walkthrough’s narrative). As for the design philosophy against *rand, it’s mentioned, but not clearly (it’s the sentence right before what you quoted).

I’m thinking I’m going to redesign some structure in the guide into a more bulleted list with bold and color so as to make things clearer. Basically all the little “Note this…” are instead going to be Note: This, and all the *commands are… well I can’t figure out how to color text on discourse, but you get where I’m going here.

@Sashira I think you’re confusing one bug for another. The problems with *rand are pretty well documented, but that doesn’t seem to be what is causing your troubles. Instead you seem to be having trouble with {references} which is something Dan recently changed. Without something reproducible, I don’t think anyone knows what exactly is the problem you’re running into. (And that’s the key to figuring things out, we need something reproducible.)


Ha! I fail completely at reading. :slight_smile: I’d say Difficult to test, unfair to play, and there’s a stat screen bug are three things. :slight_smile:

I’d definitely be in favour of more bulleted. Even using bold in some places, instead of colour would work a little better for me. And I don’t think discourse supports colours.

So, I’ve added bolding and restructured most important notes to hopefully make any problems with coding in CS more apparent. I’ve colored the first part of the guide in line with N++ Syntax Highlighter. I’ve added pictures, (just 3 at the moment, but with plans for more).

If you can take the time, a few things I’d like to know:

  1. Are the images loading for people (more specifically, are they loading in a reasonable amount of time), and are they actually functional for everyone?
  2. Does the color look fine and work on all devices. Assuming I’m understanding things correctly, it really shouldn’t be a problem, but it’s a possibility.
  3. I’ve made minor changes to the UI. Anyone find those changes to be a major detriment?

Well, the intermediate section of the guide is completed, but I’ve only done a rudimentary check on it. There shouldn’t be actual technical errors in what commands do, but there might be typos or inconsistencies.

It’s actually surprisingly difficult to keep a coherent narrative line while simultaneously coming up with a reason to use every single command once.


Hey I was wondering, can you hack choicescript to add additional spaces and thus let the code show up easier in your guide? (Would it be much the same way you can add tags for colours but using  ?)

Also can you create a search function? So we type in the name of the command we want, using input_text and it’ll take us to that relevant section of the guide?

Also, being a Brit we don’t call # a pound key. That’s the hash symbol, or even the number symbol. The pound key is £

[quote=“FairyGodfeather, post:18, topic:9866”]
Hey I was wondering, can you hack choicescript to add additional spaces
[/quote]I actually tried a bunch of stuff and couldn’t anything to work. I don’t know enough about JavaScript to know if it’s an artifact of that (although that’s what I’m guessing), or if Dan included something that heavily edits out whitespace characters at the start of new lines.

I think I’d have to actually add my own commands to do that properly, At the very least, I can make the indents appear close to correct by just duplicating the actual printing of text, altering it, and just running it as a *script while forcing an indentation. It’s a bit low on the list at the moment though, because I’ll have to check if there’s visual problems with smaller devices, and I want to at least finish the walkthough first. It still won’t be copy/paste ready, but it should look fine.

[quote=“FairyGodfeather, post:18, topic:9866”]
Also can you create a search function
[/quote]Since Dan included foo#1, yea. Before a single typo would make it difficult, and ultimately ineffective I think, but now I can extract things, I should be able to make a relatively robust search system. (It was part of why I made that little blackjack game. I wanted to make sure I could fully understand foo#1 before trying to use it).

[quote=“FairyGodfeather, post:18, topic:9866”]
Also, being a Brit we don’t call # a pound key.
[/quote]Well I’m born an raised in America. :stuck_out_tongue: But sure, I’ll drop in it being called a hash sign.

1 Like

I’ve actually implemented blank indentation (it was a lot easier than I thought, now that I know things I didn’t when I first tried). Just a few notes:

  1. I only have a Win8 PC to test on. It should work across everything while still looking fine, but I can’t be certain. (This is actually kinda important to test).
  2. I’m not 100% sure that copy and paste will work perfectly. I know in worked for me for a direct copy/paste, but I’d have to do more checking to be certain about things.
  3. I messed with the text a bunch without a solid examination, there is the possibility I’ve introduced a small problem somewhere. I’ll check later.

It does raise the point that I can actually indent all the code just a little bit to set it off from the text better. However:

  1. I’m not sure if that would be less confusing (because the actual code is separated a tiny bit more from the text), or more confusing (because all the code is a tiny bit indented)
  2. I’d have to <div style> or the equivalent to be able to do it (which I can do now), but I can’t be certain about how/if that might break across devices. (my modifications to the ui.js, if one of the people with actual JS knowledge wants to actually check for me, all I did was put in a few more [things] into printx, so it’s right at the top.)
1 Like