AGS Plugin API

AGS supports two different types of plugins - plain API plugins, for writing plugins that add extra functionality to games and need to be included with the games at runtime; and .NET plugins, for enhancing the editor. Editor .NET plugins are explained on this separate page; here we will continue talking about the plain API.

First, a few important notes about the plugin API. It's essential that you read these before even considering writing a plugin.

AGS is written with MS Visual C++, and uses the Allegro library for its multimedia output. Allegro is, among other things, a wrapper for DirectDraw.
Only VC++ plugins are currently supported. You can try writing one using another language or compiler, but I will not support it in any way. So far, AGS plugins have successfully been written in C++ and Delphi.
You can use Allegro yourself in the plugin, but if you do so you must use the SYSTEM_NONE driver when you initialize it, and you must NOT install the graphics, sound, timer, and so on. There are further limitations, such as you cannot draw on the screen bitmap. You must use Allegro 4.x, to ensure the binary compatibility of the data structures.
Your other options for graphical effects are to use DirectDraw directly, or use the interface functions provided by AGS to do any graphical work required.
Plugins are non-portable. This means that if you write a plugin, you will not be able to compile a DOS version of any game that uses the plugin.

Now, if you want to continue, on to the technical details.

AGS plugins are implemented as Windows DLL files, which must have filenames beginning with "AGS". Therefore, you will need to create your plugin as a standard Windows DLL project. When the editor starts up, it reads through all the AGS*.DLL files in the editor directory, and adds them to its plugin list.

The plugin can be started in two modes - design-time and run-time. Design-time mode is used when the plugin is loaded by the AGS Editor, and Run-time mode is used when the game is actually run.

Downloadable template files:

C++ template source files here. (21 KB)
Delphi port (now out of date) courtesy of a-v-o.

Your DLL should have the following entry points:

DllMain

The standard Windows DLL entry point, you know how to use this.
This will get called once when the editor first starts up, and once when it finally shuts down. The plugins are kept in memory at all times, so you will not get lots of load-unloads during the editor's lifetime.

Design-time events

DLLEXPORT LPCSTR AGS_GetPluginName ();

Called by the editor to retrieve a user-friendly name for the plugin. This is the very first function the editor calls as soon as it starts up, in order to build its list of plugins.
Normally, you will implement this as a simple one-line function that returns a static string with the plugin description.

DLLEXPORT int AGS_EditorStartup (IAGSEditor *lpEditor);

Called by the editor when the user selects to add the plugin to their game. This function should perform any initialization necessary for design-time operation.
The parameter passed to the function is a pointer to the editor interface, which your plugin can execute various methods on to communicate with the editor.
In particular, this function should register any additions to the script header files that it uses.

You should return 0 to indicate success; any other value indicates that a problem occured, and the editor will not attempt any further communication with the plugin unless the user tries to start it again.

DLLEXPORT void AGS_EditorShutdown ();

Called by the editor when the user elects to remove the plugin from their game. The plugin should un-register anything that it registered at startup, since if the user later decides to add the plugin again, the Startup function will be run again.

DLLEXPORT void AGS_EditorProperties (HWND parent);

(Optional - plugin does not have to have this function)

Called by the editor when the user highlights the plugin and clicks the Properties button. You can use this to display a copyright message, or allow the user to set options for your plugin, for instance. This will only be called when the plugin is selected (ie. EditorStartup has been called).
The parameter gives you the parent window handle you should use if you want to pop up a dialog. You should make any dialogs modal so that this function does not return until they are dismissed.

DLLEXPORT int AGS_EditorSaveGame (char *buffer, int bufsize);

(Optional - plugin does not have to have this function)

Called by the editor when the current game is saved to disk. This will only be called if your plugin is selected into the current game.

buffer is a byte array of size bufsize, which you can write any data to as you see fit. The buffer will then be written into the user's game file. You must return the number of bytes actually used, which can be up to and including bufsize.

If you need more storage space than bufsize provides, you will have to write your own seperate file out to disk, store in the registry, or do some compression.

The current version of AGS gives you a 5120 byte buffer, but future versions may increase or decrease this amount, so be sure to check bufsize before using it.

You will probably only need this function if you have some options in the Properties that the user can set, otherwise there's no need to use it.

DLLEXPORT void AGS_EditorLoadGame (char *buffer, int bufsize);

(Optional - plugin does not have to have this function)

Called by the editor when a game is loaded from disk. This will only be called if your plugin is selected into the new game.

buffer is a byte array of size bufsize, which contains any data you wrote out in a previous session with EditorSaveGame. Note that the buffer is not persistent - when your function returns, the buffer is freed, so you should copy any important data you need to elsewhere.

DLLEXPORT int AGS_PluginV2 ();

This entry point is never called by AGS, but it must be present and exported from your DLL in order to let AGS know that it is a valid plugin that supports version 5 and later of the engine interface. If you don't export this, AGS won't load the plugin.

The IAGSEditor interface

This interface is provided to the plugin as the way of calling back to the editor. It provides these members:

int version;

Specifies the interface version. You should check this to determine what version of the editor is being used, because certain interface methods will have been added in later versions, and attempting to use them with an earlier version will crash the system.
The current version number for the latest version of AGS is 1.

HWND GetEditorHandle ();

Returns the window handle to the AGS Editor's main frame. This might be useful if you wanted to add extra menu options to the editor, for example.

Added in version: 1

HWND GetWindowHandle ();

Returns the window handle to the current active window. If you want to pop up a messagebox, for instance, you should always use this handle as the parent, because using the main frame's handle would un-modal any dialog boxes currently displayed.

Added in version: 1

void RegisterScriptHeader (const char* header);

Adds the contents of header to the built-in script header, which is compiled into every script in the game. The idea here is that you would use this to register your text script functions, for example:

char *header = "import int Add (int, int);\r\n import int Substract(int, int);\r\n"; RegisterScriptHeader (header);

Note that the editor only keeps a reference to this string rather than a copy, so do not overwrite or destroy the string after calling this function.

