AbortGame
CallRoomScript
ClaimEvent
Debug
DeleteSaveSlot
DisableInterface
EnableInterface
EndCutscene
GetGameOption
GetGameParameter
GetGameSpeed
GetGlobalInt
GetGlobalString
GetGraphicalVariable
GetLocationName
GetLocationType
GetSaveSlotDescription
GetTextHeight
GetTextWidth
GetTranslation
GetTranslationName
GiveScore
InputBox
InventoryScreen
IsGamePaused
IsInterfaceEnabled
IsInteractionAvailable
IsKeyPressed
IsTimerExpired
IsTranslationAvailable
MoveCharacterToHotspot
MoveCharacterToObject
PauseGame
ProcessClick
QuitGame
Random
RestartGame
RestoreGameDialog
RestoreGameSlot
RunAGSGame
SaveGameDialog
SaveGameSlot
SaveScreenShot
SetAmbientTint
SetGameOption
SetGameSpeed
SetGlobalInt
SetGlobalString
SetGraphicalVariable
SetMultitaskingMode
SetNormalFont
SetRestartPoint
SetTextWindowGUI
SetTimer
SkipUntilCharacterStops
StartCutscene
UpdateInventory
UnPauseGame
Wait
WaitKey
WaitMouseKey
AbortGame(string message, ...)Aborts the game and returns to the operating system.
The standard AGS error dialog is displayed, with the script line numbers and call stack, along with message (which can include %d and %s Display-style tokens).
You can use this function rather than QuitGame if you are writing some debugging checks into your script, to make sure that the user calls your functions in the correct way.
This command should ideally never be called in the final release of a game.
Example:
function MakeWider(int newWidth) {
if (newWidth < 10)
AbortGame("newWidth expects a width of at least 10!");
}
will abort the game if MakeWider is called with a parameter less than 10.SeeAlso: QuitGame
CallRoomScript (int value)Calls the on_call function in the current room script. This is useful for things like the text parser, where you want to check for general game sentences, and then ask the current room if the sentence was relevant to it.
The on_call function will be called in the current room script, with its value parameter having the value you pass here. This allows it to distinguish between different tasks, and saves you having to use a GlobalInt to tell it what to do.
If the current room has no on_call function, nothing will happen. No error will occur.
You write the on_call function into the room script ("Edit script" button on Room Settings pane), similar to the way you do dialog_request in the global script:
function on_call (int value) {
if (value == 1) {
// Check text input
if (Said("get apple"))
Display("No, leave the tree alone.");
}
}
The function doesn't get called immediately; instead, the engine will run it in due course,
probably during the next game loop, so you can't use any values set by it immediately.Once the on_call function has executed (or not if there isn't one), the game.roomscript_finished variable will be set to 1, so you can check for that in your repeatedly_execute script if you need to do something afterwards.
SeeAlso: The text parser documentation
ClaimEvent()This command is used in a room script or script module's on_key_press or on_mouse_click function, and it tells AGS not to run the global script afterwards.
For example, if your room script responds to the player pressing the space bar, and you don't want the global script's on_key_press to handle it as well, then use this command.
This is useful if you have for example a mini-game in the room, and you want to use some keys for a different purpose to what they normally do.
The normal order in which scripts are called for on_key_press and on_mouse_click is as follows:
Example:
if (keycode == ' ') {
Display("You pressed space in this room!");
ClaimEvent();
}
prevents the global script on_key_press from running if the player pressed the space bar.SeeAlso: Script events
Debug (int command, int data)This function provides all the debug services in the system. It performs various different tasks, depending on the value of the COMMAND parameter. If debug mode is off, then this function does nothing. This allows you to leave your script unaltered when you distribute your game, so you just have to turn off debug mode in the Room Editor.
The DATA parameter depends on the command - pass 0 if it is not used. All the valid values for the COMMAND parameter are listed below along with what they do:
0 All inventory - gives the current player character one of every
inventory item. This is useful for testing so that you don't have to
go and pick up items every time you test part of the game where they
are required.
1 Display interpreter version - the engine will display its version
number and build date.
2 Walkable from here - fills in the parts of the screen where the player
can walk from their current location. This is useful if you think the
path-finder is not working properly. Yellow areas are where the man
can walk. Blue areas are defined as walkable in the Room Editor, but
he cannot get to them from his current position. The unaltered parts
of the screen are not walkable.
3 Teleport - displays a dialog box asking for what room you want to go
to, and then calls ChangeRoom to teleport you there. Useful for skipping
parts of the game or going to a specific point to test something.
4 Show FPS - toggles whether the current frames per second is displayed
on the screen. Pass DATA as 1 to turn this on, 0 to turn it off.
See Also: Debugging features
DeleteSaveSlot (int slot)Deletes the save game in save slot number SLOT.
NOTE: if you specify one of the standard slots (1-20), then AGS will rearrange the other save games to make sure there is a sequence of slots from 1 upwards. Therefore, you will need to refresh any save game lists you have after calling this function.
Example:
DeleteSaveSlot (130);deletes save game slot 130 (which we should have saved earlier).
See Also: RestoreGameSlot, SaveGameSlot
DisableInterface ()Disables the player interface. This works the same way as it is disabled while an animation is running: the mouse cursor is changed to the Wait cursor, and mouse clicks will not be sent through to the "on_mouse_click" function. Also, all interface buttons will be disabled.
NOTE: AGS keeps a count of the number of times DisableInterface is called. Every call to DisableInterface must be matched by a later call to EnableInterface, otherwise the interface will get permanently disabled.
Example:
DisableInterface();will disable the user’s interface.
See Also: EnableInterface, IsInterfaceEnabled
EnableInterface ()Re-enables the player interface, which was previously disabled with the DisableInterface function. Everything which was disabled is returned to normal.
Example:
EnableInterface();will enable the user’s interface.
See Also: DisableInterface, IsInterfaceEnabled
EndCutscene()Marks the end of a cutscene. If the player skips the cutscene, the game will fast-forward to this point. This function returns 0 if the player watched the cutscene, or 1 if they skipped it.
See Also: StartCutscene
GetGameOption (option)Gets the current setting of one of the game options, originally set in the AGS Editor Game Settings pane.
OPTION specifies which option to get, and its current value is returned.
The valid values for OPTION are listed in SetGameOption.
Example:
if (GetGameOption (OPT_ANTIGLIDE) == 1) {
Display("anti-glide mode is on!");
}
See Also: SetGameOption
GetGameParameter (parameter, int data1, int data2, int data3)Gets the value of various game properties which are wanted so rarely they don't have their own specific script command.
The possible values for PARAMETER are listed below. The data values depend on the command - if they are not required, simply pass them as 0.
| Parameter | Description |
| GP_SPRITEWIDTH | Returns the width of sprite slot DATA1 |
| GP_SPRITEHEIGHT | Returns the height of sprite slot DATA1 |
| GP_NUMLOOPS | Returns the number of loops in view DATA1 |
| GP_NUMFRAMES | Returns the number of frames in loop DATA2 of view DATA1 |
| GP_ISRUNNEXTLOOP | Returns 1 if loop DATA2 of view DATA1 has "Run next loop after this" checked |
| GP_FRAMESPEED | Returns frame speed setting of frame DATA3 in loop DATA2 of view DATA1 |
| GP_FRAMEIMAGE | Returns the sprite number of frame DATA3 in loop DATA2 of view DATA1 |
| GP_FRAMESOUND | Returns frame sound of frame DATA3 in loop DATA2 of view DATA1 |
| GP_NUMGUIS | Returns the number of GUIs in the game |
| GP_NUMOBJECTS | Returns the number of objects in the current room |
| GP_NUMCHARACTERS | Returns the number of characters in the game |
| GP_NUMINVITEMS | Returns the number of inventory items in the game |
Example:
if (GetGameParameter(GP_SPRITEWIDTH, 10, 0, 0) > 20) {
Display("Sprite 10 is wider than 20 pixels!");
}
GetGameSpeed ()Returns the current game speed (number of cycles per second).
Example:
if (GetGameSpeed() > 40) {
SetGameSpeed(40);
}
will always keep the game speed at 40 cycles per second (in case the user has raised it ) See Also: SetGameSpeed
GetGlobalInt (int index)Returns the value of global variable INDEX.
Example:
if (GetGlobalInt(20) == 1) {
// code here
}
will execute the code only if Global Integer 20 is 1.See Also: SetGlobalInt, GetGlobalString
GetGlobalString (int index, string buffer)Copies the current Global String INDEX into BUFFER. See SetGlobalString for more information.
Example:
string buffer; GetGlobalString (15, buffer);will get the value of global string 15 into buffer.
See Also: GetGlobalInt, SetGlobalString
GetGraphicalVariable (string variable_name);Returns the value of the interaction editor VARIABLE_NAME variable. This allows your script to access the values of variables set in the interaction editor.
Example:
if (GetGraphicalVariable("climbed rock")==1)
{ code here }
will execute the code only if interaction variable "climbed rock" is 1.See Also: GetGlobalInt, SetGraphicalVariable
GetLocationName (int x, int y, string buffer)Fills in BUFFER with 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 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 buffer; GetLocationName(mouse.x, mouse.y, buffer);will pass the location’s where the mouse is over name to the string buffer.
See Also: Hotspot.GetName, InventoryItem.GetName, GetLocationType, Object.GetName
GetLocationType(int x, int y)Returns what type of thing is at location (X,Y); whether it is a character, object, hotspot or nothing at all. This may be useful if you want to process a mouse click differently depending on what the player clicks on.
NOTE: The co-ordinates are screen co-ordinates, NOT room co-ordinates. See description of GetLocationName for more info.
The value returned is one of the following:
eLocationNothing nothing, GUI or inventory eLocationHotspot a hotspot eLocationCharacter a character eLocationObject an objectExample:
if (GetLocationType(mouse.x,mouse.y) == eLocationCharacter)
mouse.Mode = eModeTalk;
will set the cursor mode to talk if the cursor is over a character.See Also: Hotspot.GetAtScreenXY, GetLocationName, Object.GetAtScreenXY
GetSaveSlotDescription (int slot, string buffer)Gets the text description of save game slot SLOT into the provided BUFFER. If the slot number provided does not exist this function returns 0, if successful it returns 1.
Example:
string buffer; GetSaveSlotDescription(10,buffer);will pass the description of the save game slot 10 to buffer.
See Also: DynamicSprite.CreateFromSaveGame, RestoreGameSlot, SaveGameSlot
GetTextHeight(string text, int font, int width)Calculates the height on the screen that drawing TEXT in FONT within an area of WIDTH would take up.
This allows you to work out how tall a message displayed with a command like RawPrintMessageWrapped will be. WIDTH is the width of the area in which the text will be displayed.
The height is returned in normal 320-resolution pixels, so it can be used with the screen display commands.
Example:
int height = GetTextHeight("The message on the GUI!", 0, 100);
gBottomLine.SetPosition(0, 200 - height);
will move the BOTTOMLINE GUI so that it can display the text within the screen.See Also: GetTextWidth, RawPrint
GetTextWidth(string text, int font)Returns the width on the screen that drawing TEXT in FONT on one line would take up.
This could be useful if you manually need to centre or right-align some text, for example with the raw drawing routines.
The width is returned in normal 320-resolution pixels, so it can be used with the screen display commands.
Example:
int width = GetTextWidth("Hello!", 0);
RawPrint(160 - (width / 2), 100, "Hello!");
will print "Hello!" onto the middle of the background scene.See Also: GetTextHeight, RawPrint
GetTranslation (string original)Gets the translated equivalent of the supplied string. You do not normally need to use this since the game translates most things for you. However, if you have used an InputBox or other form of user input, and want to compare the user's input to a particular string, it cannot be translated automatically. So, you can do this instead.
Example:
string buffer;
InputBox ("Enter the password:", buffer);
if (StrComp (buffer, GetTranslation ("secret")) == 0) {
// it matched the current translation of "secret"
}
If there is no translation for the supplied string, it will be returned
unchanged, so it is always safe to use this function.See Also: IsTranslationAvailable
GetTranslationName (string buffer)Places the name of the current translation file into BUFFER. This may be useful if you want to use a different graphic somewhere depending on which translation is being used.
BUFFER is filled with the current translation filename (without the ".tra" extension). If no translation is in use, it is set to an empty string.
Returns 1 if a translation is in use, 0 otherwise.
Example:
string buffer;
GetTranslationName(buffer);
if (StrCaseComp(buffer, "German") == 0) {
Display("You are using the German translation.");
}
See Also: IsTranslationAvailable
GiveScore (int score)Adds SCORE to the player's score. This is preferable to directly modifying the variable since it will play the score sound, update any status lines and call the GOT_SCORE on_event function.
Note that SCORE can be negative, in which case the score sound is NOT played.
Example:
GiveScore(5);will give 5 points to the player.
InputBox (string prompt, string buffer)This function allows your script to read a string typed in by the user. When this function is called it pops up a window asking the user to type in a string, with PROMPT as the text in the window. What they type in will be copied into BUFFER.
Note that this function only allows small strings (about 20 characters) due to the size of the input box it uses.
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.
NOTE: This command displays a very basic input box, mainly useful for debugging purposes. 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.
Example:
string name;
InputBox("!What is your name?", 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: StringToInt
InventoryScreen ()Brings up the Sierra-style inventory window which allows the player to select and manipulate inventory items. If they select one, the cursor mode will be set to inventory-use (mode 4), and character[EGO].ActiveInventory will be set to the inventory item selected.
NOTE: This function does not actually bring up the window immediately; instead, it will show the window when the current script function finishes executing.
NOTE: If the player has no inventory items, global message 996 will be displayed.
IsGamePaused ()Returns 1 if the game is currently paused, or 0 otherwise. The game is paused when either the icon bar interface has been popped up, or a "script-only" interface has been displayed with GUI.Visible=true. While the game is paused, no animations or other updates take place.
Example:
if (IsGamePaused() == 1) UnPauseGame();will unpause the game if it’s paused.
See Also: GUI.Visible
IsInterfaceEnabled()Returns 1 if the player interface is currently enabled, 0 if it is disabled. The user interface is disabled while the cursor is set to the Wait cursor - ie. while the character is performing a blocking Walk, or other blocking action.
Example:
if (IsInterfaceEnabled())
DisableInterface();
will disable the user interface if it’s enabled.See Also: DisableInterface, EnableInterface
IsInteractionAvailable (int x, int y, int mode)Checks whether there is an interaction defined for clicking on the screen at (X,Y) in cursor mode MODE.
This function is very similar to ProcessClick, except that rather than carry out any interactions it encounters, it simply returns 1 if something would have happened, or 0 if unhandled_event would have been run.
This is useful for enabling options on a verb-coin style GUI, for example.
Example:
if (IsInteractionAvailable(mouse.x,mouse.y, eModeLook) == 0)
Display("looking here would not do anything.");
See Also: InventoryItem.IsInteractionAvailable,
ProcessClick
IsKeyPressed (int keycode)Tests whether the supplied key on the keyboard is currently pressed down or not. You could use this to move an object while the player holds an arrow key down, for instance.
KEYCODE is one of the ASCII codes, with some limitations: since it tests the raw state of the key, you CANNOT pass the Ctrl+(A-Z) or Alt+(A-Z) codes (since they are key combinations). You can, however, use some extra codes which are listed at the bottom of the section.
Returns 1 if the key is currently pressed, 0 if not.
NOTE: The numeric keypad can have inconsitent keycodes between IsKeyPressed and on_key_press. With IsKeyPressed, the numeric keypad always uses keycodes in the 370-381 range. on_key_press, however, passes different values if Num Lock is on since the key presses are interpreted as the number key rather than the arrow key.
Example:
if (IsKeyPressed(372) == 1) character[EGO].Walk(character[EGO].x, character[EGO].y+3);will move the character EGO upwards 3 pixels when the up arrow is pressed.
See Also: Mouse.IsButtonDown
IsTimerExpired (int timer_id)Checks whether the timer TIMER_ID has expired. If the timeout set with SetTimer has elapsed, returns 1. Otherwise, returns 0.
Note that this function will only return 1 once - after that, the timer is placed into an OFF state where it will always return 0 until restarted.
Example:
if (IsTimerExpired(1) == 1) {
Display("Timer 1 expired");
}
will display a message when timer 1 expires.See Also: SetTimer
IsTranslationAvailable ()Finds out whether the player is using a game translation or not.
Returns 1 if a translation is in use, 0 if not.
See Also: GetTranslation, GetTranslationName
MoveCharacterToHotspot (CHARID, int hotspot)Moves the character CHARID from its current location to the walk-to point for the specified hotspot. If the hotspot has no walk-to point, nothing happens.
This is a blocking call - control is not returned to the script until the character has reached its destination.
Example:
MoveCharacterToHotspot(EGO,6);will move the character EGO to the hotspot’s 6 "walk to point".
See Also: Hotspot.WalkToX, Hotspot.WalkToY, Character.Walk, MoveCharacterToObject
MoveCharacterToObject (CHARID, int object)Moves the character CHARID from its current location to a position just below the object OBJECT. This is useful for example, if you want the man to pick up an object. This is a blocking call - control is not returned to the script until the character has reached its destination.
Example:
MoveCharacterToObject (EGO, 0); object[0].Visible = false;Will move the character EGO below object number 0, then turn off object 0.
See Also: Character.Walk, MoveCharacterToHotspot
PauseGame ()Stops the engine processing character movement and animation, and other game features. This has the same effect on the game as happens when a script-only interface is popped up. The processing will not resume until you call the UnPauseGame function.
Example:
if (IsKeyPressed(32)==1) PauseGame();will pause the game if the player presses the space bar
See Also: UnPauseGame
ProcessClick (int x, int y, CursorMode)Simulates clicking the mouse on the location (X,Y) on the screen, in the specified cursor mode. Any conditions attached will be executed. For example,
ProcessClick (100, 50, eModeLook);will simulate clicking the mouse on co-ordinates (100,50) in the Look mode.
NOTE: This function ignores all interfaces and acts as though the point is directly visible. In other words, if the co-ordinates you pass happen to lie on a button on an interface, what actually happens will be as if the user clicked behind the interface onto the actual screen.
The available cursor modes are the ones you define on your Cursors tab (but with eMode prepended to them). Usually these are eModeWalkto, eModeLook, etc.
Example:
ProcessClick(mouse.x,mouse.y, eModeLook);will simulate a click in the LOOK MODE where the cursor is.
See Also: IsInteractionAvailable, Hotspot.RunInteraction
QuitGame(int ask_first)Exits the game and returns to the operating system.
If ASK_FIRST is zero, it will exit immediately. If ASK_FIRST is not zero, it will first display a message box asking the user if they are sure they want to quit.
Example:
QuitGame(0);will quit the game without asking the player to confirm.
See Also: AbortGame
Random (int max)Returns a random number between 0 and MAX. This could be useful to do various effects in your game.
NOTE: The range returned is inclusive - ie. if you do Random(3); then it can return 0, 1, 2 or 3.
Example:
int ran=Random(2); if (ran==0) character[EGO].ChangeRoom(1); else if (ran==1) character[EGO].ChangeRoom(2); else character[EGO].ChangeRoom(3);will change the current room to room 1,2 or 3 depending on a random result.
RestartGame ()Restarts the game from the beginning.
Example:
if (IsKeyPressed(365) == 1) RestartGame();will restart the game if the player presses the F7 key.
RestoreGameDialog ()Displays the restore game dialog, where the player can select a previously saved game position to restore.
The dialog is not displayed immediately; instead, it will be displayed when the script function finishes executing.
Example:
if (IsKeyPressed(363)=1 RestoreGameDialog();will bring up the restore game dialog if the player presses the F5 key.
See Also: RestoreGameSlot, SaveGameDialog
RestoreGameSlot (int slot)Restores the game position saved into slot number SLOT. You might want to use these specific slot functions if for example you only want to allow the player to have one save game position rather than the usual 20. If this slot number does not exist, an error message is displayed to the player but the game continues. To avoid the error, use the GetSaveSlotDescription function to see if the position exists before restoring it.
NOTE: The game will not be restored immediately; instead, it will be restored when the script function finishes executing.
Example:
RestoreGameSlot(30);will restore game slot 30 if this slot number exists.
See Also: GetSaveSlotDescription, RestoreGameDialog, SaveGameSlot
RunAGSGame (string filename, int mode, int data)Quits the current game, and loads up FILENAME instead. FILENAME must be an AGS game EXE or AC2GAME.AGS file, and it must be in the current directory.
MODE specifies various options about how you want to run the game. Currently the supported values are:
0 Current game is completely exited, new game runs as if it had been launched seperately 1 GlobalInt values are preserved and are not set to 0 for the new game.DATA allows you to pass an integer through to the next game. The value you pass here will be accessible to the loaded game by it reading the game.previous_game_data variable.
The save game slots are shared between the two games, and if you load a save slot that was saved in the other game, it will automatically be loaded.
Bear in mind that because the games must be in the same folder, they will also share the music.vox, speech.vox and so forth. This is a limitation of this command.
NOTE: The game you run will be loaded at the same resolution and colour depth as the current game; if you mismatch colour depths some nasty results will occur.
NOTE: Make sure that the game you want to run has a filename of 8 characters or less, or this command will fail in the DOS engine.
NOTE: The game you want to launch must have been created with the same point-version of AGS as the one you are launching it from. (version 2.xy - the X must be the same version between the two games).
Example:
RunAGSGame ("MyGame.exe", 0, 51);
will run the MyGame game, passing it the value 51.
SaveGameDialog ()Displays the save game dialog, where the player can save their current game position. If they select to save, then the game position will be saved.
NOTE: The dialog will not be displayed immediately; instead, it will be shown when the script function finishes executing.
Example:
if (keycode == 361) SaveGameDialog();will bring up the save game dialog if the player presses the F3 key.
See Also: RestoreGameDialog, SaveGameSlot
SaveGameSlot (int slot, string description)Saves the current game position to the save game number specified by SLOT, using DESCRIPTION as the textual description of the save position. Be careful using this function, because you could overwrite one of the player's save slots if you aren't careful.
The SaveGameDialog function uses slots numbered from 1 to 20, so if you don't want to interfere with the player's saves, I would recommend saving to slot numbers of 100 and above.
NOTE: The game will not be saved immediately; instead, it will be saved when the script function finishes executing.
Example:
SaveGameSlot(30, "save game");will save the current game position to slot 30 with the description "Save game".
See Also: DeleteSaveSlot, RestoreGameSlot, SaveGameDialog
SaveScreenShot (string filename)Takes a screen capture and saves it to disk. The FILENAME must end in either ".BMP" or ".PCX", as those are the types of files which can be saved. Returns 1 if the shot was successfully saved, or 0 if an invalid file extension was provided.
Example:
string input;
InputBox("Type the filename:", input);
StrCat(input, ".pcx");
SaveScreenShot(input);
will prompt the player for a filename and then save the screenshot with the filename the player typed.
SetAmbientTint(int red, int green, int blue, int saturation, int luminance)Tints all objects and characters on the screen to (RED, GREEN, BLUE) with SATURATION percent saturation.
This allows you to apply a global tint to everything on the screen. The RED, GREEN and BLUE parameters are from 0-255, and specify the colour of the tint.
The SATURATION parameter defines how much the tint is applied, and is from 0-100. A saturation of 100 will completely re-colourize the sprites to the supplied colour, and a saturation of 1 will give them a very minor tint towards the specified colour.
The LUMINANCE parameter allows you to adjust the brightness of the sprites at the same time. It ranges from 0-100. Passing 100 will draw the sprites at normal brightness. Lower numbers will darken the images accordingly, right down to 0 which will draw everything black.
The tint applied by this function is global. To turn it off, call this command again but pass the saturation as 0.
NOTE: This function only works in hi-colour games and with hi-colour sprites.
NOTE: This function overrides any specific region light levels or tints on the screen.
Example:
SetAmbientTint(0, 0, 250, 30, 100);will tint everything on the screen with a hint of blue.
See Also: RawDrawFrameTransparent, Character.Tint, Object.Tint
SetGameOption (option, int value)Changes one of the game options, originally set in the AGS Editor Game Settings pane.
OPTION specifies which option to change, and VALUE is its new value. Valid OPTIONs are listed below:
| Option | Values |
| OPT_WALKONLOOK | Walk to hotspot in look mode (0 or 1) |
| OPT_DIALOGOPTIONSGUI | Dialog options on GUI (0=none, otherwise GUI name/number) |
| OPT_ANTIGLIDE | Anti-glide mode (0 or 1) |
| OPT_DIALOGOPTIONSGAP | Pixel gap between options (0=none, otherwise num pixels) |
| OPT_WHENGUIDISABLED | When GUI is disabled, 0=grey out, 1=go black, 2=unchanged, 3=turn off |
| OPT_ALWAYSSPEECH | Always display text as speech (0 or 1) |
| OPT_PIXELPERFECT | Pixel-perfect click detection (0 or 1) |
| OPT_NOWALKMODE | Don't automatically move character in Walk mode (0 or 1) |
| OPT_FIXEDINVCURSOR | Don't use inventory graphics as cursors (0 or 1) |
| OPT_DONTLOSEINV | Don't automatically lose inventory items (0 or 1) |
| OPT_TURNBEFOREWALK | Characters turn before walking (0 or 1) |
| OPT_HANDLEINVCLICKS | Handle inventory clicks in script (0 or 1) |
| OPT_MOUSEWHEEL | Enable mouse wheel support (0 or 1) |
| OPT_DIALOGNUMBERED | Number dialog options (0 or 1) |
| OPT_DIALOGUPWARDS | Dialog options go upwards on GUI (0 or 1) |
| OPT_CROSSFADEMUSIC | Crossfade music tracks (0=no, 1=slow, 2=slowish, 3=medium, 4=fast) |
| OPT_ANTIALIASFONTS | Anti-alias rendering of TTF fonts (0 or 1) |
| OPT_THOUGHTGUI | Thought uses bubble GUI (GUI name/number) |
| OPT_TURNWHENFACING | Characters turn to face direction (0 or 1) |
| OPT_LIPSYNCTEXT | Whether lip-sync text reading is enabled (0 or 1) |
| OPT_RIGHTTOLEFT | Right-to-left text writing (0 or 1) |
| OPT_MULTIPLEINV | Display multiple inv items multiple times (0 or 1) |
| OPT_SAVEGAMESCREENSHOTS | Save screenshots into save games (0 or 1) |
| OPT_PORTRAITPOSITION | Speech portrait side (0=left, 1=right, 2=alternate, 3=xpos) |
The game settings which are not listed here either have a seperate command to change them (such as SetSpeechStyle), or simply cannot be changed at run-time (such as Letterbox Mode).
This command returns the old value of the setting.
Example:
SetGameOption (OPT_PIXELPERFECT, 0);will disable pixel-perfect click detection.
See Also: GetGameOption, SetSpeechStyle, SetTextWindowGUI
SetGameSpeed (int new_speed)Sets the maximum game frame rate to NEW_SPEED frames per second, or as near as possible to that speed. The default frame rate is 40 fps, but you can speed up or slow down the game by using this function. Note that this speed is also the rate at which the Repeatedly_Execute functions are triggered.
The NEW_SPEED must lie between 10 and 1000. If it does not, it will be rounded to 10 or 1000. Note that if you set a speed which the player's computer cannot handle (for example, a 486 will not be able to manage 80 fps), then it will go as fast as possible.
NOTE: Because the mouse cursor is repainted at the game frame rate, at very low speeds, like 10 to 20 fps, the mouse will appear to be jumpy and not very responsive.
NOTE: If you set the system.vsync variable to 1, the game speed will be capped at the screen's refresh rate, so you will be unable to set it higher than 60-85 (depending on the player's screen refresh).
Example:
SetGameSpeed(80);will set the game speed to 80.
See Also: GetGameSpeed
SetGlobalInt (int index, int value)Sets the global variable INDEX to VALUE. You can then retrieve this value from any other script using GetGlobalInt.
There are 500 available global variables, from index 0 to 499.
Example:
SetGlobalInt(10,1);will set the Global Integer 10 to 1.
See Also: GetGlobalInt
SetGlobalString (int index, string buffer)Sets the global string INDEX to have BUFFER as its contents. You can then retrieve this value from any other script in your game using the GetGlobalString function.
There are 50 available global strings, with INDEX values from 0 to 49.
Example:
SetGlobalString (15, "Joe");will set global string 15 to contain "Joe".
See Also: GetGlobalString, SetGlobalInt
SetGraphicalVariable(string variable_name, int value);Sets the interaction editor VARIABLE_NAME variable to VALUE. This allows your script to change the values of variables set in the interaction editor.
Example:
SetGraphicalVariable("climbed rock", 1);
will set the interaction editor "climbed rock" variable to 1.See Also: GetGraphicalVariable
SetMultitaskingMode (int mode)Allows you to set what happens when the user switches away from your game.
If MODE is 0 (the default), then if the user Alt+Tabs out of your game, or clicks on another window, the game will pause and not continue until they switch back into the game.
If MODE is 1, then the game will continue to run in the background if the user switches away (useful if, for example, you are just making some sort of jukebox music player with AGS).
Note that mode 1 does not work with some graphics cards in full-screen mode, so you should only rely on it working when your game is run in windowed mode.
Cross-Platform Support
Windows: Yes
MS-DOS: No
Linux: Yes
Example:
SetMultitaskingMode (1);will mean that the game continues to run in the background.
SetNormalFont (int font_number)Changes the font used for all in-game text, except speech. FONT_NUMBER must be from 0 to the number of fonts you have. By default the only options are 0 and 1.
Example:
SetNormalFont(4);will change the normal font to the font number 4.
See Also: SetSpeechFont
SetRestartPoint ()Changes the game restart point to the current position. This means that from now on, if the player chooses the Restart Game option, it will return here.
This function is useful if the default restart point doesn't work properly in your game - just use this function to move it.
SetTextWindowGUI (int gui)Changes the GUI used for text windows to the specified GUI. This overrides the "text windows use GUI" setting in the editor.
You can pass -1 as the GUI number to go back to using the default white text box.
Example:
SetTextWindowGUI (4);will change Textwindow GUI 4 to be used for displaying text windows in future.
SetTimer (int timer_id, int timeout)Starts timer TIMER_ID ticking - it will tick once every game loop (normally 40 times per second), until TIMEOUT loops, after which it will stop. You can check whether the timer has finished by calling the IsTimerExpired function.
Pass TIMEOUT as 0 to disable a currently running timer.
There are 20 available timers, with TIMER_IDs from 1 to 20.
Example:
SetTimer(1,1000);will set the timer 1 to expire after 1000 game cycles.
See Also: IsTimerExpired
SkipUntilCharacterStops(CHARID)Skips through the game until the specified character stops walking, a blocking script runs, or a message box is displayed.
The purpose of this command is to mimic the functionality in games such as The Longest Journey, where the player can press ESC to instantly get the character to its destination. It serves as a handy feature to allow you to give the player character a relatively slow walking speed, without annoying the player by making them wait ages just to get from A to B.
If the specified character is not moving when this function is called, nothing happens.
Example: (in on_key_press)
if (keycode == 27) SkipUntilCharacterStops(EGO);This means that if the player presses ESC, the game will skip ahead until EGO finishes moving, or is interrupted by a Display command or a blocking cutscene.
See Also: StartCutscene
StartCutscene(CutsceneSkipType)Marks the start of a cutscene. Once your script passes this point, the player can choose to skip a portion by pressing a key or the mouse button. This is useful for things like introduction sequences, where you want the player to be able to skip over an intro that they've seen before.
The CutsceneSkipType determines how they can skip the cutscene:
eSkipESCOnly by pressing ESC only eSkipAnyKey by pressing any key eSkipMouseClick by clicking a mouse button eSkipAnyKeyOrMouseClick by pressing any key or clicking a mouse button eSkipESCOrRightButton by pressing ESC or clicking the right mouse buttonYou need to mark the end of the cutscene with the EndCutscene command.
Be very careful with where you place the corresponding EndCutscene command. The script must pass through EndCutscene in its normal run in order for the skipping to work - otherwise, when the player presses ESC the game could appear to hang.
See Also: EndCutscene, SkipUntilCharacterStops
UpdateInventory ()Updates the on-screen inventory display. If you add or remove inventory items manually (ie. by using the InventoryQuantity array rather than the AddInventory/LoseInventory functions), the display may not get updated. In this case call this function after making your changes, to update what is displayed to the player.
Note that using this function will reset the order that items are displayed in the inventory window to the same order they were created in the editor.
See Also: Character.AddInventory, Character.LoseInventory, Character.InventoryQuantity
UnPauseGame ()Resumes the game.
Example:
if (IsGamePaused() == 1)
UnPauseGame();
will unpause the game if it is paused.See Also: PauseGame
Wait (int time)Pauses the script and lets the game continue for TIME loops. There are normally 40 loops/second (unless you change it with SetGameSpeed), so using a value of 80 will wait 2 seconds. Note that no other scripts can run while the Wait function is in the background.
Example:
character[EGO].Walk(120, 140, eBlock, eWalkableAreas); Wait(80); character[EGO].FaceLocation(1000,100);will move the character EGO to 120,140, wait until he gets there then wait for 2 seconds (80 game cycles) and then face right.
See Also: WaitKey, WaitMouseKey
WaitKey (int time)Pauses the script and lets the game continue until EITHER:
(a) TIME loops have elapsed, or
(b) the player presses a key
Returns 0 if the time elapsed, or 1 if the player interrupted it.
Example:
WaitKey(200);will pause the script and wait until 5 seconds have passed or the player presses a key.
See Also: Wait, WaitMouseKey
WaitMouseKey (int time)Pauses the script and lets the game continue until EITHER:
(a) TIME loops have elapsed, or
(b) the player presses a key, or
(c) the player clicks a mouse button
Returns 0 if the time elapsed, or 1 if the player interrupted it.
Example:
WaitMouseKey(200);will pause the script and wait until 5 seconds have passed or the player presses a key or clicks the mouse.
| Browser Based Help. Published by chm2web software. |