AGI Docs - Defines

Tutorials and Guides Table of Contents

Defines
By Peter Kelly

 

In order to give variables, flags and other things meaningful names, the #define command is used, like this:

#define light_on f150

This defines light_on as flag 150. Every time the compiler encounters "light_on" in the source code, it will treat it as "f150". It is a good idea to do this for all variables and flags that you use to make your code easier to understand when you (or someone else) reads it later.

One thing to be careful of, however, is defining two things to the same flag or variable. If you define both light_on and player_in_bed to flag 150, some confusion could be caused when the player turns the light on after getting out of bed, and then tries to get the paper from the table and is told "You can't reach that from your bed!". This would occur because the game resets player_in_bed when they get out, but sets light_on when they turn on the light so as far as the game is concerned the player is still in bed (as flag 150 is set).

It is generally a good idea to put all the defines in a logic together, near the top. Define names aren't supposed to be able to be used until after they have been defined, and it is also easier to see what you have defined this way.

 

Using a define in more than one logic

Sometimes you will encounter a situation when you want to use a define in more than one logic. For example, you might have "money" defined as "v94". You may then want to use it in say, room 4 which is a casino, room 5 which is a shop and room 7 which contains a vending machine. You could put the command "#define money v94" in each of these logics, but then if for some reason you want to change what money is defined as (perhaps you found out that you were already using v94 for something else and want to use v95 instead), you would have to go to each of the logics and change it. And if you later decide to put an arcade machine (that accepts coins) in room 12, you would add the define there.

There is a more efficient way of doing this - and that is putting the define in an include file. You can use the #include command to include another file in your logic, like this:

#include "defines.txt"

If the compiler sees this line when it is compiling, it will replace the line with the contents of the specified file.

If you put the define in the file defines.txt, then any logics which use the above command will be able to use that define. All logics should generally include a file like this.

The only drawback to this technique is that if you modify a define that is in an included file, then you need to recompile all logics that use that particular define. In the future I intend to modify AGI Studio so that it will allow you to recompile all logics in the game, which could solve this problem. But if you are careful to pick the right values for defines in the first place, this should not be needed. Below is some advice to help you with this.

 

Deciding which variables and flags to use

When you need to use a variable or flag for something, it is sometimes difficult to decide which number to pick. It may be that you choose a variable number that is used for something else in the game, which can cause a conflict. You've read above the problems that can be caused by having two define names pointing to the same thing.

The method I use to get around this hassle is quite simple. I treat variables and flags from 30 to 199 as global (i.e. can be used anywhere in the game). Whenever I am going to use one of these, I define it in defines.txt (which I make sure is included in all logics). Since all these are together, I can easily make sure that nothing is defined twice.

I treat variables and flags from 200 to 240 as local (can only be used in the one room). These are defined in the room's logic, and set up in the initialization section of the logic - i.e. all the local variables I'm using are set to 0 and all the local flags I'm using are reset (or whatever I need their initial state to be for that room). For example, if the player starts off in that room in bed with the light off, I would put the following commands in the initialization section:

set(player_in_bed);
reset(light_on);

This is done because the flags might be set differently from the previous logic. As with the global variables/flags, I group the defines together (at the top) so I can see if there are any duplicate defines.

Variables and flags from 241 to 255 I leave for temporary usage, and don't bother defining. For example, there are some commands like step.time that take a variable as a parameter even when you usually want to give it a specific number. So I use something like this:

v255 = 3;
step.time(clouds,v255);

I do not use variables and flags under 30 except for the ones with special meaning to the interpreter - variables 0-26 and flags 0-15. It's possible there may be a few more of these which is why I start from 30.

 

Tutorials and Guides Table of Contents

< Previous: Data Used by AGINext: Basic Structure of a Room >