Added in version: 1

void UnregisterScriptHeader (const char* header);

Unregisters the specified script header, which you earlier used with RegisterScriptHeader.

Added in version: 1

Run-time events

DLLEXPORT void AGS_EngineStartup (IAGSEngine *lpGame);

Called by the game engine when the game is loading. This function is called once AGS has loaded everything it needs to into memory, but before it loads the global script.
Your plugin should use this opportunity to register any text script functions that it provides, and to request hooks for any game events that it wants to handle.

Once this function completes, the plugin will only regain program control when one of its text script functions is called, or when one of the hooks it registered is executed.

This function is called before the graphics subsystem is started, so functions like GetScreenDimensions and GetGraphicsDriverID will not work if called from this event.

DLLEXPORT void AGS_EngineShutdown();

Called by the game engine just before it exits. This gives you a chance to free any memory and do any cleanup that you need to do before the engine shuts down.

(Shutdown is only called by engine interface version 13 and above.)

DLLEXPORT int AGS_EngineOnEvent (int event, int data);

Called by the game engine when one of the events which the plugin has requested via RequestEventHook is triggered.
data is an event-specific parameter - see RequestEventHook below for more information.

Return 0 to tell the engine to continue processing the event as normal. Return 1 to tell the engine not to call any other handlers, whether in other plugins or the text script, for this event.
For example, if you were handling a Keypress event, and you did something in response to the keystroke, you may wish to return 1 to stop anything else also dealing with the keystroke.

Only return 1 when absolutely necessary since it may interfere with other plugins operation.

DLLEXPORT int AGS_EngineDebugHook(const char *scriptName,
                                  int lineNum, int reserved);

Called by the game engine when a new line of text script is about to be executed. This will only be called if you have requested the AGSE_SCRIPTDEBUG event with the RequestEventHook function (see below).

scriptName contains which script is running (either "Global script" or "Room XX script" (where XX is the room number)). lineNum contains the line number that is about to be run.

This callback is designed to allow you to create some form of script debugger using a plugin. Note that just having this hook enabled will cause a performance hit in the game - so if the plugin is not actively debugging, it should use UnregisterEventHook to unregister itself until such time as it needs to know again.

This callback is also called with lineNum set to 0 when a script finishes running.

Return 1 if you handled the debug, or 0 to allow other plugins to have a go.

(Supported by engine interface version 13 and above)

DLLEXPORT int AGS_EngineAudioHook(int channel, char *buffer, 
                       int len, int freq, int bits, int stereo);

Called by the game engine when there is some new digital audio data that is about to be played. This will only be called if you have requested the AGSE_AUDIODECODE event with the RequestEventHook function (see below).

The purpose of this callback is to allow you to dynamically modify the sound output at runtime. However, this function must execute very quickly as it is performance-critical, so do not use complex algorithms here.

channel specifies which AGS Sound Channel number the sound is on. buffer is the raw digital output buffer that contains the sound you can modify.

freq specifies the sound's playback frequency, in Hz, should you wish to know it. bits specifies the bits per sample (8 or 16). stereo specifies the number of channels within the sound (1 for mono, 2 for stereo).

len specifies the size of the buffer, in samples. The size of each sample can be anywhere from 1 byte (8-bit mono) to 4 bytes (16-bit stereo), so make sure you check before accessing too far into the array.

This callback only works with digital soundtracks (ie. WAV, MP3, OGG). It will not be called with MIDI or MOD/XM sound.

(Supported by engine interface version 13 and above)

The IAGSEngine interface

This interface is provided to the plugin as the way of calling back to the editor. It provides the following methods.

Very little error checking is performed on these functions for performance reasons, as they provide direct entry into AGS - therefore, mistakes in your code can crash the engine.

The text script currently supports char, short and int types. These are 1, 2 and 4 byte integers respectively. Text script strings are implemented as standard C-style char* pointers, but with preallocated buffers of 200 bytes per string. Therefore, if you write a function which takes a string from the text script, make sure that if you add anything to it you don't write past 200 characters, or problems will result.

int version;

Specifies the interface version. You should check this to determine what version of the engine is being used, because certain interface methods will have been added in later versions, and attempting to use them with an earlier version will crash the system.
AGS v2.51 (the first version to support plugins) was distributed with interface version 7, so you can reasonably expect that as a minimum for your plugin.

void AbortGame (const char* reason);

Aborts the game, presenting the standard AGS "An error has occured, please correct the problem" message box to the user, with the error description being the string supplied.
To indicate that it was a user error (for example, they provided an invalid parameter to your text script function), prepend a ! to the message. For example,
AbortGame ("!MyScriptFunction: Not a valid colour");This will use the "Please contact the game author for support" heading message.

If you need to exit the game, you should always use this instead of the standard VC++ exit() functions.

Added in version: 1

const char* GetEngineVersion ();

Returns the full build number of the engine, for example "2.51.400". You can use this with strcmp if your plugin requires a specific engine version.

Added in version: 1

void RegisterScriptFunction (const char *name, void *address);

Allows you to add your own text script functions to AGS. name is the name of the function as the script knows it, for example "AddNumbers". address is a pointer to your function that implements the command. For example:

int AddNumbers (int a, int b) { return a + b; } ... RegisterScriptFunction ("AddNumbers", AddNumbers);

Note that it is possible to override the built-in functions with this command. If you do, for example,
RegisterScriptFunction ("GetLocationType", AddNumbers);
then any calls from the script to GetLocationType will be intercepted by your plugin (and in this case a stupid result returned).

If you want to override built-in functions, make sure that yours have identical parameters, otherwise the stack could get messed up and crash the engine.

AGS 2.7 and later support object-based scripting. In order to export an object from your plugin, you'll need to include its struct definition in the RegisterScriptHeader editor call. Then, you export functions as follows:

int PluginObject_DoSomething(PluginObject *obj, int a) { return a + 10; } ... RegisterScriptFunction("PluginObject::DoSomething^1", PluginObject_DoSomething);

