Fjeronimo's notes

This article requires something to be done: please sort these out and put them in the appropriate places in the Wiki.
You can help by editing it. Please discuss this issue on the talk page.
This article has been tagged since December 2006.

Rescued these from the wayback machine at

This article uses deprecated code/functionalities.
Information in this article may be out of date or just plain wrong!

General Scripting Section

Bitwise operators

Bitwise operators & and | are supported. Therefore, we can implement mask systems (Frederico Jerónimo, 29/12/02).

Imagine you declare the following defines at the beginning of the global script or in the script header:

// Humanoid: 000001b (binary)
#define HUMANOID 1
// Mechanical: 000010b (binary)
#define MECHANICAL 2
// NPC: 000100b (binary)
#define NPC 4
// PLAYABLE: 001000b (binary)
#define PLAYABLE 8 

Now, imagine that you have an NPC named Joe that is also a humanoid. You can hold these two pieces of info in a single variable. For instance:

int type = HUMANOID | NPC;

Later on, you might want to test its type. You can do something like this:

if( (type & HUMANOID) )
   DisplaySpeech(EGO, "I'm humanoid!");
if( (type & MECHANICAL) )
   DisplaySpeech(EGO, "I'm mechanical!");
if( (type & NPC) )
   DisplaySpeech(EGO, "I'm an NPC!");
if( (type & PLAYABLE) )
   DisplaySpeech(EGO, "I'm a playable character!");

This should display "I'm humanoid!", followed by "I'm an NPC!". Notice that we're using the bitwise operator '&' and not the logical operator '&&' in the if statement.

Supported variable types

Variable types officially supported by AGS: int, string, short and char (Frederico Jerónimo, 29/12/02).

The following line defines a short integer variable named (oh the originality!) test_var:

short test_var;


Make sure that everything that is time dependent, uses current game speed as its reference (normally it is 40 loops per second, but it could be different...) (Frederico Jerónimo, 29/12/02)

So, if you want to wait two seconds, do something like this:


Global variables I

Unlike for functions, AGS doesn't automatically export variables defined in the global script to the outside world. You'll have to resort to the 'export' keyword (Frederico Jerónimo, 29/12/02).

For instance, imagine you declare the following var at the _START_ of the global script:

int test_var;

You should add the following line at the _END_ of the global script:

export test_var;

Then, in whatever room you might need this var, add this at the _START_ of the room's script:

import int test_var;

Global variables II

Strings are a special case. If you plan to use global strings you should not use the string data type, but char[] instead. To avoid size problems, I recommend a constant for maximum string size. (Frederico Jerónimo, 20/01/03).

Global header:

#define MAX_STR_SIZE 50

Start of global script:

char global_str[MAX_STR_SIZE];

End of global script:

export global_str;

Now, you should add an import command somewhere in your code:

import char global_str[MAX_STR_SIZE];

Where should you add the previous line? You have two options. Either you add it to the _START_ of _EVERY_ room where this variable will be used or you add it to the script header. If you only plan to use it in a couple of rooms, then the first option is probably better. Otherwise, you should choose the second one (the import command gets included into all global and room scripts).

Function parameters

In AGS, strings are always passed by reference and all other variable types are passed as value in functions. What this means, is that if you pass a string to a function and modify it inside the function, the changes will be reflected after the function returns. For the other variable types, this doesn't happen, as a copy of the variable is created and it is that copy that is modified, leaving the original intact. (Scorpiorus, 05/01/03):

If you add this function:

// Performs some dummy operations. The string will be modified when the function
//returns, whereas the integer variable will remain untouched
function paramTest(string strTest, int intTest)
   intTest += 7;
   StrCopy(strTest, "Modified string");

And type this code somewhere:

// Setup a test string and test integer
string strTest;
StrCopy(strTest, "Initial string");
int intTest = 3;
// Print out initial values: "Initial string" for the string var
// and 3 for the integer var
string result;
StrFormat(result, "Before: %s, %d", strTest, intTest);
DisplaySpeech(EGO, result);
// Call our dummy function
paramTest(strTest, intTest);
// Print out final values: "Modified string" for the string var
// and 3 for the integer var
StrFormat(result, "After: %s, %d", strTest, intTest);
DisplaySpeech(EGO, result);

You'll see that the string was modified (passed by reference), whereas the integer stayed the same (passed by value).

Graphics Section

Transparent color

Transparent color for sprites in high-color (15/16 bits) is bright pink: RGB (255,0,255). In 256 color mode (8-bit), palette index 0 holds the transparent color (Frederico Jerónimo, 29/12/02).

Sprite's size

It seems we can have sprites of any size. Keep in mind performance issues, though... In other words, watch out for that 640x400 sprite behind you! (Frederico Jerónimo, 29/12/02).


Hotspots in AGS vary according to the type of entity considered. When dealing with characters, the sprite's hotspot is located in the bottom-center. However, with objects, the hotspot is located in the bottom-left corner. Finally, in allegro, it is located in the top-left corner (Cornjob, 05/01/03).

In short, the various hotspots are:

  • allegro/raw image - top-left corner
  • character - bottom-center corner
  • object - bottom-left corner

Input Section

Room and screen coordinates

