This article is aimed at beginners to ChoiceScript. However, if you have not already done so then the best place to start would be with the very first article in this Introduction To ChoiceScript Game Development series of linked articles: A Basic Tutorial.
This article discusses the purpose and use of basic indentation in ChoiceScript from a beginner's point of view, including some guidelines and worthwhile tips to bear in mind.
What exactly is indentation?
Indentation is the addition of "whitespace" at the start of a line to separate blocks of text, adding to your scripting what is known as a hierarchy. This hierarchy governs the program flow. In layman's terms; when indented correctly, ChoiceScript knows exactly what to do, but when you get it wrong, ChoiceScript doesn't know what to do and so returns an Indentation Error.
The logic governing proper indentation may appear daunting at first, especially to someone with little or no programming experience, but take it from a fellow non-programmer -- it does get much easier with experience and will, at some point in the not-too-distant future, suddenly all become crystal clear.
How is indentation used?
Indentation is increased (and decreased) in levels per line, with each level being a set number of spaces or a single Tab. ChoiceScript allows either spaces or Tabs, provided that you use the same throughout each scene file (mixing spaces and Tabs in the same file will always result in an error).
In addition, you are free to choose precisely how many spaces you wish to use for each indentation level. Generally speaking, most ChoiceScript authors use 2 spaces per level, while some find it easier to always get their indentation right if they use 4 or more.
In this article we will talk about levels of indentation, so bear in mind that one level is whatever you decide it will be -- whether 2 spaces, 4 spaces, or a default Tab of 8 spaces -- provided that you remain consistent throughout.
TIP: Most decent Text Editors allow you to change the properties of a Tab and specify the exact number of spaces to insert with a single keystroke. It is much more efficient to change that value as required and use just a single Tab for each level of indentation required, rather than hammer the hell out of your space bar . . .
Basic rule of indentation hierarchy
The most fundamental rule of building your indentation hierarchy is that it always increases by only one level at a time, never more. However, in some cases it will increase almost every single line for several successive lines, so may still expand very rapidly.
TIP: In a typical ChoiceScript game, rapid expansion of the indentation hierarchy is most likely to occur when using nested *choice commands (choices within choices within choices). In such cases it's often worth considering breaking things down a little, and instead use more *goto commands leading to new *labels containing *choices, thereby using fewer nested *choices (and less actual indentation). This is especially worth considering if relatively new to ChoiceScript and still finding the whole subject of indentation a little confusing.
Commands requiring indentation
Certain commands require that the following line always be indented by one level, in order for the command to be interpreted correctly. It is worth studying this list, or even making a copy for your own handy reference. If you automatically indent by one level on the line immediately following any of these commands, you're more than halfway there!
The various "following-line-must-be-indented" commands are as follows:
*fake_choice *choice # (an option line for either of the above) *allow_reuse (where preceding an #option on the same line) *disable_reuse (where preceding an #option on the same line) *hide_reuse (where preceding an #option on the same line) *selectable_if (where preceding an #option on the same line) *if *else *elseif / *elsif *scene_list *achievement *goto_random_scene *stat_chart
Remember the Golden Rule: if the command you are typing is included in the list above, the next line must be indented by one more level. Conversely, if the command is not in this list, the next line does not require indenting farther, regardless of what that line will itself contain.
Example of indentation in action
To emphasize the Golden Rule, follow the example code below bearing those particular few commands in mind. You will also see some other common commands in use, which of course are not immediately followed by indentation as they are not included in the list above. Don't worry if you don't yet fully understand what all (or even any!) of the following code actually means -- that will come with time. For the purpose of this example, just focus entirely on when indentation occurs, and when it reduces.
Note that the following example will also simply use "(Some response text goes here)" as a placeholder for paragraphs of displayed story text, to avoid detracting from the main purpose of this example. In addition, an indentation level of 4 spaces has been used for purposes of clarity.
*fake_choice
#Ordinary Option Text
(Some response text goes here)
#Ordinary Option Text
(Some response text goes here)
*choice
#Ordinary Option Text
(Some response text goes here)
*set var true
*if (var1)
*set var1 false
*goto labelname3
*else
*label labelname1
*choice
*hide_reuse #Conditional Option Text
*if (var3 < 5)
*set var3 +2
(Some response text goes here)
*page_break
*label labelname3
(Some response text goes here)
*goto_scene next_scene
*else
*if (var4 = "Jill")
(Some response text goes here)
*line_break
*line_break
(Some response text goes here)
*goto labelname1
#Ordinary Option Text
(Some response text goes here)
*page_break
(Some response text goes here)
*goto labelname3
#Ordinary Option Text
(Some response text goes here)
*set var2 +10
*finish
*selectable_if (var1 = false) #Conditional Option Text
*set var1 true
(Some response text goes here)
*choice
#Ordinary Option Text
(Some response text goes here)
*label labelname2
*choice
*hide_reuse #Conditional Option Text
(Some response text goes here)
*goto labelname2
#Ordinary Option Text
(Some response text goes here)
*finish
#Ordinary Option Text
(Some response text goes here)
*ending
As you can tell from the above, the Golden Rule of precisely when to indent one more level holds true throughout; always indenting one level after one of the listed commands, but never after an unlisted command.
The other point to bear in mind, concerning precisely when to decrease indentation once again, is that all the #Options of a particular *choice statement must share the exact same level of indentation -- even if they are preceded by a conditional command such as *selectable_if or *hide_reuse. The same holds true for any *if / *elseif / *else combination.
Resolving indentation errors
Indentation errors can be caused by both too little indentation (i.e. not abiding by the Golden Rule above) and also too much indentation. In the second case this is often due to extra spaces or tabs at the end of a line, making the actual cause very hard to spot as there's nothing actually amiss "at a glance". This can often occur as a result of copy-pasting and then quickly editing reusable segments of code, so inadvertently leaving lingering spaces or tabs where they shouldn't be.
TIP: If you cannot immediately spot the cause of an indentation error, chances are it may be caused by unwanted end-of-line spaces. Luckily, most modern Text Editors have a means of quickly identifying such. For instance, in "Textpad" the option to View--Visible Spaces will highlight potential indentation problems, and in "Notepad++" View--Show Symbol has two useful options (Show White Space and Show End of Line).
Still struggling with Indentation?
Don't despair! Although the scripting hierarchy - governed by correct indentation - is certainly the most difficult hurdle for a ChoiceScript newcomer to overcome, there are community-driven Development Tools designed to make correct indentation (among other things!) much less of a steep learning curve.
Next Tutorial Article: Basic Scene Scripting