In other words, the function takes the object as its first parameter. The exported name is structname::functionname^numparams, where numparams is the number of parameters it takes (excluding the object itself).

Added in version: 1

HWND GetWindowHandle ();

Returns the window handle of the main game window.

Added in version: 1

const char* GetGraphicsDriverID();

Returns an ID string representing the current graphics driver. This can either be "D3D9" if the player is using the Direct3D driver, or "DX5" if they are using the standard DirectDraw driver.

If the engine interface version is less than 19, this function is not available; however, in that case you can safely assume that the DX5 driver is in use since earlier versions of AGS only supported that driver.

Your AGS_EngineStartup event is called before the graphics system is initialized. Therefore, you cannot call GetGraphicsDriverID from within AGS_EngineStartup as no driver is loaded at that point.

When the Direct3D driver is in use, the screen is redrawn each frame using 3D accelerated blits, and therefore there is no virtual screen. You can only manipulate the virtual screen when running with the DX5 driver.

Added in version: 19

LPDIRECTDRAW2 GetDirectDraw2 ();

Returns the main IDirectDraw2 interface that the game is using.

This function is only supported if the player is using the DX5 graphics driver.

Added in version: 1

LPDIRECTDRAWSURFACE2 GetBitmapSurface (BITMAP *bmp);

Returns the IDirectDrawSurface2 interface associated with the specified bitmap.

This function is only supported if the player is using the DX5 graphics driver.

This is the Allegro BITMAP structure, not the Win32 GDI BITMAP. Do not try and use a win32 BITMAP with this function, as it will crash the system.

Added in version: 1

BITMAP * GetScreen ();

Returns a reference to the main screen bitmap (as an Allegro BITMAP). You can use this via DDraw with the GetBitmapSurface method, or use the various AGS drawing functions which are documented later.

This function is only supported if the player is using the DX5 graphics driver.

Added in version: 1

void RequestEventHook (int event);

Requests that the engine calls the plugin's AGS_EngineOnEvent function when the specified event occurs in future. Possible values are:

event description data value

AGSE_KEYPRESS triggered when the user presses a key on the keyboard ASCII value of keystroke, as text script on_key_press

AGSE_MOUSECLICK triggered when the user clicks a mouse button mouse button pressed (1=left, 2=right, 3=middle)

AGSE_POSTSCREENDRAW triggered after the virtual screen has been drawn each frame, but before the mouse cursor is painted and it gets copied to the screen
** See Note 1 below

AGSE_PRESCREENDRAW

(version 4 and later only) triggered every frame after the room background has been drawn, but before anything else ** See Note 1 below

AGSE_SAVEGAME

(version 5 and later only) triggered when the game position is saved. You can then use the interface FWrite function to write your own data file handle of save game

AGSE_RESTOREGAME

(version 5 and later only) triggered when the game position is loaded. You then use the FRead function to read the data back. You must read back the same number of bytes as you wrote. file handle of save game

AGSE_PREGUIDRAW

(version 6 and later only) triggered once the screen has been constructed, but before the GUIs have been drawn on.
** See Note 1 below

AGSE_LEAVEROOM

(version 6 and later only) triggered when the player leaves the current room, after the Player Leaves Screen event but before the screen fades out. old room number

AGSE_ENTERROOM

(version 6 and later only) triggered when the player enters a new room, before the screen fades in new room number

AGSE_TRANSITIONOUT

(version 6 and later only) triggered when the screen is about to fade out as the player changes rooms. If you return 1, AGS will not perform its screen transition. (unused, currently 0)

AGSE_TRANSITIONIN

(version 6 and later only) triggered when the screen is about to fade in as the player changes rooms. If you return 1, AGS will not perform its screen transition.
(unused, currently 0)

AGSE_FINALSCREENDRAW

(version 12 and later only) triggered each frame after the mouse cursor is painted and immediately before the virtual screen is copied to the screen. ** See Note 1 below

AGSE_TRANSLATETEXT

(version 12 and later only) triggered whenever there is some in-game text that might need translating. If you return 0, AGS will translate it as usual; otherwise, you can return a char* pointer with the replacement text (the return pointer must point to some static memory since AGS does not take a copy) the text to translate (cast this parameter to const char*)

AGSE_SCRIPTDEBUG

(version 13 and later only) triggers the AGS_ EngineDebugHook function every time the game script advances to a new line. N/A

AGSE_SPRITELOAD

(version 18 and later only) triggered whenever a sprite is loaded into memory. This allows you to modify sprites as soon as they are loaded into the sprite cache. Do not attempt to access any other sprites from this event, since the sprite cache may be in an inconsistent state. sprite number

AGSE_PRERENDER

(version 21 and later only) triggered every frame after the game logic has run but before anything is rendered to the pre-screen sprite cache
(unused, currently 0)

Each frame (or game loop), AGS redraws the screen from scratch. The sequence is as follows:

DX5 driver

Call AGSE_PRERENDER

Update in-memory cache of current character and object images

Draw current background scene

Call AGSE_PRESCREENDRAW

Draw cached objects and characters

Call AGSE_PREGUIDRAW

Draw screen overlays

Draw GUIs

Call AGSE_POSTSCREENDRAW

Draw mouse cursor and finalize.

Call AGSE_FINALSCREENDRAW

Paste the virtual screen to the real screen.

D3D9 driver

Call AGSE_PRERENDER

Update in-memory cache of current character and object images

Direct3DDevice9->BeginScene

Draw current background scene

Call AGSE_PRESCREENDRAW

Draw cached objects and characters

Call AGSE_PREGUIDRAW

Draw screen overlays

Draw GUIs

Call AGSE_POSTSCREENDRAW

Draw mouse cursor and finalize.

Call AGSE_FINALSCREENDRAW

Direct3DDevice9->EndScene

** Note 1: The data parameter to these events is 0 when using the DX5 driver; when using the D3D9 driver it is a pointer to the IDirect3DDevice9 that is currently being used for rendering. You can render extra primitives by calling all the normal methods on this interface.
(Interface version 20 and above only).