Independently of the screen resolution the game is running on, the mouse horizontal x-coordinates (mouse.x) always range from 0-319 and the mouse vertical y-coordinates (mouse.y) always range from 0-199. These are called room coordinates, as opposed to screen coordinates which range between zero and actual width or height of the current resolution (Frederico Jerónimo, 29/12/02).

For instance, if you're running the game at 640x400 and if the mouse.x equals 210 and mouse.y equals 27 at one given moment, the room coordinates are (210, 27) and the screen coordinates are (420, 54).

Technical Information Section


AGS imposes the following limits, as of version 2.52 (Frederico Jerónimo, 29/12/02):

  • 10 objects per room
  • 100 messages per room
  • 500 global messages
  • 299 rooms per game
  • 300 inventory items
  • 6000 imported sprites
  • 240 sprites per folder
  • 16 loops per view
  • 20 frames in each loop
  • 150 characters
  • 20 GUIs
  • 30 controls on each GUI
  • 150 total GUI controls of each type
  • 200 dialog topics
  • 2000 dialog-script messages
  • 30 options per topic
  • 8 screen overlays at a time
  • 300 text script GlobalInts
  • 100 interaction editor global variables
  • 5 background frames per room
  • 10 mouse cursors


Here's what you can delete in AGS and how - Be careful with what you delete!(Dorcan, 20/01/03):

  • Rooms (by deleteing the file Room*.crm)
  • Sprites (with [delete] )
  • Loops (by clicking on "Delete last loop")
  • Messages (by editing the message and deleting his content)
  • GUI BUTTONS (by selecting them and pressing [delete])
  • Dialogs (by replacing with a blank file)
  • Objects (by right-clicking them)
  • Hotspot, walk-behind, walkable area (by filling them with color 0)
  • Interactions (right-click, "delete this action")

Plugin Section

Color depth in AGS_EngineStartup

When the AGS_EngineStartup() function is called, there's no information available concerning color depth yet. Therefore, if you call getScreenDimensions(), the color depth will return as 0 (Frederico Jerónimo, 29/12/02).

Allegro sprite's scaling

When you use sprites made for 320x200 resolution in a 640x400 resolution game, the width and height get scaled by two and this is reflected in the w and h fields of the Allegro BITMAP struct (Frederico Jerónimo, 29/12/02).

Allegro color conversion

Use Allegro's makeCol# family of functions to convert from high-color to 8-bit color (and vice-versa) (Frederico Jerónimo, 29/12/02).

If you're running your game in 256 colors (8-bit) mode, you could store that reddish color as:

// Store 8-bit color value for color with RGB (234, 5, 2)
int StrongRed_8 = makecol8 (234, 5, 2);

The same color in 16-bit glory:

// Store 16-bit color value for color with RGB (234, 5, 2)
int strongRed_16 = makecol16(234, 5, 2);

Allegro pixel plotting

Instead of using GetRawBitmapSurface() to obtain a reference to the linear memory where the bitmap is stored and then manually plot the coordinates using the conventional (x + y * width) formula, you can opt to use allegro's getPixel and setPixel routines that accept relative coordinates (x,y) from the top-left corner of the image (Frederico Jerónimo, 29/12/02).

If you want to get get the pixel color at relative coordinates (20, 10) of the sprite located in slot 7, you can choose to do it like this:

// Obtain bitmap associated with sprite slot 7
spriteBitmap = engine->GetSpriteGraphic (7);
// Assuming we're working in high-color (15/16 bits), we need to cast
// the result to unsigned short
unsigned short **spriteMemRef = (unsigned short **)engine->GetRawBitmapSurface (spriteBitmap);
// Obtain pixel color at coordinates (20,10)
unsigned short color = spriteMemRef[10][20];

or like this:

unsigned short color = getpixel(engine->GetSpriteGraphic(7), 20, 10);

Variable types

You can use whatever C/C++ compatible data types you might require in your plugins, but keep in mind the variable types officially supported by AGS when creating function parameters or return variables (Scorpiorus, 05/01/03)

Equivalency between AGS and C:

  • AGS int <=> C int32 [32bit] Range: -2147483648..2147483647
  • AGS short <=> C signed short int [16bit] Range: -32768..32767
  • AGS char <=> C unsigned char [8bit] Range: 0..255
  • AGS string <=> A reference to array of char with preallocated 200 bytes

Utilities Section


So, you need to keep track on how much time has elapsed since the beginning of your game, or perhaps you're interested in displaying the current system time. Worry not, you've come to the right place. (Spyros, 20/01/03):

Playing Time Clock

Declare the following integers at the start of the global script:

int timer=0, sec=0, min=0, hours=0;

Then add the following function to the global script:

function updateTime()
   if (timer >= GetGameSpeed())
       if (sec >= 60)
           if (min>=60)

Don't forget to call this function every frame (in repeatedly_execute() for instance):

function repeatedly_execute()
  // [...]
  // [...]

Finally, display the integers on a GUI (hours : min : sec).

Real Time Clock

This one is pretty easy. Just add this line somewhere in your code:

Display ("The time is %d, %d minutes and %d seconds", GetTime(1), GetTime(2),GetTime(3));