Scripting, Code & Interaction

Working with variables: the basics

I need help with variables. What I am doing doesn't seem to be working. What do I do?

One of AGS's main advantages is its ability to use variables. A variale is an area of memory storage that contains a value, which you can check and change with scripting. Variables are very powerful and useful things in programming languages. If you have an RPG-style stat system in place, you can use variables to store information such as health, magic, strength, etc. You can name variables anything you'd like, as long as they're not names of functions, AGS commands, or already-declared variables, like EGO or a GUI name.

Due to AGS's emulation of the 'C' language, variable scope must also be considered. If a variable will be used throughout the entire game, it will have 'global' scope. If it to be used only in a single room, its scope will be limited to that room.

There are three major steps to using custom variables.

Step 1. If the variable will have global scope (such as health, money, etc.), go to the global script. If the variable will have room scope (such as light_is_on or guard_random_state), go to the room's main script (the button with the braces - { }). Then, at the very beginning before any functions, declare and set the variable, using the following syntax:

 vartype varname;
 varname = value;

OR

 vartype varname = value;

vartype can be string (for strings of alphanumeric text, it's advisible to use the new String type if you're using AGS V2.71 or above), int (for whole numbers), or float (for decimal numbers, supported from AGS V2.7 onwards). An example of an int declaration would be:

 int health;
 health = 100;

OR

 int health = 100;

Initially, an int variable will have a default value of zero (0). Therefore, if a variable starts off with '0' as its value, you do not need to assign a value like above.

A string would be declared and set like so:

 string myname;
 StrCopy(myname,"Richard");

OR, from V2.71 onwards:

 String mynewname = "Richard";

If you're using V2.7 or earlier, you may NOT use direct assignment of string. In other words, you CANNOT use the code myname="Richard"; as this will cause an error with AGS. Use the above code to correctly assign strings to string variables.

If you are using global variables you must do the following.

Step 2. At the end of the global script (or just after all the variable declarations), you must export any and all variables you create, like so:

 export health;
 export myname;

Step 3. For any and all global variables (whether int, string, String or float), you must import them into all rooms in which they will be used. So, in each and every room where you will be using global variables, go into the room's main script (the { } button), and at the very top -- before anything else -- import the variable(s) like so:

 import int health;
 import string myname;

The last two steps are necessary with global variables. Remember! ONLY the import command requires the data type as well as the variable name. The export command ONLY needs the variable name.

Running regular code outside dialog

I need to run some code in my dialog script that isn't in the form of a dialog command! I suppose I need to run regular AGS script from within the dialog script. What do I do?

Well, there's this little thing called run-script X. First off, create (or edit, if it's there already) a function within the global script called dialog_request (int X). You can name X whatever you'd like, as it really doesn't matter. Next, inside that function, you will check to see what value X is. When you run the run-script X command, whatever is in place of the variable X will be passed along to the dialog_request function. So, you must then check the value of the integer variable within the dialog_request function, so that the right script will be called. Let's say that "run-script 4" was called. Within the dialog_request function, there will be a set of if...else if...else if... commands. When it comes around to cheecking to see if the variable passed was 4, then whatever is put down afterward until the next "else if" command will run.

Here is an example to get you started. If, in the dialog script, you had the command run-script 5, you would need the following in your Global Script...

 function dialog_request(int blorg) {
   if (blorg==1) {
     // Put whatever goes here if "run-script 1" is run
   } else if (blorg==2) {
     // Put whatever goes here if "run-script 2" is run
   } else if (blorg==3) {
     // Put whatever goes here if "run-script 3" is run
   } else if (blorg==4) {
     // Put whatever goes here if "run-script 4" is run
   } else if (blorg==5) {
     // BINGO! This code will be run when "run-script 5" is called
   }
 }

Do you see now? When the function dialog_request() is run, with "5" being passed as the only parameter, only the right code will run, because you added an "if/else if" check within the function. This way, only that code will run if "5" was passed as the parameter.

Get it? Got it? Good! :)

Placing your code: more basics

I'm new to this scripting thing. (It's okay, we all gotta start somewhere!) Where exactly would I put code to move a character around or add an inventory item?

First, you need to think of where and when you want this to happen. Do you want this to happen the minute the game starts, before any rooms are loaded? If so, edit the global script (Game -> Edit global script..., or Ctrl-G) and find the definiton for the "game_start" function. It will probably look like:

 function game_start() {

Between the braces ( { } ), insert your code that will run the second the game loads. Do not put animation code there, as no characters have yet been drawn at that point. Only run animations when a room is loaded, and usually only after fade-in.

For things that you want to happen every time a room is loaded, choose that room in the Rooms pane and, under Room/Settings, Choose the “i” button. You will see a list of events that you can use to trigger certain events. If you don't want to use code, most functions and commands are available as interaction commands. Simply double-click the event you wish to use, OR right-click and choose Add action.... Then, in the drop-down list box, choose what you want to have happen. Note: You can indeed have more than one command running when that event occurs. They will run one after the other.

For example, if you want the player to walk to a certain location after the room is loaded (each and every time), double-click on the Player enters room (after fade-in) event. You want after fade-in, because you won't see any animations or anything at all before the room fades in. Now, select the Character - Move character command, and choose the parameters below the drop-down box.

As you get to know AGS a little better, you will see that there are many interactions... some for inventory items, objects, hotspots, even characters!