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 ChoiceScript Data Types, their general purpose from a beginner's point of view, and the main differences between the three types of data. In an effort to cover the topic thoroughly for the beginner, it will doubtless repeat some information given on other pages elsewhere in the ChoiceScriptDev Wiki.
"Data Types" refers to the type of information that the two Variable Types used in ChoiceScript can contain; numeric data (containing a number, whether an integer or a floating-point value), string data (containing "text" of some description), or boolean data (a simple but very useful true or false binary switch).
Assigning a data type to variables
While the two Variable Types in ChoiceScript (Temporary and Permanent) are in themselves very different to each other, the way each uses its data type is identical, and either of the variables types can be assigned any of the three data types. Only the manner of originally creating the variable differs: for more information on Temporary variables see the *temp command, and for Permanent variables the *create command.
Note, however, that each individual variable may only ever contain one of the three different data types.
A variable's data type is determined simply by the type of data assigned to it when first created: if you give it a number (even just zero) it becomes a numeric data type; if you give it "something in quotes" it becomes a string data type; and if you give it either true or false (without any quotes) it becomes a boolean data type.
Examples of creating a Permanent variable of each type in startup.txt:
*create var1 0 *create var2 "Jill" *create var3 false
Examples of creating a Temporary variable of each type in any ordinary scene file:
*temp var4 0 *temp var5 "Jack" *temp var6 false
Numeric Data Type
The numeric data type contains a number. This can be either an integer (whole number), a floating-point value (with decimal places), and also either negative (below zero) or positive (above zero). Or indeed, zero itself. This is why within the Wiki we have chosen to describe this data type with the all-encompassing generic label numeric.
Numeric data limitations
Although for our purposes there is no real limit to the size of the number this data type can contain (either negative or positive, or the number of decimal places), it should be noted that there is one important exception to this general rule. Where a particular numeric variable is used within a *stat_chart on the Stats screen to display a percentile bar, that value should range between 0 and 100. If anything in your scripting changes the value to be outside this range, it will have an adverse effect on the appearance of the percentile bar on the Stats screen. The easiest way to always keep a percentile value within the acceptable range is to use ChoiceScript's "Fairmath" system, described in the section on Arithmetic Operators.
Using the numeric data type
Numeric variables can be either overwritten or modified using the *set command, as follows:
*set var 10
This will overwrite the current value of the variable called var, regardless of the current value, with the value 10. Alternatively, you can instead modify the current value using arithmetic operators, for example simple addition:
*set var + 15
This will add 15 to the current value, so increasing the value of var from (e.g.) a current value of 10 to 25.
The current value of a numeric variable can also be displayed on the Stats screen, or anywhere within your story scripting, by placing the variable name in curly braces and preceded by the dollar $ symbol, as follows:
${var}
If that line followed the previous two examples in your scripting, it would display the current value of var as:
25
The value of a numeric variable can also be modified by the value of another numeric variable, also using the arithmetic operators. For example:
*set var + var1
This would add the current value of var1 to the current value of var. If var had been 10 and var1 15, var will now contain the value of 25.
Numeric variables are most commonly used within scripting for conditional purposes, using the *if command:
*if (var > 50)
In this example, we are checking to see if the current value of var is greater than 50, which is just one of many types of conditional checks possible using arithmetic operators. Subsequent scripting would then determine what to do in either of two cases -- if the stated condition is true, and if the condition is not true (i.e. is false).
String data type
The string ("text") data type consists of an array of alphanumeric characters (letters or numbers, but including common symbols such as exclamation or question marks). The string itself must always be enclosed within "quotation marks", by which means ChoiceScript knows that any words or numbers contained within are intended to be "just text", not actual numeric values.
Using the string data type
String values are also created or overwritten using the *set command, as follows:
*set var "Hello!"
String values are also displayed on the Stats screen or within your story by enclosing the string variable name within curly braces and preceded by the dollar $ symbol, as follows:
${var}
The above would then display as:
Hello!
Strings are however modified (i.e. joined together to form longer strings) by a process called concatenation, still using the basic *set command, but is too advanced a topic to include in this "Introduction to Data Types" article.
The string data type can also be used for conditional purposes, employing such as the *if command:
*if (partner_name = "Jill")
Note that all references to the contents of a string variable must always properly use "quotation marks".
Boolean data type
The boolean data type is a simple binary switch, meaning that it can only ever contain one of two values, either true or false.
Note that even though the boolean data type essentially uses an actual word as its value, it is not treated the same as the ordinary text of a string variable. It should therefore never be enclosed within "quotation marks".
Using the boolean data type
As with the numeric and string data types, the boolean data type is also *set with that command:
*set var true
or
*set var false
The boolean data type is not, however, generally displayed on the Stats screen or within the story. Its primary purposes is storing information for conditional purposes:
*if (var)
Which for a boolean is the same as:
*if (var = true)
Either syntax is acceptable. Likewise, for a boolean;
*if not (var)
Is the same as:
*if (var = false)
Again, for a boolean variable, either syntax is acceptable.
TIP: When first defining a new permanent boolean variable using the *create command in startup.txt (or creating a new *temp one in any scene file), consider carefully if a simple value of true or false is definitely all you will ever need to use this particular variable for. If there is even a small possibility that you may want it to contain different information at some point in the future, consider instead making it a numeric variable with a starting value of either 0 (false) or 1 (true). To all intents and purposes this can be used as a boolean, but also allows for future variation of use with a value of 2, or 3, or . . .
Next Tutorial Article: Indentation