Added in version: 2

int GetSavedData (char *buffer, int bufsize);

Gets the plugin data that was originally saved with AGS_EditorSaveGame. If your plugin had options that the user could set in the editor, this is how to retrieve them.

buffer is a byte array of bufsize, which the engine will copy the saved data into. It returns the number of bytes actually used.

Added in version: 2

BITMAP * GetVirtualScreen ();

Returns a reference to the virtual screen bitmap (as an Allegro BITMAP). The virtual screen is what all drawing routines will draw onto, and usually points to a screen-sized memory bitmap that the engine paints on to construct each frame. Once it is finished, the whole thing is copied to the real screen. This is done to prevent the screen flickering as various things are painted on.

This function is only supported if the player is using the DX5 graphics driver.

Added in version: 3

unsigned char ** GetRawBitmapSurface (BITMAP *bmp);

Gets a reference to the linear bank of memory that contains the surface of bmp. This allows you to directly plot pixels and so forth, simply by writing to the surface as an array.

This function locks the surface for you, which means you must call ReleaseBitmapSurface to release it when you are done. Failure to do so will most likely hang the engine.

If the bitmap colour depth is 15/16 bit, the return value should be cast to unsigned short**.
If the bitmap colour depth is 32 bit, the return value should be cast to unsigned long**.
If the bitmap colour depth is 24 bit, the return value needs to be accessed in blocks of 3 bytes. The best method of doing this is left up to you.

If you change any areas of the virtual screen bitmap via this raw surface, you should call MarkRegionDirty with the affected area, so that AGS redraws that part of the screen.

Be careful when using this surface, since writing outside it will crash the engine. Make sure you use GetBitmapDimensions to find out how big the bitmap is.

This function cannot be used with the real screen bitmap - it can only be used with the virtual screen and any other bitmaps you may have access to.

Added in version: 3

void ReleaseBitmapSurface (BITMAP *bmp);

Releases a bitmap previously locked with GetRawBitmapSurface.

Added in version: 3

void GetScreenDimensions (int *width, int *height, int *coldepth);

Fills in the supplied variables with the current display mode that the engine is running at. You can pass any of the parameters as NULL if you don't want to know them.

width is 320, 640 or 960; height is 200, 240, 400, or 480.
coldepth is either 8, 15, 16, 24 or 32 and reflects the actual colour depth that the game is running at.

Added in version: 3

void DrawText (int x, int y, int font, int color, char *text);

Writes the string text to the current virtual screen at (x, y), using game font number font in colour color.

The x and y parameters are in actual screen co-ordinates, unlike the text script commands which always use 320-scale co-ordinates. You will need to use GetScreenDimensions and multiply up the co-ordinates accordingly if you wish to draw to a specific location.

Added in version: 3

void GetMousePosition (int *x, int *y);

Fills the supplied variables with the current mouse cursor co-ordinates. Note that these are real screen size co-ordinates, and so at 640x480 resolution these variables can go up to 640 and 480, unlike the text script system.

Added in version: 3

void GetBitmapDimensions (BITMAP *bmp, int *width,
                          int *height, int *coldepth);

Fills in the supplied integer variables with the properties of the specified bitmap. You can pass any of the last three parameters as NULL if you don't want to know them.

width is the width of the bitmap, in pixels. height is the height of the bitmap, in pixels. coldepth is the colour depth of the bitmap. Note that this is not necessarily the same as the game colour depth, since it is possible to use 256-colour backgrounds in a hi-colour game. Before doing any direct bitmap drawing, you should check this to make sure that you cast the pointer correctly.

Added in version: 4

int GetNumBackgrounds ();

Returns the number of background frames that the current room has (a normal room will return 1).

Added in version: 4

int GetCurrentBackground ();

Returns the number of the currently displayed background frame. (0 is the default frame, 1 the first animated background, and so forth).

Added in version: 4

BITMAP * GetBackgroundScene (int frame);

Returns a reference to the specified background frame (0 is the default frame, 1 the first animated background, and so on).

Added in version: 4

int GetCurrentRoom ();

Returns the room number that the game is currently in.

Added in version: 4

int FRead (void *buffer, int length, int handle);

Similar to the C function fread, this reads length bytes of buffer from file handle, returning the number of bytes actually read. The handle you use here must have been passed to you by AGS. For any other I/O, you can simply use the standard C functions.

Added in version: 5

int FWrite (void *buffer, int length, int handle);

Similar to the C function fwrite, this writes length bytes of buffer to file handle, returning the number of bytes actually written. The handle you use here must have been passed to you by AGS. For any other I/O, you can simply use the standard C functions.

Added in version: 5

void SetVirtualScreen (BITMAP *bmp);

Sets bmp as the current virtual screen, so that all drawing routines will draw onto it. You should restore the virtual screen to its original setting before returning from your plugin function. (Use GetVirtualScreen first to save the old reference).

Added in version: 5

void DrawTextWrapped (int x, int y, int width, int font,
                      int color, const char *text);

Prints text to the current virtual screen at (x, y), using width pixels wide to do so, wrapping the text to ensure it does not exceed the width.

Added in version: 5

void BlitBitmap (int x, int y, BITMAP *bmp, int masked);

Draws graphic bmp to the current virtual screen at (x,y).
If masked is 0, the image is copied straight across.
If masked is 1, then transparent pixels are skipped.

Added in version: 5

int LookupParserWord (const char *word);

Checks the text parser dictionary for word, and returns its word number. All synonyms of a word have the same word number, as shown in the Text Parser pane in the AGS Editor.
Returns -1 if the word was not in the dictionary.

Added in version: 5

void PollSystem ();

Updates the internally stored mouse co-ordinates, and checks for mouse clicks and keypresses (and triggers the relevant plugin events). Also runs the music decoder to make sure that there is enough data to play.

Call this function if you have a long plugin function which takes more than half a second to execute, or if you need to get mouse and keypress events while still inside your function.

