Preprocessor

Preprocessor

Before the AGS Script compiler is ran, an AGS Preprocessor runs, which will modify the script file before it's passed on for the compiler. Preprocessor has its own set of commands that are listed below. Note that all of them begin with # - that is their signature mark making them easy to spot.

define

#define <name>
#define <name> <value>

#define creates a "macro" with or without a "value". Whenever the defined name is encountered further in script, it will be replaced verbatim by the value that follows. It's somewhat similar to a variable, but has a constant value, has no type and no restrictions, and accepts literally anything: numbers, strings, and even script commands.

There are two common use of macro:

First, as a placeholder in your script which value could be easily changed. For example, if you put this somewhere in the beginning of a script:

#define TINT_COLOR 255, 0, 255

and then use this macro in some function calls like

TintScreen(TINT_COLOR);

the compiler will see this as

TintScreen(255, 0, 255);

Now you may experiment adjusting the macro's value in its declaration, without having to search for actual script commands every time. This may be very convenient if you have multiple experimental values in your game which you are not sure about yet, or one value which is used in many places.

Second common use of macro is a signal used in preprocessor tests, or enabling and disabling parts of script.
For example there's a good practice when a script module author would define their own macro in the module's header, which may be then used to test whether such module is included in game.

This is explained further in a paragraphs about #ifdef and #error keywords.

NOTE: There's a list of macro generated by AGS itself, see Constants for more information.

---

ifdef, ifndef, endif

#ifdef <macro>
// script
#endif

#ifndef <macro>
// script
#endif

#ifdef means "if defined", and it tests if macro of this name exists, and if it is, then the following part of script between #ifdef and #endif will be enabled. If such macro does not exist, then this part of script will be disabled and not compiled at all. It does not at all matter whether macro has a value and what it is.

#ifndef means "if not defined", and it does inverse test: script underneath will be enabled if there's no such macro, and enabled if there is.

---

ifver, ifnver

#ifver <editor-version>
// script
#endif

#ifnver <version>
// script
#endif

#ifver does AGS editor version test. If the version of AGS Editor you are building your game in is at least as high as this number, then the part of the script between #ifver and #endif will be enabled, if it's not then it will be disabled and not compiled at all.

#ifnver does the opposite test: it enables the script if the version of AGS Editor is below the given number.

For example:

#ifver 3.5.0
Display("This script was compiled in AGS 3.5.0 or higher");
#endif

This keyword was introduced primarily to let script module authors to be able to keep different variants of code supported by older and newer versions of AGS. For example, if you were writing a script module, you may need to check which version of AGS the user of your module is using, for example:

#ifver 2.72
// do stuff for 2.72 and above
#endif
#ifnver 2.72
// do stuff for 2.71 and below
#endif

NOTE: This ability was only added in 2.72, so you cannot use the #ifver checks if you want your module to work with earlier versions than this.

IMPORTANT: In practice this keyword is now succeeded by SCRIPT_API_ and SCRIPT_COMPAT_ macros. Because newer versions of AGS Editor may be supporting several versions of Script API, it's recommended to test for these macros using #ifdef instead.

---

error

#error <message>

This command throws a user-defined compilation error if met in an enabled part of script. It's mainly used to detect missing requirements for a script to work.

Suppose you are writing a script module A which depends on another script module B. You let users know that in case they forgot to include module B, so that they get a comprehensible message instead of cryptic "undefined function" and similar errors. Thankfully module B has this macro declared in its header:

#define AWESOME_MODULE

Then you could do this in your module's script:

#ifndef AWESOME_MODULE
#error This script requires "Awesome Module", please include it in the game
#endif

---

region, endregion

#region
  // some code
#endregion

You can wrap a code between lines containing #region and #endregion to create a section used for code folding. In the AGS Editor you can use this to hide sections of your code you don't need to see by using the + button at the left side of the script editor. This is a purely cosmetic feature and has no effect on your script. Hidden script will still compile as usual.

---

Deprecated commands

#sectionstart
#sectionend

These preprocessor commands are long deprecated. They may be met if you import an old script or game project, but they do nothing now and may be safely ignored or deleted.