AGS tidbits & snippets

From Adventure Game Studio | Wiki
Jump to: navigation, search

Aside from all the great ideas and scripts I've found after browsing through the whole beginners and technical forum, I noticed the small things either not in the manual or easy to miss.

I have sorted through my notes and thought I'd post what I've found, maybe some of you will find this useful at one point or another.

Please don't add anything to this page, add to the Tidbits and Snippets category instead.




CJ: There's no hard limit, but a sprite cannot be taller than the screen resolution.

CJ: If you put a room file called "_blank.crm" in your game folder, it will be used as the template for new rooms. [1]

CJ: Adding a blank dialog option will make it unclickable. [2]

So you can use that as default dialog option that gets run when all others have been turned off.

CJ: Most of the data (i.e. rooms and sprites) is only loaded when needed. [3]

bonordberg: AGS only allows 35 or so characters and objects on the screen at the same time. [4]

AGS v2.62 increased the limit to 50.

CJ: You could double-click the "Edit this .AGSGame" file to open the game in the editor.
You can create this association manually if you like, just set up .AGSGame files so that their association is: [5]

c:\path\to\ags\agsedit.exe -shelllaunch "%1"

CJ: You cannot load a game saved at a different resolution.

So start playing your low-res game in hi-res if you intend to switch to bigger-sized windowed mode later.

CJ: The AGS editor can only automatically use 16-colour icons. (Tracker)

As of AGS v2.72 hi-color icons can be used when running Windows 2000/XP.

CJ: Labels and text boxes have a maximum length of 200 characters, just like the max string length. [6]

CJ: Tiled sprite import now goes from left to right in rows.

Scorpiorus: You can have about 150 lines of text in a listbox.

CJ: You can have up to 1000 rooms, but any numbered >300 will not have their state saved when the player leaves the room. This basically means that room script variables, object positions, etc will all be reset to their default values when you leave the room. [7]

CJ: Beta versions of the engine are larger, because they don't have all the debug code stripped out, and aren't compressed. [8]

CJ: #define is replaced with its definition at compile-time. [9]

CJ: AGS v2.3 and later request 85 Hz from DirectX.

Erica McLane: Games compiled for DOS have 60 Hz.

CJ: When creating a translation source, AGS only scans backwards 10 characters to check for the 'GetxxxProperty'. [10]

CJ: Fatal exceptions eip +5997 mean the MP3 player and eip +379 mean a problem drawing the GUI. [11]

Esseb: 320*200 is what the game engine reverts to if no config file is present. [12]

CJ: To ensure [the pathfinder] always works, your walkable areas should always be at least 3 pixels wide.

I suppose the same applies to non-walkable areas.

Gilbot: Sprites are always stored in the basic executable, the splitted resources only contain room data.

As of AGS v2.7, sprite data is stored in the first splitted resource file.

CJ: The inventory window currently keeps track of the order that items are added to it, until the player character is changed, at which point the items switch back to the default order. [13]

As of AGS v2.7, the inventory item order for each character is remembered.

CJ: The dialog options are drawn in the player character's talking colour. The highlighted option colour uses the GUI foreground colour if you are using a GUI TextWindow, otherwise it is hardcoded to yellow. (Tracker)

CJ: Character.UnlockView doesn't change the loop number back, so he will go to facing in whichever direction the loop that was playing in the animation was.

CJ: Character.FaceLocation will only allow a character to face directions which he can actually walk in.

inFERNo: Every interaction in the interaction editor list is executed first, the run script always when all others are done.

CJ: The maximum room height is 1400 pixels (at 320x200 resolution - you could have a 2800-tall 640x400 room).

I asked CJ for clarification:

CJ: The pathfinder uses an 1400-sized array for storing potential routes, and there's one row for each line.

That means in 320x200 and 320x240 the maximum room background height is 1400 pixels, in 640x400, 640x480 and 800x600 it's 2800 pixels. In theory, there's no width limit.

CJ: Objects are placed with 320x240-res co-ordinates, so at 640x480 you can only place them on even pixels.

Keep this in mind when designing your backgrounds/objects!


CJ: Keys that aren't listed in the ASCII Code Table have no guarantees about their keycode numbers and may well overlap keys that are listed. [14]

CJ: I'd just like to clarify that there is no point in using a short rather than an int as a local variable. In fact, ints are faster because the CPU is better at reading/writing 32-bit chunks of memory than it is at 16-bit chunks. [15]

CJ: There is no fixed limit on the size of global arrays, but as scotch says they use up memory so don't go silly with creating massive ones unless you really need to. [16]

CJ: The workaround for displaying player-entered strings, in case anyone wants to know, is simply to do this:

Display("%s", playerString);

since that way, the player string will not be parsed for special tokens. [17]

CJ: You have to place the export after the variable's declaration. [18]

So you don't necessarily have to put the exports at the end of scripts.

CJ: You should be able to have up to 15 parameters to a function. [19]

CJ: Note that optional parameters only work with int and enum parameters, you can't do it with strings or floats.

CJ: Basically, to be consistent with Java/C#, the protection level always goes first: [20]

protected import static function get_slots();

CJ: You'll get an error if you define over 4 KB's worth of variables inside a function. [21]

CJ: It's not until a room is loaded that the current viewport size is known. [22] (Tracker)

So better not rely on system.viewport_width or system.viewport_height in game_start.

(Unknown): You can use :return; to abort the rest of the script.

CJ: Local room scripts have their data segment saved when the room is destroyed, so all variables retain their values.

Useful to store the condition of light switches, for example.

CJ: RunInventoryInteraction doesn't get run immediately - instead, it gets run when the calling script finishes.

Applies only if the interaction runs a script. Interaction editor commands are executed immediately.

CJ: The number of game loops [speech text] stays for is: [23]

