Variables are probably one of the most important aspects of the ADRIFT Adventure System and imperative to creating good adventures. Unfortunately, their use can often be difficult to understand. But, once understood, variables become one of your most prized tools.
Before you can begin to understand how variables are used in ADRIFT, you first need to have an understanding of what variables are and how they function. The next few sections are intended to help you in that understanding.
The best way to look at a variable is to think of it like a cookie jar. A cookie jar holds different types of cookies which change from time to time. Likewise, a variable holds information which changes. But, the variable name is always the same, just like the cookie jar itself never changes even though the type of cookies may change. In this way, the variable's name can be used as a reference. Its contents are known as values, and whenever you open the variable, you will be shown what the current value is.
In ADRIFT, you create variables by giving them a unique name (the variable reference) and an initial value. You can then place the variable reference anywhere in any text in your adventure as many times as you want. Instead of displaying your variable reference though, ADRIFT always opens up the variable and displays the contents, or value, instead. You can change the value of your variable in many ways, and you can allow or not allow the player to do certain things based on what that value is.
From the discussions in the beginning sections of this tutorial, remember that a variable is primarily composed of two parts, a reference name and a value. The value of a variable can be changed in many places in ADRIFT. However, the reference name can only be edited in one location - the Variables tab. It is here that you will create variables, edit their reference names and initial values, or delete them when no longer needed.
To access the Variables Tab, on the Menu Bar select Adventure - Advanced, then click the Variables tab. You may use the buttons on the left side or right-click in the white space on the right side to get a quick menu with the same options.
It is important to note that you must supply an initial value for any variables you create. By default this value is set to zero (0).
You may name a variable anything you want. Generally, you do not need to use symbols or numbers in ADRIFT to make the variable unique because all variables must be surrounded by percentage symbols (%) when placed anywhere in your text.
If you do decide to use symbols when naming your variables, the symbols used most often are exclamations (!) and underscores (_) and they are usually placed at the beginning such as "_NumCoins". It is also a common practice to add a prefix to a variable name such as "vWallColor" or "varWallColor". What is important is that you use a method that easily helps you organize and use your variables.
It is also a good idea to decide on a standard for naming your variables before you begin creating your adventure. This makes it much easier to keep up with your variables and where they apply. Say for example, you wanted a variable describing the on/off condition of every light in your game. One standard method for naming your variables might include the room name, the word light and a corresponding number or description for the light in case there is more than one light in the room. You may also want to establish some standard abbreviations.
The reason it is so important to have a standard has to do with placing variable references in description fields throughout your adventure. It is often very easy to confuse your variable names, especially as your adventure grows in size. Let's assume you set up the following variables:
LightLVCeiling
LightLVDesk
LightBedroom1
LightBedroom2
Notice that for the living room lights, you used abbreviations and no numbers. But for the bedroom lights, you did just the opposite. Unfortunately, when you go to place the variable in your text, you may end up making a mistake like the following:
The bedroom light is %LightBR1%.
When playing your adventure, ADRIFT will not know what LightBR1 is because it doesn't exist. You got your naming conventions mixed up. Therefore, standardizing your variable names will save you a lot of headache and corrections in the future.
As a final point, you may have noticed that the variable names used above are written in lowercase except for the first letter of each word in the variable, which is capitalized. This is just another tool to help organize and identify your variables.
Earlier I compared a variable to a cookie jar. As I mentioned, a cookie jar can hold many different types of cookies, but it can also hold other things as well. Unlike a cookie jar, variables in ADRIFT can only hold numbers in the range from -2 to 2. Variables cannot hold text values such as "on". However, you can use the Adrift Language Resource (ALR) file in combination with variables to accomplish just that. To learn more about using ALR files to display text for a variable instead of just numbers, see the ALR Files Tutorial in this ATTS.
So what is the best value to assign a variable? Generally that depends on the purpose of the variable. It also depends on whether or not you are using ALR Files and how you are using them, because variables used in conjunction with ALR Files are used to display text, not numbers.
First, let's consider variables NOT related to ALR Files. These types of variables usually fall into two categories: counting and two-state (boolean) variables. Examples of counting variables are amounts of money, number of objects (such as matches) and the player's score. The initial values of these variables will depend on your game (except for score which always starts at 0). Events in the adventure then determine by what increment and when these variables change.
TWO-STATE variables (also know as boolean variables) will only have two values, each one being the exact opposite of the other, such as On/Off, Open/Close, Start/Stop, Yes/No, and True/False. One value represents the first state, the other value represents the second state ("state" being defined as condition or status). Usually, you should use "0" and "1" for these types of variables. The "0" should normally represent Off, Closed and False indications, and "1" should represent On, Open and True. This is a typical programming convention easily illustrated by your computer's power button. You may have noticed that power buttons on computers are generally marked with "0/1" somewhere on or above the power button. This represents Off/On. This stems from the fact the computer uses a language derived from a single piece of information called a "bit". This bit is either turned on (value of 1) or turned off (value of 0). Varying sequences of these on/off bits makes up the language which operates your computer. Using this convention in assigning variables to your two-state variables is a good standard to adhere to because it is widely accepted and understood.
What about variables used with ALR Files? The value you assign to variables used in this way is very important and depends entirely on how you choose to setup your ALR Files. Please see the ALR File Tutorial to get a better understanding of what values to use for these types of variables. It is important to note that the convention for assigning values to two-state variables (discussed above) would still be applicable to ALR variables as the text to be displayed would still represent one of two states: "open", "off", "yes", etc.
There are only two ways to set the value of a variable: by setting the initial value when the variable is first created, and by changing the value in a Task Action. Normally, the initial value is never changed (unless you decide later that you want to start off with something different). So we will concentrate on changing the value of a variable in a task.
To illustrate, we'll change a variable representing the color of a wall. Let's assume that we want the player to be able to paint the wall from white to red. We need a variable "WallColor" with an initial value of "0" (which in this case stands for white). Just for the record, you can set the values representing red and white to any number you want (such as 2000 and 2001). I am using 0 and 1 solely for illustrative purposes. Also, for this illustration, you don't have to create an object "wall", whereas in your actual adventure you may want to.
Now create a task for painting the wall (such as "paint wall"). With the "Edit a Task" dialog box open, select the Actions tab. Click the Add button and select "Change Variable" for Type of Action. The rest should read "Change WallColor to exact value 1". Now, select the Description tab, select "All Rooms" and give the task a description such as "You paint the wall cherry red".
When the player types "paint wall", the task will change the value of WallColor from "0" to "1". This variable can then be used with an ALR File to change the value "1" to the text "red" which can be displayed in a description of a "wall" object if you have created one.
To get even more complex you could have two tasks for "paint wall". One task would have a Task Restriction requiring the value of WallColor to be "0" and a Task Action changing the value to "1". The other task would be just the opposite. Now, every time the player types "paint wall", the color changes back and forth from white to red, endlessly.
Changing a value to a specific number is not the only way to change a variable. You can also increment and decrement (increase or decrease) the value of a variable by a certain number. To accomplish this, instead of selecting "Change
So far, this tutorial has covered changing a variable TO a specific value and increasing a variable BY a specific value. However, you may want the value you assign to a variable to be a random number. This can be accomplished two ways, both of which are found on the Actions tab of the "Edit a Task" dialog box (displayed whenever you create or edit a task).
The two ways are changing the value TO a random value between X and Y, and changing the value BY a random value between X and Y (where X and Y represent the beginning and ending of a range of numbers, such as "1" to "100"). It is very important to note the difference between changing the variable TO a random value and changing it BY a random value.
Changing the variable TO a random value between X and Y means that the END RESULT will always be a number in the range between X and Y. So if X is "1" and Y is "100", then the variable will always be a number between 1 and 100.
Changing the variable BY a random value between X and Y means that the END RESULT will have a random number between X and Y ADDED to, or SUBTRACTED from, the previous value. Assuming that the original value of the variable is "500", and X is "-50" and Y is "50", then the END RESULT will be 500 PLUS or MINUS some number between -50 and 50.
If you confuse these two ways of generating random values in variables, then your adventure will almost always have unexpected results.
Variables have two primary purposes in ADRIFT:
1. To determine what is going to happen in the game at a specific time. Variables provide a basic way of setting up if-then scenarios (if the door is open, then let the player enter the room). Generally, these are in the form of Task Restrictions, which determine whether or not a specific task can be accomplished based on the value of the variable. See the next section, Using Variables in Tasks, for more information.
2. To change what is displayed in a description. Most items in ADRIFT are limited to a single description. But realistically, a description often changes based on what's happening in the adventure. Variables are a great resource to use when a certain part of a description, or all of the description, changes based on the value of a variable at a given moment.
To illustrate variables in descriptions, let's say you have a variable called "NumCoins" to represent how many coins you have in your pocket. You then give the object "coins" the following description:
There are %NumCoins% gold coins emblazened with the image of Ceasar.
Initially, when the player types "look coins" he will get the description "There are 20 gold coins emblazoned with the image of Caesar." But later, the player is going to spend some of his coins, and when he does, the value of the NumCoins variable will be decreased to 10. Now, when the player types "look coins", the description will change to "There are 10 coins emblazoned with the image of Caesar."
Using Variables in Tasks
Probably the most common place to use a variable is in a task. There will be many times in an adventure where the character will or will not be allowed to perform a task based upon the completion of another task first. In programming of any kind, this is called an IF-THEN statement or scenario. The most common example of this in Interactive Fiction is opening a door before you can enter a room. ADRIFT already has a built in feature for objects that can be open or closed. However, you can also use a variable to indicate whether something is open or closed. Additionally, ADRIFT's built in feature does not allow as much control over open/closed scenarios as when using variables.
As an example, let's create a room with a single exit to the north. Also to the north is a door, blocking the exit. Instead of creating an object for the door, we are going to create three tasks and a variable. The variable will be named "DoorStatus" and the initial value will be "0". For our purposes, "0" will mean the door is closed and "1" will represent the door being open. Now we'll create the first two tasks, one for opening the door and one for closing the door. In each task, you will use the DoorStatus variable. For the "open door" task you should have a Task Restriction requiring the variable to be "0". Otherwise you should display something like "The door is already open". For this same task, you should set an Action changing the value of DoorStatus to "1". For the "close door" task you want to do just the opposite: set a Task Restriction requiring DoorStatus to be equal to "1" and set an Action changing DoorStatus to "0".
Finally, create a third task to override the default NORTH command. We do this so that we can control whether or not the character is allowed to go north based upon the value of the variable DoorStatus (1 or 0, open or closed). Set a Task Restriction for this task to require the value of DoorStatus to be "1". Otherwise, display the text, "You can't walk through a closed door!".
Of course, there are a couple of additional ways in which you can create a scenario such as this one. But this at least illustrates one of the most simple uses of variables in both Task Restrictions and Task Actions. Notice that all three tasks used the value of the DoorStatus variable to determine whether or not the task could be completed.
ADRIFT has certain variables built into it which you can access and display the values of. These are called System Variables (or References). You cannot change these variables or use them in Task Restrictions (see Examples: System Variables in Task Restrictions), but you can display their values in description fields. A few of the more important System Variables are:
%object%
%character%
%player%
%number%
%score%
%maxscore%
%turns%
To see a list of all the available System Variables and what each of the variables stand for, navigate to the Homepage and select System Variables from the Reference menu.