A.G.S. v2.21
Text Script Commands Manual by Spyros

CapturedPrint (int x, int y, string text, ...)
This command is similar to the "Display" command except that it only works while the screen is captured, and it does not wrap the text. The specified text is printed at co-ordinates (X,Y). Unlike the Display command, the text remains on-screen and does not wait for a keypress to remove it. This allows you to display multiple messages at once while the screen is captured.
Example:
CapturedPrint (100,20,"You have %d points of energy", energy);

CaptureScreen (int colour)
Sets up the screen so that the script has complete control over what is displayed. This is useful for screens like the QFG series statistics screen, where you want to display information to the player. COLOUR is the colour index with which the screen will be cleared. You can find out the colour of the various colours by using the Palette Manager in the Room Editor. While the screen is captured, all interfaces are disabled. You can use the "on_mouse_click" and "on_key_press" functions to call EndCapture to release the screen.
Example:
CaptureScreen (20);

CreateGraphicOverlay (int x, int y, int slot, int transparent)
Creates a screen overlay containing a copy of the image from SLOT in the Sprite Manager. The image is placed at (X,Y) on the screen (these are screen co-ordinates, not room co-ordinates). If TRANSPARENT is 1 then the overlay will be drawn in the same way as characters/objects, if it is 0 then the a black rectangle will be painted behind the sprite.
See the description of CreateTextOverlay for more on overlays.
Example:
CreateGraphicOverlay (100,20,234,1);

CreateTextOverlay (int x, int y, int width, int font, int color, string text)
Creates a screen overlay containing the text you pass at the position specified. A screen overlay looks identical to the way speech text is
displayed in conversations, except that with this command the text stays on the screen until either you remove it with RemoveOverlay, or the player goes to a different room, in which case it is automatically removed.
The X and Y parameters specify the upper-left corner of where the text will be written. WIDTH is the width, in pixels, of the text area. FONT is the font number from roomedit to use (0 is the normal font, 1 is the speech font). COLOR is the text color - use one of the colours from 1 to 15. Finally, TEXT is obviously the text that gets displayed. The function returns the Overlay ID, which you use later to reposition
and remove the overlay.
NOTE: screen overlays, in the same way as objects, slow down the game while displayed.
NOTE: there is currently a maximum of 3 overlays displayed at any one time
Example:
CreateTextOverlay (100,20,50, 1, 23, "House");

DisableHotspot (int hsnum)
Disables hotspot number HSNUM in the current room. All areas of the screen that were previously HSNUM now act as type 0 (no hotspot). You can turn it back on later with the EnableHotspot command.
This command permanently disables the hotspot - that is, it will not be reset when the player re-enters the room. The only way of turning the
hotspot back on is to use the EnableHotspot command
Example:
DisableHotspot(9);

EnableHotspot (int hsnum)
Turns hotspot HSNUM back on. Use this to re-enable a hotspot which you turned off earlier with the DisableHotspot command.
Example:
EnableHotspot(9);
 
EndCapture()
Ends the script's control over the screen and restores what was there previously.
Example:
EndCapture();

FadeIn (int speed)
Fades in from a black screen to the current palette. This is used to restore the screen after a FadeOut call. SPEED is from 1 (slowest) to 64 (fastest).
Note: This is a blocking function.
Note: This function does not work in hi-color modes.
Example:
FadeIn(35);

FadeOut (int speed)
Fades the screen out to black. SPEED is the speed of the fade, from 1 (slowest) to 64 (instant). You can restore the screen with FadeIn.
Note: This is a blocking function.
Note: This function is slow in hi-color modes.
Example:
FadeOut(35);

FlipScreen (int way)
Flips the screen round either the horizontal or vertical axis, or both. This function is for special effects only - all co-ordinates remain the
same and it doesn't effect any other script functions. The value of WAY selects:
0 normal
1 horizontal-flip (upside-down)
2 vertical-flip (left-to-right)
3 both (upside-down and backwards)
NOTE: This function is still a bit buggy - black parts of the screen may
show up wrong, and and pop-up messages will flip the screen back to normal.
Example:
FlipScreen(2);

GetBackgroundFrame()
Returns the number of the current background being displayed. In a room without animating backgrounds, this will always return 0. Otherwise, the current frame number is returned from 0 to 4.
Example:
GetBackgroundFrame();

GetHotspotAt (int x, int y)
Returns the number of the hotspot at SCREEN co-ordinates (X,Y). If there is no hotspot there, or if invalid co-ordinates are specified,
returns 0. See the description of GetLocationName for more on screen co-ordinates.
Example:
GetHotspotAt(236,35);

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: 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:
GetLocationName(mouse.x, mouse.y, buffer);

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 means that the location is:
0 nothing, GUI or inventory
1 a hotspot
2 a character
3 an object
Example:
GetLocationType(245,45);