AGS is single-threaded; this means that any background music has to be played by updating the buffer at regular intervals. Therefore, if your function takes a while to execute you should call this to make sure the music doesn't skip.

Added in version: 5

int GetNumCharacters ();

Returns the number of characters in the current game. Valid character ID's range from 0 to the return value minus 1.

Added in version: 6

AGSCharacter * GetCharacter (int charid);

Returns the character state struct for character charid. This struct is documented in the header file, but is mostly identical to the character[] text script variable.

Beware when modifying character state structs. There are some caveats to watch out for, such as altering the X and Y values while the character is moving.
Also, remember that all view numbers stored are 1 less than the numbers shown in the editor and used in the text script.

Added in version: 6

AGSGameOptions * GetGameOptions ();

Returns a reference to the game state structure. This is similar to the text script game. variables.

One handy member here is the AGSGameOptions.fast_forward variable. This is set to 1 while a cutscene is being skipped, so if you have any lengthy graphical effects you should not perform them if this is set. All operations which update any game state must still be performed however, or skipping the cutscene will desync the game.

Added in version: 6

AGSColor * GetPalette ();

Returns a reference to the current palette. This is an array of 256 elements of the AGSColor struct.

In a game with animating backgrounds, the palette can change quite often, so you should generally only rely on the palette remaining consistent for the length of your function.

Added in version: 6

void SetPalette (int start, int finish, AGSColor *palette);

Sets the current screen palette to palette, which must be an array of 256 color structs. The elements from start to finish are updated. Pass start as 0 and finish as 255 to update the entire palette.

Added in version: 6

int GetPlayerCharacter ();

Returns the number of the current player character.

Added in version: 7

int GetNumObjects ();

Returns the number of objects in the current room.

Added in version: 7

AGSObject * GetObject (int number);

Returns the state structure for object number.

Unlike the character structs, object state pointers are not constant throughout the game. Any time the room changes, these structs get reallocated. Therefore, do not keep a pointer that you get with this command after your function ends.

Added in version: 7

void RoomToViewport (int *x, int *y);

Converts the room co-ordinates (x, y) into current viewport co-ordinates. The input co-ordinates are room co-ordinates using the 320x200-style scheme that the text script uses and that object and character co-ordinates are stored as.

When you call this function, the variables you pass will be converted to hold the equivalent viewport co-ordinates. These are real resolution-sized co-ordinates within the current viewable area of the screen.

You should check the resulting co-ordinates with the screen size to determine whether they are currently visible on the screen.

Added in version: 7

void ViewportToRoom (int *x, int *y);

Converts the viewport co-ordinates (x, y) into room co-ordinates. The input co-ordinates are screen resolution scale co-ordinates within the current viewable area of the room.

When you call this function, the variables you pass will be converted to hold the equivalent room co-ordinates, such as stored in the character and object structs, and used in the text script.

Added in version: 7

BITMAP * GetSpriteGraphic (int slot);

Returns the bitmap with the graphic for sprite slot number slot.

This method will automatically load the sprite from disk into the sprite cache if it is not already present.

The AGS Sprite Cache may destroy any sprite from memory at any time. Therefore, never keep a pointer obtained with this command. Always call this method again if you need to perform multiple operations with the bitmap.

Added in version: 7

BITMAP * CreateBlankBitmap (int width, int height, int coldepth);

Creates a blank bitmap sized width x height pixels at coldepth-bit colour. The bitmap will initially be filled with the transparent colour for the colour depth.

Returns NULL if the bitmap could not be created. You should always check the return value to avoid crashes.

To draw onto the bitmap either use GetRawBitmapSurface, or the SetVirtualScreen command followed by one of the drawing commands such as DrawText or BlitBitmap.

The bitmap will remain in memory until you explicitly free it with FreeBitmap. Use this command sparingly, as each bitmap you create eats into the engine's available memory.

Added in version: 7

void FreeBitmap (BITMAP *bmp);

Frees the bitmap bmp from memory.

Only use this command with bitmaps you created with CreateBlankBitmap. Using it with an AGS system bitmap, such as one obtained with GetVirtualScreen, GetScreen or GetSpriteGraphic will crash the engine.

Added in version: 7

BITMAP * GetRoomMask (int which);

Returns a reference to the requested mask for the current room. which is one of the following values:
MASK_WALKABLE
MASK_WALKBEHIND
MASK_HOTSPOT
MASK_REGIONS

The walk-behind mask is exactly the same size as the room, and is at the current resolution. For example, a 320x200 room, being run at 640x400 in the engine, will give you a 640x400 bitmap.

The walkable area, hotspot and region masks are the size of the current room, but at the 320x200 resolution.

All of the masks are bitmaps with 8-bit colour depth, irrespective of what colour depth the game is running at.

The area masks are re-allocated when the player changes rooms, so do not keep a pointer returned by this function longer than you need it.

Added in version: 8 (MASK_REGIONS requires version 11).

AGSViewFrame* GetViewFrame (int view, int loop, int frame);

