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.
Manipulation of numbers is a fundamental part of all programming and scripting. This article will discuss the correct format by which we can apply these mathematical methods to both previously stored and new data.
There are several arithmetic operators you can use as a ChoiceScript game developer.
Let's say we have a numeric variable called var with a current value of 50, to which we apply any one of the following operations:
*set var + 5
A var with a value of 50 would now have a value of 55.
The current value of one variable can also be added to another:
*set var1 + var2
If var1 had a value of 50 and var2 a value of 5, var1 would now have a value of 55. The value of var2 remains unchanged.
*set var - 5
A var with a value of 50 would now have a value of 45.
The current value of one variable can also be subtracted from another:
*set var1 - var2
If var1 had a value of 50 and var2 a value of 5, var1 would now have a value of 45. The value of var2 remains unchanged.
*set var * 5
A var with a value of 50 would now have a value of 250.
The current value of one variable can also be multiplied by another:
*set var1 * var2
If var1 had a value of 50 and var2 a value of 5, var1 would now have a value of 250. The value of var2 remains unchanged.
*set var / 5
A var with a value of 50 would now have a value of 10.
The current value of one variable can also be divided by another:
*set var1 / var2
If var1 had a value of 50 and var2 a value of 5, var1 would now have a value of 10. The value of var2 remains unchanged.
Fairmath is a percentile operator and only works on numeric values in the range of 0-100. Attempting to apply a Fairmath change to any value currently outside this range will result in a game-stopping error. It is used as follows:
*set var %+ 20
To increase the current value of a numeric variable by 20%; or,
*set var %- 20
To decrease the current value of a numeric variable by 20%.
Anywhere between 5% (a relatively small change) and 30% (very significant) is common in Choice Games, with higher values usually reserved for rare or extreme circumstances.
The formula Fairmath uses for increasing a value -
- ensures three things:
- The resulting value will never be higher than 99, regardless of the percentage change applied.
- The closer the variable value currently is to 100, the less it will increase.
- The closer the variable value currently is to 0, the greater it will increase.
As an example, let's assume the following current values -- and apply a 20% Fairmath increase to each of these (e.g. *set strength %+ 20). The end result is: Essentially, when increasing a value with %+, Fairmath uses the difference between the value itself and 100.
For instance, the difference between Strength (10) and 100 is 90, so Fairmath added 20% of 90 (18) to Strength, giving us a resulting value of (10+18) = 28 - a big jump.
The difference between Intelligence (50) and 100 is 50, so Fairmath added 20% of 50 (10) to Intelligence, giving us a resulting value of (50+10) = 60 - a moderate increase.
The difference between Dexterity (90) and 100 is only 10, so Fairmath added 20% of 10 (2) to Dexterity, giving us a resulting value of (90+2) = 92 - a very small rise.
The formula fairmath uses for decreasing a value -
- also ensures three things:
- The resulting value will never be lower than 1, regardless of the percentage change applied.
- The closer the variable value currently is to 0, the less it will decrease.
- The closer the variable value currently is to 100, the greater it will decrease.
As an example, let's once again assume the following current values -- and instead apply a 20% decrease to each of these (e.g. *set strength %- 20). The end result is: Unlike for increasing a value, where Fairmath uses the difference between the value and 100 to determine the degree of change, when decreasing a value Fairmath instead uses the value itself.
20% of Strength (10) is only 2, giving us a resulting value of (10-2)= 8 - a very small drop.
20% of Intelligence (50) is 10, giving us a resulting value of (50-10)= 40 - a moderate fall.
20% of Dexterity (90) is 18, giving us a resulting value of (90-18)= 72 - a significant drop.
Bear in mind that the Fairmath formulae will never result in a value above 99 or below 1, no matter what percentage change you try to apply. Likewise, it's equally important to remember that Fairmath can only be applied to a value currently within the range of 0-100, otherwise it will cause a game-stopping error.
The difficulty in working out possible results on the fly while coding in ChoiceScript prompted CoG community member @Twiger_Fluff to devise an Online Fairmath Calculator.
Together with fellow member @Eleckar they also contrived to provide ChoiceScript writers with a Google Sheets-based Fairmath Multiple Calculator. With this tool we can track Fairmath stat increases or decreases through successive changes (say, along a particular story path, or for a particular character build) to also see the final current value, allowing us to more easily tweak and balance stats throughout.
Users of the Choicescript Integrated Development Environment (CSIDE) - see our Development Tools article for further details - should note that they can also use that application's powerful Console feature as (among many practical uses) a handy Fairmath calculator.
The *round() is used for setting a variable to the nearest integer, as following:
*set var round(30.5)
this will automatically set var to 31.
You can also use it with variables instead of numbers, as following:
*set var1 round(var2)
where var2 is equal to 20.5; var1 will be equal to 21.
Remember, never make any spaces between "round" and the "(var1)" brackets.
The modulo is used to find the remainder when one variable is divided by another. It is used by simply typing the word "modulo" between the first variable (the dividend or numerator), and the variable you want to divide by (divisor or denominator). It is a fairly obscure and weird command, but useful in two main ways. First, you can check if a number is evenly divisible to another by writing:
*if (var1 modulo var2) = 0
For example, we can try:
*if (50 modulo 10) = 0
which is true, because 50 divided by 10 leaves no remainder, but if we try:
*if (50 modulo 40) = 0
it is false, because 50 divided by 40 leaves 10 as a remainder.
Secondly, we can also get the fractional part of a number, so that if we do this:
*set var 50 *set var / 40
the result will be 1.25; then if we do:
*set var modulo 1
the result will be 0.25.
Note that the above example rewrites the variable var when the module is used. The quick way around this is to create a second variable, set it to equal the first, then use the modulo. So if we have var1 set to 50, and var2 set to 40 and want to see what the remainder if we divide var1 by var2, we'll need something like this:
*temp var3 *set var3 var1 *set var3 modulo var2
This will leave us with the var1 and var2 intact, and additionally var3 with a value of 10 (the remainder of 50 divided by 40).
N.B. When used with an *if, the modulo requires parentheses. However, when used with a *set, it requires that there be no parentheses.
Note: As of October 2016, the operator for a modulo operation was changed from the percent sign (%) to the word "modulo". The change was made to avoid confusion with the more commonly used Fairmath operations that also use the percent sign.
Next Tutorial Article: Concatenation
- Dan Fabulich, ChoiceScript’s modulo operator is changing from “%” to “modulo”, October 14, 2016.