-
Notifications
You must be signed in to change notification settings - Fork 0
Game
static bool Game.ChangeTranslation(string newTranslationName)
Changes the active translation to newTranslationName. This must be the file name without the extension, for example "French" or "Spanish". It can also be a blank string, in which case the current translation will be switched off and the game will revert to the default language.
Returns true if the translation was changed successfully, or false if there was a problem (for example, you specified an invalid translation).
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example below.
Example:
if (Game.ChangeTranslation("Spanish") == true)
{
Display("Changed the translation to Spanish!");
}
else
{
Display("Unable to change the translation");
}
will attempt to change the translation to Spanish
Compatibility: Supported by AGS 3.1.0 and later versions.
See Also: Game.TranslationFilename, IsTranslationAvailable
static bool Game.DoOnceOnly(const string token)
This function gives you an easy way of making some code run only the first time that the player encounters it. It is commonly used for awarding points.
The token parameter is an arbitrary string. You can pass whatever you like in for this, but IT MUST BE UNIQUE. It is this string that allows AGS to determine whether this section of code has been run before, therefore you should make sure that you do not use the same token string in two different places in your game.
Returns true the first time that it is called with this token, and false thereafter.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example below.
Example:
if (Game.DoOnceOnly("open cupboard")) {
GiveScore(5);
}
will give the player 5 points the first time this script is run.
See Also: GiveScore
(Formerly known as RawSetColorRGB, which is now obsolete)
static int Game.GetColorFromRGB(int red, int green, int blue)
Gets the AGS Colour Number for the specified RGB colour. The red, green and blue components are values from 0 to 255. This function gives you a run-time equivalent to the Colour Finder in the editor.
This command is slow in 256-colour games, since the palette has to be scanned to find the nearest matching colour.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example below.
Example:
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = Game.GetColorFromRGB(0, 255, 0);
surface.DrawLine(0, 0, 50, 50);
surface.Release();
will draw a bright green line onto the room background
See Also: DrawingSurface.DrawingColor
(Formerly part of GetGameParameter, which is now obsolete)
static int Game.GetFrameCountForLoop(int view, int loop)
Returns the number of frames in the specified loop of the specified view.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example for more.
Example:
int frameCount = Game.GetFrameCountForLoop(SWIMMING, 2);
Display("Loop 2 in SWIMMING view has %d frames.", frameCount);
See Also: Game.GetLoopCountForView, Game.GetRunNextSettingForLoop, Game.GetViewFrame
(Formerly known as global function GetLocationName, which is now obsolete)
static String Game.GetLocationName(int x, int y)
Returns the name of whatever is on the screen at (X,Y). This allows you to create the Lucasarts-style status lines reading "Look at xxx" as the player moves the cursor over them.
NOTE: Unlike Room.ProcessClick, this function actually works on what the player can see on the screen - therefore, if the co-ordinates are on a GUI, a blank string is returned.
NOTE: The co-ordinates are SCREEN co-ordinates, NOT ROOM co-ordinates. This means that with a scrolling room, the co-ordinates you pass are relative to the screen's current position, and NOT absolute room co-ordinates. This means that this function is suitable for use with the mouse cursor position variables.
Example:
String location = Game.GetLocationName(mouse.x, mouse.y);
will get the name of whatever the mouse is over into the string variable.
See Also: Hotspot.Name, InventoryItem.Name, GetLocationType, Object.Name
(Formerly part of GetGameParameter, which is now obsolete)
static int Game.GetLoopCountForView(int view)
Returns the number of loops in the specified view.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example for more.
Example:
int loops = Game.GetLoopCountForView(SWIMMING);
Display("The SWIMMING view (view %d) has %d loops.", SWIMMING, loops);
See Also: Game.GetRunNextSettingForLoop, Game.GetFrameCountForLoop, Game.GetViewFrame
(Formerly part of GetGameParameter, which is now obsolete)
static bool Game.GetRunNextSettingForLoop(int view, int loop)
Returns whether the specified loop in the specified view has the "Run the next loop after this one" option checked.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example for more.
Example:
if (Game.GetRunNextSettingForLoop(SWIMMING, 5) == true) {
Display("Loop 5 in view SWIMMING does have Run Next Loop set.");
}
else {
Display("Loop 5 in view SWIMMING does not have Run Next Loop set.");
}
See Also: Game.GetLoopCountForView, Game.GetFrameCountForLoop, Game.GetViewFrame
(Formerly known as global function GetSaveSlotDescription, which is now obsolete)
static String Game.GetSaveSlotDescription(int slot)
Gets the text description of save game slot SLOT.
If the slot number provided does not exist, returns null.
Example:
String description = Game.GetSaveSlotDescription(10);
will get the description of save slot 10 into the variable.
See Also: DynamicSprite.CreateFromSaveGame, RestoreGameSlot, SaveGameSlot
(Formerly part of GetGameParameter, which is now obsolete)
static ViewFrame* Game.GetViewFrame(int view, int loop, int frame)
Returns a ViewFrame instance for the specified frame in the specified loop of the specified view.
This instance allows you to query properties of the frame itself, such as its graphic, its frame-linked sound setting, and so forth.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example for more.
Example:
ViewFrame *frame = Game.GetViewFrame(SWIMMING, 2, 3);
Display("Frame 3 in loop 2 of view SWIMMING has sprite slot %d.", frame.Graphic);
See Also: Game.GetLoopCountForView, Game.GetRunNextSettingForLoop, Game.GetFrameCountForLoop, ViewFrame.Graphic, ViewFrame.Speed
(Formerly known as global function InputBox, which is now obsolete)
static String Game.InputBox(string prompt)
Pops up a window asking the user to type in a string, with PROMPT as the text in the window. Whatever they type in will be returned from this function.
This command displays a very basic input box, mainly useful for debugging purposes. Due to the size of the window, only small strings up to about 20 characters can be typed in.
The recommended way to obtain user input is to create your own GUI with a text box on it, which allows you full customization of the look of the window.
TIP: If you add a '!' character to the start of the prompt, then a Cancel button will be available in the input box. If the player presses this Cancel button (or the ESC key), a blank string is returned.
Example:
String name = Game.InputBox("!What is your name?");
will prompt the user for his name and store it in the string NAME. If the user presses Cancel, the NAME string will be blank.
See Also: String.AsInt
static bool Game.IsPluginLoaded(const string name)
Checks whether the plugin of the given name was present and loaded for the game.
IMPORTANT: If the plugin exports its own script functions that you used in your game script, and not found when the game is launched, then the game won't start up at all, exiting with error. IsPluginLoaded may therefore be useful to check for plugins that are not interacted with from game script, but just run on their own.
Example:
if (Game.IsPluginLoaded("my_plugin")) {
Display("My plugin is found and running!");
}
will display a message if plugin is present.
static AudioChannel* Game.PlayVoiceClip(Character* c, int cue, bool as_speech)
Plays a voice clip from speech.vox in a non-blocking manner. It returns an AudioChannel pointer which you may use to control playback same way you control other clips, or null if it could not be started.
Note: due how audiochannels work internally right now, this is always same channel, and you may probably also get it as System.AudioChannels[0] (maybe not a very good idea to rely on though).
Character and "cue" arguments are used to find actual clip, this works same way as when you do cEgo.Say("&10 blablabla"); <- in this case "10" is a cue number.
The as_speech argument tells whether playback has same effect on game as regular speech. At the moment this means that music volume will drop and restore after playback is finished.
This parameter as_speech = true by default, so it may be omited.
This command will be ignored if a regular blocking voice is played.
static bool Game.SetSaveGameDirectory(string directory)
Changes the directory where save game files are stored to the supplied directory. If the directory does not exist, AGS will attempt to create it.
You cannot use fully qualified directories with this command (eg.
C:\Games\Cool\Saves), because the player might have installed your
game to any folder, and they might not be running Windows.
Therefore, only two types of path are supported:
- Relative paths (eg. "Saves"). This will create a subfolder inside
default game save folder
- The special tag
$MYDOCS$which allows you to explicitly create a different folder for your save games inside the user's documents folder.
The actual folder referenced with $MYDOCS$ is different on every
platform: Windows XP: "My Documents"
Windows Vista and later: "Saved Games"
Linux: $XDG_DATA_HOME/ags
MacOS: game installation folder.
Returns true if the save game directory has been changed successfully; false if not.
NOTE: We advise you against using this function without strong need. In the most cases setting the "Save games folder name" property in the General Settings of the editor should be sufficient.
Example:
Game.SetSaveGameDirectory("$MYDOCS$/My Cool Game Saves");
will change the save game directory to "My Cool Game Saves" in My Documents, and create the folder if it does not exist (might be useful to do this in game_start).
See Also: ListBox.FillSaveGameList, RestoreGameDialog
readonly static int Game.AudioClipCount
Returns the number of audio clips in the game.
This is useful for script modules if you need to iterate through all the audio clips for some reason.
Compatibility: Supported by AGS 3.4.0 and later versions.
See Also: Game.AudioClips
readonly static int Game.AudioClips[int slot]
Returns the AudioClip* pointer by its index in game resources.
Example:
int i = 0;
int music_count = 0;
while (i < Game.AudioClipCount)
{
if (Game.AudioClips[i].Type == eAudioTypeMusic)
music_count++;
i++;
}
Display("We have %d musical clips in our game", music_count);
Compatibility: Supported by AGS 3.4.0 and later versions.
See Also: Game.AudioClipCount
static readonly Camera* Game.Camera;
Gets the primary camera. This is the default camera that is created automatically at the start of the game and cannot be deleted.
See Also: Game.Cameras, Camera, Camera.Create, Camera.Delete, Viewport.Camera
static readonly int Game.CameraCount
Gets the number of cameras.
See Also: Game.Cameras
static readonly Camera* Game.Cameras[int index];
Returns the Camera instance by its index. There's always at least primary camera at the index 0, more could be created in script using Camera.Create.
IMPORTANT: with the current implementation when you delete a custom camera in the middle all the following cameras will be shifted towards beginning of array, changing their indexes.
Example:
for (int i = 0; i < Game.CameraCount; i++) {
Game.Cameras[i].SetAt(0, 0);
}
This script positions all existing cameras at the room's top-left corner.
See Also: Game.Camera, Game.CameraCount, Camera.Create, Camera.Delete, Viewport.Camera
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.CharacterCount
Returns the number of characters in the game.
This is useful for script modules if you need to iterate through all the characters for some reason.
Example:
Display("The game has %d characters.", Game.CharacterCount);
readonly static int Game.DialogCount
Returns the number of dialogs in the game.
This is useful for script modules if you need to iterate through all the dialogs for some reason. Valid dialogs are numbered from 0 to DialogCount - 1.
Example:
Display("The game has %d dialogs.", Game.DialogCount);
Compatibility: Supported by AGS 3.0.2 and later versions.
readonly static String Game.FileName
Gets the filename that the game is running from. This will usually be the name of the EXE file, but could also be "ac2game.dat" if you are just running the game using ACWIN.EXE.
Example:
Display("The main game file is: %s", Game.FileName);
will display the game filename.
See Also: Game.Name
readonly static int Game.FontCount
Returns the number of fonts in the game.
This is useful for script modules if you need to iterate through all the fonts for some reason.
Example:
Display("The game has %d fonts.", Game.FontCount);
(Formerly known as global function GetMessageText, which is now obsolete)
readonly static String Game.GlobalMessages[int message]
Gets the text of the specified global message. The message number is one of the global message numbers from 500 to 999.
If an invalid message number is supplied, null will be returned. Otherwise, the message contents will be returned.
NOTE: Global Messages were a feature of AGS 2.x and are now obsolete. You will not need to use this property in new games.
Example:
String message = Game.GlobalMessages[997];
Display("Global message 997 says: %s", message);
will display global message 997.
(Formerly known as GetGlobalString, which is now obsolete)
(Formerly known as SetGlobalString, which is now obsolete)
static String Game.GlobalStrings[index]
Gets/sets global string index. Global strings provide you with an easy way to share string variables between scripts. There are 50 available global strings, with index values from 0 to 49.
Example:
Game.GlobalStrings[15] = "Joe";
Display("Global string 15 is now: %s", Game.GlobalStrings[15]);
will set global string 15 to contain "Joe".
See Also: GetGlobalInt, SetGlobalInt
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.GUICount
Returns the number of GUIs in the game.
This is useful for script modules if you need to iterate through all the GUIs for some reason. Valid GUIs are numbered from 0 to GUICount minus 1.
Example:
Display("The game has %d GUIs.", Game.GUICount);
static int Game.IgnoreUserInputAfterTextTimeoutMs;
Gets/sets the length of time for which user input is ignored after some text is automatically removed from the screen.
When AGS is configured to automatically remove text after a certain time on the screen, sometimes the player might try to manually skip the text by pressing a key just as it is removed automatically, and thus they end up skipping the next text line by accident. This property is designed to eliminate this problem.
This property is specified in milliseconds (1000 = 1 second), and is set to 500 by default.
Example:
Game.IgnoreUserInputAfterTextTimeoutMs = 1000;
will tell AGS to ignore mouse clicks and key presses for 1 second after text is automatically removed from the screen.
Compatibility: Supported by AGS 3.2.0 and later versions.
See Also: Game.MinimumTextDisplayTimeMs, Game.TextReadingSpeed, Speech.SkipStyle
(Formerly known as game.in_cutscene, which is now obsolete)
static bool Game.InSkippableCutscene
Returns whether the game is currently between a StartCutscene and EndCutscene, and therefore whether the player is able to skip over this part of the game.
When the player chooses to skip a cutscene all of the script code is run as usual, but any blocking commands are run through without the usual game cycle delays. Therefore, you should never normally need to use this property since cutscenes should all be handled automatically, but it could be useful for script modules.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example below.
Example:
if (Game.InSkippableCutscene)
{
Display("The player might never see this message!");
}
will display a message if we are within a cutscene
Compatibility: Supported by AGS 3.0.1 and later versions.
See Also: StartCutscene, EndCutscene, Game.SkippingCutscene
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.InventoryItemCount
Returns the number of inventory items in the game. This is the total number of items that you created in the Inventory Items pane of the editor, not how many the player is currently carrying.
Example:
Display("The game has %d inventory items.", Game.InventoryItemCount);
static int Game.MinimumTextDisplayTimeMs;
Gets/sets the minimum length of time that text is displayed on the screen. AGS automatically adjusts the length of time that text is displayed for depending on the length of the text (and you can customize this calculation with Game.TextReadingSpeed), but for very short statements like "Hi!", you might want the text to remain for longer.
This property is specified in milliseconds (1000 = 1 second), and is set to 1000 by default.
NOTE: This property is ignored if lip-sync is enabled, or if the General Settings are set not to allow text to be automatically removed.
Example:
Game.MinimumTextDisplayTimeMs = 2000;
will ensure that even the shortest "Hi!" text line will be displayed for at least 2 seconds
Compatibility: Supported by AGS 3.1.2 and later versions.
See Also: Character.SpeechAnimationDelay, Game.IgnoreUserInputAfterTextTimeoutMs Game.TextReadingSpeed
readonly static int Game.MouseCursorCount
Returns the number of mouse cursors in the game.
This is useful for script modules if you need to iterate through all the cursors for some reason.
Example:
Display("The game has %d cursors.", Game.MouseCursorCount);
static String Game.Name
Gets/sets the game's name. This is initially set in the General Settings pane of the editor, but you can change it at run-time in order to change the window title of your game.
Example:
Display("The game name is: %s", Game.Name);
will display the game name.
See Also: Game.FileName
(Formerly known as global function SetNormalFont, which is now obsolete)
static FontType Game.NormalFont
Gets/sets the font used for all in-game text, except speech. The font number must be a valid number from the Fonts pane of the editor.
More specifically, AGS uses the Normal Font for the following:
- Display
- DisplayTopBar
- dialog options text
- the built-in save and restore dialogs
The Normal Font is font 0 by default.
Example:
Game.NormalFont = eFontSpecial;
will change the normal font to the font "Special".
See Also: Game.SpeechFont
(Formerly known as game.skipping_cutscene, which is now obsolete)
static bool Game.SkippingCutscene
Returns whether the player has elected to skip the current cutscene. This will return true if the game is between a StartCutscene and EndCutscene command, and the player has chosen to skip it.
Although cutscene skipping is handled automatically by AGS, you can use this property to optimise the process by bypassing any lengthy blocks of code that don't need to be run if the cutscene is being skipped over.
NOTE: This is a static function, and thus need to be called with
Game. in front of it. See the example below.
Example:
if (!Game.SkippingCutscene)
{
aScaryMusic.Play();
Wait(100);
Game.StopAudio();
}
will only attempt to play the music if the player is not skipping the cutscene.
Compatibility: Supported by AGS 3.0.1 and later versions.
See Also: StartCutscene, EndCutscene, Game.InSkippableCutscene
(Formerly known as global function SetSpeechFont, which is now obsolete)
static FontType Game.SpeechFont;
Gets/sets the font used for character speech. The font number you supply must be a valid number from the Fonts pane of the editor.
The Speech Font is font 1 by default.
Example:
Game.SpeechFont = eFontStandard;
will change the speech font to "Standard".
See Also: Game.NormalFont
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.SpriteHeight[int slot]
Returns the height of the specified sprite.
The height will be returned in the usual 320x200-resolution co-ordinates. If an invalid sprite slot is supplied, 0 will be returned.
Example:
Display("Object 0's sprite is sized %d x %d.", Game.SpriteWidth[object[0].Graphic],
Game.SpriteHeight[object[0].Graphic]);
See Also: Game.SpriteWidth
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.SpriteWidth[int slot]
Returns the width of the specified sprite.
The width will be returned in the usual 320x200-resolution co-ordinates. If an invalid sprite slot is supplied, 0 will be returned.
Example:
Display("Object 0's sprite is sized %d x %d.", Game.SpriteWidth[object[0].Graphic],
Game.SpriteHeight[object[0].Graphic]);
See Also: Game.SpriteHeight
(Formerly known as game.text_speed, which is now obsolete)
static int Game.TextReadingSpeed;
Gets/sets the speed at which AGS assumes the player can read text, and therefore how long speech stays on the screen before it is automatically removed.
Specifically, the TextReadingSpeed is the number of characters of text that the player can read in a second. It is 15 by default. A higher number will therefore lead to the text being removed more quickly.
It is useful to link this setting to a GUI Slider on some sort of Control Panel GUI so that the player can adjust it depending on their reading speed.
NOTE: This property is ignored if lip-sync is enabled, or if the General Settings are set not to allow text to be automatically removed.
Example:
Game.TextReadingSpeed = 7;
sets the text reading speed to half the default, which will leave speech on-screen for twice as long as usual.
Compatibility: Supported by AGS 3.1.2 and later versions.
See Also: Character.SpeechAnimationDelay, Game.MinimumTextDisplayTimeMs, Speech.SkipStyle
(Formerly known as GetTranslationName, which is now obsolete)
readonly static String Game.TranslationFilename;
Gets the name of the current translation filename (without the ".tra" extension). This may be useful if you want to use a different graphic somewhere depending on which translation is being used.
If no translation is in use, a blank string is returned.
Example:
if (Game.TranslationFilename == "German") {
Display("You are using the German translation.");
}
See Also: Game.ChangeTranslation, IsTranslationAvailable
readonly static bool Game.UseNativeCoordinates
Returns whether the game is using native co-ordinates. If native co-ordinates are in use, then all X, Y, Top, Bottom, Width and Height variables in the game will be expected to reflect the resolution of the game.
If this is false, then the game is operating in backwards-compatible mode where all co-ordinates are low-res.
If the game resolution is 320x200 or 320x240, this setting has no effect.
This property is read-only; it is not possible to change this setting at run-time.
Example:
if (Game.UseNativeCoordinates)
{
Display("The player is at %d, %d -- REALLY!", player.x, player.y);
}
else
{
Display("The player is at %d, %d in the old-school system", player.x, player.y);
}
Compatibility: Supported by AGS 3.1.0 and later versions.
(Formerly part of GetGameParameter, which is now obsolete)
readonly static int Game.ViewCount
Returns the number of views in the game.
This is useful for script modules if you need to iterate through all the views for some reason. Valid views are numbered from 1 to ViewCount.
Example:
Display("The game has %d views.", Game.ViewCount);
Getting Started in AGS
Editor Reference
- Music and sound
- Distributing your game
- Backing up your game
- The text parser
- Translations
- Global variables
- Custom Properties
- Plugins
- Lip sync
- New Game templates
- Debugging features
- Auto-number speech files
- Integration with Windows
- Source Control integration
Engine
Scripting
- Scripting tutorial part 1
- Scripting tutorial part 2
- Pointers in AGS
- Calling global functions from local scripts
- The script header
- String formatting
- Multiple Scripts
- Understanding blocking scripts
- Dynamic Arrays
- Extender functions
- Game variables
- Predefined global script functions
- repeatedly_execute (_always)
- Custom dialog options rendering
- Built-in enumerated types
- Script language keywords
- AudioChannel functions and properties
- AudioClip functions and properties
- Character functions and properties
- DateTime functions and properties
- Dialog functions and properties
- DialogOptionsRenderingInfo functions and properties
- DrawingSurface functions and properties
- DynamicSprite functions and properties
- File functions and properties
- Game / Global functions
- GUI functions and properties
- GUI control functions and properties
- GUI Button functions and properties
- GUI InvWindow functions and properties
- GUI Label functions and properties
- GUI List Box functions and properties
- GUI Slider properties
- GUI Text Box functions and properties
- Hotspot functions and properties
- Inventory item functions and properties
- Maths functions and properties
- Mouse functions and properties
- Multimedia functions
- Object functions and properties
- Overlay functions and properties
- Palette functions
- Parser functions
- Region functions and properties
- Room functions
- Screen functions
- Speech functions and properties
- String functions
- System functions and properties
- Text display / Speech functions
- ViewFrame functions and properties
Working on Legacy games
Upgrading from a previous version
- Upgrading to AGS 2.7
- Upgrading to AGS 2.71
- Upgrading to AGS 3.0
- Upgrading to AGS 3.1
- Upgrading to AGS 3.2
- Upgrading to AGS 3.3
- Upgrading to AGS 3.3.5
- Upgrading to AGS 3.4
- Upgrading to AGS 3.4.1
Legal Notice
Getting in touch