Returns the view frame structure for the specified frame. view is the number you get from the editor (that's used in SetCharacterView and so forth), not the view minus 1.

Interface version 10 and later:
If frame is not valid (eg. there aren't that many frames in the specified loop), returns NULL.

Interface version 9:
If frame is not valid (eg. there aren't that many frames in the specified loop), AGS will exit with an error message.

If view or loop are invalid, AGS will exit with an error message.

Added in version: 9

int GetWalkbehindBaseline (int area);

Returns the baseline for walk-behind area number area. This is always in character-resolution, ie. the maximum value is 200 in all resolutions.

Added in version: 9

void* GetScriptFunctionAddress (const char *funcName);

Returns the memory address of the text script exported function funcName. This allows you to call any of the functions which AGS makes available to the text scripts.

Returns NULL if you specify a function that doesn't exist.

You must cast the result to the correct function type in order to call it - ie. you must know how many parameters the function expects, and call it appropriately. Failure to do so will corrupt the stack and likely crash the engine.

If you specify the name of an actual function in the script, for example repeatedly_execute, it will return an address - however, this will be a script address and attempting to call it will crash the game. Only use this feature to obtain the address of AGS's script functions as documented in the manual.

Added in version: 9

int GetBitmapTransparentColor (BITMAP *bmp);

Returns the pixel colour which is skipped when rendering the bitmap. This is 0 in 256-colour bitmaps and RGB (255,0,255) in hi-color bitmaps, so this function returns the pixel value to check for if you need to know.

Added in version: 9

int GetAreaScaling (int x, int y);

Returns the walkable area scaling level at the specified co-ordinates. This ranges from 5 to 200, and specifies the scaling percentage, as set in the editor. The co-ordinates are specified as room co-ordinates.

Added in version: 9

int IsGamePaused ();

Equivalent to the text script IsGamePaused function. This returns non-zero if the game is paused, or 0 if it is not paused.

Added in version: 9

int GetRawPixelColor (int color);

Converts color, as specified in the AGS Editor, to the appropriate raw pixel colour for the current graphics mode.

If the user is running 8-bit colour, the value is returned unchanged.

If the user is running 16-bit colour, the value is returned unchanged unless it is less than 32, in which case it is converted to be the appropriate locked colour from the editor.

If the user is running 15-bit colour, the value is converted to an appropriate 15-bit RGB pixel value.

Added in version: 10

int GetSpriteWidth (int slot);

Returns the width, in pixels, of sprite number slot.

This is faster than using GetBitmapDimensions with GetSpriteGraphic, since the image does not need to be retrieved from the sprite cache.

Added in version: 11

int GetSpriteHeight (int slot);

Returns the height, in pixels, of sprite number slot.

This is faster than using GetBitmapDimensions with GetSpriteGraphic, since the image does not need to be retrieved from the sprite cache.

Added in version: 11

void GetTextExtent (int font, const char *text,
                    int *width, int *height);

Calculates the width and height, in pixels, of displaying text in game font number font.

width or height can be NULL if you only want to know the other one.

Added in version: 11

void PrintDebugConsole (const char *message);

Prints message to the in-game debug console (which the user can pop up with the ~ key).

The debug console is designed to help the user find problems by tracing through what's happening in the game - so do not pump messages out to this debug console too quickly or they will scroll past too fast for the user to read. Use the console to say one-off events like "Requested move character to X,Y" and so forth.

Added in version: 11

int IsChannelPlaying (int channel);

Equivalent to the text script function of the same name, returns 1 if the channel is currently in use, 0 if not.

Added in version: 11

void PlaySoundChannel (int channel, int soundType, int volume,
                       int loop, const char *filename);

Plays a new sound on the sound channel number channel. volume can be from 0 to 255, loop is 0 or 1.

soundType determines which sound driver is used to load the file:

PSND_WAVE Uncompressed .WAV file

PSND_MP3STREAM MP3, streamed from disk

PSND_MP3STATIC MP3, loaded into memory before playing

PSND_OGGSTREAM OGG, streamed from disk

PSND_OGGSTATIC OGG, loaded into memory before playing

PSND_MIDI MIDI file

PSND_MOD MOD/XM/S3M file

You should normally just use the PlaySound, PlaySoundEx and PlayMusic functions (via GetScriptFunctionAddress) to play sounds - only use this function in specific circumstances.

Only one MIDI file, and one MOD/XM file can be playing at a time. You should generally keep away from these two sound types unless you are sure about what you are doing.

Added in version: 11

void MarkRegionDirty(int left, int top, int right, int bottom);

Marks the rectangle (left, top) - (right, bottom) on the virtual screen as dirty. Use this if you make any changes to the virtual screen via its raw bitmap surface, to tell AGS to repaint that area of the screen.

All engine API functions such as DrawText and BlitBitmap call this automatically, so you only need to call it if you manually modify the bitmap surface.

Added in version: 12

AGSMouseCursor* GetMouseCursor(int cursor);

Returns the mouse cursor struct which AGS uses to store details about the specified cursor mode.

The returned struct is read-only. You should not modify any members of it directly; rather, call the script functions such as ChangeCursorGraphic which ensure that the game state is updated properly.

Added in version: 12

void GetRawColorComponents(int coldepth, int color,
	int *red, int *green, int *blue, int *alpha);

Given a raw color (from a bitmap's raw surface, or from GetRawPixelColor) at a given colour depth, returns the red, green, blue and alpha components, as values from 0-255.

You can pass any of the pointers as NULL if you don't want to know that value. The alpha value only has meaning for 32-bit pixels; for all other colour depths, it will just be returned as 0.

Added in version: 12

int MakeRawColorPixel(int coldepth, int red, int green,
                      int blue, int alpha);

Given a colour depth, and RGB values (from 0-255), this function returns the raw pixel value needed to display the requested colour on a bitmap of coldepth bits per pixel.

The alpha value is only meaningful for 32-bit colour alpha channel bitmaps, and it allows you to set the alpha value for the pixel. For bitmaps without an alpha channel, pass alpha as 0.

Added in version: 12

int GetFontType(int fontNum);

Returns what type of font fontNum is, as one of the following values:

FNT_INVALID invalid font number supplied

FNT_SCI font is a SCI font

FNT_TTF font is a TTF font

Added in version: 12

int CreateDynamicSprite(int coldepth, int width, int height);

Creates a new dynamic sprite with the supplied colour depth, width and height. A dynamic sprite is not controlled by the AGS Sprite Cache, and so is not removed from memory until you manually call DeleteDynamicSprite. Thus, you can write to its bitmap surface without a problem.

You must remember to free the memory when you are done with the sprite, by calling DeleteDynamicSprite.

Returns 0 if the sprite could not be created, or the sprite slot number on success.

Added in version: 12

void DeleteDynamicSprite(int slot);

Removes the previously created dynamic sprite from memory. It can no longer be used in the game.

Added in version: 12

int IsSpriteAlphaBlended(int slot);

Determines whether the supplied sprite has an alpha channel or not. Returns 1 if it does, 0 if it does not.

This function is useful for determining whether you can ignore the alpha value when doing raw bitmap manipulations. If a sprite does have an alpha channel, you cannot ignore it since the default alpha value of 0 means totally invisible and the pixel would disappear.

Only 32-bit bitmaps can have an alpha channel. For all other colour depths, this function will always return 0.

Added in version: 12

void UnrequestEventHook(int event)

Tells the engine not to call this plugin any longer when the specified event occurs. The values of event are the same as for RequestEventHook.

This is useful to call for performance reasons if you no longer require notification of an event.

Added in version: 13

void BlitSpriteTranslucent(int x, int y, BITMAP *spr, int trans);

Draws graphic spr to the current virtual screen at (x,y), with translucency over the background.

trans is the translucency level, from 0 to 255 (where 0 is fully transparent, and 255 is fully opaque). Pixels in the bitmap's transparent colour are skipped completely.

Added in version: 13

void BlitSpriteRotated(int x, int y, BITMAP *spr, int angle);

Draws graphic spr to the current virtual screen at (x,y), but rotated to angle. Pixels in the bitmap's transparent colour are skipped completely.

The sprite is positioned with its upper-left corner at (x,y), then it is rotated about its centre by angle. The angle is specified as a number from 0 to 255, where 128 would turn it 180 degrees, and 64 would turn it 90 degrees.

Added in version: 13

LPDIRECTSOUND GetDirectSound();

Returns the main IDirectSound interface that the engine is using. This command does not AddRef the pointer it returns, so you don't need to Release it.

This function returns NULL if sound is disabled, or if the player is using the WaveOut driver rather than the DirectSound one.

Added in version: 14

void DisableSound();

Disables AGS's sound system completely. Use this if you want your plugin to take over all audio functionality.

Added in version: 14

int CanRunScriptFunctionNow();

Determines whether a game script function can be run now. Returns 0 if there is currently a script running, or 1 if there isn't.

Added in version: 14

int CallGameScriptFunction(const char *name, int globalScript,
                int numArgs, int arg1 = 0, int arg2 = 0, int arg3 = 0);

Runs a script function in the game's script. name is the name of the function to call. If globalScript is 1, it will call the function in the global script; if it is 0, the function will be run in the room script.

numArgs specifies how many arguments the function takes - this can be from 0 to 3. The following parameters then allow you to pass the contents of the function parameters. They are all 32-bit ints, so the user should declare their script function as taking int parameters.

This function returns 0 on success, and a non-zero value otherwise. This will always fail when CanRunScriptFunctionNow returns 0.

Added in version: 14

void QueueGameScriptFunction(const char *name, int globalScript,
                             int numArgs, int arg1 = 0, int arg2 = 0);

Queues a script function to be run in the game's script. name is the name of the function to call. If globalScript is 1, it will call the function in the global script; if it is 0, the function will be run in the room script.

numArgs specifies how many arguments the function takes - this can be from 0 to 2. The following parameters then allow you to pass the contents of the function parameters. They are all 32-bit ints, so the user should declare their script function as taking int parameters.

If no scripts are currently running, the requested script will be run straight away. If there are scripts running, however, then the requested script will be queued up to run when the current one finishes.

Added in version: 15

void NotifySpriteUpdated(int slot);

Notifies the engine that the specified sprite has been updated by the plugin. You would call this if you changed the contents of a dynamic sprite, to make sure that the screen is updated to reflect your changes.

Added in version: 15

void SetSpriteAlphaBlended(int slot, int isAlphaBlended);

Allows you to specify whether the sprite is alpha blended or not. This allows you to create dynamic 32-bit RGBA sprites. Pass isAlphaBlended as 1 to enable the sprite's alpha channel, or pass it as 0 to disable the alpha channel.

This function should only be used with 32-bit dynamic sprites. Using it with sprites of lower colour depths, or of sprites created in the AGS Editor, can have unpredictable results.

Added in version: 15

int RegisterManagedObject(const void *object,
                           IAGSScriptManagedObject *callback);

Registers a new managed object with the script engine. object points to the actual object itself, and callback points to the class implementing the IAGSScriptManagedObject interface, which will be called to perform operations on the object.

callback and object can, but do not have to, point to the same thing (ie. it is possible to have the actual object implement the interface; but if you do so, beware that you should not expose any normal variables from the class due to the vtable occupying the first part of the memory).

The object is added to the managed object pool, with a reference count of zero. Once this function has been called, object can be returned to the script and will be automatically picked up by the script engine.

See further down this page for a description of the IAGSScriptManagedObject interface.

From engine interface version 16 and later, this function returns the managed pool key for the object. You will not normally need this, but it can be useful to link a parent and child object if your structure is complex.

Added in version: 15

void AddManagedObjectReader(const char *typeName,
                            IAGSManagedObjectReader *reader);

Registers the specified managed object type with the script engine, and supplies an IAGSManagedObjectReader, which provides the functionality for de-serializing objects of that type. This is used when the user restores a save game, in order to recreate any managed objects that were in existence when the game was saved.

See further down this page for a description of the IAGSManagedObjectReader interface.

AGS only keeps a pointer to typeName and does not copy the string, so make sure you do not supply a temporary or local variable as the type name.

Added in version: 15

void RegisterUnserializedObject(int key, const void *object,
                                IAGSScriptManagedObject *callback);

Used from within the IAGSManagedObjectReader, this function re-registers a managed object after it has been read back from disk (for example, when the player restores a save game).

The key parameter is the object's key, supplied to the ObjectReader, which allows AGS to match up the object internally. You should pass the key in here exactly as it is passed to the ObjectReader.

Added in version: 15

int GetManagedObjectKeyByAddress(const char *address);

Gets the managed pool key of the specified object address. You will not normally need to use this function, however it can be useful to link up related objects after de-serialization.

Returns -1 if there is no such object in the pool.

This function is quite slow so you should avoid using it wherever possible.

Added in version: 16

void* GetManagedObjectAddressByKey(int key);

Gets the memory address of the specified object from the managed pool. You will not normally need to use this function, however it can be useful to link up related objects after de-serialization.

Returns NULL if the key is invalid.

Added in version: 16

const char* CreateScriptString(const char *fromText);

Creates a new script String object, containing a copy of fromText. This allows you to declare your plugin functions as returning a String -- simply return the result of CreateScriptString to the calling script.

The new string becomes part of the AGS Managed Object Pool and will be freed automatically when there are no longer any script references to it. Note that it creates a copy of fromText, so it is safe for you to free the contents of fromText after calling this function.

Added in version: 17

int IncrementManagedObjectRefCount(const char *address);

Increments the reference count of the specified object in the managed object pool. This should be used if you are storing a reference to a managed object between script function calls, in order to ensure that the object does not get deleted.

Returns the new reference count of the object.

Be very careful when using this function. If you adjust the reference count incorrectly, you could cause a memory leak or the game could crash.

Added in version: 18

int DecrementManagedObjectRefCount(const char *address);

Decrements the reference count of the specified object in the managed object pool. This should be used if you are storing a reference to a managed object between script function calls, in order to ensure that the object does not get deleted.

Returns the new reference count of the object.

Be very careful when using this function. If you adjust the reference count incorrectly, you could cause a memory leak or the game could crash.

Added in version: 18

void SetMousePosition(int x, int y);

Changes the mouse cursor position to (x,y). As with GetMousePosition, these co-ordinates are specified in real resolution units, so in a 640x480 game the co-ordinates do go up to 640,480 (unlike the script function of the same name).

Added in version: 18

void SimulateMouseClick(int button);

Simulates the mouse being clicked by the player. button is which mouse button (1=left, 2=right, 3=middle) to simulate. The effect should be identical to the user clicking the equivalent button on their mouse.

Added in version: 18

int GetMovementPathWaypointCount(int pathId);

Gets the number of waypoints on the specified movement path.

The GetMovementPath family of functions allow you to access the paths for moving characters and objects in the game; and therefore allow you to anticipate where they will end up. The pathId is the value found in the AGSCharacter.walking and AGSObject.moving variables (but only if these variables are greater than 0; 0 or less means they are not moving).

Added in version: 18

int GetMovementPathLastWaypoint(int pathId);

Gets the last waypoint that was passed on this movement path. The starting point is waypoint 0, and the destination is the WaypointCount minus 1 (though this can never be returned, since the move is marked as finished once the last waypoint is reached).

Added in version: 18

void GetMovementPathWaypointLocation(int32 pathId, 
				int32 waypoint, int32 *x, int32 *y);

Gets the X and Y co-ordinates of the specified waypoint on the specified path.

No error checking is done on these functions for performance reasons, so make sure you supply a valid pathId and waypoint.

Added in version: 18

void GetMovementPathWaypointSpeed(int32 pathId,
				int32 waypoint, int32 *xSpeed, int32 *ySpeed);

Gets the X and Y speed at which the character/object will move from the specified waypoint to the next. The speeds are returned as 32-bit fixed point numbers. This means that the high 16 bits is the whole part of the number, and the low 16 bits is the fractional part. For example, if xSpeed is 0x00038000, that would represent a speed of 3.5 pixels per frame.

Added in version: 18

int IsRunningUnderDebugger()

Returns whether the game is currently running under the AGS Editor's debugger. If it is, then you are able to use the BreakIntoDebugger command.

Added in version: 22

void BreakIntoDebugger()

Tells AGS to stop and break out into the editor's debugger. This will not happen immediately, but will happen when the next line of script code is run. This function will only work if IsRunningUnderDebugger returns 1.

Added in version: 22

void GetPathToFileInCompiledFolder(const char*fileName, char *buffer)

Fills in buffer with a path that you can use to open the specified file that resides in the Compiled folder.

If the game is running under the debugger, buffer will end up containing Compiled\fileName
Otherwise, buffer will simply be set to a copy of fileName.

You should allocate buffer as MAX_PATH bytes long.

Added in version: 22

IAGSScriptManagedObject interface

The IAGSScriptManagedObject interface is implemented for objects which the plugin wants to return to the game script. It allows a callback mechanism for AGS to request various operations on the object. You must implement the following:

int Dispose(const char *address, bool force);

Called when the reference count of the specified object reaches zero. The address parameter points to the particular object that is no longer referenced.

If force is zero, then you are merely being informed that the reference count has reached zero. Either you can destroy the object (in which case you should return 1), or you can leave it (return 0). If you leave it, then this function will be called again at various intervals to give you another opportunity to destroy the object.

If force is non-zero, then this is the object's last chance to free its memory and it will not be called again. This is the case if the player is about to restore a saved game, or is quitting the game, and so forth.

You must return 1 from this function if you destroy the object at address -- in which case, it will be removed from the managed object pool. Return 0 if you do not destroy the object, in which case it will stick around.

Added in version: 15

const char* GetType();

Returns the type name of the object. This must match the type name supplied to AddManagedObjectReader for the corresponding reader.

Added in version: 15

int Serialize(const char *address, char *buffer, int bufsize);

Called when the player saves the game. You must write any persistent data for the object at address into the supplied buffer. The buffer is bufsize bytes long, and you must not write any more data than that.

You must return the number of bytes written to the buffer.

Added in version: 15

IAGSManagedObjectReader interface

The IAGSManagedObjectReader interface is implemented for each managed object type, to enable the objects to be reconstructed after being read back from disk. You must implement the following:

void Unserialize(int key, const char *serializedData, int dataSize);

Called for each managed object when a saved game is restored. serializedData is the buffer that you wrote to in Serialize, and dataSize is the length of this buffer.

You should re-construct the object from the serialized data, and then re-register it using the RegisterUnserializedObject function. The key supplied to you here should be passed on unmodified to RegisterUnserializedObject in order for the object to be fully restored.

Added in version: 15