Constants - adventuregamestudio/ags-manual GitHub Wiki
Constants
The following predefined macros and constants are available in your scripts:
| Name | Description |
|---|---|
| DEBUG | Defined if the game is being compiled in debug mode, not defined otherwise |
| UNICODE | Defined if the game is being saved in Unicode text format. |
| SCRIPT_API_vXXX | Defined if corresponding version of script API is enabled (see the list) |
| SCRIPT_COMPAT_vXXX | Defined if certain compatibility level is enabled (see the list) |
| STRICT | Defined if "Enforce Object Based Scripting" is enabled, not defined otherwise |
| STRICT_STRINGS | Defined if "Enforce new-style strings" is enabled, not defined otherwise |
| STRICT_AUDIO | Defined if "Enforce new-style audio scripting" is enabled, not defined otherwise |
| LRPRECEDENCE | Defined if "Left-to-right operator precedence" is enabled, not defined otherwise |
| AGS_NEW_STRINGS | Defined if AGS 2.71 or later (with new-String support), not defined otherwise |
| NEW_DIALOGOPTS_API | Defined if "Use old-style dialog options rendering API" is disabled |
| NEW_KEYINPUT_API | Defined if "Use old-style key handling" is disabled |
| AGS_SUPPORTS_IFVER | Defined if AGS 2.72 or later (with #ifver support), not defined otherwise |
| AGS_MAX_INV_ITEMS | The maximum number of inventory items |
| AGS_MAX_OBJECTS | The maximum objects per room |
| AGS_MAX_HOTSPOTS | The maximum hotspots per room |
| AGS_MAX_REGIONS | The maximum regions per room |
| MAX_LISTBOX_SAVED_GAMES | Limit of save files filled into ListBox when using FillSaveGameList |
| PALETTE_SIZE | Size of game palette, for 256-color mode |
| SCR_NO_VALUE | Used as a parameter by some functions to specify "no value" or "use default value" |
You can check for whether a macro is defined or not by using the
#ifdef and #ifndef keywords:
#ifndef STRICT
// only compile the MoveCharacter command if not using object-based scripting
MoveCharacter(EGO, 30, 40);
#endif
#ifdef DEBUG
// only display this when the game is compiled in debug mode
Display("Debugging information");
#endif
There is also an #error directive you can use to stop the script
compiling:
#ifndef AGS_NEW_STRINGS
#error This script requires at least AGS 2.71
#endif
If you'd like to know if a new API is available, test for the corresponding SCRIPT_API_vXXX constant:
#ifdef SCRIPT_API_v360
// can use new code added in 3.6.0
#endif
If on contrary you need to know if a deprecated API is enabled, test for the corresponding SCRIPT_COMPAT_vXXX constant:
#ifdef SCRIPT_COMPAT_v320
// can use old code, deprecated after 3.2.0
#endif
The other constants AGS_MAX_* are useful if you are writing some
script code that you want to be portable to different versions of AGS,
and to pick up the limits from the user's AGS version. For example, if
you wanted to store some extra information on all the inventory items,
you could do:
int invWeights[AGS_MAX_INV_ITEMS];
To get the actual number of things in the game rather than the AGS
limit, use the
Game.CharacterCount-style properties.
Script API levels
Following is the list of supported values for SCRIPT_API_vXXX and SCRIPT_COMPAT_vXXX. Normally they are called after the main 3-digit version (e.g. SCRIPT_API_v350), but some refer to a later update (e.g. SCRIPT_API_v3507). Some versions of AGS do not have any distinct API level, because there were no additions or changes to script API in them.
| API version | API level | Compatibility level |
|---|---|---|
| 3.3.0 | SCRIPT_API_v330 | SCRIPT_COMPAT_v330 |
| 3.3.4 | SCRIPT_API_v334 | SCRIPT_COMPAT_v334 |
| 3.3.5 | SCRIPT_API_v335 | SCRIPT_COMPAT_v335 |
| 3.4.0 | SCRIPT_API_v340 | SCRIPT_COMPAT_v340 |
| 3.4.1 | SCRIPT_API_v341 | SCRIPT_COMPAT_v341 |
| 3.5.0 Alpha | SCRIPT_API_v350 | SCRIPT_COMPAT_v350 |
| 3.5.0 Final | SCRIPT_API_v3507 | SCRIPT_COMPAT_v3507 |
| 3.5.1 | SCRIPT_API_v351 | SCRIPT_COMPAT_v351 |
| 3.6.0 Alpha | SCRIPT_API_v360 | SCRIPT_COMPAT_v360 |
| 3.6.0 Final | SCRIPT_API_v36026 | SCRIPT_COMPAT_v36026 |
| 3.6.1 | SCRIPT_API_v361 | SCRIPT_COMPAT_v361 |