GetViewportX ()
Returns the X-offset of the current viewport in a scrolling room. This allows you to find out what part of the room the player is looking at.
The co-ordinate returned is the left edge of the screen, and so it can have a value between 0 and (ROOM WIDTH - 320).
If the room is a non-scrolling room, returns 0.
See the SetViewport function description for more information.
Example:
GetViewportX();

GetViewportY ()
Returns the Y-offset of the current viewport in a scrolling room. This allows you to find out what part of the room the player is looking at.
The co-ordinate returned is the top edge of the screen, and so it can have a value between 0 and (ROOM HEIGHT - 200).
If the room is a non-scrolling room, returns 0.
Example:
GetViewportY();

MoveOverlay (int overlay_id, int x, int y)
Repositions screen overlay OVERLAY_ID to have its upper-left corner at (X,Y). The move is instant (ie. it doesn't gradually glide over to the
new position).
Example:
MoveOverlay(2,300,245);

ReleaseViewport ()
Releases the lock on the screen viewport, allowing it to automatically scroll around following the player character as normal.
Example:
ReleaseViewport();

RemoveOverlay (int overlay_id)
Removes the specified overlay from the screen. OVERLAY_ID is the value returned from the overlay creation functions like CreateTextOverlay.
Example:
RemoveOverlay(3);

RemoveWalkableArea (int areanum)
Removes the walkable areas in colour AREANUM from the current room. You can put the area back with RestoreWalkableArea.
NOTE: When the player leaves the screen, all the walkable areas are reset. Therefore, if you want an area to remain off when they leave the screen, you will need to set a flag, then run the RemoveWalkableArea command in the "Player enters screen" event when they return.
Example:
RemoveWalkableArea(3);

RestoreWalkableArea (int areanum)
Makes the area AREANUM walkable again.
Example:
RestoreWalkableArea(3);

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:
SaveScreenShot("capture.bmp");

SetBackgroundFrame (int frame)
Locks the background to frame number FRAME of an animating-background screen. (Values for FRAME are from 0 to 4). This allows you to use the animating backgrounds feature for another purpose - you can have two frames of the background, one for example with a spaceship crashed on it. Then, once the right event has happened, call SetBackgroundFrame in the Player Enters Screen event to set the background before the screen fades in.
Call SetBackgroundFrame(-1) to set the default animating frames. The frame lock is released when the game changes rooms.
Example:
SetBackgroundFrame(3);

SetScreenTransition (int trans_type)
Changes the default screen transition. trans_type can be one of the following:
TRANSITION_FADE
TRANSITION_INSTANT
TRANSITION_DISSOLVE
All future transitions will be done as specified until you call this function again.
Example:
SetScreenTransition(TRANSITION_FADE);

SetTextOverlay (int overlay_id, int x, int y, int width, int font, int color, string text)
Similar to CreateTextOverlay, except that this function replaces an existing overlay with the new text. This has two advantages over simply
using RemoveOverlay followed by CreateTextOverlay to change the text - it is one function call, and it allows you to keep the same overlay ID number.
Example:
SetTextOverlay(3,310,135,20,1,12,"House");

SetViewport (int x, int y)
Locks the screen viewport to having the top-left hand corner at (X,Y) in a scrolling room. This allows you to manually pan across a scrolling room or to have the screen follow a non-player character. The lock is released when you either call ReleaseViewport or the player changes rooms.
NOTE: The co-ordinates supplied are 320x200-scale co-ordinates, and will be automatically multiplied up by the engine.
NOTE: This function has no effect if the current room isn't a scrolling room. For example, to scroll around and follow character MAN in a specific room, put this in the room's repeatedly execute event:
Example:
SetViewport (character[MAN].x - 160, character[MAN].y - 110);

SetWalkBehindBase (int area, int baseline)
Changes the walk-behind AREA to have new BASELINE. This effectively allows you to turn walk-behinds on and off, although you can do other tricks with it as well. BASELINE is from 1 to the height of the room (normally 200) and moves the line which you set originally in RoomEdit.
Passing BASELINE as 0 disables the walk-behind area, so that the player  will always walk in front of it. Basically, if the character's feet are below BASELINE, he will be drawn in front of it, otherwise he will be drawn behind it.
Example:
SetWalkBehindBase(1,30);
 

ShakeScreen (int amount)
Shakes the screen to simulate, for example, an earthquake. AMOUNT is how much the screen shakes: 1 is hardly anything, and 25 is a lot.
Example:
ShakeScreen (20);

GLOBAL VARIABLES

*system.screen_height
The vertical screen resolution (200 or 400)
Example:
if (system.screen_height==200);
checks if the screen height is 200

*system.screen_width
 The horizontal screen resolution (320 or 640)
Example:
if (system.screen_width==320);
checks if the screen width is 320