int gameloops = ((StrLen(text) / game.text_speed) + 1) * GetGameSpeed();

CJ: Functions cannot return structs or arrays - they can only return primitive types. [24]

Gilbot: A [char] is a one byte integer, so you can use = and = = directly. [25]

Meaning, unlike strings, you can do
char tmpchar = 'A';
tmpchar += 2; // will make tmpchar into 'C'

RickJ: A variable declaration in the header will cause a seperate [static] variable for each room.

Could be used instead of room properties if you need to change them at run-time.

SSH: Strings in structs have to be declared as char desc [256]; [26]

I think it's 200, the AGS maximum string length:
struct myStruct {
  char mystring [200];
Since you can't make arrays from string variables, you can make it from such a struct instead. (AGS v2.71's new String type works as an array.)


cJack.Say("The new code is %04d", GetGlobalInt(99));

will add leading zeros (up to 4) if necessary.

Here are more format flags:
// (number) = Create a field (number) characters wide:
Display("Here comes %4d a test", 22); //=> Here comes   22 a test
// - = Left justify:
Display("Here comes %-4d a test", 22); //=> Here comes 22   a test
// 0 = Field is padded with 0's instead of blanks:
Display("Here comes %04d a test", 22); //=> Here comes 0022 a test
// + = Sign of number always shown:
Display("Here comes %+d a test", 22); //=> Here comes +22 a test
// (blank) = Positive values begin with a blank:
Display("Here comes % d a test", 22); //=> Here comes  22 a test

RickJ: The character's global inventory variables are integers and can be used to keep track of how many items the character has.

Characters, objects & hotspots

Scorpiorus: The exact MoveCharacterToObject offsets are +5 and +6 from the object's x and y respectively." [27]

This function is obsolete as of AGS v2.7

CJ: A character with a move speed of 0 instantly warps to their destination. [28]

Spyros: The default idle view delay is 20 sec.

It's hidden in the manual.

Cornjob: Character.LoseInventory only decreases the quantity by 1. (ezboard-Thread)

Similarly, Character.AddInventory increases the quantity by one each time it's used.

So better use

if (player.InventoryQuantity[iCoin.ID]) { // if player has one OR MORE of inv item iCoin
instead of
if (player.InventoryQuantity[iCoin.ID] == 1) { // if player has EXACTLY one inv item iCoin

CJ: There is an undocumented Character.on variable, which is normally 1, but you can set it to 0 to make the character invisible.

Note that Character.Walk and the like don't work with characters turned off this way.

Scorpiorus: If the hide player option is ticked the Character.on variable holds 0. [29]

CJ: Directly modifying won't prompt a room change, it'll just make the player character disappear.


CJ: If you don't want to bundle the flic's, just put them in your Compiled folder rather than your game folder, and they won't get built into the EXE. [30]

Scorpiorus: The PlayMP3File(filename) function requires the mp3 file to be in the game\compiled folder rather than game folder.

I think this is in the manual. However, I find it worth repeating.

CJ: The 'Play music on room load' textbox only accepts music numbers from 1-120. To play a higher numbered music, you need to use PlayMusic.

CJ: Music 0 is automatically played at game startup.

Works with compiled games, too. :)

(Unknown): If you import 24-bit pictures in AGS, it will automatically convert to [16-bit].

Just import 24-bit pictures into your high-color game.

Windows default sound volume: All sliders to 50%

CJ: AGS doesn't actually use Media Player itself to play avi videos, it just uses the same DirectShow that Media Player does.

Scorpiorus: If music has been disabled or there's no sound card, GetMP3PosMills() always returns 0.


CJ: You can disable the abort key by doing: game.abort_key = -1; [31]

Please don't. If your game locks up, the user won't be able to abort.

In dialog scripts, the '...' will pause for 1 second (regardless of game speed setting).

CJ: Calling "game.exe --setup" is all that the winsetup.exe program does.

CJ: You can rename winsetup.exe to anything you like, it will still work.

Character to mask % symbol in strings: %

Display("The %% is the percent symbol.");

Character to mask quotemarks in strings: \

Display("The \" is a quotemark.");

Character for line breaks in strings: [

Display("The [ is a line break.");

Character to mask [ in strings: \

Display("The \[ is a left brace.");


Scorpiorus: Blocking commands block the text script but not the interaction editor's actions." [32]

CJ: The linux engine can play any games created with AGS v2.5 and later. [33]

CJ: In the editor AGS has to convert the 16-bit images to 15-bit for display (or for clipboard copy). [34]

CJ: Set your desktop colour depth to 32-bit, then run winsetup and select to run the game in a window. Then, you can launch ACWIN (or any AGS game) with the parameter "--15bit" (without the speech marks), which will force it into 15-bit mode. [35]

CJ: Object.MergeIntoBackground is effectively RawDrawObject followed by Object.Visible = false;. [36]

CJ: With TTF fonts the full 256 characters are supported (but not unicode, sorry).

Works only using translations, not directly.

CJ: GUI names actually #define to a special hidden function FindGUIByName, so that even if the numbers have changed, it will still find the right one. [37]

Gilbot: FLICs are limited to 256 colours.

FLI supports only one resolution: 320x200 with 256 colors

FLC supports any resolution up to 1024x768 with 256 colors.

Scorpiorus: AGS moves characters only when all scripts are finished.

CJ: Only characters, objects, mouse cursors and GUI backgrounds support being drawn with an alpha channel in-game.

You can have alpha-channel GUI buttons if you use a GUI background image that has no background layer.

CJ: If the conversation is launched from a global script function (eg. the character interaction) then repeatedly_execute doesn't run in the background.

Is this still true?

See also

  • Tidbits and Snippets - Better organized version of this page (may not be complete yet). Use this when adding new stuff.