ags.tex

\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
%\input{psbox.tex}
\newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
\newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
\newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
\newcommand{\indexit}[1]{#1\index{#1}}%
\newcommand{\inioption}[1]{{\bf {\tt #1}}\index{#1}}%
\parskip=10pt%
\parindent=0pt%
\backgroundcolour{255;255;225}\textcolour{0;0;0}% Has an effect in HTML only
\title{Adventure Game Studio 3.2.1}%
\author{by Chris Jones}%
\makeindex%
\begin{document}%

\maketitle%
\pagestyle{fancyplain}%
\bibliographystyle{plain}%
\pagenumbering{roman}%
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Welcome to Adventure Game Studio! This new Windows Help version of the manual should
help you get even more out of AGS. Enjoy!

\tableofcontents%

\chapter*{Copyright and terms of use}%
\setheader{{\it COPYRIGHT}}{}{}{}{}{{\it COPYRIGHT}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Copyright (c) 1999-2010 Chris Jones.

THE SOFTWARE IS PROVIDED 'AS-IS' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL CHRIS JONES BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE
POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

NO MONEY WHATSOEVER MAY BE CHARGED FOR ADVENTURE GAME STUDIO UNLESS EXPRESS
WRITTEN PERMISSION IS GIVEN BY THE AUTHOR. IF YOU PAID FOR THIS, THE SELLER
IS BREACHING THE TERMS OF DISTRIBUTION OF THIS APPLICATION.

AGS is an adventure game creation system. As such, it is provided to you in
good faith by the author. Chris Jones cannot be held responsible for the
contents of any works created with AGS, including but not limited to any which
infringe on copyright, are libellous or contain offensive material.
Please use AGS responsibly.

AGS allows user-made "Plugins" to be incorporated into games created by the system.
These Plugins can access all standard Windows functionality and are therefore
not protected from system functions as the scripting language is.
Chris Jones cannot be held responsible for any Plugins for AGS which you use
in your game. Any problems with the Plugin should be addressed to its author.

Anything you distribute which has been created with AGS \bf{MUST} retain the Version resources
unaltered in order to display the AGS version and copyright in the Version tab of the EXE
properties.

Please note that this is the \bf{only} evidence that remains that your game was created
with AGS - I do not place any splash screens or copyright messages in your game, and
leaving the version tab is all I ask.

TrueType font display uses ALFont by Javier Gonzalez and the Freetype project. Distributed
under the terms of the Freetype Project license.

OGG Vorbis player is alogg by Javier Gonzalez, using the Ogg Vorbis decoder, which is available
from http://www.xiph.org/ .  Copyright (c) 2002, Xiph.org Foundation

OGG Theora player is APEG by Chris Robinson, using the Ogg Theora decoder, which is
Copyright (C) 2002-2008 Xiph.Org Foundation and contributors.

MP3 player is almp3 v2.0.4, by Javier Gonzalez and the MPG123 team. It uses the mpg123 MP3 decoder,
and again is distributed under the terms of the GNU Lesser General Public License version 2.1.

Copyright information on the various other modules AGS uses can be found in the
\helpref{credits}{Credits} section. 

Pentium is a trademark of Intel corporation.
Windows is a trademark or registered trademark of Microsoft corp.

\chapter{Introduction}%

\Large{Adventure Game Studio}

\large{Copyright 1999-2010 Chris Jones}\hrule

Welcome to AGS!

Adventure Game Studio allows you to create your own point-and-click adventure
games like the old Sierra and Lucasarts classics, but with modern features
such as digital music and alpha blending. 

AGS is based around an easy-to-use IDE, where you can set up all the parts of
your game, and then add some script to process game events. Making a game
has never been so productive!

To get started, \helprefn{read the tutorial}{StartingOff}.

\section{System Requirements}%

To run the Editor, you need a Windows-based PC with at least 128 MB RAM and
the .NET 2.0 Framework installed (games you create do \bf{NOT} require the framework).

Any games you create have at least these system requirements:

\begin{itemize}\itemsep=0pt
\item Pentium or higher processor
\item 64 Mb RAM
\item Windows 98, ME, 2000, XP or Vista with DirectX 5 or above
\item Supports all DirectX-compatible sound and video cards
\end{itemize}

Depending on your game's resolution and colour depth, you may have higher requirements.
The processor required is as follows:

\begin{itemize}\itemsep=0pt
\item 320x200, 256-colour:  Any Pentium-class system
\item 640x400, 256-colour:  266 Mhz or above
\item 800x600, 256-colour:  500 Mhz or above recommended
\item 320x200, 16-bit colour:  233 Mhz or above
\item 640x400, 16-bit colour:  500 Mhz system minimum, may need faster if you use large objects
\item 800x600, 16-bit colour:  600 Mhz system minimum, may need faster if you use large objects
\item 320x200, 32-bit colour:  300 Mhz or above
\item 640x400, 32-bit colour:  700 Mhz system minimum, may need faster if you use large objects
\item 800x600, 32-bit colour:  900 Mhz system minimum, may need faster if you use large objects
\end{itemize}

These requirements are not an exact science though - game speed is affected by many
factors, including how many objects/characters are on the screen, whether background music
is playing, the complexity of your scripts, and more. The best way to determine the requirements
of your game are to test it on different computer configurations.


\chapter{The run-time engine}\index{Engine}\index{Run-time engine}\index{Interpreter}%

The engine (also called the "interpreter") is what runs your game and is what
the end player will use.

If you are using the default interface, then you use the right mouse button to
cycle between the available 'modes', and the left button to use the current
mode on the mouse position. You can also move the mouse to the top of the
screen to bring up the icon bar where you can directly select a mode.
To exit the engine, press Ctrl-Q. You can save your game position using F5
and restore with F7.

The controls described above work with the default setup; however, you can
customize your game to use a different interface and shortcut keys.


\section{The demo game}\index{Demo game}%

The first thing you'll probably want to do is to run the demo game. This
game will try to show you some of what AGS can do.

To run the demo, choose the "Open the Demo Game" option from the AGS folder
in your start menu. If you're looking for the files, they're located in the
All Users Application Data folder (this is for compatibility with Windows Vista's
new security filters).

\bf{NOTE:} The demo game is currently under development. It has various unfinished
or unimplemented areas.



\section{Graphics driver selection}\label{GraphicsDriver}\index{Direct3D engine}%

AGS has two different graphics drivers when run on Windows -- DirectDraw and Direct3D.

DirectDraw is the 'classic' software graphics driver, that AGS has used ever since
the initial Windows version was released. It's perfectly fine for simple games
that don't use many large sprites, tinting or alpha blending. It's also quite fast
at doing RawDrawing to the screen.

Direct3D is a new, hardware accelerated graphics driver. It uses the Direct3D 9.0 to
render the game in a fully hardware-accelerated environment. This means that the
game will run a lot faster if you use features such as alpha blending and tinting,
which are quite slow to perform in software mode. However, with Direct3D doing RawDraw
operations can be quite slow, and the driver won't work on all graphics cards.

No matter which you choose as your default graphics driver, the player can always
run the Setup program and switch to using the other driver if they are having problems
on their PC.

\bf{System Requirements}

\bf{DirectDraw}: any Windows-based PC with DirectX 5 or later installed ILBRK
\bf{Direct3D}: any Windows-based PC with DirectX 9.0 installed and a graphics card designed
for DirectX 8.1 or later (most cards manufactured from 2003 onwards).

If you get the error message "Graphics card does not support Pixel Shader 1.4" on startup,
this indicates that your graphics card is too old to run with the Direct3D driver. You
should choose the DirectDraw driver instead.

See Also: \helprefn{System.HardwareAcceleration property}{System.HardwareAcceleration}


\section{Run-time engine setup}\index{Setup}%

The engine Setup program allows the player to customize certain game settings.

Firstly, they can change the game resolution. If they do so, all your game
graphics will automatically be stretched or shrunk to fit, and the option is a
handy way for the player to start the game if their system won't run at the default
resolution for some reason.

They can also select to run the game in a window on the desktop rather than full-screen.
This will take a performance hit though, so it's always preferable to run full-screen.

The "Use 85 Hz display" option sets the monitor refresh rate to 85 Hz to run the game, which
eliminates flicker. However, this does not work on all monitors, and not at all on flat
panel displays, which is why it is disabled by default.

The "Force alternate letterbox resolution" option is only available for 320x200 and 640x400
modes, and tells AGS to actually run at 320x240 or 640x480 instead, with black 'letterbox'
borders at the top and bottom of the screen. This is useful because some computers no longer
support the 320x200 or 640x400 resolutions, but do support the letterboxed versions.

"Smooth scaled sprites" will apply anti-aliasing to scaled characters, in order to
give a smoother look to the resizing. This can slow down the game though, so it is off
by default.

Finally, the "Downgrade 32-bit graphics to 16-bit" option is only available for 32-bit games.
It allows people with slower PCs to choose to play the game at 16-bit instead, in order
to boost performance. If they use this, the graphical quality will reduce, but it should at
least allow them to play the game at a decent speed.


\chapter{Tutorial}%

This section will introduce you to the AGS by leading you through how to
create a simple game.

\section{Starting off}\label{StartingOff}%

The tutorial has now been updated for AGS 3.0. Follow the links below
to run through it.

\urlref{Tutorial Part 1 - Creating the game}{acintro1.htm}

\urlref{Tutorial Part 2 - Creating your first room}{acintro2.htm}

\urlref{Tutorial Part 3 - Hotspots and events}{acintro3.htm}

\urlref{Tutorial Part 4 - Objects}{acintro4.htm}

\urlref{Tutorial Part 5 - Managing inventory}{acintro5.htm}

\urlref{Tutorial Part 6 - Using your own graphics}{acintro6.htm}

\urlref{Tutorial Part 7 - Animations and cutscenes}{acintro7.htm}

\urlref{Tutorial Part 8 - Conversations}{acintro8.htm}

\urlref{Tutorial Part 9 - Cursors and fonts}{acintro9.htm}

For the latest version of the tutorials, always check the AGS website.


\section{Setting up the game}\label{Settingupthegame}%

Now that you know how to create a room, it's time to set up the game-wide
settings. These include inventory items, sprite graphics, palette setup
and other things which do not depend on individual rooms.

\subsection{Palette setup}\label{PalSetup}%

The first thing you need to do when you create a new game is to decide whether
you want to use 8-bit (palette-based) colour or 16-bit (hi-colour).
If you want to use 16-bit colour, you can still use 256-colour backgrounds and
sprites if you want to, but the engine will only run in a 16-bit colour
resolution, thus slowing it down.

If you want to use 8-bit (because it runs faster), you need to set up the
palette. This is because all sprite and background scene imports rely on the
palette setup to be the same. You \bf{CANNOT} use hi-colour sprites or backgrounds
in a 256-colour game.

You set your chosen colour depth by opening the General Settings pane and
adjusting the Colour Depth setting near the top of the list.

Now, choose the "Colours" pane. Here you will see the 256-colour
palette displayed in a grid. Most of the slots are marked "X" - these are the
slots reserved for the background pictures, and will be different in each
room. The other colours will be as they look here for the entire game. These
fixed colours allow things like the main character graphics, which must be
displayed on more than one screen, to work.

If you want, you can assign more or less colours to the backgrounds. To toggle
the background assignment on/off, click on the slot, then check the 
"This colour is room-dependant" box to swap the slot's status.

\bf{IMPORTANT NOTE:} \it{You must set up the palette as you want it before you start
making your game - if you change it later, you will have to re-import all the
sprites and background scenes.}

You can select multiple colour slots by clicking on the first slot, then
shift-clicking on the last slot in the range you want to select. You can then
toggle the background status of all the selected slots at once.

You can right-click in the palette grid to export the entire palette to 
a .PAL or PCX file which you can then use to read back into the Editor in 
a different game. 
If you choose to export to a pcx file, then a screen shot of the Palette Editor will
be saved as the picture. This way you can see all the game-wide colours in
the file.

The "Replace palette" option replaces the palette entries with those
entries from the PAL or PCX file you choose. It can read standard 768-byte
PAL files, SCI palette resources (renamed to extension .pal) and JASC PSP
palette files.

\subsection{Inventory}%

Most adventure games allow the player to carry a set of objects, which he can
then use to solve puzzles. Adventure Game Studio makes this inventory easy
for you to manage.

Every inventory item which the player may carry during the game at one time
or another is listed under the "Inventory items" node. Here, each item
has a number and a script name which you use in scripts to identify the object.
To create a new item, right-click on the "Inventory items" node.

Double-click on an inventory item to open it up. On the
left you'll see the graphic used for the object in the inventory window. To change
this, select the "Image" entry in the property grid on the right, and click the "..."
button.

The last thing to do with the inventory items is to define their events:
what happens when the player manipulates them in the inventory window. Click
the "Events" button (the lightning bolt button at the top of the property grid), 
which brings up a list which works identically to the hotspot events. 
The available events are described in the reference section.

\it{NOTE: Each character in the game carries their own set of inventory items.
This means, if you want to create a game like Day of the Tentacle, where the
player can control three different characters, each character will have a
separate inventory.}

You have two choices about how the inventory is displayed to the player -- a
built-in inventory window to get you started, and support for custom inventory
windows when you're ready to make your own.

The default option is the Sierra-style pop-up inventory window, which is
popped up by clicking on the Inventory icon on the icon bar. You can also have 
the current inventory item displayed in its own button on the icon bar by creating
a button on the GUI and setting its text to  (INV)  which stretches the item
picture to the button size, or  (INVNS)  which draws the inventory item
picture straight onto the button with no resizing. Finally, (INVSHR) , probably
the best option, will draw it at actual size if it will fit, or shrink it if not.

The other option is a custom inventory window. To use this, you
will need to edit the GUI to add it, so I will explain this later on.
While you are starting off with AGS, it is recommended to use the supplied
standard Sierra-style inventory window.

Finally, you may have noticed a "Hotspot Marker Settings" frame at the top of the
Inventory pane. This allows you to switch on an option so that when the 
selects an inventory item, the mouse cursor for it will have a dot and mini-crosshair
drawn on it, to show the player where the hotspot is. 
You can enter the colour for the centre dot and also for the surrounding 4 pixels.

\subsection{Importing your own sprite graphics}\index{Alpha blended sprites}%

When you were choosing the graphics for the object earlier in this tutorial,
you probably noticed that most of the graphics available didn't look up to
much. This is no problem, because you can import your own graphics using
the Sprite Manager.

Go to the \bf{Sprites} pane in the editor. Here, you will see
the complete sprite set for the game. There are two ways to import your
graphics - either overwrite an existing slot with your graphic, or
create a new slot for it.

To overwrite an existing sprite, right-click the sprite and select "Replace sprite
from file". To import a new slot, right-click on the background to the window
and choose "Import new sprite".

The graphic you choose to import must be at the same colour depth as your game 
(ie. if you are using hi-colour backgrounds, your sprites must be hi-colour,
and vice versa). AGS will attempt to convert the image if possible, but if
your game is 256-colour then the results of downgrading a hi-colour image
can be poor.

Then, the Import Sprite window will appear. Here, you need to decide which portion
of the image will be imported. You do this by right-clicking and dragging in the
image, which will produce a yellow rectangle showing the selection. Once you are
happy with it, left-click to import.
Alternatively, you can import the entire image with the "Import whole image" button.

\it{NOTE (256-colour only):
You may well find that the colours on your graphic look slightly strange in
the AGS Editor. This is because the sprites are only allocated, by default,
the first 41 of the palette colours (see the \helpref{palette section}{PalSetup}), so
your graphic will be remapped to this much smaller palette. If you find that
many of your imported sprites look strange, you can increase the number of
colours assigned to sprites, at the expense of background colours (again see
the section above for information on how to do this).

If your sprite will only be used in one room then alternatively you can
use the "use background palette" option, which will remap your graphic to
the palette of the room currently loaded, giving much better results. Note,
however, that if you do this, and then try and use the sprite on another
screen, its colours will most likely be screwed up. To use the room palette,
check the "use bkgrnd pal" check-box. Make sure to un-check this box before
you import any other sprites.}

NOTE: The transparent colour used by AGS is palette index 0 (for 256-colour
sprites) and RGB (255,0,255) for hi-color. Any pixels you draw on imported
sprites in these colours will be transparent.

You can group imported sprites into folders. This prevents the main sprite
list from becoming too long. By default, the Sprite Manager displays the
Main folder, which contains some graphics and a sub-folder called "Defaults".
Folders work the same way as Windows folders. Right-click on a folder in the
tree to rename it or make a sub-folder.

You can delete a folder by right-clicking on it and selecting the "Delete"
option; beware though that \bf{this will also delete all the sprites in the folder}.

* \it{NOTE: A few people have experienced problems when importing from clipboard,
in that the image colours get reversed (red becomes blue, blue becomes red, and so on)
when they are running Windows at 24-bit or 32-bit colour. If this happens to you, there
are two solutions: (a) turn down your desktop colour depth to 16-bit to run the AGS Editor,
or (b) import your sprites from files rather than the clipboard.}

\bf{Tiled sprite import}

You may have noticed a checkbox called "Tiled sprite import". Some people find
this a useful way of importing many frames of a character's animation at once.

In order for this to work, you need to have all your sprites lined up on your
source bitmap at even intervals. Then, use the "Import from file" option and import it
as usual. Check the "Tiled sprite import" box, and select the upper-left frame.

When you click the left mouse button, the selection rectangle will become un-filled
and now you can drag the mouse to define how many frames to import - they'll all
be enclosed by selection rectangles. Once you have the correct number, click the left
button again and they will all be imported.

\bf{Alpha blended sprites}

AGS supports alpha blended sprites if your game is 32-bit colour. In this case, you
need to import a PNG image with an alpha channel (you cannot paste alpha-blended
images from the clipboard).

When you do so, AGS will prompt you asking whether you want to use the image's alpha
channel or not. If you select Yes, then the sprite will be drawn alpha blended in
the game if it is used for a character, object, mouse cursor or GUI.

Note that if you use alpha blending, any overall transparency that you set (such
as Character.Transparency, Object.Transparency, GUI.Transparency) will be ignored.

\bf{NOTE:} Currently, alpha blended sprites cannot be antialiased, so if you have
the Anti Alias Sprites option turned on in Setup, it will not be applied to alpha-blended
characters.

\subsection{Introduction sequences}\index{Cutscenes}%

You can easily add intro, outro and cutscene sequences to your game. There
is no specific function to do these, but using the provided animation and
script commands you can create almost anything you might need.

Normally, the game will start in room 1. This is defined by the starting room
number of the player character. To change it, open up the player character's
Character pane, and change the StartingRoom number in the property grid.

\it{TIP: The starting room facility is also useful when testing your game - you
can make the game start in any room, at the point where you are testing it,
rather than having to keep playing the game through to get there.}

Cutscenes are created using the normal animation script commands, such as
Character.Walk, Object.SetView, and so forth. I would suggest you leave this
until you are more comfortable with AGS, and have some experience of how
to use these functions.

\subsection{Animations}\label{Views}\index{Views}%

In most games you will use some sort of animation during the game, whether
it be a flag waving in the breeze or the player bending over to pick something
up. The term "animation" refers to the ability to change the look of, and
move, objects.

Animations in AGS are managed using Views. A "view" is a set of one or more
"loops". A loop is a set of frames which, when put together, give the effect
of movement. Each frame in the view can be set a graphic and a speed.

Go to the editor's "Views" node, right-click it and select the "New view" 
option to create us a new, empty view. Double-click the new view to open it.
Each loop is displayed horizontally with its number at the left hand side,
frames going out to the right. To add a frame, click the grey "New frame"
button. To delete a frame, right-click it.

To change a frame's graphic, double-left-click it. The sprite list screen
will be displayed (you may remember this from the Object graphic selection)
where you can choose the graphic you want to use for this frame.

Note that for walking animations, the first frame in each loop is reserved for
the standing frame, and when walking it will only cycle through from the second
frame onwards.

You select a frame by left-clicking it -- when you do so, the property grid
will update with information about the frame. One of these settings is
called "Delay", which is the frame's \bf{relative} speed. The larger the number,
the longer the frame stays (ie. the slower it is). When the animation is run,
an overall animation speed will be set, so the actual speed of the frame
will be:  overall_speed + frame_speed  . Note that you can use negative
numbers for the frame delay to make it particularly fast, for example setting
it to -3 means that the frame will stay for hardly any time at all. ILBRK
Animation speed is specified in Game Loops (ie. animation speed 4 will show the
frame for 4 game loops - at 40fps, that would be 0.1 seconds).

The "Sound" propery allows you to enter a sound number that will be played
when this frame becomes visible on the screen.
This is especially useful for footstep sounds.

You run an animation by using the script animation commands, which will 
be explained in detail later. Briefly, to animate an object, you first 
of all need to set the object's view to the correct view number (use 
the Object.SetView script command), and then use the Object.Animate
script command to actually start the animation. 

\subsection{Characters}\index{Idle animations}%

A character is similar to an object, except that it can change rooms,
maintain its own inventory, and take part in conversations (more on
these later). It can also have its own custom animation speed and movement
speed.

Go to the "Characters" node in the main tree. You will see under it a
list of all the characters in the game.
To create a new character, right-click the "Characters" node and
choose the "New character" option.

You will see that there are a lot of options which you can set for each
character. The most immediately obvious one is the "Make this the player character"
button, which allows you to change which character the player will control
at the start of the game. 
When the game starts, the first room loaded will be this character's
starting room.

The rest of the options are hidden away in the property grid on the right. Some
of them are described below:

The "UseRoomAreaScaling" option allows you to specify whether this
character will be stretched or shrunk in scaling areas of the screen. You might
want to disable this if you have a character who always stands still in the same
place, and you want the graphics on-screen to be the same size as you drew
them, even though he is standing on a scaled area.

The "Clickable" option tells AGS whether you want the player to be able
to click on the character. If Clickable is enabled, then the character will
be interactable, like the way things worked in Sierra games. If it is not
enabled then the character works like the main character did in Lucasarts games -
if you move the cursor over him or click to look, speak, etc, then the game will
ignore the character and respond to whatever is behind him.

To set which room this character starts in, change the "StartingRoom"
property. You can set the character's location within this room by using
the "StartX" and "StartY" properties to type in the X,Y co-ordinates you want him
to start at. These co-ordinates define where the middle of his feet will be placed.

The "NormalView" is where you set what the character looks like. You must
create a view in the \helpref{View Editor}{Views}, and this
view must have either 4 or 8 loops. If you use 4 loops, then when walking
diagonally the closest straight direction is used for the graphics. Each loop
is used for the character walking in one direction, as follows:
\begin{verbatim}
 Loop 0 - walking down (towards screen)
 Loop 1 - walking left
 Loop 2 - walking right
 Loop 3 - walking up (away from screen)
 Loop 4 - walking diagonally down-right
 Loop 5 - walking diagonally up-right
 Loop 6 - walking diagonally down-left
 Loop 7 - walking diagonally up-left
\end{verbatim}
To change the rate at which the character animates, change the Animation Speed box.
Here, a smaller number means faster animation. Note that this does NOT
effect the speed at which the character actually moves when walking.

\bf{NOTE:} The first frame in each loop is the standing still frame. When walking, the
game will cycle through the rest of the frames in the loop.

The "MovementSpeed" option allows you to control how fast the character moves when
walking. Here, a larger number means he walks faster. If you find that a movement
speed of 1 is still too fast, you can use negative numbers (eg. -3) which will move
even more slowly. The lower you go, the slower the movement speed.

The "SpeechColor" option specifies which colour is used for the text when
this character is talking. It effects all messages that are said by this
character. You can find out the colour for each number by going
to the "Colours" pane.

The "IdleView" option allows you to set an idle animation for the character.
To do this, create a new view, with one or more loops of the character idle
(eg. smoking, reading a book, etc). Then, set the "Idle view" to this view number.
If the player stands still for 20 seconds (you can change the timeout with
the Character.SetIdleView script function), then the current loop
from the idle view will be played.

The "ScriptName" property sets the name by which the character will be
referred to in scripts and in conversation scripting.
The difference from the RealName of the character is that the script name
may only contain letters A-Z and numbers 0-9 (the first character must be
a letter, however). The convention in AGS is that character script names
start with a lower case "c".

To set what happens when the player interacts with the character, click the
"Events" button (this is the lightning bolt button at the top of the property
grid). You will be presented with the events list; select an event and
press the "..." button to allow you to enter some script to handle the event.

You can also set a talking view for the character. To set one, use the
"SpeechView" property. If you set a talking view, then that view will be
used to animate the character while they are speaking. You should generally
have about 2-3 frames in each loop (the loops are used for
the same directions as in the main view).

There is also an available "Blinking view". This is used to play intermittent extra
animations while the character is talking. You may want to use this for effects
such as blinking (hence the name).  If you set a view here, it will play intermittently
while the character talks (it is drawn on top of the normal talking view). The default
time between it playing is 3-4 seconds, but you can change this with the Character.BlinkInterval
script property.ILBRK
\bf{NOTE}: the blinking view is currently only supported with sierra-style speech.

"UseRoomAreaLighting" allows you to tell AGS whether this character will be
affected by light and tint levels set on room regions.

If you disable "TurnBeforeWalking", it will override the General Setting for
turning and tell AGS not to turn this particular character around on the
spot before they move.

"Diagonal loops" specifies that loops 4-8 of the character's view will be used for
the four diagonal directions. If this option is not enabled, the character will only
face 4 ways, and you can use loops 4-8 for other purposes.

"Adjust speed with scaling" modifies the character's walking speed in line with their
zoom level, as set on the walkable areas.

"Adjust volume with scaling" modifies the volume of any frame-linked sounds on the
character's view (eg. footstep sounds) with their zoom level, as set on the walkable areas.

"Solid" specifies that this character is solid and will block other characters from
walking through it. Note that \bf{both} characters must be solid in order for them
to block one another.

AGS allows you to export your characters to a file, and then import the file into a
different game - so you can share the same main character between games, or
create one for distribution on the internet. Right-click on the character and
choose "Export character". The entire character setup and graphics will be exported
to the file, including the character's walking and talking animations.
To import the character into a different game, load it up, right-click the "Characters"
node and choose "Import Character". The file selector appears, where you find the CHA file which
you exported earlier. A new character slot will be created and all the settings imported.

\it{NOTE: Because importing always creates a new slot, you cannot use it to
overwrite an existing character.}

\subsection{Conversations}\index{Dialogs}\index{run-script}\index{add-inv}\index{goto-dialog}\index{new-room}\index{option-off}\index{option-on}\index{option-off-forever}\index{play-sound}\index{return}%

While the old Sierra games were mainly based on action and not talking, the
Lucasarts games took the opposite approach.

If you want to create a game with conversations where the player can choose
from a list of optional topics to talk about, you can now with the new Dialog
Editor. Go to the "Dialogs" node.

Conversations are made up of Topics. A "topic" is a list of choices from
which the player can choose. You may have up to 30 choices in a topic.
However, not all of them need to be available to the player at the start of the
game - you can enable various options for conversation once the player has
said or done other things. For example, when you talk to the man in the demo
game, the first option is just "Hi". Once he has said this, however, a new
option becomes available.

The Dialog Editor is quite self-explanatory. Double-click a dialog topic
to open up its window. You'll see the list of options for the topic on 
the left, and the dialog script on the right. Each option
has a couple of checkboxes to its right:
\begin{itemize}\itemsep=0pt
\item The "Show" column specifies whether that option is available to the player
at the start of the game.
\item The "Say" column defines whether the character
says the option when the player clicks it. The default is on, but if you
want options describing the player's actions rather than the actual words,
you may want to turn this column off for that dialog.
\end{itemize}
\bf{Dialog scripts}

You control what happens when the player chooses an option by editing
the script on the right. This is called the \bf{dialog script}, and is a
simplified version of scripting streamlined for conversations.

With a newly created dialog topic, all you will see in the script is a number
of lines starting with an '@' symbol. In the dialog script, these signify the starting points of
the script for each option. For example, when the player clicks on option 3,
the script will begin on the line following "@3". There is also a special
starting point, called "@S". This is run when the conversation starts, before
any choices are given to the player. This could be used to display a "Hello"
message or something similar.

To display some speech, you begin the line with the character's SCRIPT NAME
(not full name), followed by a colon, then a space, and then what you want
them to say. For example, if my main character's script name is EGO, I would
write
\begin{verbatim}
ego: "I am very happy today because it's my birthday."
\end{verbatim}
The character name is used by the system to choose the correct colour for
the text.

\bf{IMPORTANT:} Do \bf{NOT} include the "c" at the start of the character's
script name here.

You can also use the special character name "narrator", which
displays the text in the pop-up message box instead of as speech text; and the
alias "player", which will say it as the current player character - useful if
you don't know which character the player will be controlling when they speak
the conversation.

If you just use \verb$...$ as the text for a character to say, the game will
pause briefly as if they are stopping to think, and nothing will be displayed.

To signal the end of the script for this option, place a "return" command on
the last line of it. For example,
\begin{verbatim}
@1
ego: "Hello. How are you?"
narrator: The man looks you in the eye.
otherman: ...
otherman: "I'm fine."
return
\end{verbatim}
"return" tells AGS to go back and display the choices again to the player.
If you use "stop" instead of return, then the conversation is ended. Alternatively,
you can use "goto-dialog" or "goto-previous", which abort the current dialog script
and transfer control to the new dialog.

\bf{NOTE:} Do \bf{NOT} indent these lines with spaces or tabs. Indented lines
signify that AGS should interpret the line as a normal scripting command
rather than a dialog scripting command.

The dialog commands available are:
\begin{itemize}\itemsep=10pt
\item \bf{goto-dialog X} ILBRK
  Switches the current topic to Topic X, and displays the current list of
  choices for that topic. 
\item \bf{goto-previous} ILBRK
  Returns to the previous topic that this one was called from. If the dialog
  started on this topic, then the dialog will be stopped.
\item \bf{option-off X} ILBRK
  Turns option X for the current topic off, meaning it won't be displayed in
  the list of choices next time.
\item \bf{option-off-forever X} ILBRK
  Turns option X off permanently. It will never again be displayed, not even
  if an "option-on" command is used.
\item \bf{option-on X} ILBRK
  Turns option X for the current topic on, including it in the list of choices
  to the player next time they are displayed.
\item \bf{return}ILBRK
  Stops the script and returns to the list of choices.
\item \bf{stop} ILBRK
  Stops the conversation and returns the player to the game.
\end{itemize}
For an example of a dialog script, load the demo game into the editor and
look at the script for its topic 0.

\bf{Using scripting commands in dialogs}

Often the provided dialog scripting commands won't be enough for what you want
to do in the dialog. You might want to give the player an inventory item or
add some points to their score, for example.

AGS now lets you put normal scripting commands in your dialog script, by indenting
the line with spaces or tabs. For example:
\begin{verbatim}
@1
ego: "Hello. How are you?"
narrator: The man looks you in the eye.
  player.AddInventory(iKey);
  Display("This line is displayed from a normal script command");
otherman: "I'm fine."
return
\end{verbatim}
Here, you can see dialog script commands being used, but also then a
couple of normal scripting commands have been inserted, on indented lines.

When working with dialog scripts, the \bf{this} keyword allows you to access
the currently running dialog.

If you want to conditionally break out of the dialog
script, the special tokens \verb$RUN_DIALOG_GOTO_PREVIOUS$, \verb$RUN_DIALOG_RETURN$
and \verb$RUN_DIALOG_STOP_DIALOG$ are available which you can \verb$return$ from inside
a script block. For example:

\begin{verbatim}
@1
ego: "Hello. How are you?"
narrator: The man looks you in the eye.
  if (player.HasInventory(iKey)) {
    player.Say("Actually, I'd better go.");
    return RUN_DIALOG_STOP_DIALOG;
  }
otherman: "Here's a key for you."
return
\end{verbatim}

\bf{Parser input}

You'll notice in the dialog editor, the property grid has an option called "ShowTextParser".
If you enable this, a text box will be displayed below the predefined options in the game,
which allows the player to type in their own input.

If they type in something themselves, then the dialog_request global script function
will be run, with its parameter being the dialog topic number that the player was in.

AGS automatically calls ParseText with the text they typed in before it calls dialog_request,
so you can use Said() calls to respond. See the \helprefn{text parser}{TextParser} section
for more info.

\subsection{Game options}\index{options}\index{Anti-aliasing fonts}\index{Crossfading music}%

The Game Settings pane contains a list of all the various overall options
that you can set for your game.

Note that some things listed here are explained later in the documentation,
so if you don't understand one of the items in this list, come back to it
later.

Most of these options can be changed at runtime with the script command SetGameOption.
\begin{itemize}
\item \bf{Debug Mode} - whether the debug keys are active. When debug mode is on,
you can press Ctrl-X to teleport to any room, Ctrl-S to give all inventory
items, Ctrl-A to display walkable areas on the screen, and Ctrl-D to display
statistics about the current room. When debug mode is off, these do nothing.
See the \helprefn{Debugging features}{Debuggingfeatures} section for more.
\item \bf{Play sound on score} - controls whether a sound effect is played when
the player scores points. If so, you can set the sound number, which will
play SOUNDx.WAV (or SOUNDx.MP3), where X is the number you set.
\item \bf{Walk to hotspot in Look mode} - controls whether the player will walk
to "walk-to" spots when the player looks at the hotspot. Normally he only
walks on use, speak and use-inv. 
\item \bf{Dialog options on GUI} - controls where the player's options for dialog are
displayed. If this option is not checked, then in a conversation, the options
will be displayed at the bottom of the screen. If you check this box, then
instead the options will be displayed on the GUI you specify.
\item \bf{Use "anti-glide" mode} - you may notice that, as the character walks, it
can seem as if he is gliding, especially if you have a slow animation speed
setting. When anti-glide mode is on, the man's position is only updated
when the frame of animation changes. You will need to increase each
character's walking speed if you use this option.
\item \bf{Text windows use GUI} - allows you to customize the standard text window
appearance in the game, using the specified interface element. See \helpref{here}{TextWin}
for more information.
\item \bf{Pixel gap between options} - defines the gap between the options displayed
to the player in a conversation. Normally this is 0, which means the
options are right below each other. Changing it to 1 or 2 can make the
option display look less cluttered; it's a matter of personal preference.
\item \bf{Skip Speech} - determines how and whether the player can skip speech
in-game. This can be set to allow the mouse and/or keyboard, or neither, to
skip speech in the game.
\item \bf{When interface disabled} - determines what happens to buttons on your
GUIs while the game interface is disabled (eg. during a cutscene).
\item \bf{Always display text as speech} - if you select this option, then all normal
text in the game will be displayed above the main character's head as speech
text, much like the way the Lucasarts games worked. If this option is not
checked, then normal text appears in a pop-up message box, like the way that
the Sierra games worked.
\item \bf{Speech style} - in the default Lucasarts-style speech, when a character talks, the
speech text is displayed above their head in the game, and the character's
talking view is used to animate the actual character. ILBRK
However, if you set this option to Sierra-style then the talking view is used to display an
animating portrait separately in the top-left of the screen, with the text to the right of it.
This is similar to the way that Space Quest 5, King's Quest 6 and other
later Sierra games worked. You can also cycle to another option, "Sierra-
style with background", which is the same except a text window is drawn
behind the speech text to make it easier to read. ILBRK
"Whole Screen" uses a full-screen character portrait, like the way that QFG4 worked.
\item \bf{Speech portrait side} - if you're using Sierra-style speech, then this
determines whether the portrait appears on the left or the right of the screen. The "alternate"
setting means it swaps sides whenever a different person talks, and the "Based on X position"
setting means that the side of the screen is chosen depending on where the characters are
standing.
\item \bf{Room transition style} - defines what type of screen transition is used when
moving from one room to another. Various options are available.
\item \bf{Save screenshots in save games} - Saves a mini-screenshot of the player's current
position into the save game file. This will create larger save game files, but it will
mean that you can use a save game thumbnails GUI to make the save/load interface
more professional.
\item \bf{Enforce object-based scripting} - Puts the script compiler into strict mode,
where it will not accept the old-style (pre-AGS 2.7) script commands. This should
preferably be ticked, since you should no longer be using the old commands.
\item \bf{Left-to-right operator precedence} - if this is ticked, then operators of
equal precedence in the script will be evaluated left to right. For example,
5 - 4 - 3 could be interpreted as  (5 - 4) - 3  or as  5 - (4 - 3), thus giving
different results. You should always use parenthesis to clarify expressions like this,
so that the operator precedence doesn't affect the result.
\item \bf{Pixel-perfect click detection} - normally, when the player clicks the
mouse, AGS just checks to see if the cursor is within the rectangular area
of each character and object on the screen. However, if this option is
checked, then it will further check whether the player clicked on an actual
pixel of the object graphic, or whether it was a transparent part of the
graphic. If this option is enabled and they click on a transparent pixel,
then the hotspot behind the object will be activated instead.
\item \bf{Don't automatically move character in Walk mode} - normally, when you click the mouse in
the Walk mode, the main character will move to where you clicked. However,
if you want to create a game all viewed from a 1st-person perspective, and
so don't have a main character, then selecting this option allows you to
use the Walk mode for other things. If selected, then "Character stands on
hotspot" events are instead triggered by clicking the Walk cursor on the
hotspot.
\item \bf{Use letterbox (320x240 / 640x480) resolution} - this option is only available if your
game is 320x200 or 640x400, and it will tell AGS to run the game at 320x240 or
 640x480 instead. The screen will be "letter-boxed" - that is,
there will be a black border top and bottom. You may want to use this option
if you need a square pixel aspect ratio for your graphics.
\item \bf{Don't use inventory graphics as cursors} - normally, when you select an inventory
item the mouse cursor is changed into that item. However, if you want to
create a Lucasarts-style game (where the inventory cursor is always a
cross-hair), check this option and it won't be changed.
\item \bf{Don't scale up fonts at 640x400} - normally, if the player chooses 640x400, then
the fonts will be scaled up to match. However, if you have drawn your fonts
for the 640x400 resolution, use this option to stop them being stretched.
\item \bf{Resources split every Mb} - see \helpref{here}{SplitRes} for information.
\item \bf{Characters turn before walking} - specifies that when a character starts
to walk somewhere, it will first turn round to face the correct direction
using available animation frames, rather than just suddenly switching to
face the right way.
\item \bf{Override built-in inventory window click handling} - AGS has some built-in processing
of Inventory Window GUI controls, whereby a right-click will Look at the item, and a left click
will select it if the cursor mode is Interact. However, if you enable this
option, then clicking on an inventory item in an Inventory Window will call your \verb$on_mouse_click$ 
function  with eMouseLeftInv, eMouseMiddleInv or eMouseRightInv, and you then need to process it
yourself. You can use the \verb$game.inv_activated$ variable to find out what they clicked on.
\item \bf{Enable mouse wheel support} - if enabled, on_mouse_click can be called with
the values eMouseWheelNorth and eMouseWheelSouth, which signify the user scrolling their mouse
wheel north or south, respectively.

\bf{NOTE:} Not all mice have mouse wheels, and the DOS engine does not support the
mouse wheel at all. Therefore, your game should never require the mouse wheel in order to
be playable - it should only be used as a handy extra.
\item \bf{Number dialog options} - adds an index number before each dialog option when
they are displayed to the player. For example,
\begin{verbatim}
1. Hello there!
2. Goodbye
\end{verbatim}
This allows you to visually show the player which option the shortcut keys will choose,
as well as seperating the options if you don't use a bullet point.
\item \bf{Dialog options go upwards on GUI} - Normally, if you select a non-textwindow GUI
for the dialog options, they will be printed from the top down. However, if you select this
option they will go from the bottom of the GUI upwards.
\item \bf{Crossfade music tracks} - This allows you to tell AGS to crossfade between your
background music tracks. Crossfading means fading out the old track while fading in the
new one when the music changes. You can select a crossfade speed from the drop-down list.
There are some disadvantages to using this option - firstly, it's fairly slow, since AGS
has to decode two music files at once. Secondly, it only works with OGG, MP3 and WAV music.
You cannot crossfade MIDI, XM, MOD, S3M or IT music.
\item \bf{Anti-alias TTF fonts} - If enabled, any TTF fonts you have in your game will
be rendered to the screen anti-aliased. This can make them look a lot better, but it has
two drawbacks - firstly, anti-aliasing is significantly slower than normal rendering, so
you might want an option to allow the player to turn it off. Second, anti-aliasing only
works in hi-color games (in 256-colour games, the output will look blurred and unreadable).
\bf{NOTE} that anti-aliasing is not currently done on lucasarts-style speech due to
technical reasons.
\item \bf{Thought uses bubble GUI} - Determines which text window GUI is used for displaying
thoughts with \helprefn{Think}{Character.Think}.
\item \bf{Characters turn to face direction} - if set, then when a character turns round
with the \helprefn{Character.FaceLocation}{Character.FaceLocation} or \helprefn{Character.FaceCharacter}{Character.FaceCharacter}
script commands, they will visibly turn around using their available loops.
If this option is not set, they will immediately appear facing their new direction.
\item \bf{Write game text backwards} - in-game text will be written right-to-left, ie. line
breaks are worked out from the end of the sentence going backwards, and the last words
are displayed first. This is used by languages such as Arabic and Hebrew.
\item \bf{Display multiple inventory items multiple times} - normally, if the player has
two of an inventory item, the item will still only be shown once in the Inventory window.
If you check this option, however, then all the copies of the item that the player has
will be displayed. Useful for RPG-style inventories.
\item \bf{Save games folder name} - if this is blank, then the player's saved games will
be saved to the folder where the game is installed. This is not a good idea, because it
forces different users on the same machine to share save games, and Windows Vista discourages
games from writing to the Program Files folder. Instead, if you supply a folder name here,
then AGS will automatically create it within the user's Saved Games (Vista) or My Documents
(XP and earlier) folder, and their save games will be saved there.
\end{itemize}

See Also: \helprefn{Enhanced Saved Games}{EnhancedSaveGames} ILBRK
See Also: \helprefn{Windows Vista Game Explorer}{GameExplorer}


\subsection{Cursors}\index{Mouse cursors}%

The Cursors node of the editor shows you the current mouse cursor modes available in
the game. Each cursor mode performs a different action within the game. Double-click
one to open it up.

The "StandardMode" option in the property grid tells AGS that this is a 'normal' cursor mode - ie.
using this cursor will fire an event on whatever is clicked on as usual. This
mode applies to the standard Walk, Look, Interact and Talk modes, but you can create
others too. Do not tick it for the Use Inventory mode, since this is a special mode.

The "Animate" option allows you to specify that the mouse cursor will animate while it
is on the screen. Choose a view number, and the cursor will animate using the first
loop of that view. You can make it animate only when over something (hotspot, object
or character) by enabling the "AnimateOnlyOnHotspots" option.

The "AnimateOnlyWhenMoving" box allows you to do a QFG4-style cursor, where it only
animates while the player is moving it around.

Three of the cursor modes are hard-coded special meanings into AGS:
\begin{itemize}
\item \bf{Mode 4 (Use Inventory)}. This is special because the game decides whether to
allow its use or not, depending on whether the player has an active inventory item
selected.
\item \bf{Mode 6 (Pointer)}. This cursor is used whenever a modal dialog is displayed
(ie. a GUI that pauses the game). Normally this is a standard arrow pointer.
\item \bf{Mode 7 (Wait)}. This cursor is used whenever the player cannot control the
action, for example during a scripted cutscene. For a lucasarts-style game where the cursor
disappears completely in this state, simply import a blank graphic over the wait cursor.
\end{itemize}

For the standard modes,
\begin{itemize}
\item Mode 0 will cause the player to walk to the mouse pointer location when clicked.
\item Modes 1, 2, 3, 5, 8 and 9 will run the event with the same name as the cursor mode.
\end{itemize}


\subsection{Fonts}%

AGS comes with a couple of default fonts, but you can replace the and add your own.
You can use both TrueType (TTF) and SCI fonts (Sierra's font format).

SCI fonts can be created in two ways:
\begin{itemize}
\item Extract the font from a Sierra game, using the SCI Decoder program
available on the internet.
\item Create your own font and save it in SCI Font format, using the
\urlref{SCI Graphic Studio program}{http://scigraphicstudio.cjb.net}.
\end{itemize}
There are also some fonts available on the 
\urlref{AGS website}{http://www.adventuregamestudio.co.uk/fonts}.

Note that SCI fonts are faster to render than TTF fonts, and so may give your game
a speed advantage. It's preferable to use a SCI font if you can.

Go to the "Fonts" node in the main tree. Here you can see all the current fonts
listed underneath. You can create a new font by right-clicking the "Fonts" node
and choosing "New font". To overwrite an existing font, open it up and
press the "Import over this font" button.

Fonts can have outlines. For lucasarts-style speech, outlines are really a
necessity since they stop the text blending into the background and becoming
un-readable. To outline a font, either set the OutlineStyle to "Automatic" to
have AGS do it for you, or you can use a specific font slot as the outline font
(it will be drawn in black behind the main font when the main font is used).

\bf{NOTE:} If you go to your Windows Fonts folder, you will not be able to select
any fonts to import, since double-clicking them will open them up in the Windows Font
Viewer. Unfortunately there is nothing I can do about this, you must either type the
filename in manually, or copy the font to another folder and import it from there.

\bf{NOTE:} Font 0 is used as the normal text font, and font 1 is used as the
speech font. To use any additional fonts, you can set the Game.NormalFont
and Game.SpeechFont properties in your script.

\section{Advanced room features}%

This section describes slightly more advanced things you can do with the
rooms.

\subsection{Character scaling}\index{Scaling}%

AGS supports scaling of characters, where the character can appear to get
smaller as he walks away from the screen. Character scaling is supported as
part of the walkable areas in a room.

The reason why you have multiple colours available for the walkable areas is
because you can set a zoom level for each colour, which defines how large
the character will be while he is in that area. The default for all walkable
areas is \verb$100%$, ie. full size. However, you can adjust it using the "Walkable
Areas" mode to anywhere from \verb$10%$ (one-tenth size) to \verb$200%$ (double size).

The scaling settings can effect all characters and objects in the game. For characters,
it is on by default but you can disable the scaling for an individual character by
setting the "UseRoomAreaScaling" option in that character's properties.

For objects, it is off by default but you can make a specific object obey scaling
levels by setting its "UseRoomAreaScaling" option.

If you set the "UseContinuousScaling" option, then rather than just specifying a
zoom level for the whole walkable area, you specify a min and max zoom level. These
specify the scaling at the top and bottom of the walkable area. When the game is run,
AGS will interpolate these values to make the character smoothly scale down from 
one value to another as he walks towards the back or front of the screen.

\subsection{Scrolling}%

It's easy to create scrolling rooms like the ones used in Lucasarts games
like Monkey Island (tm) and Day of the Tentacle.

To do this, just import a background scene that is larger than your game resolution.
For example, in a 320x200 game, 500x200 is a good size for Lucasarts-type rooms.

That's all you have to do. Draw on the walkable areas, hotspots and so on, as
normal, and then save the room. The screen will scroll to follow the main character
around.

The script command \helprefn{SetViewport}{SetViewport} allows you to manually scroll
the room around if you don't want it to follow the character.


\subsection{Importing a file as the walkable area mask}\index{Mask, importing}%

AGS has the ability to import an external BMP or PNG file to use as the
walkable-area, hotspot or walk-behind area mask. If you don't like the way
you have to draw these in the editor itself, you can draw them in another
program and then import them. This is also useful if you are converting a
game you were making with another game-creation system into AGS.

To use the feature, click the "Import Mask" button (in the toolbar) in the
relevant mode of the Areas editor. There are some restrictions to how this
file must be drawn: it must be the exact same size as the background scene,
and it must be in 16-colour (4-bit) or 256-colour (8-bit). Then, colour 0
on the bitmap signifies transparency and colours 1-15 are used as the
respective hotspot/walk-behind/walkable area numbers. 

\bf{IMPORTANT:} Do NOT use any colour numbers above 15 on the mask bitmap. Use only
palette indexes 0 to 15.


\subsection{Animating background scenes}%

If you want to have a lot of animation on the screen, you will come across
two problems if you try to do it using objects:
\begin{itemize}
\item There is a limit on the number of objects per screen, so you may not be able to
animate everything that you want to that way.
\item Objects slow down the game - the more objects on the screen, the slower
the game runs.
\end{itemize}
The solution to these problems is to use an animating background scene.

How it works is this: Each room can have from 1 to 5 backgrounds. Normally,
each room just has one background. However, you can import up to four extra
backgrounds in each room, and if you do so then the game will cycle through
them, giving the effect of animation.

This gives two main advantages - you can animate the entire screen, and due
to the way the engine works, it doesn't slow down the game at all.

To import a second background for a room, load the room into the editor, pull
down the "Main background" list box, and choose the "Import new background" option.
Choose the file that's storing the background and you're done.

To delete a background, select it then click the "Delete" button. 

You define the speed at which the backgrounds will animate by setting the 
"BackgroundAnimationDelay" option in the property grid for the room. The default
is 5, which cycles background every 5 frames.

\it{NOTE: All the background scenes must be the same size.

NOTE: (256-colour only) The backgrounds frames each have their own palette (unless
you select "Share palette with main background" before importing). This means
that when the current frame switches in-game, the palette will get reset - therefore
you can't use special palette effects such as CyclePalette or SetPalRGB on screens
with animating backgrounds.}


\subsection{Lighting effects}%

You can control the brightness of your characters, courtesy of the "LightLevel" setting
for room Regions.

By default this is \verb$100%$, but you can change it from \verb$0% to 200%$.
This number is the light level in the current walkable area. Smaller
numbers are darker, so that \verb$0%$ is pitch black and \verb$200%$ is very bright.

This feature could be useful if, for example, you have a street lamp on your scene so
when the character walks under it they get brighter, or if a wall is shading
the character from the light they can get darker.

You can alternatively use a colour tint for the region. If you select this, then you
can enter Red, Green and Blue values as numbers from 0-255, which reflect the colour
you want the area to be tinted to. The Amount setting determines to what extent
characters will be tinted, and is from 0-100.

\bf{NOTE:} Light levels only work when the character's graphic is at the same
colour depth as the background (ie. a 256-colour character in a hi-colour
game won't get lightened).

\bf{NOTE:} In a 256-colour game, only darkening areas (light level < \verb$100%$) will work.
Also, depending on the room palette the quality of the darkening will vary
in 256-colour games.

\bf{NOTE:} Light levels affect characters and objects, depending on
the "UseRoomAreaLighting" setting for each one.
They do not affect overlays or the background scene.


\chapter{Other Features}%

This section describes AGS features that were not covered in the tutorial.

\section{Music and sound}\label{MusAndSound}\index{Sound effects}\index{Audio}%

Sound and music are an essential part of any gameplay experience, and AGS 3.2 now
provides a re-written audio system giving you full control over your game audio.

\bf{File formats}

AGS is able to play the following types of audio file: OGG, MP3, MIDI, WAV (uncompressed),
MOD, XM, IT, S3M and VOC.

The only limitation to this is that AGS is only able to play one MIDI file at a time.
If you attempt to play two simulataneous MIDI music files, the first one will be cut
off when the second one starts playing.

If you haven't heard of OGG before, it's a digital music format, similar to MP3, but achieving
better compression and higher quality. More importantly, it is a totally free format
so no royalty payments or licenses are required to use it. For more information and
programs to encode your music to OGG, see http://www.vorbis.org/

\bf{Audio in the Editor}

Look under the "Audio" branch in the project tree. Here you'll find sub-nodes called 
"Speech", "Types" and two default folders called "Music" and "Sounds".

\bf{Speech}

At the moment, voice speech files are not setup within the editor. See the \helprefn{Speech}{VoiceSpeech}
help page to find out more about adding speech to your game.

\bf{Audio Types}

Audio Types allow you to group together similar types of audio files. The standard
distinction here is between Sound and Music, whereby you usually only want one Music
file to be playing at any one time; whereas you might have several simultaneous sound
effects.

Double-click on an Audio Type and it will open up; you can see its properties in the
Property Grid. Here, the "MaxChannels" setting allows you to specify how many audio
clips of this type are allowed to play at the same time. The "VolumeReductionWhenSpeechPlaying"
setting allows you to have AGS automatically reduce the volume of these audio clips while
speech is playing, to make it easier for the player to hear the speech over the background
music.

You'll probably find that the default settings here are fine, and in many games you won't
need to change them.

\bf{Importing audio files}

Now let's get on to the important question -- how do you add sound and music to your game?
Well, if you right-click on the "Sound" or "Music" folders (or any other folders that
you create yourself), you'll see an option called "Add Audio Files".

Select this option, and you'll be given a dialog box to find the audio files that you
want to import. Once imported, they'll be assigned script names automatically.

Double-click an audio file in the project tree to open a window where you can preview
it, as well as change its properties in the Property Grid.

\bf{Playing audio in the game}

The script to play an audio clip in the game is very simple. For example:
\begin{verbatim}
aExplosion.Play();
\end{verbatim}
plays the audio clip called \it{aExplosion}.

\bf{Priorities and channels}

AGS currently has an 8-channel audio system, which means that up to 8 sounds can be
playing at the same time. With the default Audio Types settings, one channel is reserved
for speech, one for music and one for ambient sounds; thus leaving 5 available for
sound effects.

If you try to play an audio clip and there are no channels available, then an existing
one will be stopped and the new one will take its place. However, this will only
happen if the new audio clip has an \bf{equal or higher} priority than one of the currently
playing sounds.

Thus, the priority allows you to decide which audio clips are more important than others.
For example, you might set a footstep sound as low priority, and a door opening as
high priority. This can be configured at the folder level in the editor, and also by
changing the properties of an individual audio clip (by default they will inherit from
their containing folder).

Sometimes you might not want the priority of the sound to be fixed in the editor -- you
might want to decide it at run-time in the script. For this reason the \it{Play} command
has an optional parameter which allows you to explicity specify the priority when you
play it, for example:
\begin{verbatim}
aExplosion.Play(eAudioPriorityLow);
\end{verbatim}

\bf{Seeking and changing volume}

So, how do you change a sound once it is playing? Well, there are no methods on the
Audio Clip to do this, because you might be playing two copies of the same sound at
once, and then AGS wouldn't know which one you wanted to access. That's where \bf{Audio
Channels} come to the rescue. 

When you use the Play() command, AGS returns to you an AudioChannel* instance representing
the channel on which the sound is playing. You can store this to a global variable and
access it later on. For example:

\begin{verbatim}
AudioChannel* chan = aExplosion.Play();
chan.Volume = 20;
\end{verbatim}

This will start the \it{aExplosion} audio clip playing, and then change its volume to \verb$20%$.

\bf{Using Audio Channels}

Supposing you want to start playing a sound now, and then change its volume or panning later on. 
How would you do that? Well, you'd need to keep the AudioChannel around, so that you can access
it later. The easiest way to do that is to make it a Global Variable; if you open the Global Variables
editor, you can create a new AudioChannel* variable (let's call it \it{longWindedSound}). Then when
you play the sound you set it like this:

\verb$longWindedSound = aExplosion.Play();$

later on, elsewhere in the script, you can change the volume by doing:
\begin{verbatim}
if (longWindedSound != null)
{
  longWindedSound.Volume = 20;
}
\end{verbatim}
Note the check for null here -- this makes sure that your game won't crash if the sound isn't
playing (it might have finished, or not have been started yet).

\bf{Overall system volume}

There is a property called \helprefn{System.Volume}{System.Volume} that controls the
overall game volume, which you can use with some sort of volume control slider for the
player. All individual sound volumes work within the overall system volume.

\bf{Conclusion}

The new audio system in AGS gives you much more control over your game audio.
Please see the following sections for a complete list of the supported commands:

\helprefn{AudioClip reference}{AudioClipCommands}, 
\helprefn{AudioChannel reference}{AudioChannelCommands}


\subsection{Voice speech}\label{VoiceSpeech}\index{Speech}%

With AGS you can link a line of dialog to a speech file, to enable "talkie"-
style games. Suppose you have a dialog script with the following:
\begin{verbatim}
ego: "Hi! How are you?"
david: "I'm fine."
\end{verbatim}
Normally this would display the words in the speech text above the characters
heads. However, you can add the special character '&' to symbolise that a
voice file should also be played. The file name is made up of the \bf{first four
letters} of the character's \bf{script name}, then an ID number. For example,
\begin{verbatim}
ego: &10 "Hi! How are you?"
david: &7 "I'm fine."
\end{verbatim}
This would play EGO10.WAV with the first line, and DAVI7.WAV with the second.
When a line of text has a voice linked to it, the text on the screen will not
be removed until the voice file has finished playing. If the player interrupts
it by clicking the mouse or pressing a key, the text and voice will be stopped.
Voice files must be placed in the "Speech" sub-directory of the game folder.

You can also use speech with Say script function.
\begin{verbatim}
cEgo.Say("&10 Hi! How are you?");
cDavid.Say("&7 I'm fine.");
\end{verbatim}

\bf{NOTE:} WAV, OGG and MP3 format files can be used for speech.

\bf{NOTE:} You cannot use speech file numbers above 9999. That is, you can
have EGO1.OGG all the way up to EGO9999.OGG, but not EGO10000.OGG or higher.

Speech is compiled into a file called SPEECH.VOX and is separate
from the rest of your game data so that you can offer it as an optional extra
download to the player. The game will function correctly if the file is not
present.

\it{SeeAlso:} \helprefn{SetVoiceMode}{SetVoiceMode} script function.


\subsection{The AudioCache folder}\label{AudioCache}\index{AudioCache folder}%

When you import audio files into AGS, you'll probably notice that a folder
inside your game folder, called AudioCache, starts to fill up with files. What
is it and why is it there?

Well, when you import audio into AGS, you might be importing it from anywhere --
it could be off your hard drive, but it might also be off a USB stick or a CD.
AGS can't rely on the audio files always being there because you might remove
the USB stick or delete the files on it.

Therefore, when you import audio into AGS it makes a copy of the file in the AudioCache
folder. AGS also remembers where the file came from, and when you compile your game
it will check if the file has been updated in its original location -- if so it will
copy the latest version to the AudioCache.

But if the source file no longer exists, your game will continue to build just fine
because AGS has its own copy of the file.

This allows AGS to stick to one of its core principles, that all the files you need
to build your game are within the game's folder. That way, you have complete security
in knowing that by backing up your game folder, your game will be safe if the worst happens.


\section{Editing the GUIs}\index{GUI}%

The game interface is split up into GUIs. Each GUI is a
rectangular region on the screen which is drawn on top of the background
scene. Each can be set to either:
\begin{itemize}
\item be always displayed (for example the Sierra status-line)
\item pop-up when the mouse moves to a certain position (eg. Sierra icon-bar)
\item pop-up on script command only
\end{itemize}
The default interface is made up of two GUIs - the status line, and the
icon bar.

Go to the "GUIs" node in the main tree. Under this all the GUIs in the game
are listed -- double-click one to edit it. To create a new one, right-click 
on the main "GUIs" node and choose "New GUI".

Once you've opened up a GUI, you'll notice the GUI itself in the main window,
and its settings can be edited in the Properties grid. This allows you to change the
background colour of the GUI, set a background picture, and set the
location and width/height amongst other things.

The "Visibility" property allows you to set when the GUI is displayed. The
default is "Normal", which means that the GUI will initially be visible,
though you can turn it off with a GUI.Visible=false command in game_start if you need to.

The "Popup modal" option means that the GUI will be initially
off and must be turned on by a script command. With this option,
the game will be paused while the GUI is displayed, during which time the
on_mouse_click  and  on_key_press  functions will not get run.

The "Mouse YPos" option means that the GUI only appears when the mouse vertical
position moves above the y-coordinate set with the "Popup-YP" option.

"Persistent" is like "Normal", except that this GUI will not be removed
during a cutscene when the setting "GUIs turn off when disabled" is set in 
the general settings. Useful if you want most of your GUIs to turn off, except
a status line or whatever.

The "Z-Order" setting allows you to set which order the GUIs are drawn in - ie. when
there are two GUIs that overlap, which is drawn in front. The Z-order setting is an
arbitrary number between 0 and 1000. AGS draws the GUIs in order, from the lowest numbered
at the back to the highest numbered at the front.

The "Clickable" setting allows you to set whether the GUI and buttons on it
respond to mouse clicks. This is on by default, but if you turn it off and
the player clicks on the GUI, the game will actually process the click as if 
they clicked behind the GUI onto the actual screen. Useful for transparent GUIs
which are only used to display information.

You'll notice that the GUIs have names. These can be used in the script in the
same way as character names. For example, if a GUI is called "gIconBar", you can use
scripts such as:

\verb$gIconBar.Visible = true;$


\subsection{GUI buttons}\index{Buttons}%

To provide interactivity with the interface, you use buttons.

To add a button, click the "Add button" button in the toolbar, and then drag a rectangle
with the mouse onto the GUI. You will see it displayed as a text button, with
the text "New button" on. Notice that the Properties window is now displaying
properties for your new button rather than the GUI.

Using the Properties window, you can set a picture for the button instead,
and you can also set various other self-explanitory attributes.
You set what happens when the player clicks on the button by using the "Click
Action" attribute. This can be set to "Run Script" (the default), and also "Set
mode", which changes the cursor mode to the mode specified in the "New mode number"
property.

To delete a GUI button, right-click it and choose Delete.

\subsection{Interface text}\index{Labels}%

You can easily display static text on interfaces. For example, the Sierra-style
interface displays the score in the status bar.

To show text to a GUI, you need a label. Click the "Add label" button in the
toolbar, then drag out a rectangle like you did when adding a button. You can change the
text displayed in the label by editing the "Text" property. Notice that the
text automatically wraps round to fit inside the rectangle you drew.

As well as typing normal text into the label, you can add some special markers
which allow the text to change during the game. The following tokens will be
replaced with the relevant values in the game:
\begin{verbatim}
 @GAMENAME@    The game's name, specified on the Game Settings pane
 @OVERHOTSPOT@ Name of the hotspot which the cursor is over
 @SCORE@       The player's current score
 @SCORETEXT@   The text "Score: X of XX" with the relevant numbers filled in.
 @TOTALSCORE@  The maximum possible score, specified on the Game Settings pane
\end{verbatim}
Example: You have @SCORE@ out of @TOTALSCORE@ points.

The Properties window also allows you to align the text to left, right or
centre, as well as change its font and colour.

\subsection{Customized Text Windows}\label{TextWin}\index{Text windows, customizing}%

If you want to add a personal touch to the standard white text-boxes which
display all the messages during the game, you can create a border using the
GUI Editor. Right-click the "GUIs" node, and choose "New Text Window GUI".

The element will be resized to about 1/4 of the screen, and you will see 8
pictures - one in each corner and one on each side. These are the border
graphics. You change the graphic for a corner in the normal way.

In the game, the corner graphics will be placed in the respective corners of
the text window, and the side graphics will be repeated along the edge of
the window. To tell the game to use your custom text window style, go to the
General Settings pane, and check the "Text windows use GUI" box. Then, enter
the number of the GUI which you used.

You can also set a background picture for the text window. In the GUI editor,
simply set a background picture for the GUI element. The graphic you specify
will not be tiled or stretched in the game; however, it will be clipped to
fit the window. You should use a graphic of at least about 250x80 pixels to
make sure that it fills up the whole window.

To set the text colour in the window, simply set the Foreground Colour of
the GUI and that will be used to print the message text in.

\subsection{Custom inventory}\index{Inventory, Lucasarts-style}%

Another option you may have noticed in the GUI editor is the Add Inventory
button. This allows you to drag out a rectangle which will display the
player's current inventory, in the same way as the Lucasarts games did. To
make the inventory window scrollable, you will need to add Up and Down arrow
buttons, and attach script code to those buttons to use the available
functions such as \helprefn{InvWindow.ScrollUp}{InvWindow.ScrollUp} and
\helprefn{InvWindow.ScrollDown}{InvWindow.ScrollDown}.

To see a full list of commands available for inventory windows, see
the \helprefn{GUI Inv Window Functions and Properties}{GUIInvFuncs} section.

\subsection{Sliders}%

You can now add sliders to your GUIs. This allows you to have a nice interface
for the player to change settings such as volume and game speed.
To add a slider, click the "Add slider" button and drag out its rectangle just
like you would for a button. You can also resize it by dragging the bottom-
right hand corner out in the same way as a button.

Sliders can be either vertical or horizontal. The direction that it is drawn
in is automatic depending on the size that you stretch the slider box to - if
it is wider than it is tall you will get a horizontal slider, otherwise you'll
get a vertical slider.

For the properties of a slider you can set the minimum, maximum and current
values that the slider can have. In the game, the user will be able to drag
the handle from MIN to MAX, and the slider will start off set to VALUE.
For horizontal sliders, MIN is on the left and MAX on the right, for vertical
sliders MAX is at the top and MIN is at the bottom.

Whenever the user moves the handle's position on the slider, the OnChange event is
called. This means that if they continually drag the handle up and down,
the event will get called repeatedly.

Your script can find out the value of the slider using the Slider.Value script property.

\subsection{Text Boxes}%

A text box is a simple device that allows the player to type information into
your game. Adding a text box works like adding the other types of control.

If a text box is on a currently displayed GUI, all standard keypresses (ie.
letter keys, return and backspace) are diverted to the textbox instead of
being passed to the on_key_press function. When the player presses Return in
the text box, the OnActivate event is called. You can then use the TextBox.Text
property to retrieve what they typed in.

\subsection{List Boxes}%

List box controls allow you to add a list of items to your GUI. This could
be useful for doing a custom save/load dialog box, allowing the user to
choose between various options, and so forth.

You use the ListBox script functions to manipulate the list box - for
example, ListBox.AddItem to add an item, or ListBox.SelectedIndex to get the current
selection.

The OnSelectionChanged event is fired when the player clicks on an item in the list.
You may wish to ignore this or to do something useful with it.

\section{Distributing your game}\label{DistGame}\index{Compiling the game}\index{Splash screen, creating}\index{Loading screen, creating}%

When you choose the "Build EXE" option in the Editor, a "Compiled" sub-directory
is created in your game's folder, with all the files that you need to distribute
your game. At its simplest this will just be your game executable and the setup
program, but you may also have audio and speech libraries (AUDIO.VOX and
SPEECH.VOX); and if you have selected to split resources files, you will also
have several files named "game.001", "game.002", and so forth.

So, when you want to upload your game to the internet, just zip up the files in
the Compiled folder, and there you go!

\it{NOTE: It is not possible to load the exe file back into the AGS Editor. This
means two things when only the EXE file is available: (1) other people can't
edit your game's data, and (2) you can't either. Always keep a backup of the
other files produced (*.CRM, GAME.AGF, etc) as they are what the Editor
needs to be able to load your game for editing.}

\it{TIP:} You can make a "Loading..." style splash screen to be displayed while your game starts
up. To do so, simply save the image as  PRELOAD.PCX (must be the same resolution and colour depth
as the game) in the game folder, and build the game. It should then display while the game is loading.

\it{NOTE: Due to the licenses of code used by AGS, your documentation should acknowledge the
following:}

TrueType font display uses ALFont by Javier Gonzalez and the Freetype project. Distributed
under the terms of the FreeType project license.

OGG player is alogg by Javier Gonzalez, using the Ogg Vorbis decoder, which is available
from http://www.xiph.org/  Copyright (c) 2002-2008, Xiph.org Foundation

MP3 player is almp3, by Javier Gonzalez and the FreeAmp team. It uses the mpg123 MP3 decoder,
and is distributed under the terms of the GNU Lesser General Public License version 2.1.

You should also include all the license_* files from the DOCS directory with your game.

\bf{IMPORTANT:} If you intend to make money for your game, be it shareware or commercial,
it is imperative that you read the Legal Information page on the AGS website, currently
at http://www.bigbluecup.com/aclegal.htm

\bf{NOTE:} The AUDIO.VOX file contains audio clips that you have marked as "InSeperateVOX"
in the editor. This allows you to have an optional audio download, if your game uses lots
of sound files but you don't want the player to have to download them.


\subsection{Custom icon}\index{Icon}%

If you wish, you can use your own custom icon when you build a Windows EXE
file. To do this, simply place your icon in your game's folder, and name
it USER.ICO. Then, load the editor and save the game.

AGS is only able to build your custom icon if you are running the editor on
Windows 2000, XP or Vista. If you're using Windows 98 then your game will be
built with the standard AGS icon.

\it{NOTE: The icon \bf{must} be a proper Windows .ICO file, \bf{not} just a renamed
BMP file. Icon editors, such as AX-Icons from http://www.axialis.com, will convert
it for you.}

You can also have a custom icon for the Setup program generated. To do so, create
your icon as above but name it \bf{setup.ico} in the game folder.

\subsection{Splitting resource files}\label{SplitRes}%

Some people found that once their game became large, the single EXE file
was slow to load due to anti-virus checkers scanning the whole file.
AGS includes an option to split up the resource files into smaller chunks
to avoid this happening. On the General Settings pane you'll notice a
setting "Split resource files into X Mb sized chunks".

If you tick this, then type in a number such as 1 or 2, then save the game,
the game data will be split up into chunks that size, named GAME.001,
GAME.002 and so on.

Some resources are still combined into the EXE file but
all the rooms will be placed into the other files.
If you use this option, you need to distribute your game's EXE file plus
all the GAME.00? files.


\section{Backing up your game}%

You will no doubt want to back up your game files, and should do so regularly during
your game development. But which files should you back up?

When taking a backup, make sure you copy \bf{ALL} the files listed below:

\begin{itemize}
\item \bf{GAME.AGF} - this is the main data file for your game and contains almost
all of the game settings. Without it, your game is lost.
\item \bf{ACSPRSET.SPR} - this is your game's sprite file, containing all the sprites
from the sprite manager.
\item \bf{ROOM*.CRM} - all the ROOM*.CRM files are your room files, and obviously without
one of them you wouldn't be able to go into that room any longer.
\item \bf{*.ASC, *.ASH} - these are your script files, and contain all of your
scripting handywork.
\item \bf{*.TRS} - translation source files. They contain any translations that you've
had done.
\item \bf{AGSFNT*.TTF, AGSFNT*.WFN} - these files contain any fonts you have imported.
\end{itemize}

Also remember to back up any sound, music and video files you are using.

\section{The text parser}\label{TextParser}\index{Text parser}\index{Parser}%

You can now use a text parser in your games if you wish to, much as the older
Sierra games did.  Go to the "Text parser" pane in the editor. There, you
will see a short list of words which are provided for you. Each word has a
number beside it.

Basically, you add words you want to use by right-clicking the list, and
selecting "Add word".
However, the real beauty of the parser is its ability to recognise synonyms -
that is, two words that mean the same thing. So, for example, if you wanted
the player to type "look at fence", they might well type "look at wall"
instead, if that's how they see the drawing. Or, a British person might type
"colour" whereas an American might type "color", both of which should have
the same effect.

To add a synonym for an existing word, highlight the current word, right-click it
and choose "Add synonym". You'll notice that the new word is given the same
number as the old one. All words with the same number are considered identical
by the parser.

You will notice that the provided list has a lot of words with number 0. This
is a special number, that indicates that the parser should ignore the word
completely. In our previous example, the player might type "look at the fence",
"look at fence", or just "look fence". By adding words like "at" and "the" to
the ignore list, they get stripped out of the user's input automatically. To
add new ignore words, just select an existing one and add a synonym.

So, how do you use the text parser? Well, you'll need a text box GUI control
somewhere in order for the user to type in their input, or you could just
use the InputBox command (but it has quite a short line length).

When the user has typed in their text (you'll probably know this by the text
box's event being activated), you call the  Parser.ParseText  script
function which tells AGS what input string to use in subsequent commands.
You then simply use the Said command to test what the player typed in.

You type the whole sentence (but NOT including any ignore words), and AGS will
compare it to the user's string, considering all synonyms identical.
For example (assuming our text box is called "txtUserInput"):
\begin{verbatim}
  String input = txtUserInput.Text;
  Parser.ParseText(input);
  if (Parser.Said("look fence")) {
    Display("It's an old wooden fence.");
  }
  if (Parser.Said("eat apple")) {
    Display("You'd love to, but you don't have one.");
  }
\end{verbatim}
There are a couple of special words you can use with the Said command.
"anyword" will match any word that the user types in. For example,
Said("throw anyword away")  will match if they type "throw dagger away",
or "throw trash away".
"rol" (short for Rest-of-Line) will match the rest of the user's input. So,
you might want to do:
\begin{verbatim}
if (Parser.Said("kill rol")) {
  Display("You're not a violent person.");
}
\end{verbatim}
This way if they try to kill anything they will get the generic response.

Sometimes, you want to accept two different words that are not synonyms as
the same thing. For example, the words "take" and "eat" normally have totally
different meanings, so you wouldn't make them synonyms of each other. However,
if the player has a headache tablet, for instance, then "take tablet" and
"eat tablet" would both be valid. This is where the comma "," comes in - if
you include a comma in your input, all synonyms of all words separated by
the comma will match. So:
\begin{verbatim}
if (Parser.Said("eat,take tablet"))
\end{verbatim}
will match eat or take and all their synonyms, then tablet and its synonyms.

Another fairly common task with a parser is to check for optional words - for example,
if there is a brick wall on the screen, you want the player to be able to type "look wall"
and "look brick wall". Although this can be done with two OR'ed Said commands, AGS makes it
easier. You can use [brackets] to signify an optional word. So:
\begin{verbatim}
if (Parser.Said("look [brick] wall"))
\end{verbatim}
will match "look wall" and "look brick wall".

Now this is all very well, but in different rooms you have different items to interact
with - for example, in one room there might be a tree that the player should be able
to type "look at tree" to look at, and so on. Putting all this in your global script would make
a big mess. So, enter the \helpref{CallRoomScript}{CallRoomScript} function. Using this,
you can do:
\begin{verbatim}
  Parser.ParseText(input);
  String badWord = Parser.SaidUnknownWord();
  if (badWord != null)
    Display("You can't use '%s' in this game.", badWord);
  else if (Parser.Said("eat apple")) {
    Display("You'd love to, but you don't have one.");
  }
  ... // other game-wide commands
  else
    CallRoomScript (1);
\end{verbatim}

Then, the room script can check for things that the player can do in the current room.
See the \helpref{CallRoomScript}{CallRoomScript} description for more information.

\section{Translations}%

AGS now makes it easy for you to create translations of your games.
Right-click the "Translations" node in the tree, and choose "New translation". Once
you've named it, AGS will ask if you want to populate the file now. Say yes.

Creating the translation writes all lines of game text to the file - no script
sources, just all the displayable text from the game. The file is generated with
each line of text separated by a blank line.

You can now give this file to your translators. They should \bf{fill in each blank line
with the corresponding translation of the English line above it (DO NOT REPLACE THE
ORIGINAL ENGLISH LINES WITH THE TRANSLATION)}. If a line is left blank, it will simply
not be translated.

Once the translation is done, right-click the translation and choose "Compile".
It will be converted into a compiled translation (\verb$.TRA$) file in the 
Compiled folder, which can be used with the game engine.

Run the game Setup program, and select the translation from the drop-down box.
Then, run the game, and all the text should be translated.

\it{NOTE: With SCI fonts, only 128 characters are available, so many of the extended
characters needed for non-english translations are not available. You may need to use
substitute characters, or consider using TTF fonts for international applications. However,
bear in mind that TTF rendering slows down the engine.}

While most in-game text is translated automatically, there are a few instances when
this is not possible. These are when a script uses functions like Append to build
up a string, or CompareTo to check some user input. In these cases, you can use the
\helprefn{GetTranslation}{GetTranslation} function to make it work.

You'll also have noticed a "Update" option when right-clicking a translation. This is useful if you've
got a translated version of your game, but you want to update the game and add a few bits in.
Once you've updated your game, run the Update Translation option and the translation file
you select will get any new bits of text added to it at the bottom -- then you can just ask
your translator to additionally translate these lines.


\section{Global variables}\label{GlobalVariables}%

The Global Variables pane allows you to easily add variables to your game which
can then be accessed from all your scripts.

In previous versions of AGS, declaring a global variable in the script involved
defining it in three different places, with import and export clauses in the
appropriate locations. Now, this whole process is vastly simplified with the new
Global Variables Editor.

\bf{When should I use a global variable?}

Use a global variable when you need to store some information that you need
to access from different scripts. For example, if you want to store the player's
health and you want all your different scripts to be able to access this value,
then use a global variable.

If you just need to store some information locally (for example, a "door opened" flag
that only applies to one particular room) then you should declare the variable
manually at the top of the room's script file instead.

\bf{What about GlobalInts and Graphical Variables?}

GlobalInts and Graphical Variables were ways in which previous versions of AGS
provided global variable capabilities. They are now considered obsolete, and are
replaced with this new Global Variables system instead.

\bf{How do I use global variables?}

The Global Variables Editor is pretty self-explanitory. To add a variable, right-click
and choose "Add". You can name the variable, and choose its type and initial value.
Most of the time you'll probably be using the \it{int} and \it{String} types. Optionally,
you can also set a default value for the variable.

Then, in your scripts it's a simple matter of just using the variable with the name
that you gave it. Simple! So, for example if you add an int global variable called
"myVariable", then in your script you can just do things like this:

\begin{verbatim}
if (myVariable == 3)
{
  myVariable = 4;
}
\end{verbatim}

or

\verb$Display("myVariable: %d", myVariable);$

That's it! Just use it as you'd use any other variable declared in the script.

Note that some of the types available are managed instance pointers, like "GUI",
"DynamicSprite" and "Character". These are for more advanced users only.
If you create one of these you cannot set a default value, and it will initially
be set to \it{null}. You will need to initialize the pointer in your script to
point to something before you use it.


\section{Custom Properties}\index{Properties}%

\bf{What are custom properties?}

Suppose you're making a Lucasarts-style game, and you want all your hotspots to have
a default event (so if the player right-clicks a window, for example, "Open" will be
the default, but if they click on a pen, "Pick up" will be the default).

To do that, surely you would have to script in lots of code to change the default mode
over each different object?

This is where Custom Properties come to the rescue. You can create a custom property
for "Default event", for example, and then have some simple code in the global script
to use the setting accordingly.

\bf{How do I use them?}

You'll notice that characters, objects, hotspots, rooms and inventory items all have
a "Properties" option in their property grids. Select it and click the "..." button.

Since you don't yet have any custom properties, you'll get a blank window, so 
click the "Edit Schema" button. This takes you to the Schema Editor, where you
can create the various properties you want in your game. To begin with you are
presented with an empty list box, so right-click in it and choose "Add property".

In the "Add Property" window you can set various options about the new property:
\begin{itemize}
\item \bf{Name} - this is the name by which you will access the property from the script.
This cannot be changed after the property has been created.
\item \bf{Description} - this is the user-friendly description which will be displayed
in the custom property editor when you are setting the property.
\item \bf{Type} - this specifies what type of property you want. "Boolean" gives you
a checkbox (which will return 0 or 1 to the script), "Number" gives you a text box which
you can type numbers into, and "Text" gives you a larger text box which can store a string.
\item \bf{Default value} - this specifies what the default value of the property will be
for objects where you have not set it specifically.
\end{itemize}

For example, add a new "Boolean" property. Close the schema editor, and then click the
"Properties" button again. You'll now have a window with a checkbox with the description
text you typed in. You can click the "Edit schema" button there to return to the schema
editor if you like.

All types of game item share the same schema. That is, if you create a "Jibble" property
in the schema editor for a hotspot, it will also appear in the properties window for
characters, objects, and so on.

\bf{Getting values in the script}

To access the properties from the script, there are various script functions. See
their descriptions for how they work:

\helprefn{Character.GetProperty}{Character.GetProperty}, \helprefn{Character.GetTextProperty}{Character.GetTextProperty} ILBRK
\helprefn{Hotspot.GetProperty}{Hotspot.GetProperty}, \helprefn{Hotspot.GetTextProperty}{Hotspot.GetTextProperty} ILBRK
\helprefn{InventoryItem.GetProperty}{InventoryItem.GetProperty}, \helprefn{InventoryItem.GetTextProperty}{InventoryItem.GetTextProperty} ILBRK
\helprefn{Object.GetProperty}{Object.GetProperty}, \helprefn{Object.GetTextProperty}{Object.GetTextProperty} ILBRK
\helprefn{GetRoomProperty}{GetRoomProperty}, \helprefn{Room.GetTextProperty}{Room.GetTextProperty}

Custom property values cannot currently be set from within the game script - they are read-only
at runtime.

\section{Plugins}%

AGS supports user-written plugins in order to provide functionality to your game
that AGS itself does not support.

The plugin developer's guide is available from the Resources section of the AGS website.

Plugins come as DLL files with the names  AGS*.DLL, for example  agscircle.dll  might be a
plugin providing a DrawCircle script function. 

\bf{How to use a plugin}

So, you've downloaded a plugin for AGS. What do you do with it?
Well, firstly read any readme file that the plugin author has included. But to get
any plugin to work you must do the following:

1. Place a copy of the plugin files in the AGSEDIT directory (not your game folder).

2. Start the AGS Editor up, and load your game. Go to the Plugins node in the main tree.
Open it up, and you should see all available plugins listed. To use one in your game,
right-click it and choose "Use plugin". The plugin developer should provide
instructions on what to do next. Save your game to make sure that AGS remembers
that you want to use the plugin.

\section{Lip sync}%

If you want, AGS can pretend to 'read' out speech text. Go to the 'Lip Sync' pane
in the editor.

Normally when a character is talking, AGS simply cycles through the speech animation
from start to finish, and then loops back round. However, lip syncing allows you to be
cleverer by specifying a particular frame to go with various letters and sounds. Then,
as the character talks, AGS plays appropriate frames to simulate the character actually
saying those words.

In the Lip Sync Editor, you have 20 text boxes, one for each possible frame of the
talking loop. In each box, you can enter all the letters which will cause that frame of
the loop to be played. Letter combinations such as 'th' and 'ch' can be used too - AGS
will match each part of the spoken text to the longest possible phrase in the lip sync
editor.

separate the letters by forward slashes. For example,

\begin{verbatim}
3  R/S/Th/G
\end{verbatim}

will mean that frame 3 of the character's talking animation is shown whenever the
letter R, S, Th or G is spoken.

The "Default frame for unlisted characters" box allows you to set which frame is used
when a character not listed in any of the text boxes is encountered.


\bf{Voice speech lip sync}

AGS supports lip syncing voice speech to the talking animation. If you enable this
feature, you cannot use the standard lip-sync for non-voice lines.

\bf{NOTE: This is an unofficial feature and is not currently supported. Use at
your own risk}

\bf{NOTE:} The voice sync feature only supports Sierra-style speech.

In order to do this, you need to download the third-party PAMELA application:

\verb$http://www-personal.monash.edu.au/~myless/catnap/pamela/$

Set up the phenomes in Pamela so that there are only 10 (or as many talking frames as you have)
available choices. Then, in the Lip Sync pane of AGS, change the Type property to "Voice".
Enter the Pamela phenomes into the text boxes to create the association
between the pamela phenome code and the AGS frame number.

For example, enter "AY0" into frame 0's box, "E" into frame 1, and so forth - corresponding
to how it is set up in Pamela. For multiple phenomes to share the same frame, seperate them
with forward slashes -- for example, "AY0/AY1" allows both of those phenomes to correspond
to the specified frame.

Use the Pamela application on each of your speech lines, and save a Pamela project file
(.pam file) for each speech file, naming it the same as the speech.

For example, the pamela project for  EGO46.OGG  would be called  EGO46.PAM, placed
in your game's Speech folder.

When you build the game, this pam file is compiled into the speech.vox and will be used
to sync the animation of the talking frames during the game.

\bf{NOTE:} Voice lip sync does not work well with MP3 files. It is strongly recommended
that you use OGG or WAV for speech.



\section{New Game templates}\index{Templates, creating}%

When you choose "Start a new game" in the initial "Welcome to AGS" dialog
box, a window appears with various templates that you can base your game off.

AGS comes with a few standard templates, but you can create your own too.

\bf{Using downloaded templates}

If you've downloaded a game template from the internet, you should find a file with
a .AGT extension. This is the AGS Template File, and you just need to copy it into
the "Templates" folder within the AGS Editor directory.

\bf{Creating your own template}

A game template is basically just an archive containing all of the game source files,
which are then extracted into the new folder when the user creates a new game. It is
similar to you just zipping up your game folder and sending it to a friend - except that
this way looks far more professional.

To create a template, first of all you create a game as normal in the editor. Once you
have everything set up how you want it, select "Make template from this game" on the File
menu. This will prompt you for a name for the template (this is what will appear under its
icon in the "Start New Game" dialog box), and then it will go away and compile the template
for you.

The template game takes the following files from your game folder:
Core game files (GAME.AGF, ACSPRSET.SPR), all script and room files, all sound and music
files, all fonts, game icons, and *.TXT (to allow you to include a README.TXT or whatever).

If you include a  \bf{template.ico} file in your game folder when you make the template,
then it will be used as the icon in the Start New Game dialog box. Otherwise, the icon will
be taken from user.ico (if present), or if not it will get the default AGS icon.

You can also include a "template.txt" file in your game folder. If you do, then its contents
will be displayed to the user in a messagebox after they create a new game based on the
template. You could use this to explain briefly about any key aspects of the template, or
it could tell them to read your README.TXT file. This file should be quite small - its entire
contents need to fit into a standard message box.

\bf{NOTE:} Do not simply make a template out of a half-finished game. If you want to make
a template, you should start a game from scratch and make your changes - the user probably
doesn't want to already have a semi-completed game when they use your template.



\section{Debugging features}\label{Debuggingfeatures}%

It happens to the best of us - you're merrily ploughing along making your game, when
suddenly something just isn't working right. It's not always obvious where the problem is.

AGS now has some advanced debugging features that can help you out. If all else fails, you
can of course ask for help on the AGS forums.

There are two different types of debugging, that are enabled in different ways. The script
debugger is only enabled when you use F5 to run your game; but the Debug() commands are
only available when "Enable debug mode" is set in your Game Settings. So, just before you
release your game, set that option to False and compile the game again to make sure the
player can't cheat using these features.

\bf{1. The script debugger}

When you run the game using the Run (F5) option, the game will be started with the debugger.
This allows you to pause your game and follow it through one line at a time.

There are two main ways to use this feature:

* Press SCROLL LOCK while playing the game. This will break out when the next line of script is run.

* Place a breakpoint in your script. You do this by clicking on a line of code
in the script editor, then pressing F9. Then, when the game arrives at this
line of code, it will stop running. 

\bf{NOTE:} The editor will allow you to place a breakpoint on any line of script.
However, in order for it to work, it must be placed on a line that has some code on it.

Once the script has stopped, you can use the "Step Into" button (F11) to step through
the lines of code, one by one. To allow the game to continue running normally, use the Run (F5) button.

\bf{NOTE:} The Script Debugger is not supported on Windows 98 or Windows ME systems.
If you're still using Windows 98, please upgrade to Windows XP or Vista to take advantage
of this feature.

\bf{2. The Debug() command}

There is a scripting command, \helprefn{Debug}{Debug}, which you can use in your script
to help you find problems. The default setup enables some hotkeys for the various features -
in particular, Ctrl+X allows you to teleport to another room, Ctrl+A shows the walkable
areas on the screen and Ctrl+S gives you all the inventory items.

You can also use the Debug command to assign a hotkey to toggle FPS display on and off.
(FPS is Frames Per Second, which allows you to see the game speed and spot any slow-running
rooms).

This command only works if Debug Mode is enabled in your Game Settings.

\bf{3. Current room information}

Pressing Ctrl+D displays some information about the current room. It tells you what
room number you are in, followed by the current status of all objects in the room. After that,
another messagebox tells you all the characters that are in the current room and various
information about them.

This command only works if Debug Mode is enabled in your Game Settings.


\section{Auto-number speech files}%

If you've already made your game, and then you decide you want a voice pack to go with it,
the thought of manually adding speech numbers to every line of speech in the game is rather
daunting. But never fear, this is where the Auto-number Speech Files feature comes in.

If you select this option, then it will go through all the speech lines in the game and
add a &NUM to the start of them. A summary of the results is written to a file called
SPEECHREF.TXT in the game folder, so that you can easily see what file is what when
recording the speech.

The following types of message are auto-numbered. If one of the messages already has a speech
number, it will be overwritten:
\begin{itemize}
\item room messages set to be displayed as speech
\item dialog script messages
\item dialog options (if "Say" is selected for the option)
\item Say commands in scripts
\end{itemize}


\section{Integration with Windows}%

AGS has the ability to integrate with Windows in two ways. Firstly, it can
be set up to launch save games directly from explorer when the player double-clicks
them; and secondly, in Windows Vista, AGS can integrate with the Game Explorer feature.


\subsection{Enhanced Save Games}\label{EnhancedSaveGames}\index{Save games, enhanced}%

Optionally, AGS can set up Windows Explorer so that you can double-click on a save game
file to directly launch the game and continue from where you left off.

\bf{Setting it up}

In order to enable this, open the General Settings pane, and look for the "Saved Games"
section. Here, there is an option called "Enhanced Save Games". If you switch this on,
then AGS will enable the integration with Windows Explorer. 

To make this work, you need to set the Save Game File Extension setting to a file extension.
This is how Windows will identify the save game files, and you must supply an extension
of between 5 and 20 characters in length ("DemoQuestSave" would be an appropriate
extension for Demo Quest, for example).

By changing these settings, your game's saved game filenames will change, and therefore
you will lose access to any existing saved games.

\bf{Windows Vista extras}

If the player is running Windows Vista, then this feature will also allow them to see
the save game description and screenshot (if enabled) in the Explorer preview window:

LTSSimg src="images/GameExplorer3.jpg" GTSS ILBRK
\it{Save games with embedded screenshots on Vista}

\bf{Enabling the integration}

Once you've built the game, the integration won't be enabled immediately. If you want to
use this feature, you'll need to distribute your game in an installer rather than a zip
file, because there's an extra step you need to run after installation to set up the
association.

In your installer, you need to run the game executable with the special
parameter \verb$-registergame$  When you do this, AGS will create the necessary
associations in Explorer to get the feature working. If it is successful, it will
not display any messages.

You can manually test this by creating a shortcut to your game EXE file, and modifying
it to add \verb$-registergame$ to the end of the command line. Then, run the shorcut
and the associations should be created for you.

For un-installing, run the game EXE again but with a  \verb$-unregistergame$  parameter.
This will cause AGS to remove the associations from the player's system.

\bf{Cross-Platform Support}

Windows: \bf{ Yes }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ No }ILBRK
MacOS: \bf{ No }


\subsection{Windows Vista Game Explorer}\label{GameExplorer}\index{Vista Game Explorer}\index{Game Explorer}%

Windows Vista has a feature called the Game Explorer, which is a special folder on
the Start Menu that lists all the games installed on the user's system and provides
easy shortcuts to play them.

AGS is now able to add your games to this list. However, in order to do so you
would need to distribute your game using an installer rather than just in a plain
zip file, since you need to tell AGS to add the game to the list at install-time.

LTSSimg src="images/GameExplorer1.jpg" GTSS ILBRK
\it{The "Games" option launches the Game Explorer}

\bf{Enabling Game Explorer support}

Open the General Settings pane in the editor. If you scroll down to the bottom of the
list, you'll find a section titled "Windows Vista Game Explorer". The main setting
is called "Enable Game Explorer integration", and is disabled by default. Set this
to True if you want to be able to add your game to the Game Explorer (it will
have no effect on Windows XP and earlier versions).

\bf{Game Explorer settings}

The rest of the settings here allow you to set up various fields that the Game Explorer
can display. \bf{Developer Website} must be a URL starting with "http://" if you fill
it in, and \bf{Version} must be a four-point version number (eg. 1.0.0.0).

The \bf{Windows Experience Index} is a score that Vista gives each computer depending
on its game-playing prowess. 1 is the lowest score, and 5 is the highest at present.
This field allows you to specify the minimum score required to play your game (this
will usually be 1 for AGS games, unless you have high resolution and lots of animation).

\bf{Save games}

If you set the \it{Save games folder name} property in the Saved Games section, then
the Game Explorer will provide a right-click option to go straight to the save game folder.
This is only useful if you also enable Enhanced Save Games.

\bf{Parental controls}

AGS is not currently able to support the Vista Parental Controls, due to Vista requiring
the game to be digitally signed for this to work. Digital signatures require you to buy
a certificate from an authority such as Verisign, so at present they are not supported.
Your game will be classed as "Unrated" by Vista.

\bf{Boxart image}

The Game Explorer can display a high-resolution alpha-blended image for your game, rather
than the standard game icon. To utilise this, place a file called \verb$GameExplorer.png$
in your game folder, and rebuild the game EXE. This must be a PNG image, no larger
than 256 x 256 pixels:

LTSSimg src="images/GameExplorer2.jpg" GTSS ILBRK
\it{My game ("Chris Kwest") in the Game Explorer}

\bf{Adding the game to the Game Explorer}

In order to actually add the game to the Game Explorer's list, you need to run the
game executable with the special parameter \verb$-registergame$  When you do this,
AGS will add the game to the Game Explorer and exit. If it is successful, it will
not display any messages.

Therefore, as part of your installer, once the game files are all installed you should
add a step at the end to run the game EXE file with this parameter. It will do nothing
on Windows XP and earlier versions.

For un-installing, run the game EXE again but with a  \verb$-unregistergame$  parameter.
This will cause AGS to remove the game from the Game Explorer's list.

\bf{NOTE:} If you have both Enhanced Save Games and Game Explorer Integration enabled,
then the \verb$-registergame$ and \verb$-unregistergame$ commands will register/unregister
both.

\bf{Cross-Platform Support}

Windows: \bf{ Vista only }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ No }ILBRK
MacOS: \bf{ No }


\section{Source Control integration}\label{SourceControl}%

The AGS Editor supports integration with source control systems like SourceSafe and Perforce.

\bf{What is source control?}

Source Control allows you to easily keep copies of old versions of your files, so that
if you break something you can easily look back and see what your script was like
in previous versions.

AGS does not provide this functionality itself, but it is able to integrate with
Source Control applications such as SourceSafe and Perforce in order to allow you
to easily check things in and out.

\bf{Which providers are supported?}

AGS supports any source control system that can integrate with Visual Studio
(this is called the MSCCI interface). Most source control systems are quite
heavyweight and designed for use by large teams, but there are smaller
systems like SourceSafe available which work well on a standalone PC.

\bf{How do I use it?}

If AGS detects an installed source control system, an extra option "Add to
source control" will appear on the File menu. Use this to add your game to
source control, and from then on whenever AGS attempts to edit a file it
will prompt you to check it out if necessary.

You can check in files by using the "Show Pending Checkins" option that
appears on the File menu once you've added your game to source control.

\bf{Which files does AGS put under source control?}

AGS currently puts the main game file and your scripts, rooms, fonts and
translations under source control. Optionally, you can also add sound, music
and sprites by changing the setting in the General Settings pane.


\chapter{Scripting}%

The AGS scripting system allows you to write a mini-program, giving you great
control over your game.

\section{Scripting tutorial part 1}%

The Scripting Tutorial is online here:
\urlref{http://www.bigbluecup.com/actutor.htm}{http://www.bigbluecup.com/actutor.htm}

\section{Scripting tutorial part 2}%

The Scripting Tutorial Part 2 is online here:
\urlref{http://www.bigbluecup.com/actutor2.htm}{http://www.bigbluecup.com/actutor2.htm}

\section{Upgrading to AGS 2.7}\label{UpgradingTo27}%

The script language in AGS 2.7 has changed quite significantly from previous versions.
Many of the script commands have become \it{object-based}, which has several advantages
over the previous approach. This page will attempt to introduce you to the new method and
explain its benefits.

Firstly, so that you can get an idea of the changes, here's an example of some old-style
script commands and their new equivalents:
\begin{verbatim}
AnimateObjectEx(0,2,0,0,0,1);
ListBoxAdd(3, 5, "New item");
\end{verbatim}
becomes:
\begin{verbatim}
oWaterfall.Animate(2, 0, eOnce, eForwards, eBlock);
lstTest.AddItem("New item");
\end{verbatim}

Just from looking at that example the advantages should be obvious; the script is more
intuitive for people to learn, much easier to read (no guessing what all the numbers mean
in the AnimateObjectEx call), and therefore you're less likely to make mistakes when using it.
GUI controls having names brings it much more into line with Visual Basic-style GUI
development, so you don't have to remember what control number all your buttons are.

The script editor's autocomplete functionality has been significantly enhanced to aid
in all this as well. You'll see as you start to experiment that autocomplete pops up more
often and lists only the relevant commands thanks to object-based scripting.

\bf{So does this mean I have to throw out all my scripts?}

No, certainly not! The new version is fully backwards compatible, so all your existing
scripts will continue to work just fine. However, for any new scripts that you write,
it's strongly recommended that you use the new object-based commands.

\bf{Ok, so uh... what's changed exactly?}

The script language syntax hasn't changed at all (that's the way you use semicolons, brackets,
and so on). It's still just like it was before, but with some new additions. Most
significantly, most commands are now called \bf{on something}. For example, the old
command:

\verb$StopMoving(EGO);$

Just from looking at that, it's not at all obvious what StopMoving does. Does it stop
a character moving, an object moving, or does it stop the screen moving? It's not intuitive.
So now, rather than supplying the character as a parameter to the function, you actually
call the function \bf{on} the character. So:

\verb$character[EGO].StopMoving();$

Now it's perfectly clear that it's the character EGO that we want to stop moving.

Suppose you're wondering what commands you can call on a character. Previously it was hard
to tell, but now if you type  \verb$character[EGO].$  in the script editor, auto-complete will
pop up and list all the valid functions and properties that you can access on the character.

\bf{So I have to keep typing character[EGO] all the time? What a pain!}

Not so fast! Most of the new object-based commands can be called in two ways -- either
through the main array as we just saw, but also through what's called the character's
\bf{Script O-Name}. This is a shorthand that allows you to directly access things, and
for characters it is the script name in sentence case, with a "c" added to the beginning.
So, in this example it would be:

\verb$cEgo.StopMoving();$

This line has an identical effect to the one with character[EGO] that we used above.

Furthermore, the \it{player} variable is now kept up to date with the current player
character, so it is actually useful. In a multi-character game, what you previously had
to write like this:

\verb$StopMoving(GetPlayerCharacter());$

can now be done like this:

\verb$player.StopMoving();$

\bf{Hmm, I see... so what exactly has been object-ised?}

Currently, the following object-based things are available:

\begin{tabular}{|l|l|}
\row{ \bf{ Global array } & \bf{ O-Name example }
}\row{{ character[] } & { cEgo }
}\row{{ object[] } & { oDoor }
}\row{{ hotspot[] } & { hTree }
}\row{{ gui[] } & { gInventory }
}\row{{ inventory[] } & { iPinkPoster }
}\row{{ region[] } & { (none) }
}\end{tabular}

GUI controls are handled slightly differently. They all have a script name,
and are directly accessed via that. For example, if you set the script name of
a list box to "lstSaves", then you would use "lstSaves." to access it. There is no
global array of GUI controls.

\bf{How do I find out the new equivalents of old functions?}

The help file's index has been set up to automatically redirect you to the new commands.
Just open the help file, go to the index and type in the name of an old command, and
it will bring you to the new object-based equivalent (if there is one).

\bf{Which commands haven't been changed?}

Commands which don't operate on anything in particular (and therefore wouldn't really
benefit from being object-based) have been left alone. For example, SaveGameSlot, QuitGame
and so on have all remained identical to how they were in previous versions.

\bf{What's the deal with these "eBlock" type things?}

AGS now supports \bf{enumerated types}. Basically, in situations where you have to choose
one from a list of possible options, an enumerated type (or \it{enum}) now steps in. In
the past, you had commands with descriptions like this:

"Pass 1 if you want the function to block, or 0 if you don't".

This lead to lots of 1's and 0's in function calls, which are hard to read. Now, instead
of this each number is represented by an easy-to-remember word (such as \it{eBlock} and
\it{eNoBlock}). Even better, when you call a function that uses an enum parameter,
auto-complete automatically pops up the list of options for you to choose from.

See the \helprefn{enum keyword}{enum} description for information on how to create your own.

\bf{So do I have to pass all these things like eBlock every time I call the function?}

Nope! Many functions now support \bf{optional parameters}, where the most common options
are selected automatically. If you look at the help for a function such as the
\helprefn{Animate character command}{Character.Animate}, you'll see some of the parameters
are defined as "optional". This means that you don't have to supply them; if you don't,
the default option that will be chosen is described in the help for that command.

\bf{So what else is new?}

Well, 2.7 introduces the \it{float} data type, so AGS now finally supports floating-point
arithmetic in your scripts. Also, for more advanced scripters, you can create your own
member functions (including protected and static ones) to write cleaner script than just
having a bunch of global functions.

Also, the script editor is now much better at checking your script for errors. You may
well find that a script which compiled fine before no longer works on 2.7. Hopefully
the error message should direct you towards fixing any problems.

\bf{Is there anything else I should watch out for?}

Because of the new additions, the script language has more reserved words than before. For
example, words like "gui", "object" and "hotspot" are now reserved (since they are used
to access the global arrays). If your script uses any variables with these names, it will
no longer work. You'll need to change the variable name in order to compile.

Also, the script language now supports \it{pointers}. Because they are a fairly
complex topic, there's a \helprefn{separate page}{Pointers} devoted to explaining what
they are.

\bf{Blimey, that's a lot to take in. Where do I start?}

I'd recommend attempting to write your next section of script in the new way. Each time
you're about to use an old-style command, simply look it up in the manual to find out
what it's replacement is.

Once you get used to the new system, I'm sure you'll agree that it is a significant
improvement over the old scripting system and you'll start to enjoy the benefits of
faster and more intuitive coding.

As always, if there's something you really can't get your head round, post on the
AGS Forums and we'll help you out as best we can!

Have fun, ILBRK
CJ

\bf{Next:} \helprefn{Pointers in AGS}{Pointers}


\section{Pointers in AGS}\label{Pointers}%

Various commands in the new scripting language will require you to use pointers.
This section has been split into three separate topics to introduce you
to pointers depending on your previous programming experience -- select one of the
links below:

\subsection{Pointers for programming newbies}\label{PointersForNewbies}%

Pointers can be quite a daunting prospect, and in languages like C and C++ they certainly
are; but AGS tries to make things as simple as possible.

Basically, a pointer is a variable that \it{points} to something of a particular type.
For example, a \it{Character} pointer would point to characters. What's the point of
all this, I hear you ask?

Well, let's look back at AGS 2.62. If you wanted to reference a particular hotspot,
you'd need to remember its number. If you wanted to switch on an object, you'd need to
remember what number it was too. And because you could accidentally use an object
number where you wanted a hotspot number, mistakes could easily happen and it all got
rather messy.

That's where pointers step in -- basically, they allow you to do away with identifying
things by number, and in the process provide \it{type checking}, so you can't accidentally
use a hotspot where you meant to use an object.

Let's look at an example. If you wanted to write a string to a file in 2.62, you'd do this:
\begin{verbatim}
int handle = FileOpen("temp.txt", FILE_WRITE);
FileWrite(handle, "Test!");
FileClose(handle);
\end{verbatim}
That's simple enough; but what if you wanted to open the file in one place, and write
to it somewhere else? You'd have to make \it{handle} a global variable, and then make
sure you remembered that it was a file handle and not a hotspot number or anything else.
Now, with 2.7 the same code would be:
\begin{verbatim}
File *file = File.Open("temp.txt", eFileWrite);
file.WriteString("Test!");
file.Close();
\end{verbatim}
Looks fairly simple, doesn't it. The only slightly confusing part is getting used
to declaring the variable as \verb$File*$ rather than \verb$int$; but that's something
you'll get used to quite quickly, and all the examples in the manual should point
you in the right direction.

Let's look at another example. Suppose you want a variable that contains the current
hotspot that the mouse is over. In 2.62, you might have something like this:
\begin{verbatim}
// top of global script
int mouseOverHotspot;

// repeatedly_execute
mouseOverHotspot = GetHotspotAt(mouse.x, mouse.y);
\end{verbatim}
How would you do this in 2.7? Well, quite simply:
\begin{verbatim}
// top of global script
Hotspot *mouseOverHotspot;

// repeatedly_execute
mouseOverHotspot = Hotspot.GetAtScreenXY(mouse.x, mouse.y);
\end{verbatim}
But hold on, what if you want to know whether the mouse is over your Door hotspot (say
it's hotspot 2). In 2.62, you'd have done:
\begin{verbatim}
if (mouseOverHotspot == 2) {
  Display("Mouse over the door");
}
\end{verbatim}
but that's rather messy, because what if you change the door's hotspot number? You'd
have to remember to go back and change all the 2's to 3, or whatever. In 2.7, you now just
do this (assuming you gave the hotspot a script name of hDoor):
\begin{verbatim}
if (mouseOverHotspot == hDoor) {
  Display("Mouse over the door");
}
\end{verbatim}
If you're a fan of numbers for some strange reason, you can still use them like this:
\begin{verbatim}
if (mouseOverHotspot == hotspot[2]) {
  Display("Mouse over the door");
}
\end{verbatim}
So, that concludes our introduction to pointers. Hopefully you've got an understanding of
what they are and what they do; if there's anything you can't work out, feel free to ask
on the Technical forums.


\subsection{Pointers for people who know Java or C\verb$#$}\label{PointersForJavaCSharp}%

AGS pointers work in a very similar way to object variables in Java and C\verb$#$. The main
difference is that AGS pointers are declared in the C-style manner with an asterisk t
represent the pointer. So:
\begin{verbatim}
Hotspot *hs;
\end{verbatim}
would declare a variable \it{hs} which points to a Hotspot. This would be equivalent to
the following in Java or C\verb$#$:
\begin{verbatim}
Hotspot hs;
\end{verbatim}
In AGS, pointers are used to point to various built-in types, such as Hotspots, Inventory Items,
Characters and so on. Because AGS does not have a \it{new} keyword, you cannot create pointers
to custom struct types.

You use pointers in the same way as you would in Java and C\verb$#$. Various built-in AGS static
methods return a pointer to an instance (for example, \helprefn{File.Open}{File.Open},
\helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY}, and so on). You can save this
pointer into a pointer variable, and then call its methods as you would in Java or C\verb$#$.
The following examples are all valid:
\begin{verbatim}
File *theFile = File.Open("test.dat", eFileWrite);
if (theFile == null) Display("It's null!");
File *file2 = theFile;
if (theFile == file2) Display("They're the same file!");
theFile = null;
file2.WriteInt(10);
file2.Close();
\end{verbatim}
If you attempt to call a method on a null pointer, an error will occur (just like you'd
get an exception in Java or C\verb$#$).

Pointer memory management in AGS is all automatic -- the memory is freed when there are
no longer any variables pointing to the instance. Thus, if you have global pointer variables
in your global script, it's a good idea to set them to \it{null} when you're no longer
using them, to allow the memory to be freed.


\subsection{Pointers for people who know C or C++}\label{PointersForC}%

Pointers in AGS are based on the C/C++ syntax, so they are declared with an asterisk.
However, in AGS you can only create pointers to built-in AGS types, and not to any
custom structs declared in your script.

Pointer members are accessed with the dot operator, and not the \verb$->$ C-style operator.
Because AGS doesn't support features such as pointers-to-pointers and so forth, there
is no need for a separate operator.

In AGS, pointer memory management is done automatically based on reference counting (similar
to the way COM works), so there is no \it{new} or \it{delete} keyword. When an object
is no longer referenced by any pointer variables, it will be freed. For this reason,
if you have any global pointer variables it's advisable to set them to \it{null} if
you are done with them.

AGS pointers are strongly typed, and you cannot cast between types at will like you
can in C and C++. AGS will only allow you to compare and assign pointers of the same
type, or of the same base type. There is a special keyword \it{null} which all pointers
can be set to and compared with, which indicates that they are unassigned.

Because there is no \it{new} keyword, you cannot create object instances; rather, they
are returned by static member functions in AGS, such as \helprefn{File.Open}{File.Open}
and \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY}. See the examples for the
functions to get an idea of how to use them.


\section{Upgrading to AGS 2.71}\label{UpgradingTo271}%

AGS 2.71 adds new simple string support to the scripting language. Strings have long
been a pain to use in AGS, but this is finally addressed by v2.71.

There's a new String type (that's a capital 'S'). These new strings behave like Java/\verb$C#$
strings in that you can easily assign to and manipulate them.

For example, in 2.7 and previous versions, you had to do this: ILBRK
\begin{verbatim}
string text;
StrCopy(text, "This is my text");
\end{verbatim}
in 2.71, you can now do:
\begin{verbatim}
String text = "This is my text";
\end{verbatim}
Furthermore, the == and != operators can be used to compare strings for equality (equivalent
to using StrComp but much more intuitive). An additional benefit is that there is no longer
a need for GetText() and SetText() methods -- instead, we can now just have Text properties.

All the old-style functions that took a "string buffer" parameter have now been replaced with
new ones that return a string instead. Where properties have been created, you should be able
to use them like any other property, so:
\begin{verbatim}
lblLabel.Text = "Hello";
String buttonValue = btnOK.Text;
\end{verbatim}
and so on.

\bf{NOTE:} Some of the new functions are provided on the Game object -- for example, the new
GetSaveSlotDescription function needs to be called like this:ILBRK
\verb$String description = Game.GetSaveSlotDescription(10);$ ILBRK
This is part of a move towards all built-in functions being object-based, but watch out for it
as it could well cause some confusion. The manual will show you which functions require this.

Rather than using old functions like StrCat and StrContains, you now call the functions
directly on the strings:
\begin{verbatim}
String text = "Hello";
text = text.Append("World");
\end{verbatim}
will mean that \it{text} now contains "HelloWorld". ILBRK
Note the \bf{text =} in that expression. Functions like Append will return a modified version
of the string, they won't actually change the original. Therefore, to update the \it{text}
variable you need to assign the result to it.

\bf{Backwards compatibility}

In order to maintain backwards compatibility, a new "const" keyword has been added. This
applies only to old-style strings, and allows them to interoperate with the new ones. A
new-style String can be passed to a function that expects a "const string" (which means
that it will not be allowed to change the string's contents), but cannot be passed to a
function that expects a "string" (since it could overwrite the string data and mess things up).

So, you may find that any custom functions you have that take a string parameter stop 
working. If this is the case, change the parameter from "string" to "const string" and
that should fix it.

Apologies for the inconvenience, but this is the only way to allow new Strings to
interoperate safely with old-style strings.



\section{Calling global functions from local scripts}%

You can now call your global script functions directly from your rooms. This
means that if you have a common script that you want to use in response to
various different events during the game, you can call it from your room
scripts rather than duplicating code.

To use a global function, open up the main script header (GlobalScript.ash), 
and add a line similar to the following:
\begin{verbatim}
import function my_function_name (parameters);
\end{verbatim}
Where \it{my_function_name} is the name of the global script function, and
\it{parameters} is a list of the TYPES ONLY of the parameters it takes. For example,
if you had in your global script:
\begin{verbatim}
function do_animation (int anim_number) {
\end{verbatim}
then you would write:
\begin{verbatim}
import function do_animation (int);
\end{verbatim}
To use the function, you just call it normally in your script, eg:
\begin{verbatim}
do_animation (3);
\end{verbatim}
You can also return a value to the caller by using the "return" statement,
and the local script picks this up the same way it does with built-in
functions. For example, the end of your global script function could be:
\begin{verbatim}
return 51;
\end{verbatim}
then the local script just does:
\begin{verbatim}
int value = do_animation(3);
\end{verbatim}

\section{The script header}\index{Script header}\index{Header}%

This allows you to include the same information into all your scripts. For
example, if you have a global function you want all the room scripts to use,
you can add its import definition to the header file.

Do NOT place any actual functions or variables in this header, because if
you do you will need to re-compile ALL the scripts whenever you modify the
function. Instead, place your functions in your global script and just place
an import line in the header file to allow the other scripts to access it.


\section{String formatting}\label{StringFormats}%

You will find many times in your game when you need to create a string based
on the values of variables, and functions like \helprefn{Display}{Display} and
\helprefn{String.Format}{String.Format} allow you to do so.

AGS uses printf-style argument formatting (used by the C language). This means
that you intersperse your text with special codes to insert a variable's value. These
special codes begin with a percent sign, and then specify the variable type. The
actual variables that you want to display are then listed afterwards.

The special codes you can use are as follows:
\begin{tabular}{|l|l|}
\row{ \bf{ Code } & \bf{ Description }
}\row{{ \verb$%d$ } & { Integer (use to display value of int and short variables) }
}\row{{ \verb$%0Xd$ } & { Integer left-padded with up to X zeros }
}\row{{ \verb$%s$ } & { String (use to display string variables) }
}\row{{ \verb$%c$ } & { Character (displays the ASCII character of the supplied value) }
}\row{{ \verb$%f$ } & { Float (displays a float variable) }
}\row{{ \verb$%.Xf$ } & { Float to X decimal places }
}\row{{ \verb$%%$ } & { Display the percent character (ie. no variable) }
}\row{{ \verb$[$ } & { Inserts a new line into the message }
}\end{tabular}

Some examples:
\begin{verbatim}
int life = 42;
float twoPi = Maths.Pi * 2.0;
String message = "A string variable";

Display("A normal string with no variables.");
Display("The meaning of life is %d.", life);
Display("The meaning of life in 3 digits is %03d.", life);
Display("2 times Pi is %f.", twoPi);
Display("The message says: %s.", message);
\end{verbatim}
would display:
\begin{verbatim}
A normal string with no variables.
The meaning of life is 42.
The meaning of life in 3 digits is 042.
2 times Pi is 6.283186.
The message says: A string variable.
\end{verbatim}

You can display as many variables as you like in one line:
\begin{verbatim}
int life = 42;
float twoPi = Maths.Pi * 2.0;

Display("Life is %d, 2 x Pi = %f, and my dinner is %s.", life, twoPi, "awful");
\end{verbatim}
but, \bf{be very careful} that you supply the right number of variables to correspond
with the tags you use in the text. If you don't supply enough variables, your game could
crash.


\section{Multiple Scripts}\label{ScriptModules}\index{Modules}\index{Script modules}%

If you're working on a fairly large game, you'll find that your global script can
quickly become rather large and unwieldy. AGS allows you to create extra scripts
(formerly known as Script Modules) in order to split up your code and easily
import scripts written by other people.

The main global script still has to contain all the event functions (Look At
Character scripts, Interact With Inventory scripts and so forth) and all the GUI
handlers (btnSave_Click, etc).

But if you have any custom functions then you can put them in a separate script in
order to divide up your code. Scripts have the added advantage that they can be
easily exported and imported, if you want to share some of your code with other
people, or even just move it from one game to another.

The scripts for the game can be seen under the "Scripts" node in the project tree. Each
script has its own header, which is where you place the \helprefn{import}{importkeyword}
definitions for that script to allow the rest of your game to access its functionality.

The order of the scripts is important. A script can only use functionality from other
scripts that come before it in the list, so the Move Up and Move Down options allow you
to adjust the order. The global script is always at the bottom so that it can access all
other scripts, and room scripts are automatically provided with access to all the scripts.

As an example, suppose you want to have a special \it{AddNumbers} function in a module.
You'd create a new script, then put this in its header file (.ASH):
\begin{verbatim}
import function AddNumbers(int a, int b);
\end{verbatim}
Then, in the script file (.ASC) you could put:
\begin{verbatim}
function AddNumbers(int a, int b) {
  return a + b;
}
\end{verbatim}
That's the basic principle behind using multiple scripts!

\bf{Special functions}

Can extra scripts use special functions like \verb$game_start$ and \verb$repeatedly_execute$?
Well, yes and no. They can contain the following functions, and they will
be called at the appropriate times just before the global script's function is:
\begin{itemize}
\item function game_start()
\item function on_event(EventType event, int data) 
\item function on_key_press(eKeyCode keycode) 
\item function on_mouse_click(MouseButton button) 
\item function repeatedly_execute()
\item function repeatedly_execute_always()
\end{itemize}
All other special functions, such as \verb$dialog_request$, will only be called in
the Global Script, even if they exist in another script. If you need other scripts to
handle any of this functionality, you can simply create a custom function in the
script and then call it from the global script.

The \helprefn{ClaimEvent}{ClaimEvent} command is supported for on_key_press, on_mouse_click
and on_event. Calling it prevents the rest of the scripts (including the global script) from being called.


\section{Understanding blocking scripts}\label{BlockingScripts}\index{Blocking scripts, explained}%

You will see some commands listed as "blocking", where control does not return
to the script until the command finishes. But what does this mean, exactly?

In order to better understand this, we need to explore a little about the way
that the AGS script engine works. In an AGS game, there are three script \bf{threads}
that can be running at once. Think of a thread as a mini-CPU that executes your scripts.

At the start of the game, the threads are all idle (not running any scripts):

LTSSimg src="images/threads1.gif" GTSS

Now, as and when your scripts need to be run, AGS will try to run them on the
appropriate thread (the Room thread for local scripts, and the Global thread
for global scripts).

So, on the first game loop, your global scripts' repeatedly_execute will be run:

LTSSimg src="images/threads2.gif" GTSS

That's fine, and when it finishes running the thread becomes idle again.

But, suppose that within repeatedly_execute, you make a call to the Character.Say
command. Say (or \it{DisplaySpeech} in old-style scripting) is a blocking command
and does not return until the character finishes talking:

LTSSimg src="images/threads3.gif" GTSS

The global thread is now \bf{blocked}, waiting for the character to
finish talking. This means that none of your global script functions such
as repeatedly_execute, on_event and on_key_press will be run while the character
is talking, since the thread is busy.

Now, AGS does queue up to 5 script functions to be run on the thread
as soon as it is free; but if you have a lot of things happening within your script,
it's possible that you will lose some events such as on_events and keypresses if
you script is blocked for a long time.

Let's explore the most common situation in which this causes confusion. Suppose you
have a \it{Player looks at inventory} event on a Key inventory item, which
runs a script to display a message.

Let's also suppose that you have some code at the end of your on_mouse_click function
to make the character stand still after running mouse click events.

What you'll find is that the code at the end of on_mouse_click actually gets called
\it{before} the inventory item's event. Let's look at why:

LTSSimg src="images/threads4.gif" GTSS

Remember that AGS does not run events automatically; rather, the on_mouse_click
script function handles the mouse click and calls ProcessClick to run the appropriate
event. When it does so, it finds that the key's Look At Item event has a script function
associated with it.

But oh no! Inventory item scripts are in the global script, and the global thread is
already blocked because of the mouse click. Therefore, the inventory event script
gets added to the thread's queue, and on_mouse_click then finishes running.
The inventory event script will follow on afterwards.

Now you might think that this means that object and hotspot events can run within
on_mouse_click, since they use the room thread, like this:

LTSSimg src="images/threads5.gif" GTSS

However, this is not the case. It is still the global thread that is calling ProcessClick,
so the room script will actually be run on the global thread once it is free.

Finally, we come onto the No-Block thread. This thread is only used to run the
\it{repeatedly_execute_always} function. Because repeatedly_execute_always is not
allowed to run any blocking functions, this ensures that the thread never gets blocked
and so it will always run, even when the other threads are busy:

LTSSimg src="images/threads6.gif" GTSS

I hope that helps explain blocking in terms of AGS scripting. If there's anything that
you don't think is clear, please suggest amendments on the Technical forum.


\section{Dynamic Arrays}\label{DynamicArrays}%

Suppose that you're writing a script that you want people to be able
to use in their games. You need to store the Health for every character
in the game, but you don't know how many characters there will be. What do you do?

Dynamic Arrays are designed for just this purpose. You can declare an array like this:

\verb$int characterHealth[];$

in your script file. This special notation tells AGS that you don't yet know how large
you want the array to be. Now, before you use the array (so probably in game_start),
you can do this:

\verb$characterHealth = new int[Game.CharacterCount];$

If you forget to do this \verb$new$ command, you'll get a Null Pointer Error if you try
to access the array. You can change the size of an array by simply using another
\verb$new$ command with a different size; but this will erase the contents of the
array in the process.

Currently dynamic arrays are supported as global and local variables, but
you can't put one inside a struct.
Also, at present you can create arrays of basic types (int, char, etc) and
of built-in types (String, Character, etc) but not of custom structs.


\section{Extender functions}\label{ExtenderFunctions}%

Suppose that you wanted to add a new function, "Scream", to characters which would make 
them cry out "AARRRGGGHHH". Because the Character type is defined within AGS, it's not
possible for you to just add a method to it.

That's where Extender Functions come in. Here's an example:
\begin{verbatim}
function Scream(this Character*)
{
this.Say("AAAAARRRRGGGGHHHHHH!!!!");
}
\end{verbatim}
This adds a new "Scream" function to the Character type, so that in your script code
elsewhere you can do things like:
\begin{verbatim}
player.Scream();
character[EGO].Scream();
\end{verbatim}
and so on.

\bf{Where do I put this code?}

In the script header, you'd put:

\verb$import function Scream(this Character*);$

and then put the main function in the script file. This will then allow it to be used
by other scripts.


\section{Game variables}\label{Gamevariables}\index{Variables}\index{game. variables}%

The following variables are available to your script. They allow you to do various tweaks
to the engine at run-time.

Names in \bf{bold} are \bf{read-only variables} and should NOT be modified by the script.

All the following variables are \verb$int$ variables.

\begin{tabular}{|l|l|}
\row{ { game.abort_key }&{ The keycode for Abort Game, which allows the you to quit even if your script is stuck. Default 324 (Alt+X). }
}\row{ { game.ambient_sounds_persist  }&{  If 0 (default), ambient sounds are stopped on room change.
                                      Set to 1 to tell AGS to leave ambient sounds playing when going to a new room. }
}\row{ { game.anim_background_speed  }&{ The current room's animating background speed - same values as in editor. }
}\row{ { game.auto_use_walkto_points  }&{ Default 1; set to 0 to stop AGS automatically using hotspot walk-to points. }
}\row{ { game.bgspeech_game_speed    }&{ If 0 (default), background speech stays on the screen
                           for the same amount of time, no matter what the game speed.
                           If 1, the amount of time it stays is relative to the game speed. }
}\row{ { game.bgspeech_stay_on_display    }&{ If 0 (default), background speech is removed when
                           a Say command happens; if 1, it isn't.}
}\row{ { game.close_mouth_end_speech_time }&{ At the end of speech text, the speech animation
                           will stop for this number of game loops. Default 10. No affect in voice mode.}
}\row{ { game.debug_mode    }&{     Whether we are in debug mode or not.}
}\row{ { game.dialog_options_x    }&{ Offset into dialog options GUI to compensate for borders }
}\row{ { game.dialog_options_y    }&{ Offset into dialog options GUI to compensate for borders }
}\row{ { game.disable_antialiasing }&{ Set to 1 to disable smoothing of scaled characters,
                              overriding the user's choice in Setup. Default 0. }
}\row{ { game.following_room_timer}&{ How long to wait before following char emerges in
                           new room, default 150. (higher is longer).}
}\row{ { game.keep_screen_during_instant_transition }&{ Normally the Instant transition blacks the screen in 8-bit 
  colour modes, to avoid strange palette effects. However you can set this to 1 to prevent it doing so. }
}\row{ {\bf game.inv_activated    }&{ Inventory item that the player last clicked on. Useful for unhandled_event. }
}\row{ { game.inventory_greys_out }&{ Set to 1 to make inventory controls grey out when GUI disabled is set to "GUIs Grey Out" }
}\row{ { game.lipsync_speed }&{ Similar to Game.TextReadingSpeed, but this determines how quickly the text is 'read' out by the mouth moving.
                           You should normally only set this faster than text_speed, otherwise the reading will get cut off when the text times out. Default 15. }
}\row{ { game.max_dialogoption_width  }&{ Maximum width of textwindow-based dialog options
                           box. Default 180. }
}\row{ { game.min_dialogoption_width  }&{ Minimum width of textwindow-based dialog options
                           box. Default 0. }
}\row{ { game.narrator_speech }&{ Which character ID to use for voice speech within Display() command. Default initial player character. You can also use NARRATOR which uses 'NARR' prefix - special narrator character. }
}\row{ { game.no_textbg_when_voice  }&{  Normally 0. If 1, and the Sierra-style With Background
                           speech style is in use, will change to the Sierra-style (No Bg) if
                           a voice speech line is present. }
}\row{ { game.read_dialog_option_color  }&{  By default, -1. You can set this to a colour number, in which
                case dialog options that the player has selected before will be displayed in this colour. }
}\row{ { game.roomscript_finished }&{  The on_call function has completed executing. (See
\helprefn{CallRoomScript}{CallRoomScript}) }
}\row{ {\bf game.score          }&{    The player's score. To modify the score, use the
  GiveScore script function.}
}\row{ { game.score_sound    }&{    Sound effect to play when the player gets points, originally
  set in the editor. }
}\row{ { game.screenshot_height }&{  The height of screenshot images when saved into save games.
     The largest you can have is the full screen size (320x200), which gives the highest
     quality but the largest size save game files. The default is 160x100. }
}\row{ { game.screenshot_width }&{  The width of screenshot images when saved into save games. }
}\row{ { game.show_single_dialog_option }&{ If only a single dialog option is available, show it anyway (default=0) }
}\row{ { game.sierra_inv_color }&{  The background color of the sierra-style inventory.}
}\row{ { game.skip_display   }&{    Setting for how Display() messages are skipped;
                           valid values are same as for SetSkipSpeech (default 3).}
}\row{ { game.skip_speech_specific_key }&{ Default 0. You can set it to a keycode, in which case only that key can skip speech text. }
}\row{ { game.speech_bubble_width }&{ Maximum width of the thought bubble text window (default 100) }
}\row{ { game.speech_text_align }&{ Sets how text in Lucasarts-style speech is aligned. Same possible values as game.text_align, default eAlignCentre }
}\row{ { game.speech_text_gui }&{   The textwindow GUI number used for sierra-style speech.}
}\row{ { game.text_align }&{ Sets how text in message boxes and Sierra-style speech is aligned: ILBRK
 eAlignLeft:   text aligned to left within message box (default) ILBRK
 eAlignCentre: text is centred within the message box ILBRK
 eAlignRight:  text is right-aligned within the message box ILBRK
 These options do not affect Lucasarts-style speech, which is always centred. }
}\row{ { game.text_shadow_color}&{  Color used for speech text shadow (default 16).}
}\row{ { game.top_bar_XXXX  }&{ Customizations for \helprefn{DisplayTopBar}{DisplayTopBar}, see link for details }
}\row{ { game.total_score   }&{     Maximum possible score, initially set in the editor.}
}\row{ { game.used_mode     }&{     Cursor mode used with last click (use with "any click"
                           events to find out which mode was used)}
}\row{ {\bf mouse.x         }&{       Mouse X co-ordinate when the last game loop was run (320-res)}
}\row{ {\bf mouse.y          }&{      Mouse Y co-ordinate when the last game loop was run (320-res)}
}\row{ { palette[SLOT].r }&{       The red component (0-63) of palette slot SLOT}
}\row{ { palette[SLOT].g  }&{      The green component (0-63) of palette slot SLOT }
}\row{ { palette[SLOT].b  }&{      The blue component (0-63) of palette slot SLOT}
}\row{ { player.[x,y,name,...] }&{ Alias to the current player character. }
}\end{tabular}


\section{Predefined global script functions}\label{TextScriptEvents}\index{dialog_request}\index{game_start}\index{on_event}\index{interface_click}\index{on_key_press}\index{on_mouse_click}\index{unhandled_event}%

In your main global script file, there are some functions which are
automatically added when you create the game. These are global events, and the
function is called when a particular event happens. There are also some
other events which you can add if you want to.

The available event functions are:
\begin{description}
\item [dialog_request (int parameter)]
  Called when a dialog script line "run-script" is processed. PARAMETER is
  the value of the number following the "run-script" on that line of the
  dialog script.
\item [game_start ()]
  Called at the start of the game, before the first room is loaded. You can
  use this to set up the initial positions of characters, and to turn
  GUIs on and off. \bf{You cannot run animations or do anything else
  which relies on a room being loaded}.
\item [interface_click (int interface, int button)]
  \bf{(Now Obsolete)} Called when the player clicks on a button on a GUI which has its
  action set as "Run script". INTERFACE is the number of the GUI which they
  clicked on. BUTTON is the object number of the button within this GUI.
\item [on_event (EventType event, int data)]
  Called whenever certain game events happen. The value of DATA depends on
  which event has occurred. This allows you to perform checks or update things
  every time the player does something, regardless of which room it is in.
  The possible values of event are:\begin{verbatim}
eEventEnterRoomBeforeFadein
      called just before room Player Enters Room event is run.
      DATA = new room number
eEventLeaveRoom
      called just after room Player Leaves Room event is run.
      DATA = room number they are leaving
eEventGotScore  
      called whenever the player's score changes
      DATA = number of points they got
eEventGUIMouseDown
      called when a mouse button is pressed down over a GUI
      DATA = GUI number
eEventGUIMouseUp
      called when a mouse button is released over a GUI
      DATA = GUI number
eEventAddInventory
      the player just got a new inventory item
      DATA = inventory item number that was added
eEventLoseInventory
      the player just lost an inventory item
      DATA = inventory item number that was lost
eEventRestoreGame
      tells your game that it has just been restored from a save game
      DATA = save slot number\end{verbatim}
\item [on_key_press (eKeyCode keycode)]
  Called whenever a key is pressed on the keyboard. KEYCODE holds the ASCII
  value of the key. A list of these values is in \helpref{this section}{ASCIIcodes}.
\item [on_mouse_click (MouseButton button)]
  Called when the player clicks a mouse button. BUTTON is either LEFT,
  RIGHT or MIDDLE, depending on which button was clicked. The "mouse.x" and "mouse.y"
  global variables contain the mouse's position. ILBRK
  If 'Handle inventory clicks in script' is enabled in the game options, this
  function can also be called with eMouseLeftInv, eMouseMiddleInv or eMouseRightInv, which
  indicate a left, middle or right click on an inventory item, respectively. ILBRK
  If 'Enable mouse wheel support' is enabled, this function can also be called with
  eMouseWheelNorth or eMouseWheelSouth, which indicate the user moving the mouse wheel north or
  south, respectively.
\item [repeatedly_execute()]
  Called every game cycle (normally 40 times per second).
  See \helprefn{this help page}{RepExec} for more information.
\item [repeatedly_execute_always()]
  Called every game cycle, even when a blocking routine (eg. speech/cutscene) is in
  progress. You \bf{cannot} call any blocking functions from this event handler. 
  See \helprefn{this help page}{RepExec} for more information.
\item [unhandled_event (int what, int type)]
  Called when an event occurs, but no handler is set up in the Events list.
  This could be used to display a default "I can't do that" type of message.
  The values of WHAT and TYPE tell you what the player did. ILBRK
  The possible values are listed below:\begin{verbatim}
	WHAT TYPE Description
	 1    1   Look at hotspot
	 1    2   Interact with hotspot
	 1    3   Use inventory on hotspot
	 1    4   Talk to hotspot
	 1    7   Pick up hotspot
	 1    8   Cursor Mode 8 on hotspot
	 1    9   Cursor Mode 9 on hotspot
	 2    0   Look at object
	 2    1   Interact with object
	 2    2   Talk to object
	 2    3   Use inventory on object
	 2    5   Pick up object
	 2    6   Cursor Mode 8 on object
	 2    7   Cursor Mode 9 on object
	 3    0   Look at character
	 3    1   Interact with character
	 3    2   Speak to character
	 3    3   Use inventory on character
	 3    5   Pick up character
	 3    6   Cursor Mode 8 on character
	 3    7   Cursor Mode 9 on character
	 4    1   Look at nothing (ie. no hotspot)
	 4    2   Interact with nothing
	 4    3   Use inventory with nothing
	 4    4   Talk to nothing
	 5    0   Look at inventory
	 5    1   Interact with inventory (currently not possible)
	 5    2   Speak to inventory
	 5    3   Use an inventory item on another
	 5    4   Other click on inventory\end{verbatim}
  Note that the "Character stands on hotspot" event does not trigger this
  function, and it will not be triggered if there is an "Any click" event defined.
  
  This function is \bf{not} triggered if the player clicks on nothing (hotspot 0).
\end{description}

The \it{on_key_press} and \it{on_mouse_click} events can also be handled by
individual room scripts. If you add their function definitions to your room script
in a similar way to how they are in the global script, the room script can intercept
the keypress/mouseclick first, and then decide whether to pass it on to the global
script or not. See the \helprefn{ClaimEvent}{ClaimEvent} function for more.


\section{repeatedly_execute (_always)}\label{RepExec}\index{repeatedly_execute}\index{repeatedly_execute_always}%

One of the most common things you'll need to do when scripting is to check if something
has happened in the game -- and if so, then make the game do something in response.

For example, suppose that you want a bird to fly backwards and forwards across the screen
in the background. You need a way of telling the bird to move in one direction, recognise
when it has finished, and tell it to move back again.

This is where \it{repeatedly_execute} and \it{repeatedly_execute_always} come in. 

\bf{What's the difference between them?}

The \it{repeatedly_execute} event is run on every game loop (by default this is 40 times per
second), but only when the game is not blocked. That means that it will run as long as there
are no current blocking animations or moves going on (ie. a Walk or Animate command where
\it{eBlock} has been specified as a parameter).

On the other hand, \it{repeatedly_execute_always} is always run on every game loop, no matter
whether the game is blocked or not. This comes at a price though, which is that you cannot
run any blocking code within it. So if you try to script a \it{player.Walk()} command that
passes the \it{eBlock} parameter -- or even just try to use a \verb$Wait(1);$ command, these
will fail within \it{repeatedly_execute_always}.

\bf{What would I use each one for?}

You would usually use \it{repeatedly_execute} for doing things that affect the player character,
and \it{repeatedly_execute_always} for doing background tasks that don't directly affect the
player.

For example, if your game kept track of the player's hunger, you might want to check in
\it{repeatedly_execute} how long it has been since he last ate -- and if it has been more than 20
minutes, make the player character stop walking and rub his stomach. Because you want to perform
a blocking animation, and you wouldn't want this to interrupt any specific cutscenes that were going on,
repeatedly_execute would be the ideal place for it.

On the other hand, in the case of our bird flying across the screen, because we don't want to
block the game while the bird flies, and we just want it to happen in the background, 
\it{repeatedly_execute_always} would be the place to put it.

\bf{How do I create them?}

In main game scripts, you create your \it{repeatedly_execute} script function by just pasting
it into the script as follows. In the GlobalScript.asc it is already created for you:
\begin{verbatim}
function repeatedly_execute()
{
  // Put your script code here
}
\end{verbatim}
In rooms, it is slightly different. If you want to run some script that is specific to a particular
room, open that room's Events Pane and you'll see a "Repeatedly execute" event. Click the "..." button
and a function called something like \it{Room_RepExec} will be created for you.

This is important to remember -- in a room script, \bf{you cannot simply paste in a repeatedly_execute
function}; you need to use the Events Pane to create it instead.

To create \it{repeatedly_execute_always}, you can simply paste it into the script as above -- but
you can also paste it into room scripts. Therefore the following will work in any script, whether
it be a room or a global script.
\begin{verbatim}
function repeatedly_execute_always()
{
  // Put your script code here
}
\end{verbatim}
Remember, of course, that RepExec or \it{repeatedly_execute_always} functions in a room script
will only be run while the player is actually in that room!

\bf{Can you show me an example?}

Let's implement the two things we just talked about. Here's our hunger checking code:
\begin{verbatim}
function repeatedly_execute()
{
  // increment our timer variable (we would have created this
  // in the Global Variables editor)
  hungerTimer++;
  
  if (hungerTimer == 800)
  {
    Display("You are getting very hungry.");
    player.LockView(RUBSTOMACH);
    player.Animate(0, 5, eOnce, eBlock, eForwards);
    player.UnlockView();
  }
}
\end{verbatim}
and let's put the bird flying code in the room script, because we only want it to happen in that one room:
\begin{verbatim}
function repeatedly_execute_always()
{
  if (!cBird.Moving)
  {
    if (cBird.x < 100)
    {
      // if the bird is on the left hand side of the screen,
      // start it moving towards the right
      cBird.Walk(400, cBird.y, eNoBlock, eAnywhere);
    }
    else
    {
      // otherwise, move it towards the left
      cBird.Walk(0, cBird.y, eNoBlock, eAnywhere);
    }
  }
}
\end{verbatim}


\section{Custom dialog options rendering}\label{CustomDialogOptions}\index{Dialog options, custom rendering}%

By default, AGS comes with two types of dialog options -- displaying them using the size
and position of an existing GUI, or creating a text window to display the options in.

As of AGS 3.1, if neither of these methods suit you (for example, because you want to
use picture-based dialog options, or you want to add scroll arrows), you can now implement
the dialog options display yourself in the script.

\bf{NOTE:} This topic involves some advanced scripting. If you're just starting out with AGS,
please just use one of the built-in dialog option styles for now, and come back to this later
when you're comfortable with scripting.

To write your custom dialog options code, you need to do the following:
\begin{itemize}
\item Add a \verb$dialog_options_get_dimensions$ function to your script (an example follows).
This function is called by AGS to find out which part of the screen you will be drawing onto.
By setting the width and height to values greater than 0, the custom dialog system is activated.
\item Add a \verb$dialog_options_render$ function, which is called by AGS when it needs to
draw the dialog options. A standard script \helprefn{DrawingSurface}{DrawingSurfaceFunctions} is
supplied, which you can use to draw onto.
\item Add a \verb$dialog_options_get_active$ function, which is called by AGS as the player moves
the mouse around the screen. This needs to work out which option the mouse is currently hovering
over, so that AGS knows which option to process if the player clicks the mouse button.
\item Optionally, add a \verb$dialog_options_mouse_click$ function. This is called by AGS if the
player clicks the mouse when it is not over one of the options. You might want to use this to
process clicks on some custom scroll arrows, for example.
\end{itemize}
These functions don't have to go in the global script; you can put them in any script you like.
However, beware that if the functions are present in more than one script they could interfere
with each other and cause problems.

\bf{IMPORTANT:} When adding the functions to the script, they all take in a parameter of
type \helprefn{DialogOptionsRenderingInfo}{DialogOptionsRenderingInfoFunctions} and the
dialog_options_mouse_click function has an extra parameter for the mouse button. See the example below.

\bf{IMPORTANT:} The four Custom Dialog functions all run on the non-blocking thread. That means
that you should not make any blocking calls, such as Character.Say, Wait or Display within them,
as they may not behave correctly.

\bf{Example}

Below is a very simple implementation of a dialog options screen. 

\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  // Create a 200x200 dialog options area at (50,100)
  info.X = 50;
  info.Y = 100;
  info.Width = 200;
  info.Height = 200;
  // Put the text parser at the bottom (if enabled)
  info.ParserTextBoxX = 10;
  info.ParserTextBoxY = 160;
  info.ParserTextBoxWidth = 180;
}

function dialog_options_render(DialogOptionsRenderingInfo *info)
{
  // Clear the area yellow
  info.Surface.Clear(14);
  int i = 1,  ypos = 0;
  // Render all the options that are enabled
  while (i <= info.DialogToRender.OptionCount)
  {
    if (info.DialogToRender.GetOptionState(i) == eOptionOn)
    {
      if (info.ActiveOptionID == i) info.Surface.DrawingColor = 13;
      else info.Surface.DrawingColor = 4;
      info.Surface.DrawStringWrapped(5, ypos, info.Width - 10, 
                         eFontFont0, eAlignLeft, info.DialogToRender.GetOptionText(i));
      ypos += GetTextHeight(info.DialogToRender.GetOptionText(i), eFontFont0, info.Width - 10);
    }
    i++;
  }
}

function dialog_options_get_active(DialogOptionsRenderingInfo *info)
{
  int i = 1,  ypos = 0;
  // Find the option that corresponds to where the player clicked
  while (i <= info.DialogToRender.OptionCount)
  {
    if (info.DialogToRender.GetOptionState(i) == eOptionOn)
    {
      ypos += GetTextHeight(info.DialogToRender.GetOptionText(i), eFontFont0, info.Width - 10);
      if ((mouse.y - info.Y) < ypos)
      {
        info.ActiveOptionID = i;
        return;
      }
    }
    i++;
  }
}

function dialog_options_mouse_click(DialogOptionsRenderingInfo *info, MouseButton button)
{
  // do something here if you want!
}
\end{verbatim}
The example above is slightly naive; in reality you would probably want to track
the Y position of each option in a variable to save having to continually scan through
all the options.

For more detail on the commands used here, see the \helprefn{DialogOptionsRenderingInfo}{DialogOptionsRenderingInfoFunctions}
page.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.



\section{Built-in enumerated types}\label{BuiltInEnums}\index{Enumerated types (built-in)}%

AGS has several \helprefn{enumerated types}{enum} built in. These are used in calls to
various commands, and will usually pop up automatically in autocomplete. However, for times
where autocomplete doesn't do the job, having a manual reference is invaluable:

\begin{verbatim}
enum BlockingStyle {
  eBlock,
  eNoBlock
};
\end{verbatim}
\it{Used by:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.FaceCharacter}{Character.FaceCharacter},
\helprefn{Character.FaceLocation}{Character.FaceLocation},
\helprefn{Character.FaceObject}{Character.FaceObject},
\helprefn{Character.Move}{Character.Move},
\helprefn{Character.Walk}{Character.Walk},
\helprefn{Character.WalkStraight}{Character.WalkStraight},
\helprefn{Object.Animate}{Object.Animate},
\helprefn{Object.Move}{Object.Move}

\begin{verbatim}
enum Direction {
  eForwards,
  eBackwards
};
\end{verbatim}
\it{Used by:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Object.Animate}{Object.Animate}

\begin{verbatim}
enum WalkWhere {
  eAnywhere,
  eWalkableAreas
};
\end{verbatim}
\it{Used by:} \helprefn{Character.Move}{Character.Move},
\helprefn{Character.Walk}{Character.Walk},
\helprefn{Object.Move}{Object.Move}

\begin{verbatim}
enum RepeatStyle {
  eOnce,
  eRepeat
};
\end{verbatim}
\it{Used by:} \helprefn{Button.Animate}{Button.Animate},
\helprefn{Character.Animate}{Character.Animate},
\helprefn{Object.Animate}{Object.Animate}

\begin{verbatim}
enum Alignment {
  eAlignLeft,
  eAlignCentre,
  eAlignRight
};
\end{verbatim}
\it{Used by:} \helprefn{Character.LockViewAligned}{Character.LockViewAligned}

\begin{verbatim}
enum eFlipDirection {
  eFlipLeftToRight,
  eFlipUpsideDown,
  eFlipBoth
};
\end{verbatim}
\it{Used by:} \helprefn{DynamicSprite.Flip}{DynamicSprite.Flip}

\begin{verbatim}
enum TransitionStyle {
  eTransitionFade,
  eTransitionInstant,
  eTransitionDissolve,
  eTransitionBoxout,
  eTransitionCrossfade
};
\end{verbatim}
\it{Used by:} \helprefn{SetScreenTransition}{SetScreenTransition},
\helprefn{SetNextScreenTransition}{SetNextScreenTransition}

\begin{verbatim}
enum MouseButton {
  eMouseLeft,
  eMouseRight,
  eMouseMiddle,
  eMouseLeftInv,
  eMouseMiddleInv,
  eMouseRightInv,
  eMouseWheelNorth,
  eMouseWheelSouth
};
\end{verbatim}
\it{Used by:} \helprefn{Mouse.IsButtonDown}{Mouse.IsButtonDown} ILBRK
\it{Passed into:} on_mouse_click

\begin{verbatim}
enum EventType {
  eEventLeaveRoom,
  eEventEnterRoom,
  eEventGotScore,
  eEventGUIMouseDown,
  eEventGUIMouseUp,
  eEventAddInventory,
  eEventLoseInventory,
  eEventRestoreGame
};
\end{verbatim}
\it{Passed into:} on_event

\begin{verbatim}
enum RoundDirection {
  eRoundDown,
  eRoundNearest,
  eRoundUp
};
\end{verbatim}
\it{Used by:} \helprefn{FloatToInt}{FloatToInt}

\begin{verbatim}
enum eSpeechStyle {
  eSpeechLucasarts,
  eSpeechSierra,
  eSpeechSierraWithBackground,
  eSpeechFullScreen
};
\end{verbatim}
\it{Used by:} \helprefn{SetSpeechStyle}{SetSpeechStyle}

\begin{verbatim}
enum eVoiceMode {
  eSpeechTextOnly,
  eSpeechVoiceAndText,
  eSpeechVoiceOnly
};
\end{verbatim}
\it{Used by:} \helprefn{SetVoiceMode}{SetVoiceMode}

\begin{verbatim}
enum DialogOptionState {
  eOptionOff,
  eOptionOn,
  eOptionOffForever
};
\end{verbatim}
\it{Used by:} \helprefn{Dialog.GetOptionState}{Dialog.GetOptionState},
\helprefn{Dialog.SetOptionState}{Dialog.SetOptionState}

\begin{verbatim}
enum CutsceneSkipType {
  eSkipESCOnly,
  eSkipAnyKey,
  eSkipMouseClick,
  eSkipAnyKeyOrMouseClick,
  eSkipESCOrRightButton
};
\end{verbatim}
\it{Used by:} \helprefn{StartCutscene}{StartCutscene}

\begin{verbatim}
enum eOperatingSystem {
  eOSDOS,
  eOSWindows,
  eOSLinux,
  eOSMacOS
};
\end{verbatim}
\it{Used by:} \helprefn{System.OperatingSystem}{System.OperatingSystem}

\begin{verbatim}
enum eCDAudioFunction {
  eCDIsDriverPresent,
  eCDGetPlayingStatus,
  eCDPlayTrack,
  eCDPausePlayback,
  eCDResumePlayback,
  eCDGetNumTracks,
  eCDEject,
  eCDCloseTray,
  eCDGetCDDriveCount,
  eCDSelectActiveCDDrive
};
\end{verbatim}
\it{Used by:} \helprefn{CDAudio}{CDAudio}

\begin{verbatim}
enum CursorMode {
  eModeXXXX,
  eModeXXXX,
  ...
};
\end{verbatim}
The CursorMode enumeration is generated automatically based on your mouse cursors.
The cursor mode name is taken, all its spaces are removed, and \it{eMode} is added
to the front. ILBRK
\it{Used by:} \helprefn{IsInteractionAvailable}{IsInteractionAvailable},
\helprefn{ProcessClick}{ProcessClick},
\helprefn{Mouse.ChangeModeGraphic}{Mouse.ChangeModeGraphic},
\helprefn{Mouse.ChangeModeHotspot}{Mouse.ChangeModeHotspot},
\helprefn{Mouse.DisableMode}{Mouse.DisableMode},
\helprefn{Mouse.EnableMode}{Mouse.EnableMode},
\helprefn{Mouse.UseModeGraphic}{Mouse.UseModeGraphic},
\helprefn{Mouse.Mode}{Mouse.Mode},
\helprefn{InventoryItem.IsInteractionAvailable}{InventoryItem.IsInteractionAvailable},
\helprefn{InventoryItem.RunInteraction}{InventoryItem.RunInteraction},
\helprefn{Hotspot.RunInteraction}{Hotspot.RunInteraction},
\helprefn{Object.RunInteraction}{Object.RunInteraction},
\helprefn{Character.RunInteraction}{Character.RunInteraction}

\begin{verbatim}
enum FontType {
  eFontXXXX,
  eFontXXXX,
  ...
};
\end{verbatim}
The FontType enumeration is generated automatically based on your fonts.
The font name is taken, all its spaces are removed, and \it{eFont} is added
to the front. ILBRK
\it{Used by:} \helprefn{Button.Font}{Button.Font},
\helprefn{DrawingSurface.DrawMessageWrapped}{DrawingSurface.DrawMessageWrapped},
\helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString},
\helprefn{DrawingSurface.DrawStringWrapped}{DrawingSurface.DrawStringWrapped},
\helprefn{Game.NormalFont}{Game.NormalFont},
\helprefn{Game.SpeechFont}{Game.SpeechFont},
\helprefn{GetTextHeight}{GetTextHeight},
\helprefn{GetTextWidth}{GetTextWidth},
\helprefn{Label.Font}{Label.Font},
\helprefn{ListBox.Font}{ListBox.Font},
\helprefn{TextBox.Font}{TextBox.Font},
\helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.SetText}{Overlay.SetText}


\begin{verbatim}
enum LocationType {
  eLocationNothing,
  eLocationHotspot,
  eLocationCharacter,
  eLocationObject
};
\end{verbatim}
\it{Returned by:} \helprefn{GetLocationType}{GetLocationType}

\begin{verbatim}
enum FileMode {
  eFileRead,
  eFileWrite,
  eFileAppend
};
\end{verbatim}
\it{Used by:} \helprefn{File.Open}{File.Open}

\begin{verbatim}
enum DialogOptionSayStyle {
  eSayUseOptionSetting,
  eSayAlways,
  eSayNever
};
\end{verbatim}
\it{Used by:} \helprefn{Dialog.DisplayOptions}{Dialog.DisplayOptions}

\begin{verbatim}
enum VideoSkipStyle {
  eVideoSkipNotAllowed,
  eVideoSkipEscKey,
  eVideoSkipAnyKey,
  eVideoSkipAnyKeyOrMouse
};
\end{verbatim}
\it{Used by:} \helprefn{PlayVideo}{PlayVideo}

\begin{verbatim}
enum AudioFileType {
  eAudioFileOGG,
  eAudioFileMP3,
  eAudioFileWAV,
  eAudioFileVOC,
  eAudioFileMIDI,
  eAudioFileMOD
};
\end{verbatim}
\it{Used by:} \helprefn{AudioClip.FileType}{AudioClip.FileType}

\begin{verbatim}
enum AudioPriority {
  eAudioPriorityVeryLow = 1,
  eAudioPriorityLow = 25,
  eAudioPriorityNormal = 50,
  eAudioPriorityHigh = 75,
  eAudioPriorityVeryHigh = 100
};
\end{verbatim}
\it{Used by:} \helprefn{AudioClip.Play}{AudioClip.Play},
\helprefn{AudioClip.PlayFrom}{AudioClip.PlayFrom},
\helprefn{AudioClip.PlayQueued}{AudioClip.PlayQueued}


\section{Script language keywords}


\subsection{Arrays}\label{Arrays}%

\it{data_type} \it{name} \verb$[$ \it{size} \verb$];$

Arrays allow you to easily create several variables of the same type. For example,
suppose you wanted to store a health variable for all the different characters in the game.
One way would be to declare several different variables like this:
\begin{verbatim}
int egoHealth;
int badGuyHealth;
int swordsmanHealth;
\end{verbatim}
but that quickly gets messy and difficult to keep up to date, since you need to use
different script code to update each one. So instead, you can do this:
\begin{verbatim}
int health[50];
\end{verbatim}
This example declares 50 int variables, all called \it{health}. ILBRK
You access each seperate variable via its \bf{index} (the number in the brackets). Indexes
start from 0, so in this case the \it{health} array can be accessed by indexes 0 to 49.
If you attempt to access an invalid index, your game will exit with an error.

Here's an example of using the array:
\begin{verbatim}
  health[3] = 50;
  health[4] = 100;
  health[player.ID] = 10;
\end{verbatim}
this sets Health 3 to 50, Health 4 to 100, and the Health index that corresponds to the player
character's ID number to 10.

See Also: \helprefn{Dynamic arrays}{DynamicArrays}


\subsection{Data types}\label{Datatypes}\index{short}\index{char}\index{int}\index{string}\index{float}%

\begin{tabular}{|l|l|}
\row{ \bf{ Type } & \bf{ Description }
}\row{{ char } & { Single byte data type, can store a single character or number 0 to 255 }
}\row{{ short } & { 16-bit integer, can store numbers from –32,768 to 32,767 }
}\row{{ int } & { 32-bit integer, can store from –2,147,483,648 to 2,147,483,647 }
}\row{{ String } & { Stores a string of characters }
}\row{{ float } & { A 32-bit floating point number. Accuracy normally about 6 decimal places,
                    but varies depending on the size of the number being stored. }
}\row{{ bool } & { a variable that stores either 'true' or 'false' }
}\end{tabular}

You will normally only need to use the \bf{int} and \bf{String} data types. The smaller types
are only useful for conserving memory if you are creating a very large number of variables.

To declare a variable, write the type followed by the variable name, then a semicolon.
For example:

\verb$int my_variable;$

declares a new 32-bit integer called  my_variable  

\bf{WARNING:} When using the \it{float} data type, you may find that the == and != operators
don't seem to work properly. For example:
\begin{verbatim}
float result = 2.0 * 3.0;
if (result == 6.0) {
  Display("Result is 6!");
}
\end{verbatim}
may not always work. This is due to the nature of floating point variables, and the solution
is to code like this:
\begin{verbatim}
float result = 2.0 * 3.0;
if ((result > 5.99) && (result < 6.01)) {
  Display("Result is 6!");
}
\end{verbatim}
The way floating point numbers are stored means that 6 might actually be stored as 6.000001
or 5.999999; this is a common gotcha to all programming languages so just be aware of it
if you use any floating point arithmetic.


\subsection{Operators}%

The AGS scripting engine supports the following operators in expressions. They are listed
in order of precedence, with the most tightly bound at the top of the list.

\bf{WARNING:} When using operators of equal precedence, AGS by default evaluates them
right-to-left. So, the expression \verb$a = 5 - 4 - 2;$ evaluates as \verb$a = 5 - (4 - 2);$
which is not what you might expect. Always use parenthesis to make it clear what you want. ILBRK
The "Left-to-right operator precedence" option on the General Settings pane allows you to
control this behaviour.

\bf{\begin{verbatim}
Operator  Description              Example
\end{verbatim} }

\begin{verbatim}
  !    NOT                        if (!a) 
  *    Multiply                   a = b * c;
  /    Divide                     a = b / c;
  %    Remainder                  a = b % c;
  +    Add                        a = b + c;
  -    Subtract                   a = b - c;
  <<   Bitwise Left Shift         a = b << c;
       (advanced users only) 
  >>   Bitwise Right Shift        a = b >> c;
       (advanced users only) 
  &    Bitwise AND                a = b & c;
       (advanced users only) 
  |    Bitwise OR                 a = b | c;
       (advanced users only) 
  ^    Bitwise XOR                a = b ^ c;
       (advanced users only) 
  ==   Is equal to                if (a == b)
  !=   Is not equal to            if (a != b)
  >    Is greater than            if (a > b)
  <    Is less than               if (a < b)
  >=   Is greater than or equal   if (a >= b)
  <=   Is less than or equal      if (a <= b)
  &&   Logical AND                if (a && b)
  ||   Logical OR                 if (a || b)
\end{verbatim}

This order of precedence allows expressions such as the following to evaluate as expected:

\verb$if (!a && b < 4)$

which will execute the 'if' block if \bf{a} is 0 and \bf{b} is less than 4.

However, it is always good practice to use parenthesis to group expressions. It's much
more readable to script the above expression like this:

\verb$if ((!a) && (b < 4))$



\subsection{Constants}\label{Constants}\index{Predefined constants}\index{#ifdef}\index{#ifndef}\index{#error}\index{DEBUG}\index{STRICT}\index{LRPRECEDENCE}\index{AGS_NEW_STRINGS}\index{AGS_MAX_* constants}%

The following predefined macros are available in your scripts:

\begin{tabular}{|l|l|}
\row{ \bf{ Name } & \bf{ Description }
}\row{{ DEBUG } & { Defined if the game is being compiled in debug mode, not defined otherwise }
}\row{{ STRICT } & { Defined if "Enforce Object Based Scripting" is ticked, not defined otherwise }
}\row{{ STRICT_STRINGS } & { Defined if "Enforce new-style strings" is ticked, not defined otherwise }
}\row{{ STRICT_AUDIO } & { Defined if "Enforce new-style audio scripting" is ticked, not defined otherwise }
}\row{{ LRPRECEDENCE } & { Defined if "Left-to-right operator precedence" is ticked, not defined otherwise }
}\row{{ AGS_NEW_STRINGS } & { Defined if AGS 2.71 or later (with new-String support), not defined otherwise }
}\row{{ AGS_SUPPORTS_IFVER } & { Defined if AGS 2.72 or later (with \verb$#ifver$ support), not defined otherwise }
}\row{{ AGS_MAX_INV_ITEMS } & { The maximum number of inventory items }
}\row{{ AGS_MAX_CONTROLS_PER_GUI } & { The maximum number of controls on a GUI }
}\row{{ AGS_MAX_OBJECTS } & { The maximum objects per room }
}\row{{ AGS_MAX_HOTSPOTS } & { The maximum hotspots per room }
}\row{{ AGS_MAX_REGIONS } & { The maximum regions per room }
}\end{tabular}

You can check for whether a macro is defined or not by using the \verb$#ifdef$ and
\verb$#ifndef$ keywords:
\begin{verbatim}
#ifndef STRICT
  // only compile the MoveCharacter command if not using object-based scripting
  MoveCharacter(EGO, 30, 40);
#endif
#ifdef DEBUG
  // only display this when the game is compiled in debug mode
  Display("Debugging information");
#endif
\end{verbatim}
There is also an \verb$#error$ directive you can use to stop the script compiling:
\begin{verbatim}
#ifndef AGS_NEW_STRINGS
#error This script requires at least AGS 2.71
#endif
\end{verbatim}

The other constants (AGS_MAX_*) are useful if you are writing some script code that you
want to be portable to different versions of AGS, and to pick up the limits from the user's
AGS version. For example, if you wanted to store some extra information on all the inventory
items, you could do:
\begin{verbatim}
int invWeights[AGS_MAX_INV_ITEMS];
\end{verbatim}
To get the actual number of things in the game rather than the AGS limit, use the
\helprefn{Game.CharacterCount}{Game.CharacterCount}-style properties.


\subsection{Version checking}\label{VersionChecks}\index{#ifver}\index{#ifnver}%

If you are writing a script module, you may need to check which version of AGS the user
of your module is using.

For this purpose there are two directives:
\begin{verbatim}
#ifver 2.72
// do stuff for 2.72 and above
#endif
#ifnver 2.72
// do stuff for 2.71 and below
#endif
\end{verbatim}

Note that this ability was only added in 2.72, so you cannot use the \verb$#ifver$ checks
if you want your module to work with earlier versions than this.


\subsection{if, else statements}\label{ifelsestatements}\index{else statement}%

\bf{if (} \it{expression} \bf{)}  \verb${$ ILBRK
  \it{statements1} ILBRK
\verb$}$ ILBRK
[ \bf{else}  \verb${$ ILBRK
  \it{statements2} ILBRK
\verb$}$ ]

If \it{expression} is true, then \it{statements1} are run.

If \it{expression} is not true, and there is an \bf{else} clause present, then
\it{statements2} are run instead.

For example:

\begin{verbatim}
if (GetGlobalInt(5) == 10) {
  Display("Globalint 5 is 10.");
}
else {
  Display("Globalint 5 is not 10.");
}
\end{verbatim}

In this example, the first message will be displayed if the return value from
\verb$GetGlobalInt(5)$ is 10, and the second message will be displayed if it is not.

\bf{if} statements can be nested inside \bf{else} statements to produce an "else if"
effect. For example:

\begin{verbatim}
if (GetGlobalInt(5) == 1) {
  Display("Globalint 5 is 1.");
}
else if (GetGlobalInt(5) == 2) {
  Display("Globalint 5 is 2.");
}
else {
  Display("Globalint 5 is not 1 or 2.");
}
\end{verbatim}


\subsection{while}\label{whilestatement}%

\bf{while (} \it{expression} \bf{)}  \verb${$ ILBRK
  \it{statements} ILBRK
\verb$}$

Runs \it{statements} continuously, while \it{expression} is true.

For example:

\begin{verbatim}
while (cEgo.Moving) {
  Wait(1);
}
\end{verbatim}

will run the script \verb$Wait(1);$ repeatedly, as long as \verb$cEgo.Moving$ is
not zero. Once it is zero, the \bf{while} statement will exit at the end of the loop.


\subsection{function}\label{function}%

\bf{function} \it{name} \verb$($ [\it{type1 param1}, \it{type2 param2}, ... ] \verb$)$

Declares a custom function in your script. A function is a way in which you can
separate out commonly used code into its own place, and thus avoid duplicating code.

For example, suppose that you quite often want to play a sound and add an inventory item
at the same time. You could write both commands each time, or you could define a custom
function:

\begin{verbatim}
function AddInvAndPlaySound(InventoryItem* item) {
  player.AddInventory(item);
  aInventorySound.Play();
}
\end{verbatim}

then, elsewhere in your code you can simply call:
\begin{verbatim}
AddInvAndPlaySound(iKey);
\end{verbatim}
to add inventory item \it{iKey} and play the sound.

Generally, you place your functions in your global script. You then need to add
an \helprefn{import}{importkeyword} line to your script header to allow the function to be called
from room scripts.

\bf{Optional parameters}

You can make \it{int} parameters optional if there is a default value that the user
doesn't need to supply. To do this, change the script header \it{import} declaration like this:
\begin{verbatim}
import function TestFunction(int stuff, int things = 5);
\end{verbatim}
that declares a function with a mandatory \it{stuff} parameter, and an optional \it{things}
parameter. If the caller does not supply the second parameter, it will default to 5.

\bf{NOTE:} To use optional parameters, you need to have an "import" declaration for the function
in the script header. The default values cannot be specified in the actual function declaration
itself.


\subsection{struct}\label{struct}\index{class}%

\bf{struct} \it{name} \verb${$

Declares a custom struct type in your script. ILBRK
Structs allow you to group together related variables in order to make your
script more structured and readable. For example, suppose that wanted to store
some information on weapons that the player could carry. You could declare
the variables like this:
\begin{verbatim}
int swordDamage;
int swordPrice;
String swordName;
\end{verbatim}
but that quickly gets out of hand and leaves you with tons of variables to keep track of.
This is where structs come in:
\begin{verbatim}
struct Weapon {
  int damage;
  int price;
  String name;
};
\end{verbatim}
Now, you can declare a struct in one go, like so:
\begin{verbatim}
Weapon sword;
sword.damage = 10;
sword.price = 50;
sword.name = "Fine sword";
\end{verbatim}
Much neater and better organised. You can also combine structs with \helprefn{arrays}{Arrays}:
\begin{verbatim}
// at top of script
Weapon weapons[10];
// inside script function
weapons[0].damage = 10;
weapons[0].price = 50;
weapons[0].name = "Fine sword";
weapons[1].damage = 20;
weapons[1].price = 80;
weapons[1].name = "Poison dagger";
\end{verbatim}
structs are essential if you have complex data that you need to store in your scripts.


\subsection{enum}\label{enum}%

\bf{Recommended for advanced users only}

\bf{enum} \it{name} \verb${$ ILBRK
  \it{option1} [ = \it{value1} ], ILBRK
  \it{option2} [ = \it{value2} ], ILBRK
  ... ILBRK
\verb$};$

Declares an enumeration type. An enumeration allows you to group together a set of related
options, where only one will be true at any one time -- a bit like the contents of a list box.

For example, if you have a script function, \it{doStuff}, that can perform 3 different
operations, you could do this:

\begin{verbatim}
function doStuff(int param) {
  if (param == 1) {
    // do something
  }
  else if (param == 2) {
    // do something else
  }
  // etc
}
\end{verbatim}

but it's hard to read, and when calling the function from elsewhere in your script,
it's not clear what 1 or 2 means. That's where enums come in:

\begin{verbatim}
enum DoStuffOption {
  BakeCake,
  DoLaundry
};

function doStuff(DoStuffOption param) {
  if (param == BakeCake) {
    // do something
  }
  else if (param == DoLaundry) {
    // do something else
  }
  // etc
}
\end{verbatim}

and then the calling code looks like: ILBRK
\verb$doStuff(BakeCake);$ ILBRK
thus making it perfectly clear what the command will do.

Normally, you would put the enum definition into the script header.

In summary, enums are not an essential part of scripting and you can get away perfectly
well without using them, but in some specific situations they're very handy.


\subsection{this}\label{this}%

There are two uses for the \verb$this$ keyword.

\bf{1. Accessing members of the current struct}

When you are creating custom \helprefn{structs}{struct}, you use the "this" keyword inside member
functions to refer to the current struct. For example:

Suppose you had this in your script header:
\begin{verbatim}
struct MyStruct {
  int myValue;
  
  import function MyMethod();
};
\end{verbatim}
Then, in your main script, you could put this:
\begin{verbatim}
function MyStruct::MyMethod()
{
  this.myValue = 5;
}
\end{verbatim}
The \verb$MyStruct::MyMethod$ tells AGS that you are defining the function \it{MyMethod}
which belongs to the struct \it{MyStruct} (the \verb$::$ operator means "belongs to").

The code above will mean that when the MyMethod function is called, it sets
the \verb$myValue$ variable to 5.

\bf{2. Declaring extender functions}

Please see the \helprefn{Extender functions}{ExtenderFunctions} page for details.


\subsection{import}\label{importkeyword}%

\bf{import} \it{declaration} ;

Declares \it{declaration} as a variable or function which is external to the current
script, but that the script needs access to it. You use this to provide your room scripts
with access to parts of your global script.

For example:

\begin{verbatim}
import int counter;
import function add_numbers (int, int);
\end{verbatim}

This imports an integer variable \verb$counter$ and the function \verb$add_numbers$ from
the global script to enable the current script to call them. You normally place import
statements into the script header so that all rooms can benefit from them.

In order to import the variable, it must have been exported from the global script
with the \helprefn{export keyword}{exportkeyword}.

\bf{NOTE:} You \bf{MUST} import external variables with the correct type. If \verb$counter$
was declared as a \bf{short} in the global script, you MUST import it as a short, otherwise
your game may crash.

\bf{NOTE:} You cannot import old-style \verb$string$ variables (this does not
apply to new-style \verb$String$ variables).


\subsection{export}\label{exportkeyword}%

\bf{export} \it{variable} [, \it{variable} ... ] ;

Declares that \it{variable} can be exported and accessed by other scripts. You must place
this at the \bf{end} of your global script. You can export many variables with one export
line.

For example:

\begin{verbatim}
export my_variable;
export counter, strength;
\end{verbatim}

This exports three variables - my_variable, counter and strength.


\subsection{noloopcheck}\label{noloopcheck}%

function \bf{noloopcheck} \it{function_name} ( \it{parameters ...} ) \verb${$

The noloopcheck keyword disables the script loop checking for the current function.

Normally, if a \helprefn{while}{whilestatement} loop runs for more than 150,000
loops, AGS will assume that the script has hung and abort the game. This is to assist
scripting since otherwise the game would lock up if you scripted a loop wrongly.

However, there are some rare situations in which you need a loop to run several thousand
times (for example, when initialising a very large array). In this case, the \it{noloopcheck}
keyword can be used to stop AGS aborting your script.

\bf{NOTE:} The \it{noloopcheck} keyword must be placed between "function" and the function's name. ILBRK
If you import the function into the script header, you \bf{do not} include the "noloopcheck" keyword
in the import declaration -- it is only included in the actual function body.

\bf{NOTE:} If AGS gives you a script iterations error, \bf{DO NOT} just automatically
add this keyword as a way to fix the problem -- more often than not, it is a fault in
your scripting and using this keyword will mean that the game will hang rather than abort.

For example:
\begin{verbatim}
function noloopcheck initialize_array() {
  char bigarray[200000];
  int a = 0;
  while (a < 200000) {
    bigarray[a] = 1;
    a++;
  }
}
\end{verbatim}
without the "noloopcheck" keyword here, AGS would abort that script.


\section{AudioChannel functions and properties}\label{AudioChannelCommands}%

The AudioChannel instance represents a currently playing audio file. You can use this
instance to check the status of playing sounds, and adjust them.


\subsection{Seek}\label{AudioChannel.Seek}\index{AudioChannel.Seek}\index{SeekMODPattern}\index{SeekMP3PosMillis}\index{SeekMIDIPosition}%

\it{(Formerly known as SeekMIDIPosition, which is now obsolete)} ILBRK
\it{(Formerly known as SeekMODPattern, which is now obsolete)} ILBRK
\it{(Formerly known as SeekMP3PosMillis, which is now obsolete)}

\begin{verbatim}
AudioChannel.Seek(int position)
\end{verbatim}
Seeks the audio clip that is currently playing on this channel to \it{position}.

What \it{position} represents depends on the FileType of the audio clip:
\begin{itemize}
\item \bf{MIDI} - the beat number
\item \bf{MOD/XM/S3M} - the pattern number
\item \bf{WAV/VOC} - the sample number (eg. in a 22050 Hz sound, 22050 = 1 second)
\item \bf{OGG/MP3} - milliseconds offset
\end{itemize}

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Wait(40);
channel.Seek(0);
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, wait for a second, then seek it back to the start.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.Position}{AudioChannel.Position}


\subsection{SetRoomLocation}\label{AudioChannel.SetRoomLocation}\index{AudioChannel.SetRoomLocation}%

\it{(Formerly part of PlayAmbientSound, which is now obsolete)}

\begin{verbatim}
AudioChannel.SetRoomLocation(int x, int y)
\end{verbatim}
Sets the currently playing audio to be a directional sound, eminating from (x,y).

The volume of the channel will be dynamically adjusted depending on how close the player
character is to the co-ordinates. Therefore, as the player walks closer the volume will
increase, and as they walk away the volume will decrease.

The channel's Volume setting sets the maximum possible volume when the player is standing
on the specified co-ordinates.

Pass the co-ordinates as (0,0) to remove the directional effect and return this channel
to playing at its normal volume.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aMachine.Play();
channel.SetRoomLocation(oMachine.X, oMachine.Y);
\end{verbatim} 
will start playing the \it{aMachine} audio clip, and set it at the location of the \it{oMachine}
room object.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.Volume}{AudioChannel.Volume}


\subsection{Stop (audio channel)}\label{AudioChannel.Stop}\index{AudioChannel.Stop}\index{StopChannel}\index{StopAmbientSound}%

\it{(Formerly known as StopAmbientSound, which is now obsolete)} ILBRK
\it{(Formerly known as StopChannel, which is now obsolete)}

\begin{verbatim}
AudioChannel.Stop()
\end{verbatim}
Stops the sound that is currently playing on this audio channel.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Wait(40);
channel.Stop();
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, wait for a second, then stop it.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.StopAudio}{Game.StopAudio}


\subsection{ID property (audio channel)}\label{AudioChannel.ID}\index{AudioChannel.ID}%

\begin{verbatim}
readonly int AudioChannel.ID
\end{verbatim}
Gets the Channel ID of this audio channel. You will not normally need to use this,
but it can be used for inter-operating with legacy commands such as StopChannel.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Display("Explosion playing on channel %d", channel.ID);
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, and display which channel it is playing on.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.


\subsection{IsPlaying property}\label{AudioChannel.IsPlaying}\index{AudioChannel.IsPlaying}\index{IsChannelPlaying}%

\it{(Formerly known as IsChannelPlaying, which is now obsolete)}

\begin{verbatim}
readonly bool AudioChannel.IsPlaying
\end{verbatim}
Gets whether this audio channel is currently playing a sound. Returns \it{true} if it is,
or \it{false} if it is not.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
while (channel.IsPlaying) Wait(1);
Display("Finished playing the explosion");
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, and wait until it finishes.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{LengthMs property}\label{AudioChannel.LengthMs}\index{AudioChannel.LengthMs}%

\begin{verbatim}
readonly int AudioChannel.LengthMs
\end{verbatim}
Gets the length of the audio playing on this channel, in milliseconds.

This is supported by all file types, but with MIDI music it is only accurate to the nearest second.

If this channel is not currently playing any audio, returns 0.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Display("The Explosion sound is %d ms long.", channel.LengthMs);
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, then display its length.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.PositionMs}{AudioChannel.PositionMs}


\subsection{Panning property}\label{AudioChannel.Panning}\index{AudioChannel.Panning}%

\begin{verbatim}
int AudioChannel.Panning
\end{verbatim}
Gets/sets the panning of this audio channel.

Panning allows you to adjust the stereo balance of the audio. The default is 0, which is
centred and will play at the same volume on both speakers. However you can adjust this 
between -100 (fully left) to 100 (fully right) to adjust the balance between the speakers.

\bf{NOTE:} MIDI music files do not support panning.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
channel.Panning = -100;
\end{verbatim} 
will start playing the \it{aExplosion} audio clip on the left speaker only.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{PlayingClip property}\label{AudioChannel.PlayingClip}\index{AudioChannel.PlayingClip}\index{GetCurrentMusic}%

\it{(Formerly known as GetCurrentMusic, which is now obsolete)}

\begin{verbatim}
readonly AudioClip* AudioChannel.PlayingClip
\end{verbatim}
Gets the audio clip that is playing on this channel. This allows you to find out the type
of the clip, and other information.

Returns \it{null} if there is no sound currently playing on this channel.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = System.AudioChannels[2];
if (channel.PlayingClip == null)
{
  Display("Nothing is playing on channel 2");
}
else 
{
  Display("Channel 2 is playing a clip of type %d", channel.PlayingClip.Type);
}
\end{verbatim} 
will display what is currently playing on audio channel 2.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}, \helprefn{System.AudioChannels}{System.AudioChannels}


\subsection{Position property}\label{AudioChannel.Position}\index{AudioChannel.Position}\index{GetMODPattern}\index{GetMP3PosMillis}\index{GetMIDIPosition}%

\it{(Formerly known as GetMIDIPosition, which is now obsolete)} ILBRK
\it{(Formerly known as GetMODPattern, which is now obsolete)} ILBRK
\it{(Formerly known as GetMP3PosMillis, which is now obsolete)}

\begin{verbatim}
readonly int AudioChannel.Position
\end{verbatim}
Gets the current position of the audio playing on this channel.

What \it{position} represents depends on the FileType of the audio clip:
\begin{itemize}
\item \bf{MIDI} - the beat number
\item \bf{MOD/XM/S3M} - the pattern number
\item \bf{WAV/VOC} - the sample number (eg. in a 22050 Hz sound, 22050 = 1 second)
\item \bf{OGG/MP3} - milliseconds offset
\end{itemize}

This property is read-only. If you want to change the current playback position within the audio file,
use the \helprefn{AudioChannel.Seek}{AudioChannel.Seek} function.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Wait(40);
channel.Seek(channel.Position + 1000);
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, wait for a second, then seek it ahead one second (if it is OGG/MP3/WAV).

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.PositionMs}{AudioChannel.PositionMs}, 
\helprefn{AudioChannel.Seek}{AudioChannel.Seek}


\subsection{PositionMs property}\label{AudioChannel.PositionMs}\index{AudioChannel.PositionMs}%

\begin{verbatim}
readonly int AudioChannel.PositionMs
\end{verbatim}
Gets the current position of the audio playing on this channel, in milliseconds.

This is supported by all file types except MIDI, and returns the current offset into the sound
in milliseconds. MIDI files will always return 0.

This property is read-only. If you want to change the current playback position within the audio file,
use the \helprefn{AudioChannel.Seek}{AudioChannel.Seek} function.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Wait(40);
Display("After 1 second, offset is %d ms.", channel.PositionMs);
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, wait for a second, then display its position.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \it{See Also:} \helprefn{AudioChannel.LengthMs}{AudioChannel.LengthMs},
\helprefn{AudioChannel.Position}{AudioChannel.Position}


\subsection{Volume property (audio channel)}\label{AudioChannel.Volume}\index{AudioChannel.Volume}\index{SetChannelVolume}\index{SetMusicVolume}%

\it{(Formerly known as SetChannelVolume, which is now obsolete)} ILBRK
\it{(Formerly known as SetMusicVolume, which is now obsolete)}

\begin{verbatim}
int AudioChannel.Volume
\end{verbatim}
Gets/sets the volume of this audio channel, from 0 to 100. This allows you to dynamically
adjust the volume of a playing sound.

This command adjusts the volume of this channel relative to the other channels.
It is still constrained within the overall volume, set by the System.Volume property.

\bf{NOTE:} This command only affects the current sound being played on the channel.
When a new audio clip starts playing on this channel, the volume will be set to the
DefaultVolume of the new audio clip.

\bf{NOTE:} The volume returned by this property is the channel's base volume, ie. it does
not include the effects of any directional audio set with SetRoomLocation, or any temporary
volume drop while speech is playing.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = aExplosion.Play();
Wait(40);
channel.Volume = 20;
\end{verbatim} 
will start playing the \it{aExplosion} audio clip, wait for a second, then reduce its volume.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.SetRoomLocation}{AudioChannel.SetRoomLocation},
\helprefn{Game.SetAudioTypeVolume}{Game.SetAudioTypeVolume}, \helprefn{System.Volume}{System.Volume}


\section{AudioClip functions and properties}\label{AudioClipCommands}%

AudioClips are created when you import files in the AGS Editor. The commands in this
section allow to play them.


\subsection{Play}\label{AudioClip.Play}\index{AudioClip.Play}\index{PlaySound}\index{PlayAmbientSound}\index{PlaySoundEx}\index{PlayMusic}\index{PlayMP3File}\index{SetMusicRepeat}%

\it{(Formerly known as PlayAmbientSound, which is now obsolete)} ILBRK
\it{(Formerly known as PlayMP3File, which is now obsolete)} ILBRK
\it{(Formerly known as PlayMusic, which is now obsolete)} ILBRK
\it{(Formerly known as PlaySound, which is now obsolete)} ILBRK
\it{(Formerly known as PlaySoundEx, which is now obsolete)} ILBRK
\it{(Formerly known as SetMusicRepeat, which is now obsolete)}

\begin{verbatim}
AudioChannel* AudioClip.Play(optional AudioPriority, optional RepeatStyle)
\end{verbatim}
Plays the audio clip.

Optionally you can supply a priority and Repeat setting; if you do not supply these,
the defaults set for the audio clip in the editor will be used.

This command searches through all the available audio channels to find one that is
available for this type of audio. If no spare channels are found, it will try to find
one that is playing a clip with a lower or equal priority, and interrupt it to replace
it with this new sound.

If all audio channels are busy playing higher priority sounds, then this new audio clip
will not be played.

This command returns the AudioChannel instance that the new sound is playing on, or
\it{null} if it did not play for any reason.

\bf{NOTE:} AGS can only play one MIDI file at a time.

\fcol{red}{Example:}
\begin{verbatim}
aExplosion.Play();
\end{verbatim}
plays the \it{aExplosion} audio clip.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.PlayFrom}{AudioClip.PlayFrom},
\helprefn{AudioClip.PlayQueued}{AudioClip.PlayQueued},
\helprefn{AudioClip.Stop}{AudioClip.Stop}


\subsection{PlayFrom}\label{AudioClip.PlayFrom}\index{AudioClip.PlayFrom}%

\begin{verbatim}
AudioChannel* AudioClip.PlayFrom(int position, optional AudioPriority, 
                                 optional RepeatStyle)
\end{verbatim}
Plays the audio clip, starting from \it{position}. For the meaning of the position,
see the \helprefn{AudioChannel.Seek}{AudioChannel.Seek} help page.

Otherwise, this command behaves identially to \helprefn{AudioClip.Play}{AudioClip.Play}.
Please see that help page for more information.

\fcol{red}{Example:}
\begin{verbatim}
aExplosion.PlayFrom(1000);
\end{verbatim}
plays the \it{aExplosion} audio clip, starting from a 1 second offset (if it is OGG/MP3).

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{PlayQueued}\label{AudioClip.PlayQueued}\index{AudioClip.PlayQueued}\index{PlayMusicQueued}%

\it{(Formerly known as PlayMusicQueued, which is now obsolete)}

\begin{verbatim}
AudioChannel* AudioClip.PlayQueued(optional AudioPriority, optional RepeatStyle)
\end{verbatim}
Plays the audio clip, or queues it to be played later if it cannot be played now.

This command behaves identially to \helprefn{AudioClip.Play}{AudioClip.Play},
except that if there are no available audio channels, it will queue this audio clip
to be played when a channel becomes available.

Additionally, unlike the Play command, using PlayQueued will not interrupt an existing audio
clip with an equal priority; it will only interrupt clips with a lower priority.

You can queue up to 10 tracks in the audio queue. Note that if you queue audio clips to
be played after a repeating audio clip, they will never be played.

\fcol{red}{Example:}
\begin{verbatim}
aExplosion.Play();
aAftermath.PlayQueued();
\end{verbatim}
plays the \it{aExplosion} audio clip, and queues the \it{aAftermath} sound to be played
afterwards.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{Stop (audio clip)}\label{AudioClip.Stop}\index{AudioClip.Stop}%

\begin{verbatim}
AudioClip.Stop()
\end{verbatim}
Stops all currently playing instances of this audio clip.

\fcol{red}{Example:}
\begin{verbatim}
aExplosion.Play();
Wait(40);
aExplosion.Stop();
\end{verbatim}
plays the \it{aExplosion} audio clip, waits 1 second and then stops it again.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{FileType property (audio clip)}\label{AudioClip.FileType}\index{AudioClip.FileType}%

\begin{verbatim}
readonly AudioFileType AudioClip.FileType;
\end{verbatim}
Gets the file type of this audio clip. This is useful in conjunction with the PlayFrom
and Seek commands to determine what the position offset represents.

\fcol{red}{Example:}
\begin{verbatim}
if (aExplosion.FileType == eAudioFileMIDI)
{
  Display("Explosion is a MIDI file!");
}
\end{verbatim}
displays a message if aExplosion is a MIDI file

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.Seek}{AudioChannel.Seek},
\helprefn{AudioChannel.Position}{AudioChannel.Position},
\helprefn{AudioClip.PlayFrom}{AudioClip.PlayFrom}


\subsection{IsAvailable property (audio clip)}\label{AudioClip.IsAvailable}\index{AudioClip.IsAvailable}\index{IsMusicVoxAvailable}%

\it{(Formerly known as IsMusicVoxAvailable, which is now obsolete)}

\begin{verbatim}
readonly bool AudioClip.IsAvailable;
\end{verbatim}
Gets whether this audio clip is available on the player's system.

This will normally be \it{true}, unless the clip was bundled in the external AUDIO.VOX
file and the player does not have the file on their system.

You do not normally need to check this property, since the Play command will silently
fail if it cannot find the audio clip to play.

\fcol{red}{Example:}
\begin{verbatim}
if (aExplosion.IsAvailable)
{
  aExplosion.Play();
}
\end{verbatim}
checks if the aExplosion audio clip is available, and if so plays it.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}


\subsection{Type property (audio clip)}\label{AudioClip.Type}\index{AudioClip.Type}%

\begin{verbatim}
readonly AudioType AudioClip.Type;
\end{verbatim}
Gets the type of this audio clip, as initially set in the editor.

The AudioType allows you to group audio clips into areas such as Sound and Music.

\fcol{red}{Example:}
\begin{verbatim}
if (aExplosion.Type == eAudioTypeMusic)
{
  Display("Explosion is music!");
}
\end{verbatim}
displays a message if the \it{aExplosion} clip is music.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}, 
\helprefn{Game.IsAudioPlaying}{Game.IsAudioPlaying}


\section{Character functions and properties}%


\subsection{AddInventory}\label{Character.AddInventory}\index{Character.AddInventory}\index{AddInventory}\index{AddInventoryToCharacter}%

\it{(Formerly known as global function AddInventory, which is now obsolete)} ILBRK
\it{(Formerly known as global function AddInventoryToCharacter, which is now obsolete)}

\begin{verbatim}
Character.AddInventory(InventoryItem *item, optional int addAtIndex)
\end{verbatim}
Adds the specified item to the character's inventory. This
ensures that the item gets added to the character's inventory list, and that
any on-screen inventory display gets updated if appropriate.

The first parameter is the inventory item's Script O-Name from the editor (for
example, \it{iPoster}).

By default, the new item is added to the end of the character's inventory list. However,
you can insert it in a particular position in the list by supplying the second parameter.
The new item is inserted \it{before} the current item at \it{addAtIndex}. Indexes are
numbered from 0, so to add the item at the start of the list, pass 0 as the second parameter.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.AddInventory(iKey);
\end{verbatim} 
will give inventory item iKey to character EGO.

\it{See Also:} \helprefn{Character.HasInventory}{Character.HasInventory},
\helprefn{Character.LoseInventory}{Character.LoseInventory},
\helprefn{UpdateInventory}{UpdateInventory}


\subsection{AddWaypoint}\label{Character.AddWaypoint}\index{Character.AddWaypoint}\index{MoveCharacterPath}%

\it{(Formerly known as MoveCharacterPath, which is now obsolete)}

\begin{verbatim}
Character.AddWaypoint(int x, int y)
\end{verbatim}
Tells the character to move to (X,Y) directly, after it has finished its current
move. This function allows you to queue up a series of moves for the character to make, if
you want them to take a preset path around the screen. Note that any moves made with
this command ignore walkable areas.

This is useful for situations when you might want a townsperson to wander onto the screen
from one side, take a preset route around it and leave again.

\fcol{red}{Example:}
\begin{verbatim}
cSomeguy.Walk(160, 100);
cSomeguy.AddWaypoint(50, 150);
cSomeguy.AddWaypoint(50, 50);
\end{verbatim}
tells character SOMEGUY to first of all walk to the centre of the screen normally (obeying
walkable areas), then move to the bottom left corner and then top left corner afterwards.

\it{See Also:} \helprefn{Character.Move}{Character.Move}
\helprefn{Character.Walk}{Character.Walk}


\subsection{Animate (character)}\label{Character.Animate}\index{Character.Animate}\index{AnimateCharacter}\index{AnimateCharacterEx}%

\it{(Formerly known as AnimateCharacter, which is now obsolete)} ILBRK
\it{(Formerly known as AnimateCharacterEx, which is now obsolete)}

\begin{verbatim}
Character.Animate(int loop, int delay, optional RepeatStyle,
                  optional BlockingStyle, optional Direction)
\end{verbatim}
Starts the character animating, using loop number LOOP of his current view. The
overall speed of the animation is set with DELAY, where 0 is the fastest, and
increasing numbers mean slower. The delay for each frame is worked out as DELAY + FRAME SPD,
so the individual frame speeds are relative to this overall speed.

Before using this command, you should use \helprefn{LockView}{Character.LockView} in order
to select the view you want to animate with and prevent any automatic animations (eg.
walking or idle animations) from playing.

The \it{RepeatStyle} parameter sets whether the animation will continuously repeat
the cycling through the frames. This can be \it{eOnce} (or zero), in which case the animation
will start from the first frame of LOOP, and go through each frame in turn until the
last frame, where it will stop. If RepeatStyle is \it{eRepeat} (or 1), then when the last frame
is reached, it will go back to the first frame and start over again with the animation.

\it{direction} specifies which way the animation plays. You can either pass eForwards (the
default) or eBackwards.

For \it{blocking} you can pass either eBlock (in which case the function will wait
for the animation to finish before returning), or eNoBlock (in which case the animation
will start to play, but your script will continue). The default is eBlock.

If the character is currently moving, it will be stopped.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockView(5);
cEgo.Animate(3, 1, 0, eBlock, eBackwards);
cEgo.UnlockView();
\end{verbatim}
will animate the character once using loop number 3 of view 5 backwards, and
wait until the animation finishes before returning.

\it{See Also:} \helprefn{Object.Animate}{Object.Animate}



\subsection{ChangeRoom}\label{Character.ChangeRoom}\index{Character.ChangeRoom}\index{NewRoom}\index{NewRoomEx}\index{NewRoomNPC}%

\it{(Formerly known as NewRoom, which is now obsolete)} ILBRK
\it{(Formerly known as NewRoomEx, which is now obsolete)} ILBRK
\it{(Formerly known as NewRoomNPC, which is now obsolete)}

\begin{verbatim}
Character.ChangeRoom(int room_number, optional int x, optional int y)
\end{verbatim}

Changes the room that the character is in.

If you call this on the player character, then the game will move into the new
room with them.

\bf{IMPORTANT:} This command does not change the room immediately; instead, it
will perform the actual room change once your script function has finished
(This is to avoid problems with unloading the script while it is still
running). This means that you should not use any other commands which rely
on the new room (object positionings, and so on) after this command within
the same function.

If you call this on a non-player character, then they are instantly transported
to the new room number.

Optionally, you can include an X and Y co-ordinate (you must include either both
or neither). If you do so, then the character will also be moved to the specified
co-ordinates in the new room.

\fcol{red}{Example:}
\begin{verbatim}
player.ChangeRoom(4, 100, 50); 
\end{verbatim}
will move the player character to room 4 and also place him at coordinates 100,50.
This will also mean that the game moves into room 4.

\it{See Also:} \helprefn{Character.ChangeRoomAutoPosition}{Character.ChangeRoomAutoPosition}



\subsection{ChangeRoomAutoPosition}\label{Character.ChangeRoomAutoPosition}\index{Character.ChangeRoomAutoPosition}%

\begin{verbatim}
Character.ChangeRoomAutoPosition(int room_number, optional int newPosition)
\end{verbatim}

Changes the room that the character is in, and positions him along one of the room edges.

This command simulates the behaviour of the old "Go to room" interaction command from AGS 2.72
and previous versions. If \it{newPosition} is not specified or is 0, the character will be
placed on the opposite side of the new room, if he is within 10 pixels of a room edge in the
current room.

Altenatively, you can specify the position where he will get placed in the new room.
\it{newPosition} can be 1000 for the left edge, 2000 for the right edge, 3000 for the
bottom edge and 4000 for the top edge. Then, add on the offset within that edge where
you want to place the character, in normal room co-ordinates.

\bf{IMPORTANT:} This command does not change the room immediately; instead, it
will perform the actual room change once your script function has finished
(This is to avoid problems with unloading the script while it is still
running). This means that you should not use any other commands which rely
on the new room (object positionings, and so on) after this command within
the same function.

\bf{NOTE:} This command can only be used with the player character.

\fcol{red}{Example:}
\begin{verbatim}
player.ChangeRoomAutoPosition(4, 2100); 
\end{verbatim}
will move the player character to room 4 and place him half way down the right hand side of the screen.
This will also mean that the game moves into room 4.

\it{See Also:} \helprefn{Character.ChangeRoom}{Character.ChangeRoom}



\subsection{ChangeView}\label{Character.ChangeView}\index{Character.ChangeView}\index{ChangeCharacterView}%

\it{(Formerly known as ChangeCharacterView, which is now obsolete)}

\begin{verbatim}
Character.ChangeView(int view)
\end{verbatim}
Changes the normal view number of the character to \it{view}. This is
useful if, for example, you want the character to change the clothes
they are wearing, and so permanently alter their view number.

\bf{NOTE:} This command is \bf{not} intended to change the view temporarily to
perform an animation. If you want to do that, use the LockView command instead. This
ChangeView command permanently changes the character's normal walking view.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ChangeView(5);
\end{verbatim}
will make the EGO character use view number 5 as his walking view.

\it{See Also:} \helprefn{Character.LockView}{Character.LockView},
\helprefn{Character.NormalView}{Character.NormalView}


\subsection{FaceCharacter}\label{Character.FaceCharacter}\index{Character.FaceCharacter}\index{FaceCharacter}%

\it{(Formerly known as global function FaceCharacter, which is now obsolete)}

\begin{verbatim}
Character.FaceCharacter(Character* toFace, optional BlockingStyle)
\end{verbatim}
Turns the graphic of the character so that it looks like he is facing
character TOFACE. This involves changing the current loop to the appropriate
loop number, and setting the frame number to 0 (standing).

If the character has Turning enabled (ie. the "Characters turn to face direction" game
option is turned on, and the character does not have the "Do not turn before walking"
option checked), then the character will turn on the spot in order to face the new direction.
In this case, the BlockingStyle parameter determines whether the script waits for the
character to finish turning (eBlock, the default) or whether the script continues immediately
and the character finishes turning later on (eNoBlock).

If the character does not have Turning enabled, he will immediately turn to face the
new direction and the BlockingStyle parameter has no effect. In this case, the screen
will not be refreshed straight away -- if you want to see the character facing his new direction
immediately, call  Wait(1);

\fcol{red}{Example:}
\begin{verbatim}
cEgo.FaceCharacter(cMan);
\end{verbatim}
will make the character EGO face the character MAN

\it{See Also:} \helprefn{Character.FaceLocation}{Character.FaceLocation},
\helprefn{Character.FaceObject}{Character.FaceObject},
\helprefn{Character.Walk}{Character.Walk}


\subsection{FaceLocation}\label{Character.FaceLocation}\index{Character.FaceLocation}\index{FaceLocation}%

\it{(Formerly known as global function FaceLocation, which is now obsolete)}

\begin{verbatim}
Character.FaceLocation(int x, int y, optional BlockingStyle)
\end{verbatim}
Similar to the FaceCharacter function, except that this faces the character
to room co-ordinates (X,Y). This allows him to face not only other characters,
but also hotspots or anything else as well (you can get co-ordinates by
watching the co-ordinates displayed in the Room Settings mode as you move the mouse
over the room background).

If the character has Turning enabled (ie. the "Characters turn to face direction" game
option is turned on, and the character does not have the "Do not turn before walking"
option checked), then the character will turn on the spot in order to face the new direction.
In this case, the BlockingStyle parameter determines whether the script waits for the
character to finish turning (eBlock, the default) or whether the script continues immediately
and the character finishes turning later on (eNoBlock).

If the character does not have Turning enabled, he will immediately turn to face the
new direction and the BlockingStyle parameter has no effect. In this case, the screen
will not be refreshed straight away -- if you want to see the character facing his new direction
immediately, call  Wait(1);

\fcol{red}{Example:}
\begin{verbatim}
cEgo.FaceLocation(cEgo.x + 50, cEgo.y);
\end{verbatim}
will make the character face to the east.

\it{See Also:} \helprefn{Character.FaceCharacter}{Character.FaceCharacter}


\subsection{FaceObject}\label{Character.FaceObject}\index{Character.FaceObject}%

\begin{verbatim}
Character.FaceObject(Object* object, optional BlockingStyle)
\end{verbatim}
Similar to the FaceCharacter function, except that this faces the character
to object OBJECT in the current room.

If the character has Turning enabled (ie. the "Characters turn to face direction" game
option is turned on, and the character does not have the "Do not turn before walking"
option checked), then the character will turn on the spot in order to face the new direction.
In this case, the BlockingStyle parameter determines whether the script waits for the
character to finish turning (eBlock, the default) or whether the script continues immediately
and the character finishes turning later on (eNoBlock).

If the character does not have Turning enabled, he will immediately turn to face the
new direction and the BlockingStyle parameter has no effect. In this case, the screen
will not be refreshed straight away -- if you want to see the character facing his new direction
immediately, call  Wait(1);

\fcol{red}{Example:}
\begin{verbatim}
player.FaceObject(object[2]);
\end{verbatim}
will make the player character face object 2.

\it{See Also:} \helprefn{Character.FaceCharacter}{Character.FaceCharacter}


\subsection{FollowCharacter}\label{Character.FollowCharacter}\index{Character.FollowCharacter}\index{FollowCharacter}\index{FollowCharacterEx}%

\it{(Formerly known as global function FollowCharacter, which is now obsolete)} ILBRK
\it{(Formerly known as global function FollowCharacterEx, which is now obsolete)}

\begin{verbatim}
Character.FollowCharacter(Character* chartofollow, optional int dist,
                          optional int eagerness)
\end{verbatim}
Tells the character to follow CHARTOFOLLOW around, wherever he goes.
You could use this command to have a group of main characters who go around
together, or for example when the hero has rescued someone from the bad
guy, they can follow the hero home.

Pass CHARTOFOLLOW as \it{null} to stop the character following.

There are a couple of extra optional parameters:

DIST sets how far away from CHARTOFOLLOW that CHARID will
stand. If DIST is 1, they will try to stand very close; if DIST is for
example 20, they will stand about 20 pixels away.

EAGERNESS sets on average how long the character will stand around before
checking if he needs to move again. Setting this to 0 means that he will
always be on the move until he reaches CHARTOFOLLOW; setting this to 99
means that he will pause and think for a while on route. Values in between
specify different lengths of idle time.

The default values are DIST=10 and EAGERNESS=97.

As a special case, setting DIST=0 and EAGERNESS=0 makes CHARID behave as if
it is chasing CHARTOFOLLOW - it will try and get there as quickly as possible.
Setting EAGERNESS=0 also tells the character not to stop when they reach
CHARTOFOLLOW, but instead to randomly wander around the character - useful
perhaps for a very energetic dog or something.

There is also another special use for this command. You can pass the special
value FOLLOW_EXACTLY as the DIST parameter rather than passing a number. If you
do this, then CHARID will always remain at exactly the same X and Y co-ordinates
as CHARTOFOLLOW. This might be useful for effects such as a temporary halo over 
the character and so forth.

If you use FOLLOW_EXACTLY, then EAGERNESS has another meaning. If you pass 0, CHARID
will be drawn in front of CHARTOFOLLOW; if you pass 1, it will be drawn behind.

\fcol{red}{Example:}
\begin{verbatim}
cMan.FollowCharacter(cEgo, 5, 80);
\end{verbatim}
will make character MAN follow character EGO standing about 5 pixels near
him and waiting for a while before he makes his move.


\subsection{GetAtScreenXY (character)}\label{Character.GetAtScreenXY}\index{Character.GetAtScreenXY}\index{GetCharacterAt}%

\it{(Formerly known as global function GetCharacterAt, which is now obsolete)}

\begin{verbatim}
static Character* Character.GetAtScreenXY(int x, int y)
\end{verbatim}
Checks if there is a character at SCREEN co-ordinates (X,Y).
Returns the character if there is, or null if there is not.
See the description of GetLocationName for more on screen co-ordinates.

NOTE: Any characters with the "Clickable" property set to false will not be seen
by this function.

\fcol{red}{Example:}
\begin{verbatim}
if (Character.GetAtScreenXY(mouse.x, mouse.y) == cEgo) {
  Display("The mouse is over the main character");
}
\end{verbatim}
will display the message if the mouse cursor is over the EGO character

\it{See Also:} \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY},
\helprefn{Object.GetAtScreenXY}{Object.GetAtScreenXY},
\helprefn{Game.GetLocationName}{Game.GetLocationName}


\subsection{GetProperty (character)}\label{Character.GetProperty}\index{Character.GetProperty}\index{GetCharacterProperty}%

\it{(Formerly known as GetCharacterProperty, which is now obsolete)}

\begin{verbatim}
Character.GetProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the specified character.

This command works with Number properties (it returns the number), and with Boolean
properties (returns 1 if the box was checked, 0 if not).

Use the equivalent GetTextProperty function to get a text property.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.GetProperty("Value") > 200)
  Display("EGO's value is over 200!");
\end{verbatim}
will print the message if EGO has its "Value" property set to more than 200.

\it{See Also:} \helprefn{Character.GetTextProperty}{Character.GetTextProperty}


\subsection{GetTextProperty (character)}\label{Character.GetTextProperty}\index{Character.GetTextProperty}\index{Character.GetPropertyText}\index{GetCharacterPropertyText}%

\it{(Formerly known as GetCharacterPropertyText, which is now obsolete)} ILBRK
\it{(Formerly known as Character.GetPropertyText, which is now obsolete)}

\begin{verbatim}
String Character.GetTextProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the specified character.

This command works with Text properties only. The property's text will be
returned from this function.

Use the equivalent GetProperty function to get a non-text property.

\fcol{red}{Example:}
\begin{verbatim}
String description = cEgo.GetTextProperty("Description");
Display("EGO's description: %s", description);
\end{verbatim}
will retrieve EGO's "description" property and display it.

\it{See Also:} \helprefn{Character.GetProperty}{Character.GetProperty}


\subsection{HasInventory}\label{Character.HasInventory}\index{Character.HasInventory}%

\begin{verbatim}
bool Character.HasInventory(InventoryItem *item)
\end{verbatim}
Checks whether the character currently has the specified inventory item.
Returns \it{true} if they do, or \it{false} if they don't.

The parameter is the inventory item's Script O-Name from the editor (for
example, \it{iPoster}).

\fcol{red}{Example:}
\begin{verbatim}
if (player.HasInventory(iKey))
{
  Display("The player has the key!!");
}
\end{verbatim} 
will display a message if the player has the key.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Character.AddInventory}{Character.AddInventory},
\helprefn{Character.InventoryQuantity}{Character.InventoryQuantity},
\helprefn{Character.LoseInventory}{Character.LoseInventory}



\subsection{IsCollidingWithChar}\label{Character.IsCollidingWithChar}\index{Character.IsCollidingWithChar}\index{AreCharactersColliding}%

\it{(Formerly known as AreCharactersColliding, which is now obsolete)}

\begin{verbatim}
Character.IsCollidingWithChar(Character* otherChar)
\end{verbatim}
Checks if the character is touching OTHERCHAR. This function just checks
the baseline of both characters, so if one is standing a fair distance behind
the other, it will not be marked as colliding.

Returns 1 if the characters feet are touching, 0 otherwise.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.IsCollidingWithChar(cMan) == 1)
   { colliding code here }
\end{verbatim}
will execute the colliding code only if the characters EGO and MAN are colliding. 

\it{See Also:} \helprefn{Character.IsCollidingWithObject}{Character.IsCollidingWithObject}, 
\helprefn{Object.IsCollidingWithObject}{Object.IsCollidingWithObject},
\helprefn{AreThingsOverlapping}{AreThingsOverlapping}


\subsection{IsCollidingWithObject (character)}\label{Character.IsCollidingWithObject}\index{Character.IsCollidingWithObject}\index{AreCharObjColliding}%

\it{(Formerly known as AreCharObjColliding, which is now obsolete)}

\begin{verbatim}
Character.IsCollidingWithObject(Object* obj)
\end{verbatim}
Checks whether the character's feet (ie. the bottom third of the character) are
touching OBJ. This can be used to determine if the character is standing on the object.

Returns 1 if they are, and 0 if they are not.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.IsCollidingWithObject(object[3]) == 1) {
  // colliding code here
}
\end{verbatim}
will execute the colliding code only if the character EGO and the object number 3 are colliding. 

\it{See Also:} \helprefn{Character.IsCollidingWithChar}{Character.IsCollidingWithChar}, 
\helprefn{Object.IsCollidingWithObject}{Object.IsCollidingWithObject},
\helprefn{AreThingsOverlapping}{AreThingsOverlapping}


\subsection{LockView}\label{Character.LockView}\index{Character.LockView}\index{SetCharacterView}%

\it{(Formerly known as SetCharacterView, which is now obsolete)}

\begin{verbatim}
Character.LockView(int view)
\end{verbatim}

Sets the character's view to VIEW. This can be used to perform animations
with characters, for example bending down to pick something up, which don't
use the default view.

\bf{NOTE:} This function locks the character's view to the specified view, so
that it can only be changed by other script commands (ie. it won't
automatically be changed by AGS on walkable areas, screen changes,
etc). When you are done with the animation, call UnlockView to allow AGS to
take control back.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockView(12);
cEgo.Animate(0, 0, eOnce, eBlock, eForwards);
cEgo.UnlockView();
\end{verbatim}
will change the character's EGO view to view 12, perform an animation using loop 0,
wait until the animation finishes and then return the character to his normal view.

\it{See Also:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.ChangeView}{Character.ChangeView},
\helprefn{Character.SpeechView}{Character.SpeechView},
\helprefn{Character.LockViewAligned}{Character.LockViewAligned},
\helprefn{Character.LockViewOffset}{Character.LockViewOffset}
\helprefn{Character.UnlockView}{Character.UnlockView},


\subsection{LockViewAligned}\label{Character.LockViewAligned}\index{Character.LockViewAligned}\index{SetCharacterViewEx}%

\it{(Formerly known as SetCharacterViewEx, which is now obsolete)}

\begin{verbatim}
Character.LockViewAligned(int view, int loop, Alignment)
\end{verbatim}

Sets the character's view to VIEW, and sets the character's current frame to
the first frame in LOOP of VIEW.

The main purpose of this command is that it can align the new frame to the previous one.
This is particularly useful if you want to go from the character's normal walking view to
a specific animation - since characters have the central point as their 'axis', if
you have a wider animation then it can be difficult to stop yourself getting a jumping
effect when the animation starts.

\it{Alignment} can have one of the following values:

\begin{tabular}{|l|l|}
\row{ {\bf align } & {\bf Description }
}\row{{ eAlignLeft } & { Moves the new frame so that the left hand side is at exactly 
                          the same X co-ordinate as the old one was. }
}\row{{ eAlignCentre } & { Leaves the frames centred in the middle. This is the default
                          and using this is equivalent to just calling LockView. }
}\row{{ eAlignRight } & { Moves the new frame so that the right hand side is at exactly
                         the same X co-ordinate as the old one was. }
}\end{tabular}

Note that this only aligns the first frame of the animation, so to get the full benefit
all your frames in the animation loop should be the same width. All following frames will
be shifted by the same amount, until UnlockView is called.

\bf{NOTE:} This function locks the character's view to the specified view, so
that it can only be changed by other script commands (ie. it won't
automatically be changed by the program on regions, screen changes,
etc). When you are done with the animation, call UnlockView to
allow the program to take control back.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockViewAligned(12, 1, eAlignLeft);
cEgo.Animate(1, 5, eOnce, eBlock, eForwards);
cEgo.UnlockView();
\end{verbatim}
will change the character's EGO view to view 12, perform an animation using loop 1,
wait until the animation finishes and then return the character to his normal view.

\it{See Also:} \helprefn{Character.LockView}{Character.LockView},
\helprefn{Character.LockViewOffset}{Character.LockViewOffset},
\helprefn{Character.UnlockView}{Character.UnlockView}


\subsection{LockViewFrame}\label{Character.LockViewFrame}\index{Character.LockViewFrame}\index{SetCharacterFrame}%

\it{(Formerly known as SetCharacterFrame, which is now obsolete)}

\begin{verbatim}
Character.LockViewFrame(int view, int loop, int frame)
\end{verbatim}
Sets the character's graphic to frame FRAME of loop LOOP of view number VIEW.
This is useful if you don't want an animation, but just want to change the
character to display a specific frame.

The frame will be locked to the one you specify until you call UnlockView.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockViewFrame(AGHAST, 2, 4);
Wait(40);
cEgo.UnlockView();
\end{verbatim}
will change EGO to have frame 4 of loop 2 in the AGHAST view, wait for a second,
then return him to normal.

\it{See Also:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.LockView}{Character.LockView},
\helprefn{Character.UnlockView}{Character.UnlockView}


\subsection{LockViewOffset}\label{Character.LockViewOffset}\index{Character.LockViewOffset}\index{SetCharacterViewOffset}%

\it{(Formerly known as SetCharacterViewOffset, which is now obsolete)}

\begin{verbatim}
Character.LockViewOffset(int view, int xOffset, int yOffset)
\end{verbatim}

Sets the character's view to VIEW, in the same way as LockView does. However,
it also adds a specified offset to all the character's frames until UnlockView
is called.

The XOFFSET and YOFFSET parameters specify \bf{in actual game resolution units} how much
to move the character's sprite. Positive values for X move right, for Y move down; negative
values do the opposite.

This command is designed to allow you to cope with those niggly situations where animations
don't quite line up with the standing frame, assuming all the frames of the animation are
the same size. Note that LockViewAligned is easier to use if your frames will align at
the left or right hand side.

\bf{NOTE:} You should only use this command for minor adjustments, since the offsets do not
affect the clickable area of the character, what walkable area he is in, and so forth. You
should limit the use of this command to in-game cutscenes where the player has no control.

\bf{NOTE:} This is the only command in AGS which uses actual game-resolution co-ordinates.
Therefore, specifying an x offset of 1 will actually move 1 pixel in a 640x400 game, and will
not be multiplied up to 2 (they will be automatically adjusted though if the player chooses
to play the game at another resolution).

\bf{NOTE:} This function locks the character's view to the specified view, so
that it can only be changed by other script commands (ie. it won't
automatically be changed by AGS on walkable areas, screen changes, etc). When
you are done with the animation, call UnlockView to allow AGS to take control back.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockViewOffset(12, 1, -1);
cEgo.Animate(1, 5, eOnce, eBlock, eForwards);
cEgo.UnlockView();
\end{verbatim}
will change EGO's view to view 12 and animate using loop 1, meanwhile all frames will be
shifted 1 pixel right and 1 pixel up.

\it{See Also:} \helprefn{Character.LockView}{Character.LockView},
\helprefn{Character.LockViewAligned}{Character.LockViewAligned},
\helprefn{Character.UnlockView}{Character.UnlockView}


\subsection{LoseInventory}\label{Character.LoseInventory}\index{Character.LoseInventory}\index{LoseInventory}\index{LoseInventoryFromCharacter}%

\it{(Formerly known as global function LoseInventory, which is now obsolete)}ILBRK
\it{(Formerly known as LoseInventoryFromCharacter, which is now obsolete)}

\begin{verbatim}
Character.LoseInventory(InventoryItem *item)
\end{verbatim}
Removes the specified inventory item from the character's inventory.
If they do not have the item, nothing happens.

The parameter is the inventory item's Script O-Name from the editor.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LoseInventory(iKey);
\end{verbatim}
will make the character EGO lose the inventory item iKey from the inventory tab

\it{See Also:} \helprefn{Character.AddInventory}{Character.AddInventory}


\subsection{Move (character)}\label{Character.Move}\index{Character.Move}%

\begin{verbatim}
Character.Move(int x, int y, optional BlockingStyle,
                             optional WalkWhere);
\end{verbatim}
Starts the character moving from its current location to (X,Y), but does 
not play the character's walking animation.

The parameters to this command are identical to the \helprefn{Character.Walk}{Character.Walk}
command -- see that page for more details. The only difference is that \it{Walk}
plays the walking animation whereas \it{Move} does not.

In the vast majority of cases, you will use \bf{Character.Walk} instead.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Move(155, 122, eBlock);
\end{verbatim}
will make the character move to 155,122 without playing his walking animation.
The script will not continue until the character has reached his destination.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Character.AddWaypoint}{Character.AddWaypoint},
\helprefn{Character.FaceCharacter}{Character.FaceCharacter},
\helprefn{Character.Walk}{Character.Walk},
\helprefn{MoveCharacterToObject}{MoveCharacterToObject},
\helprefn{Object.Move}{Object.Move},
\helprefn{Character.StopMoving}{Character.StopMoving}


\subsection{PlaceOnWalkableArea}\label{Character.PlaceOnWalkableArea}\index{Character.PlaceOnWalkableArea}\index{MoveToWalkableArea}%

\it{(Formerly known as MoveToWalkableArea, which is now obsolete)}

\begin{verbatim}
Character.PlaceOnWalkableArea()
\end{verbatim}
Places the character in the nearest walkable area to its current location.
If the character is already on a walkable area, nothing happens.

This is useful for example in the Player Enters Room event of a room, to
make sure the character can move if a ChangeRoom with co-ordinates has been issued to get there.
You could also use this in on_event for eEventEnterRoomBeforeFadein to use whenever a
player enters a room.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.x = Random(320);
cEgo.y = Random(200);
cEgo.PlaceOnWalkableArea();
\end{verbatim}
will move character EGO to a random position but make sure that he is on a walkable area.


\subsection{RemoveTint (character)}\label{Character.RemoveTint}\index{Character.RemoveTint}%

\begin{verbatim}
Character.RemoveTint()
\end{verbatim}

Undoes the effects of calling Tint, and returns the character to using the room's ambient tint.

\fcol{red}{Example:}
\begin{verbatim}
player.Tint(0, 250, 0, 30, 100);
Wait(40);
player.RemoveTint();
\end{verbatim}
will tint the player character green for a second, then turn it back to normal.

\it{See Also:} \helprefn{Character.HasExplicitTint}{Character.HasExplicitTint},
\helprefn{Character.Tint}{Character.Tint}


\subsection{RunInteraction (character)}\label{Character.RunInteraction}\index{Character.RunInteraction}\index{RunCharacterInteraction}%

\it{(Formerly known as RunCharacterInteraction, which is now obsolete)}

\begin{verbatim}
Character.RunInteraction(CursorMode)
\end{verbatim}
Fires the event script as if the player had clicked the mouse on the character
in the specified cursor mode. This is one of the mouse cursor
modes, as defined in your Cursors tab in the editor.

\fcol{red}{Example:}
\begin{verbatim}
cMan.RunInteraction(eModeTalk);
\end{verbatim}
will execute the code defined in the MAN's "TALK TO CHARACTER" event.

\it{See Also:} \helprefn{ProcessClick}{ProcessClick}, \helprefn{Hotspot.RunInteraction}{Hotspot.RunInteraction},
\helprefn{InventoryItem.RunInteraction}{InventoryItem.RunInteraction}


\subsection{Say}\label{Character.Say}\index{Character.Say}\index{DisplaySpeech}%

\it{(Formerly known as DisplaySpeech, which is now obsolete)}

\begin{verbatim}
Character.Say(string message)
\end{verbatim}
Displays the text MESSAGE as speech above the character's head.
The text will remain on screen for a limited time, and the user may or may
not be able to click it away depending on the setting of "Player can't
skip speech text". The text displayed by this function looks identical to
that used by the dialog system.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Say("My name is ego");
\end{verbatim}
will display the message above the character's EGO head like the LEC games,
whilst playing the character's talking animation.

\it{See Also:} \helprefn{Display}{Display}, \helpref{Character.SayAt}{Character.SayAt},
\helprefn{Character.SayBackground}{Character.SayBackground},
\helprefn{Character.Think}{Character.Think}


\subsection{SayAt}\label{Character.SayAt}\index{Character.SayAt}\index{DisplaySpeechAt}%

\it{(Formerly known as DisplaySpeechAt, which is now obsolete)}

\begin{verbatim}
SayAt(int x, int y, int width, string message)
\end{verbatim}
Similar to \helprefn{Say}{Character.Say}, except that the text is displayed with its top
left corner at (X,Y), in an area WIDTH wide.

You can use this function to write the character's speech text anywhere you like, and
AGS will still play the character's talking animation and so on if appropriate.

\bf{NOTE:} This function does not support Whole-Screen speech.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.SayAt(220, 20, 100, "My name is ego");
\end{verbatim}
will display the message in the top right corner of the screen, whilst playing the
character's talking animation.

\it{See Also:} \helprefn{Character.Say}{Character.Say},
\helprefn{Character.SayBackground}{Character.SayBackground}


\subsection{SayBackground}\label{Character.SayBackground}\index{Character.SayBackground}\index{DisplaySpeechBackground}%

\it{(Formerly known as DisplaySpeechBackground, which is now obsolete)}

\begin{verbatim}
Overlay* Character.SayBackground(string message)
\end{verbatim}
Similar to Say, except that this function returns immediately
and the game continues while the character is talking. This allows you
to have characters talking in the background while the player does other
things. Note that the character's talking animation is not played if this
function is used.

This command works by creating a text overlay with an automatic removal time
delay. The overlay is returned by this command, so you can save it for
use later with Overlay.IsValid and Overlay.Remove, if you want to remove the
text prematurely.

If background speech is already on-screen for the character, it will be removed and
replaced with the new MESSAGE.

All background speech is automatically removed when a normal Say command
is used (unless you set the global variable \helpref{game.bgspeech_stay_on_display}{Gamevariables} to 1).

\fcol{red}{Example:}
\begin{verbatim}
cMan.SayBackground("Hey, why won't you talk to me?");
\end{verbatim}
will display the message above character MAN's head without pausing the game.

\it{See Also:} \helprefn{Character.Say}{Character.Say}


\subsection{SetAsPlayer}\label{Character.SetAsPlayer}\index{Character.SetAsPlayer}\index{SetPlayerCharacter}%

\it{(Formerly known as SetPlayerCharacter, which is now obsolete)}

\begin{verbatim}
Character.SetAsPlayer()
\end{verbatim}
Changes the character which the player controls to the specified character.
This function will also cause the room to change to the room which the
chosen character is currently in (though as with ChangeRoom, the change won't
happen until the end of the script).

Additionally, calling this command will cause the "player" variable to be
updated to point to the specified character.

\fcol{red}{Example:}
\begin{verbatim}
cMan.SetAsPlayer();
\end{verbatim}
will change the character that the player controls to character MAN and also change to the room
that MAN is in, if he is not in the current room.

\it{See Also:} \helprefn{Character.ID}{Character.ID},
\helprefn{Character.ChangeRoom}{Character.ChangeRoom}


\subsection{SetIdleView}\label{Character.SetIdleView}\index{Character.SetIdleView}\index{SetCharacterIdle}%

\it{(Formerly known as SetCharacterIdle, which is now obsolete)}

\begin{verbatim}
Character.SetIdleView(int idleview, int delay)
\end{verbatim}
Changes the character's idle view to IDLEVIEW, with a timeout of DELAY seconds
of inactivity before it is played. Inactivity is defined as when the character
is not moving and not being animated.

Setting DELAY to 0 causes the idle view to be looped continuously when
the character is not moving - this is useful when for example the character
is swimming and they need to tread water when idle.

Pass IDLEVIEW as -1 to disable the idle view completely.

\bf{NOTE:} The DELAY is actually relative to the game speed. Setting this to 1 means
a one second delay at the default 40 fps, but if you have adjusted the game speed then
the delay will be adjusted accordingly.

\bf{NOTE:} Due to a quirk in AGS, you cannot set the Idle View to view 1. In the unlikely event that you
created your idle view in View 1, you'll need to move it to another view number.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.SetIdleView(12, 30);
\end{verbatim}
will change/set the character EGO's idle view to 12. The idle view will be
played if the character is idle for 30 seconds.


\subsection{SetWalkSpeed}\label{Character.SetWalkSpeed}\index{Character.SetWalkSpeed}\index{SetCharacterSpeed}\index{SetCharacterSpeedEx}%

\it{(Formerly known as SetCharacterSpeed, which is now obsolete)}ILBRK
\it{(Formerly known as SetCharacterSpeedEx, which is now obsolete)}

\begin{verbatim}
Character.SetWalkSpeed(int x_speed, int y_speed)
\end{verbatim}

Changes the character to have a walking speed of X_SPEED in the horizontal direction
and Y_SPEED in the vertical direction. The values used for X_SPEED and Y_SPEED are
identical to those set in the AGS Editor for walking speed.

X_SPEED and Y_SPEED can be identical, in which case the character moves with the same
speed in any direction. (the editor calls this "Uniform movement speed")

\bf{NOTE:} This function CANNOT be called while the character is moving, so
you must stop him first.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.SetWalkSpeed(10, 10);
\end{verbatim}
will change the character EGO's speed to 10.

\it{See Also:} \helprefn{Character.AnimationSpeed}{Character.AnimationSpeed},
\helprefn{Character.StopMoving}{Character.StopMoving},
\helprefn{Character.Walk}{Character.Walk},
\helprefn{Character.WalkSpeedX}{Character.WalkSpeedX},
\helprefn{Character.WalkSpeedY}{Character.WalkSpeedY}



\subsection{StopMoving (character)}\label{Character.StopMoving}\index{Character.StopMoving}\index{StopMoving}%

\it{(Formerly known as global function StopMoving, which is now obsolete)}

\begin{verbatim}
Character.StopMoving()
\end{verbatim}
Stops the character moving and sets its graphic to the standing frame of the current loop.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.x > 299) 
{
  cEgo.StopMoving();
}
\end{verbatim}
will stop the character when he reaches the coordinate x=300.

\it{See Also:} \helprefn{Character.Walk}{Character.Walk}, \helprefn{Object.StopMoving}{Object.StopMoving}


\subsection{Think}\label{Character.Think}\index{Character.Think}\index{DisplayThought}%

\it{(Formerly known as DisplayThought, which is now obsolete)}

\begin{verbatim}
Character.Think(string message, ...)
\end{verbatim}
Displays the text MESSAGE as a thought above the specified character's head.
The text will remain on screen for a limited time, and the user may or may
not be able to click it away depending on the setting of "Player can't
skip speech text".

How this function displays the text depends on a few things: the Speech Style
setting, the 'Thought uses bubble GUI' setting, and whether the character has a thinking
animation or not.

If the "Thought uses bubble GUI" setting is not checked, then the thought will be displayed
in the same way as normal speech - the difference being that the character's thinking animation
will play (or no animation if they don't have one).

If you are using Sierra-style speech and the character doesn't have a thinking animation,
the thought bubble will be displayed in lucasarts-style.

If the "Thought uses bubble GUI" setting has been set, then the thought will be displayed
like normal speech, except that the bubble GUI will be used for the window background.
In Lucasarts-style speech this means above the character's head, in Sierra-style it will
be done along the top of the screen as normal.

If the character has a thinking animation, it will just loop through once (it won't repeat).

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Think("I wonder what's for dinner.");
\end{verbatim}
will display the message above EGO's head and play the character's thinking animation.

\it{See Also:} \helprefn{Character.BlinkWhileThinking}{Character.BlinkWhileThinking},
\helprefn{Character.Say}{Character.Say},
\helprefn{Character.ThinkView}{Character.ThinkView},
\helprefn{game.speech_bubble_width}{Gamevariables}


\subsection{Tint (character)}\label{Character.Tint}\index{Character.Tint}%

\begin{verbatim}
Character.Tint(int red, int green, int blue,
               int saturation, int luminance)
\end{verbatim}

Tints the character on the screen to (RED, GREEN, BLUE) with SATURATION percent
saturation.

This function applies a tint to a specific character. For the meaning of all the parameters,
see \helprefn{SetAmbientTint}{SetAmbientTint}.

The tint set by this function overrides any ambient tint set for the room. For this
reason, passing the SATURATION as 0 to this function does not turn it off - rather, it
ensures that no tint is applied to the character (even if an ambient tint is set).

To remove the tint set by this function and return to using the ambient tint for this
character, call \helprefn{RemoveTint}{Character.RemoveTint}.

\bf{NOTE:} This function only works in hi-colour games and with hi-colour sprites.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Tint(0, 250, 0, 30, 100);
\end{verbatim}
will tint the EGO character green.

\it{See Also:} \helprefn{Character.HasExplicitTint}{Character.HasExplicitTint},
\helprefn{Character.RemoveTint}{Character.RemoveTint},
\helprefn{SetAmbientTint}{SetAmbientTint}


\subsection{UnlockView}\label{Character.UnlockView}\index{Character.UnlockView}\index{ReleaseCharacterView}%

\it{(Formerly known as ReleaseCharacterView, which is now obsolete)}

\begin{verbatim}
Character.UnlockView()
\end{verbatim}
Allows the engine to automatically control the character's view, as normal.
Use this once you have finished doing the animation which you started with
the LockView command.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.LockView(12);
cEgo.Animate(0, 0, eOnce, eBlock, eForwards);
cEgo.UnlockView();
\end{verbatim}
will play an animation using loop 0 of view 12, then return the character to its normal view.

\it{See Also:} \helprefn{Character.LockView}{Character.LockView}



\subsection{Walk}\label{Character.Walk}\index{Character.Walk}\index{MoveCharacter}\index{MoveCharacterBlocking}\index{MoveCharacterDirect}%

\it{(Formerly known as MoveCharacter, which is now obsolete)}ILBRK
\it{(Formerly known as MoveCharacterBlocking, which is now obsolete)}ILBRK
\it{(Formerly known as MoveCharacterDirect, which is now obsolete)}

\begin{verbatim}
Character.Walk(int x, int y, optional BlockingStyle,
                             optional WalkWhere);
\end{verbatim}
Starts the character moving from its current location to (X,Y), whilst playing
his walking animation.

If \it{blocking} is eNoBlock (the default) then control returns to the script immediately, and
the character will move in the background.

If \it{blocking} is eBlock then this command will wait for the character
to finish moving before your script resumes.

If \it{walkWhere} is eWalkableAreas (the default), then the character will attempt to
get as close a possible to (X,Y) by using the room's walkable areas.

If \it{walkWhere} is eAnywhere, then the character will simply walk directly from its
current location to (X,Y), ignoring the room walkable areas.

If you don't want the character's walking animation to play, you can use the
\helprefn{Move}{Character.Move} command instead.

\bf{NOTE:} this function only works with characters which are on the current screen.

\bf{NOTE:} if you need to find out when the character has reached its destination,
use the \helprefn{Moving}{Character.Moving} property.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Walk(155, 122, eBlock);
\end{verbatim}
will make the character walk to 155,122. The script will not continue until the
character has reached his destination.

\it{See Also:} \helprefn{Character.AddWaypoint}{Character.AddWaypoint},
\helprefn{Character.FaceCharacter}{Character.FaceCharacter},
\helprefn{Character.Move}{Character.Move},
\helprefn{MoveCharacterToObject}{MoveCharacterToObject},
\helprefn{Object.Move}{Object.Move},
\helprefn{Character.StopMoving}{Character.StopMoving}


\subsection{WalkStraight}\label{Character.WalkStraight}\index{Character.WalkStraight}\index{MoveCharacterStraight}%

\it{(Formerly known as MoveCharacterStraight, which is now obsolete)}

\begin{verbatim}
Character.WalkStraight(int x, int y, optional BlockingStyle);
\end{verbatim}
Moves the character from its current location towards (X,Y) in a straight
line as far as is possible before hitting a non-walkable area. This is
useful for use with the arrow keys for character movement, since it
guarantees that the character will move in a straight line in the direction
specified.

\it{blocking} determines whether the function waits for the character to finish moving
before your script resumes. eNoBlock is the default (which means your script
resumes straight away, and the character moves in the background). You can also pass
eBlock, in which case your script will not resume until the character finishes moving.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.WalkStraight(166, 78);
\end{verbatim}
will move the character EGO in a straight line towards co ordinates 166,78 until he
hits a non walkable area.

\it{See Also:} \helprefn{Character.Walk}{Character.Walk}


\subsection{ActiveInventory property}\label{Character.ActiveInventory}\index{Character.ActiveInventory}\index{SetActiveInventory}%

\it{(Formerly known as SetActiveInventory, which is now obsolete)} ILBRK
\it{(Formerly known as character[].activeinv, which is now obsolete)}

\begin{verbatim}
InventoryItem* Character.ActiveInventory
\end{verbatim}
Gets/sets the character's current active inventory item.
Setting it will update the mouse cursor if appropriate.

This property is useful in "Use inventory on hotspot/character/etc" events, to
find out which inventory item the player is trying to use on the target.

To deselect the current inventory, set it to \it{null}.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ActiveInventory = iKey;
\end{verbatim}
will make the inventory item iKey active (before you use it make sure that the player
has the inventory item)


\subsection{Animating property (character)}\label{Character.Animating}\index{Character.Animating}%

\it{(Formerly known as character[].animating, which is now obsolete)}

\begin{verbatim}
readonly bool Character.Animating
\end{verbatim}
Returns 1 if the character is currently animating. ILBRK
Returns 0 if the character has finished its animation.

This property is read-only. To change character animation, use the
\helprefn{Animate}{Character.Animate} command.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Animate(5, 0);
while (cEgo.Animating) Wait(1);
\end{verbatim}
will animate EGO and wait until the animation finishes.

In reality, you would simply use the Blocking parameter of Animate so you wouldn't need
to do this.

\it{See Also:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.Moving}{Character.Moving},
\helprefn{Character.Speaking}{Character.Speaking}


\subsection{AnimationSpeed property}\label{Character.AnimationSpeed}\index{Character.AnimationSpeed}%

\it{(Formerly known as character[].animspeed, which is now obsolete)}

\begin{verbatim}
int Character.AnimationSpeed;
\end{verbatim}

Gets/sets the character's animation delay, as set in the editor.

\fcol{red}{Example:}
\begin{verbatim}
player.AnimationSpeed = 4;
\end{verbatim}
will change the player character's animation speed to 4.

\it{See Also:} \helprefn{Character.SetWalkSpeed}{Character.SetWalkSpeed},
\helprefn{Character.SpeechAnimationDelay}{Character.SpeechAnimationDelay}


\subsection{Baseline property (character)}\label{Character.Baseline}\index{Character.Baseline}\index{SetCharacterBaseline}%

\it{(Formerly known as SetCharacterBaseline, which is now obsolete)}

\begin{verbatim}
int Character.Baseline
\end{verbatim}
Gets/sets the character's baseline. This allows you to set a specific
base line for the character, which works similarly to walk-behind area and
object baselines.

The baseline can be from 1 to the height of the room (normally 200), or set it
to 0 to go back to using the character's feet as the baseline.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Baseline = 120;
\end{verbatim}
will move the character's baseline (which can be used for testing collisions,
or for walk-behinds) to a line positioned at y coordinate = 120.

\it{See Also:} \helprefn{Object.Baseline}{Object.Baseline}, \helprefn{SetWalkBehindBase}{SetWalkBehindBase}



\subsection{BlinkInterval property}\label{Character.BlinkInterval}\index{Character.BlinkInterval}\index{SetCharacterBlinkView}%

\it{(Formerly part of SetCharacterBlinkView, which is now obsolete)}

\begin{verbatim}
int Character.BlinkInterval
\end{verbatim}
Gets/sets the character's blinking interval, which specifies how long the game waits
between playing the blinking animation. This is specified in game loops - an interval
of 80 would play the blinking animation about every 2 seconds.

This property has no effect if no \helpref{BlinkView}{Character.BlinkView} has been set.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.BlinkView = 10;
cEgo.BlinkInterval = 160;
\end{verbatim}
will change the character EGO's blink view to view 10, and play the animation every 4 seconds.

\it{See Also:} \helprefn{Character.BlinkView}{Character.BlinkView},
\helprefn{Character.SpeechView}{Character.SpeechView}



\subsection{BlinkView property}\label{Character.BlinkView}\index{Character.BlinkView}\index{SetCharacterBlinkView}%

\it{(Formerly part of SetCharacterBlinkView, which is now obsolete)}

\begin{verbatim}
int Character.BlinkView
\end{verbatim}
Gets/sets the character's blinking view. To stop the character from blinking, set
this to -1.

The \helprefn{BlinkInterval}{Character.BlinkInterval} property sets how often the blinking
animation is played.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.BlinkView = 10;
cEgo.BlinkInterval = 160;
\end{verbatim}
will change the character EGO's blink view to view 10, and play the animation every 4 seconds.

\it{See Also:} \helprefn{Character.BlinkInterval}{Character.BlinkInterval},
\helprefn{Character.SpeechView}{Character.SpeechView}


\subsection{BlinkWhileThinking property}\label{Character.BlinkWhileThinking}\index{Character.BlinkWhileThinking}%

\begin{verbatim}
bool Character.BlinkWhileThinking
\end{verbatim}
Gets/sets whether the character can blink while thinking. By default this is set to true,
but if your blinking animation only goes with the talking animation and not the thinking
one, you can stop the character from blinking while Thinking by setting this to false.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.BlinkWhileThinking = false;
\end{verbatim}
will stop EGO from blinking while his thinking animation is playing.

\it{See Also:} \helprefn{Character.BlinkView}{Character.BlinkView},
\helprefn{Character.Think}{Character.Think}


\subsection{BlockingHeight property (character)}\label{Character.BlockingHeight}\index{Character.BlockingHeight}%

\begin{verbatim}
int Character.BlockingHeight
\end{verbatim}
Gets/sets the character's blocking height.

The blocking height determines how large of a blocking rectangle the character exerts to
stop other characters walking through it. If this is set to 0 (the default), then the
blocking rectangle is automatically calculated to be the character's width, and 5 pixels
high.

You can manually change the setting by entering a blocking height in pixels, which is the
size of walkable area that the character effectively removes by standing on it.

\bf{NOTE:} This property has no effect unless the \helprefn{Solid}{Character.Solid} property
is set to \it{true}.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.BlockingHeight = 20;
\end{verbatim}
will make EGO block 20 pixels high (10 above and 10 below his baseline)

\it{See Also:} \helprefn{Character.BlockingWidth}{Character.BlockingWidth},
\helprefn{Character.Solid}{Character.Solid}


\subsection{BlockingWidth property (character)}\label{Character.BlockingWidth}\index{Character.BlockingWidth}%

\begin{verbatim}
int Character.BlockingWidth
\end{verbatim}
Gets/sets the character's blocking width.

The blocking width determines how large of a blocking rectangle the character exerts to
stop other characters walking through it. If this is set to 0 (the default), then the
blocking rectangle is automatically calculated to be the character's width, and 5 pixels
high.

You can manually change the setting by entering a blocking width in pixels, which is the
size of walkable area that the character effectively removes by standing on it.

\bf{NOTE:} This property has no effect unless the \helprefn{Solid}{Character.Solid} property
is set to \it{true}.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.BlockingWidth = 50;
\end{verbatim}
will make EGO block 50 pixels wide (25 pixels to the left of his X co-ordinate, and 25 to the right)

\it{See Also:} \helprefn{Character.BlockingHeight}{Character.BlockingHeight},
\helprefn{Character.Solid}{Character.Solid}


\subsection{Clickable property (character)}\label{Character.Clickable}\index{Character.Clickable}\index{SetCharacterClickable}%

\it{(Formerly known as SetCharacterClickable, which is now obsolete)}

\begin{verbatim}
bool Character.Clickable
\end{verbatim}
Gets/sets whether the character is recognised as something which the
player can interact with. This allows you to modify the "Clickable"
property set initially in the Editor.

If you set this to \it{true} then the player can look at, speak to, and so on
the character (as with the old Sierra games). If you set this to \it{false}, then
if the player clicks on the character it will activate whatever is behind
them (as with the old Lucasarts games).

\fcol{red}{Example:}
\begin{verbatim}
cMan.Clickable = 0;
\end{verbatim}
will make the game ignore clicks on the character MAN.

\it{See Also:} \helprefn{Object.Clickable}{Object.Clickable}


\subsection{DiagonalLoops property}\label{Character.DiagonalLoops}\index{Character.DiagonalLoops}%

\it{(Formerly part of SetCharacterProperty, which is now obsolete)}

\begin{verbatim}
bool Character.DiagonalLoops
\end{verbatim}
Gets/sets whether diagonal walking loops are used for the character. If this is set
to \it{true}, then loops 4-7 will be used as diagonal walking loops. If this is set to
\it{false}, then the character will only face in 4 directions and you can use
loops 4-7 for other purposes.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.DiagonalLoops = true;
\end{verbatim}
will enable diagonal walking loops for character EGO.


\subsection{Frame property (character)}\label{Character.Frame}\index{Character.Frame}%

\it{(Formerly known as character[].frame, which is now obsolete)}

\begin{verbatim}
int Character.Frame
\end{verbatim}
Gets/sets the character's current frame number. Usually you won't change this
directly, but will use the Animate command to play an animation.

\fcol{red}{Example:}
\begin{verbatim}
Display("EGO currently using frame %d.", cEgo.Frame);
\end{verbatim}
displays EGO's current frame number within his view.

\it{SeeAlso:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.Loop}{Character.Loop},
\helprefn{Character.View}{Character.View}


\subsection{HasExplicitTint property}\label{Character.HasExplicitTint}\index{Character.HasExplicitTint}%

\begin{verbatim}
readonly bool Character.HasExplicitTint
\end{verbatim}
Returns \it{true} if the character has a tint set explicitly with the 
\helprefn{Character.Tint}{Character.Tint} command.

Returns \it{false} if the character has no explicit tint, but it may still be
tinted by \helprefn{SetAmbientTint}{SetAmbientTint} or a region tint.

\fcol{red}{Example:}
\begin{verbatim}
if (player.HasExplicitTint)
{
  player.RemoveTint();
}
\end{verbatim}
removes the player's tint if it currently has one.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{SeeAlso:} \helprefn{Character.Tint}{Character.Tint},
\helprefn{Character.RemoveTint}{Character.RemoveTint}


\subsection{ID property (character)}\label{Character.ID}\index{Character.ID}%

\begin{verbatim}
readonly int Character.ID
\end{verbatim}
Gets the character's ID number. This is the character's number from the editor, and is
useful if you need to interoperate with legacy code that uses the character's number
rather than name.

\fcol{red}{Example:}
\begin{verbatim}
MoveCharacter(cEgo.ID, 100, 50);
\end{verbatim}
uses the obsolete MoveCharacter function to move EGO to (100, 50)


\subsection{IdleView property}\label{Character.IdleView}\index{Character.IdleView}%

\begin{verbatim}
readonly int Character.IdleView
\end{verbatim}
Gets the character's current idle view. If the character doesn't have one, returns -1.

This property is read-only; to change the view, use the \helprefn{SetIdleView}{Character.SetIdleView}
function.

\fcol{red}{Example:}
\begin{verbatim}

Display("EGO's idle view is currently view %d.", cEgo.IdleView);
\end{verbatim}
will display EGO's current idle view number.

\it{SeeAlso:} \helprefn{SetIdleView}{Character.SetIdleView}


\subsection{IgnoreLighting property}\label{Character.IgnoreLighting}\index{Character.IgnoreLighting}\index{SetCharacterIgnoreLight}%

\it{(Formerly known as SetCharacterIgnoreLight, which is now obsolete)}

\begin{verbatim}
bool Character.IgnoreLighting
\end{verbatim}
Allows you to dynamically modify the "ignore lighting" checkbox for the
character. If this is set to 0, the character will be affected by region light
levels and tints; if this is set to 1, then the character will ignore all
region lighting.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.IgnoreLighting = 1;
\end{verbatim}
will make the character look the same no matter if he stands on regions with
different light levels.


\subsection{IgnoreWalkbehinds property (character)}\label{Character.IgnoreWalkbehinds}\index{Character.IgnoreWalkbehinds}\index{SetCharacterIgnoreWalkbehinds}%

\it{(Formerly known as SetCharacterIgnoreWalkbehinds, which is now obsolete)}

\begin{verbatim}
bool Character.IgnoreWalkbehinds
\end{verbatim}
Gets/sets whether the character is affected by walkbehind areas. Passing \it{false}
(the default setting) means that the character will be placed behind walk-
behind areas according to the relevant baselines.

Passing \it{true} means that the character will never be placed behind a walk-behind
area. This is useful if for example you want to use the character as an
overlay to display rain or snow onto a scene.

\bf{NOTE:} enabling this property does not currently work properly when using
the Direct3D driver. 

\fcol{red}{Example:}
\begin{verbatim}
cEgo.IgnoreWalkbehinds = true;
\end{verbatim}
will make the character EGO ignore walk-behinds.

\it{See Also:} \helprefn{Character.Baseline}{Character.Baseline},
\helprefn{Object.IgnoreWalkbehinds}{Object.IgnoreWalkbehinds}


\subsection{InventoryQuantity property}\label{Character.InventoryQuantity}\index{Character.InventoryQuantity}%

\it{(Formerly known as character[].inv, which is now obsolete)}

\begin{verbatim}
int Character.InventoryQuantity[]
\end{verbatim}
Gets/sets the quantity of the specified inventory item that the character currently has.
The array index is the inventory item number, from the Inventory pane in the editor.

Usually, you should use the AddInventory and LoseInventory functions to modify the
character's inventory; however, if you need to add or remove a large number of items
in one go, directly changing this array can be an easier method.

If you change this array directly, the on-screen inventory will not be updated. In this
case, you must call UpdateInventory to see any new or removed items.

If you just want to quickly check whether the character has a particular item or
not, use the \helprefn{HasInventory}{Character.HasInventory} function instead.

\fcol{red}{Example:}
\begin{verbatim}
Display("The player has $%d.", player.InventoryQuantity[iCash.ID]);
\end{verbatim}
will display how many inventory items of type iCash the player has.

\it{See Also:} \helprefn{UpdateInventory}{UpdateInventory},
\helprefn{Character.AddInventory}{Character.AddInventory},
\helprefn{Character.HasInventory}{Character.HasInventory},
\helprefn{Character.LoseInventory}{Character.LoseInventory}


\subsection{Loop property (character)}\label{Character.Loop}\index{Character.Loop}%

\it{(Formerly known as character[].loop, which is now obsolete)}

\begin{verbatim}
int Character.Loop
\end{verbatim}
Gets/sets the character's current loop number. Usually you won't change this
directly, but will use the Animate command to play an animation.

\fcol{red}{Example:}
\begin{verbatim}
Display("EGO currently using loop %d.", cEgo.Loop);
\end{verbatim}
displays EGO's current loop number within his view.

\it{SeeAlso:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Character.Frame}{Character.Frame},
\helprefn{Character.View}{Character.View}


\subsection{ManualScaling property (character)}\label{Character.ManualScaling}\index{Character.ManualScaling}\index{Character.IgnoreScaling}\index{IgnoreScaling property (character)}%

\it{(Formerly known as Character.IgnoreScaling, which is now obsolete)} ILBRK
\it{(Formerly part of SetCharacterProperty, which is now obsolete)}

\begin{verbatim}
bool Character.ManualScaling
\end{verbatim}
Gets/sets whether the character's scaling level is determined by the walkable area that
he is walking on, or whether it is set manually by the script. This is equivalent
to the "Ignore room area scaling" checkbox in the editor.

If this is set to \it{true}, then the character's scaling level is set manually by the
\helprefn{Scaling}{Character.Scaling} property (by default this is \verb$100%$).
If it is set to \it{false}, then the character will be stretched or shrunk
automatically as appropriate on walkable areas.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ManualScaling = true;
cEgo.Scaling = 50;
\end{verbatim}
will tell EGO to ignore walkable area scaling levels and be fixed to \verb$50%$ zoom level.

\it{SeeAlso:} \helprefn{Character.Scaling}{Character.Scaling}


\subsection{MovementLinkedToAnimation property}\label{Character.MovementLinkedToAnimation}\index{Character.MovementLinkedToAnimation}%

\begin{verbatim}
bool Character.MovementLinkedToAnimation
\end{verbatim}
Gets/sets whether the character's movement is linked to their animation. By default
this is \it{true}, which means that when the character is walking their movement across
the screen will be kept in sync with their animation frame changing. Without this, the
character can appear to "glide" across the screen.

In some special cases you may wish to turn this off though, and to do so you can set this
property to \it{false}.

In previous versions of AGS, this setting was known as "Anti-glide mode" and was a game-wide
setting.

\fcol{red}{Example:}
\begin{verbatim}
player.MovementLinkedToAnimation = false;
player.Walk(50, 100, eBlock);
player.MovementLinkedToAnimation = true;
\end{verbatim}
will turn off movement-linked animation for the player character, walk him to (50,100),
then turn it back on again.

\it{Compatibility:} Supported by \bf{AGS 3.1.1} and later versions.

\it{See Also:} 
\helprefn{Character.Move}{Character.Move},
\helprefn{Character.Moving}{Character.Moving},
\helprefn{Character.Walk}{Character.Walk}


\subsection{Moving property (character)}\label{Character.Moving}\index{Character.Moving}%

\it{(Formerly known as character[].walking, which is now obsolete)}

\begin{verbatim}
readonly bool Character.Moving
\end{verbatim}
Returns \it{true} if the character is currently moving, or \it{false} if not.

This property is read-only; to change the character's movement, use the \helprefn{Walk}{Character.Walk},
\helprefn{Move}{Character.Move} and \helprefn{StopMoving}{Character.StopMoving} commands.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Walk(125, 40);
while (cEgo.Moving) Wait(1);
\end{verbatim}
will move EGO to 125,40 and return control to the player when he gets there.

\it{See Also:} \helprefn{Character.Animating}{Character.Animating},
\helprefn{Character.Move}{Character.Move},
\helprefn{Character.Speaking}{Character.Speaking},
\helprefn{Character.StopMoving}{Character.StopMoving},
\helprefn{Character.Walk}{Character.Walk}


\subsection{Name property (character)}\label{Character.Name}\index{Character.Name}%

\it{(Formerly known as character[].name, which is now obsolete)}

\begin{verbatim}
String Character.Name
\end{verbatim}
Gets/sets the name of the character, as set in the AGS Editor. This is the full name,
not the script name.

Note that character names are limited to 40 characters, so if you set the name it
will be truncated to that length.

\fcol{red}{Example:}
\begin{verbatim}
Display("You are controlling %s.", player.Name);
\end{verbatim}
will display the name of the player character


\subsection{NormalView property}\label{Character.NormalView}\index{Character.NormalView}%

\it{(Formerly known as character[].defview, which is now obsolete)}

\begin{verbatim}
readonly int Character.NormalView
\end{verbatim}
Gets the character's normal view. This is the character's standard walking view, that
is used when his view is not locked to something else.

This property is read-only; to change it, use the \helprefn{ChangeView}{Character.ChangeView} command.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.View == cEgo.NormalView) {
  Display("EGO is not animating, not talking and not idle.");
}
\end{verbatim}
will display a message if EGO is currently displayed using his normal view.

\it{See Also:} \helprefn{Character.ChangeView}{Character.ChangeView},
\helprefn{Character.View}{Character.View}


\subsection{PreviousRoom property}\label{Character.PreviousRoom}\index{Character.PreviousRoom}%

\it{(Formerly known as character[].prevroom, which is now obsolete)}

\begin{verbatim}
readonly int Character.PreviousRoom
\end{verbatim}
Gets the room number that the character was previously in. If the character is still
in the room that they started in, this will be -1. Otherwise, it will be the room number
of the room that they were last in.

This is a read-only property. It is set automatically by \helprefn{ChangeRoom}{Character.ChangeRoom}.

\fcol{red}{Example:}
\begin{verbatim}
Display("EGO's previous room was %d.", cEgo.PreviousRoom);
\end{verbatim}
will display the EGO character's previous room.


\subsection{Room property}\label{Character.Room}\index{Character.Room}%

\it{(Formerly known as character[].room, which is now obsolete)}

\begin{verbatim}
readonly int Character.Room
\end{verbatim}
Gets the room number that the character is currently in.

This is a read-only property. It is set by \helprefn{ChangeRoom}{Character.ChangeRoom}.

\fcol{red}{Example:}
\begin{verbatim}
Display("EGO is in room %d.", cEgo.Room);
\end{verbatim}
will display the EGO character's current room.


\subsection{ScaleMoveSpeed property}\label{Character.ScaleMoveSpeed}\index{Character.ScaleMoveSpeed}%

\it{(Formerly part of SetCharacterProperty, which is now obsolete)}

\begin{verbatim}
bool Character.ScaleMoveSpeed
\end{verbatim}
Gets/sets whether the character's movement speed is adjusted in line with his
current scaling level. This allows you to modify the "Adjust speed with scaling" option
from the editor.

If you set this to \it{true}, the character's movement speed will be adjusted so that he walks
at a speed relative to his current scaling level. If you set this to \it{false}, the character
will always just move at his normal speed.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ScaleMoveSpeed = true;
\end{verbatim}
will mean that EGO's speed is adjusted in line with his scaling

\it{See Also:} \helprefn{Character.ScaleVolume}{Character.ScaleVolume}


\subsection{ScaleVolume property}\label{Character.ScaleVolume}\index{Character.ScaleVolume}%

\begin{verbatim}
bool Character.ScaleVolume
\end{verbatim}
Gets/sets whether the character's volume is adjusted in line with his
current scaling level. This allows you to modify the "Adjust volume with scaling" option
from the editor.

By default, this is \it{false}. If you set it to \it{true}, then any frame-linked
sounds for the character (for example, footstep sounds) will have their volume
automatically adjusted in line with the character's scaling level. At the normal \verb$100%$
zoom level the sounds will be played at normal volume, but will then get quieter
and louder as appropriate in scaled walkable areas.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ScaleVolume = true;
\end{verbatim}
will mean that EGO's footstep sounds are adjusted in line with his scaling

\it{See Also:} \helprefn{Character.ScaleMoveSpeed}{Character.ScaleMoveSpeed}


\subsection{Scaling property (character)}\label{Character.Scaling}\index{Character.Scaling}%

\begin{verbatim}
int Character.Scaling
\end{verbatim}
Gets/sets the character's current scaling level.

This property can always be read, and returns the character's current zoom level, which
will be between 5 and 200 (the default being 100 if they are not currently scaled).

You can only set the value of this property if \helprefn{ManualScaling}{Character.ManualScaling}
is enabled for the character; otherwise, the scaling is determined automatically based on
the walkable area that the character is on.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ManualScaling = true;
cEgo.Scaling = 50;
\end{verbatim}
will tell EGO to ignore walkable area scaling levels and be fixed to \verb$50%$ zoom level.

\it{SeeAlso:} \helprefn{Character.ManualScaling}{Character.ManualScaling}


\subsection{Solid property (character)}\label{Character.Solid}\index{Character.Solid}%

\it{(Formerly part of SetCharacterProperty, which is now obsolete)}

\begin{verbatim}
bool Character.Solid
\end{verbatim}
Gets/sets whether the character can be walked through by other characters.

If this is set to \it{true}, then the character is solid and will block the path of other
characters. If this is set to \it{false}, then the character acts like a hologram, and other
characters can walk straight through him.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Solid = true;
\end{verbatim}
will mean that EGO blocks the path other characters.

\it{See Also:} \helprefn{Character.BlockingHeight}{Character.BlockingHeight},
\helprefn{Character.BlockingWidth}{Character.BlockingWidth}


\subsection{Speaking property}\label{Character.Speaking}\index{Character.Speaking}%

\begin{verbatim}
readonly bool Character.Speaking
\end{verbatim}
Returns true if the character is currently talking, or false if not.

This property is read-only. It will \bf{only} return true for the active talking character;
that is, it will not return true for any characters talking with the SayBackground command.

Since this property will only be true while the character is speaking, and speaking is
a blocking command, this property will probably only be useful to access from
the repeatedly_execute_always handler.

\fcol{red}{Example:}
\begin{verbatim}
if ((cEgo.Speaking) && (!cEgo.Animating)) {
  cEgo.Animate(3, 5, eRepeat, eNoBlock);
}
\end{verbatim}
will animate the character using loop 3 while they are talking (only useful with Sierra-style speech).

\it{See Also:} \helprefn{Character.Animating}{Character.Animating},
\helprefn{Character.Moving}{Character.Moving},
\helprefn{Character.Say}{Character.Say},
\helprefn{Character.SpeakingFrame}{Character.SpeakingFrame}


\subsection{SpeakingFrame property}\label{Character.SpeakingFrame}\index{Character.SpeakingFrame}%

\begin{verbatim}
readonly int Character.SpeakingFrame
\end{verbatim}
Returns the current frame number of the character's talking animation. This is
useful when using Sierra-style speech, if you want to synchronize events with the
progress of the close-up face talking animation.

This property is read-only. It is only accessible while the character is speaking;
if you attempt to call it when \helprefn{Character.Speaking}{Character.Speaking} is
\it{false} then it will raise an error.

Since speaking is a blocking command, this property will probably only be useful 
access from the repeatedly_execute_always handler.

\fcol{red}{Example:}
\begin{verbatim}
if (cEgo.Speaking) {
  if (cEgo.SpeakingFrame == 0) {
    cMan.Move(cMan.x + 10, cMan.y, eNoBlock, eAnywhere);
  }
}
\end{verbatim}
will move cMan to the right every time the talking animation loops back to Frame 0. 

\it{See Also:} \helprefn{Character.Say}{Character.Say},
\helprefn{Character.Speaking}{Character.Speaking}


\subsection{SpeechAnimationDelay property}\label{Character.SpeechAnimationDelay}\index{Character.SpeechAnimationDelay}%

\begin{verbatim}
int Character.SpeechAnimationDelay;
\end{verbatim}

Gets/sets the character's speech animation delay, as set in the editor. This specifies
how many game loops each frame of the character's speech animation is shown for.

\bf{NOTE:} This property is ignored if lip sync is enabled.

\bf{NOTE:} This property \bf{cannot} be used if the backwards compatibility option
"Old-style game-wide speech animation speed" is enabled in the General Settings. In that
case, the legacy \it{game.talkanim_speed} setting is used instead.

\fcol{red}{Example:}
\begin{verbatim}
player.SpeechAnimationDelay = 4;
\end{verbatim}
will change the player character's speech animation speed to 4.

\it{Compatibility:} Supported by \bf{AGS 3.1.2} and later versions.

\it{See Also:} \helprefn{Character.AnimationSpeed}{Character.AnimationSpeed},
\helprefn{Character.SpeechView}{Character.SpeechView},
\helprefn{Game.TextReadingSpeed}{Game.TextReadingSpeed}


\subsection{SpeechColor property}\label{Character.SpeechColor}\index{Character.SpeechColor}\index{SetTalkingColor}%

\it{(Formerly known as SetTalkingColor, which is now obsolete)}

\begin{verbatim}
int Character.SpeechColor
\end{verbatim}
Gets/sets the character's speech text color. This is set by default in the
editor.

NEWCOLOR is the colour slot index from the Palette Editor. This can be 0-255 for
a 256-colour game, or one of the hi-colour indexes available from the Palette Editor.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.SpeechColor = 14;
\end{verbatim}
will change the character's EGO talking color to yellow.

\it{See Also:} \helprefn{Character.SpeechView}{Character.SpeechView}


\subsection{SpeechView property}\label{Character.SpeechView}\index{Character.SpeechView}\index{SetCharacterSpeechView}%

\it{(Formerly known as SetCharacterSpeechView, which is now obsolete)}ILBRK
\it{(Formerly known as character[].talkview, which is now obsolete)}

\begin{verbatim}
int Character.SpeechView
\end{verbatim}
Gets/sets the character's talking view. If you change it, the new view number will
be used as the character's talking view in all future conversations.

You can set this to -1 to disable the character's speech view.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.SpeechView = 10;
\end{verbatim}
will change the character EGO's speech view to view 10.

\it{See Also:} \helprefn{Character.ChangeView}{Character.ChangeView},
\helprefn{Character.BlinkView}{Character.BlinkView},
\helprefn{Character.SpeechAnimationDelay}{Character.SpeechAnimationDelay},
\helprefn{Character.SpeechColor}{Character.SpeechColor}


\subsection{ThinkView property}\label{Character.ThinkView}\index{Character.ThinkView}%

\it{(Formerly known as character[].thinkview, which is now obsolete)}

\begin{verbatim}
int Character.ThinkView
\end{verbatim}
Gets/sets the character's thinking view. This is used to animate the character
when a thought is being displayed.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.ThinkView = 14;
\end{verbatim}
will change the character EGO's thinking view to 14.

\it{See Also:} \helprefn{Character.Think}{Character.Think}


\subsection{Transparency property (character)}\label{Character.Transparency}\index{Character.Transparency}\index{SetCharacterTransparency}%

\it{(Formerly known as SetCharacterTransparency, which is now obsolete)}

\begin{verbatim}
int Character.Transparency
\end{verbatim}
Gets/sets the character's transparency. This is specified as a percentage, from 0 to 100.
100 means fully transparent (ie. invisible), and 0 is totally opaque (fully visible). Numbers
in between represent varying levels of transparency.

\bf{NOTE:} Transparency only works in 16-bit and 32-bit colour games.

\bf{NOTE:} When using the DirectX 5 driver, a large transparent character can significantly slow
down AGS.

Some rounding is done internally when the transparency is stored -- therefore, if you get
the transparency after setting it, the value you get back might be one out. Therefore, using
a loop with \verb$cEgo.Transparency++;$ is not recommended as it will probably
end too quickly.

In order to fade a character in, the best approach is shown in the example below:

\fcol{red}{Example:}
\begin{verbatim}
int trans = cEgo.Transparency;
while (trans < 100) {
  trans++;
  cEgo.Transparency = trans;
  Wait(1);
}
\end{verbatim}
will gradually fade out the character from its current transparency level to being fully
invisible.

\it{See Also:} \helprefn{Object.Transparency}{Object.Transparency}


\subsection{TurnBeforeWalking property}\label{Character.TurnBeforeWalking}\index{Character.TurnBeforeWalking}%

\it{(Formerly part of SetCharacterProperty, which is now obsolete)}

\begin{verbatim}
bool Character.TurnBeforeWalking
\end{verbatim}
Gets/sets whether the character turns to face his new direction before walking. This
is equivalent (though opposite) to the editor "Do not turn before walking" tick-box.

If you set this to 1, the character will turn on the spot to face his new direction
before setting off on a walk. If you set this to 0, the character will instantly face
in the correct direction and start walking.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.TurnBeforeWalking = 1;
\end{verbatim}
will tell EGO to turn to face his new direction before setting off, whenever he walks.


\subsection{View property (character)}\label{Character.View}\index{Character.View}%

\begin{verbatim}
readonly int Character.View
\end{verbatim}
Gets the view that the character is currently displayed using.

This property is read-only; to change the view, use the ChangeView and LockView functions.

\fcol{red}{Example:}
\begin{verbatim}
Display("EGO's view is currently view %d.", cEgo.View);
\end{verbatim}
will display EGO's current view number.

\it{SeeAlso:} \helprefn{Character.ChangeView}{Character.ChangeView},
\helprefn{Character.Frame}{Character.Frame},
\helprefn{Character.LockView}{Character.LockView},
\helprefn{Character.Loop}{Character.Loop},
\helprefn{Character.NormalView}{Character.NormalView}


\subsection{WalkSpeedX property}\label{Character.WalkSpeedX}\index{Character.WalkSpeedX}%

\begin{verbatim}
readonly int Character.WalkSpeedX;
\end{verbatim}

Gets the character's walking speed in the X direction. If using uniform movement,
this will be the same as the Y walking speed.

This property is read-only. To change the walking speed, use the SetWalkSpeed function.

\fcol{red}{Example:}
\begin{verbatim}
Display("player's x speed: %d", player.WalkSpeedX);
\end{verbatim}
will display the player's X speed.

\it{See Also:} \helprefn{Character.SetWalkSpeed}{Character.SetWalkSpeed},
\helprefn{Character.WalkSpeedY}{Character.WalkSpeedY}


\subsection{WalkSpeedY property}\label{Character.WalkSpeedY}\index{Character.WalkSpeedY}%

\begin{verbatim}
readonly int Character.WalkSpeedY;
\end{verbatim}

Gets the character's walking speed in the Y direction. If using uniform movement,
this will be the same as the X walking speed.

This property is read-only. To change the walking speed, use the SetWalkSpeed function.

\fcol{red}{Example:}
\begin{verbatim}
Display("player's y speed: %d", player.WalkSpeedY);
\end{verbatim}
will display the player's Y speed.

\it{See Also:} \helprefn{Character.SetWalkSpeed}{Character.SetWalkSpeed},
\helprefn{Character.WalkSpeedX}{Character.WalkSpeedX}


\subsection{x property (character)}\label{Character.x}\index{Character.x}%

\begin{verbatim}
int Character.x;
\end{verbatim}

Gets/sets the character's current X co-ordinate. This is expressed in normal room
co-ordinates, and specifies the centre-bottom of the character's sprite.

\bf{NOTE:} Do \bf{NOT} change this property while the character is moving. Make
sure the character is standing still before changing his co-ordinates.

\fcol{red}{Example:}
\begin{verbatim}
Display("The player is at %d,%d.", player.x, player.y);
\end{verbatim}
displays the player character's current coordinates.

\it{See Also:} \helprefn{Character.y}{Character.y},
\helprefn{Character.z}{Character.z}


\subsection{y property (character)}\label{Character.y}\index{Character.y}%

\begin{verbatim}
int Character.y;
\end{verbatim}

Gets/sets the character's current Y co-ordinate. This is expressed in normal room
co-ordinates, and specifies the centre-bottom of the character's sprite.

\bf{NOTE:} Do \bf{NOT} change this property while the character is moving. Make
sure the character is standing still before changing his co-ordinates.

\fcol{red}{Example:}
\begin{verbatim}
Display("The player is at %d,%d.", player.x, player.y);
\end{verbatim}
displays the player character's current coordinates.

\it{See Also:} \helprefn{Character.x}{Character.x},
\helprefn{Character.z}{Character.z}


\subsection{z property (character)}\label{Character.z}\index{Character.z}%

\begin{verbatim}
int Character.z;
\end{verbatim}

Gets/sets the character's current Z position. This allows the character to levitate
off the ground, whilst still retaining its normal Y co-ordinate for baseline calculations
and regions.

Normally this is set to 0 (ground-level), but you can increase it to make the character float.

\fcol{red}{Example:}
\begin{verbatim}
while (player.z < 20) {
  player.z++;
  Wait(1);
}
\end{verbatim}
gradually levitates the character up to 20 pixels.

\it{See Also:} \helprefn{Character.x}{Character.x},
\helprefn{Character.y}{Character.y}


\subsection{SetCharacterProperty}\label{SetCharacterProperty}%

\begin{verbatim}
SetCharacterProperty (CHARID, PROPERTY, int new_value)
\end{verbatim}

\bf{This command is now obsolete. It has been replaced by the following properties:}

\helprefn{Clickable}{Character.Clickable} ILBRK
\helprefn{DiagonalLoops}{Character.DiagonalLoops} ILBRK
\helprefn{IgnoreLighting}{Character.IgnoreLighting} ILBRK
\helprefn{ManualScaling}{Character.ManualScaling} ILBRK
\helprefn{ScaleMoveSpeed}{Character.ScaleMoveSpeed} ILBRK
\helprefn{Solid}{Character.Solid} ILBRK
\helprefn{TurnBeforeWalking}{Character.TurnBeforeWalking}



\section{DateTime functions and properties}%


\subsection{Now property}\label{DateTime.Now}\index{DateTime.Now}\index{GetTime}%

\it{(Formerly known as GetTime, which is now obsolete)}

\begin{verbatim}
readonly static DateTime* DateTime.Now;
\end{verbatim}
Gets the current system time.
You could use this for timing a loop, or for effects like telling the
player to go to bed, and so on.

A \it{DateTime} object is returned, which contains various properties that you can use.

Note that the DateTime object that you get will not be kept up to date with the current time;
it will remain static with the time at which you called DateTime.Now.

\fcol{red}{Example:}
\begin{verbatim}
DateTime *dt = DateTime.Now;
Display("The date is: %02d/%02d/%04d", dt.DayOfMonth, dt.Month, dt.Year);
Display("The time is: %02d:%02d:%02d", dt.Hour, dt.Minute, dt.Second);
\end{verbatim}
will display the current date and time in 24-hour format

\it{See Also:} \helprefn{DateTime.DayOfMonth}{DateTime.DayOfMonth},
\helprefn{DateTime.Hour}{DateTime.Hour},
\helprefn{DateTime.Minute}{DateTime.Minute},
\helprefn{DateTime.Month}{DateTime.Month},
\helprefn{DateTime.RawTime}{DateTime.RawTime},
\helprefn{DateTime.Second}{DateTime.Second},
\helprefn{DateTime.Year}{DateTime.Year}


\subsection{DayOfMonth property}\label{DateTime.DayOfMonth}\index{DateTime.DayOfMonth}%

\begin{verbatim}
readonly int DateTime.DayOfMonth;
\end{verbatim}
Gets the day of the month represented by the DateTime object. This will be from 1 to 31,
representing the current day within the month.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\subsection{Hour property}\label{DateTime.Hour}\index{DateTime.Hour}%

\begin{verbatim}
readonly int DateTime.Hour;
\end{verbatim}
Gets the hour represented by the DateTime object. This will be from 0 to 23,
representing the hour in 24-hour format.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\subsection{Minute property}\label{DateTime.Minute}\index{DateTime.Minute}%

\begin{verbatim}
readonly int DateTime.Minute;
\end{verbatim}
Gets the minute represented by the DateTime object. This will be from 0 to 59,
representing the minute in 24-hour format.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\subsection{Month property}\label{DateTime.Month}\index{DateTime.Month}%

\begin{verbatim}
readonly int DateTime.Month;
\end{verbatim}
Gets the month represented by the DateTime object. This will be from 1 to 12,
representing the month of the year.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\subsection{RawTime property}\label{DateTime.RawTime}\index{DateTime.RawTime}\index{GetRawTime}%

\it{(Formerly known as GetRawTime, which is now obsolete)}

\begin{verbatim}
readonly int DateTime.RawTime;
\end{verbatim}
This function returns the raw system time, as the number of seconds since January 1970.
While this value is not useful in itself, you can use it to calculate time differences
by getting the value at the start of the game, for example, and then getting the value
later on, and the difference between the two is how much time has elapsed.

\bf{NOTE:} Because this accesses the real-time clock on the users' system, it is not
a good idea to use this for long term timing tasks, since if the user saves the game and
then restores it later, the Time value returned by this function will obviously include
the difference when they were not playing.

\fcol{red}{Example:}
\begin{verbatim}
DateTime *dt = DateTime.Now;
int start_time = dt.RawTime;
Wait(120);
dt = DateTime.Now;
Display("After the wait it is now %d seconds later.", dt.RawTime - start_time);
\end{verbatim}
should display that 3 seconds have elapsed.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}, \helprefn{SetTimer}{SetTimer}


\subsection{Second property}\label{DateTime.Second}\index{DateTime.Second}%

\begin{verbatim}
readonly int DateTime.Second;
\end{verbatim}
Gets the second represented by the DateTime object. This will be from 0 to 59,
representing the second.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\subsection{Year property}\label{DateTime.Year}\index{DateTime.Year}%

\begin{verbatim}
readonly int DateTime.Year;
\end{verbatim}
Gets the year represented by the DateTime object. This is the full year,
for example \it{2005}.

\fcol{red}{Example:}
For an example, see \helprefn{DateTime.Now}{DateTime.Now}.

\it{See Also:} \helprefn{DateTime.Now}{DateTime.Now}


\section{Dialog functions and properties}%


\subsection{DisplayOptions (dialog)}\label{Dialog.DisplayOptions}\index{Dialog.DisplayOptions}%

\begin{verbatim}
int Dialog.DisplayOptions(optional DialogOptionSayStyle)
\end{verbatim}
Presents the options for this dialog to the user and waits until they select
one of them. The selected option number is returned.

\bf{NOTE:} This command does not run any dialog scripts, it simply displays
the options and waits for the player to choose one.  To run the dialog normally,
use the \helprefn{Dialog.Start}{Dialog.Start} command instead.

This command is useful if you want to implement your own dialog system, but still
use the standard AGS dialog option selection screens.

The optional \it{DialogOptionSayStyle} parameter determines whether the chosen option
is automatically spoken by the player character. The default is \it{eSayUseOptionSetting},
which will use the option's "Say" setting from the dialog editor. You can alternatively
use \it{eSayAlways}, which will speak the chosen option regardless of its setting
in the editor; or \it{eSayNever}, which will not speak the chosen option.

If the text parser is enabled for this dialog and the player types something into
it rather than selecting an option, the special value \verb$DIALOG_PARSER_SELECTED$
will be returned, and AGS will have automatically called \helprefn{Parser.ParseText}{Parser.ParseText}
with the player's text. Therefore, you can call \helprefn{Parser.Said}{Parser.Said}
to process it.

\fcol{red}{Example:}
\begin{verbatim}
int result = dOldMan.DisplayOptions();
if (result == DIALOG_PARSER_SELECTED)
{
  Display("They typed something into the parser!!");
}
else
{
  Display("They chose dialog option %d.", result);
}
\end{verbatim}
will show the options for dialog \it{dOldMan} and display a message depending
on what the player selected.

\it{Compatibility:} Supported by \bf{AGS 3.0.2} and later versions.

\it{See Also:} \helprefn{Dialog.Start}{Dialog.Start},
\helprefn{Parser.ParseText}{Parser.ParseText}


\subsection{GetOptionState (dialog)}\label{Dialog.GetOptionState}\index{Dialog.GetOptionState}\index{GetDialogOption}%

\it{(Formerly known as global function GetDialogOption, which is now obsolete)}

\begin{verbatim}
Dialog.GetOptionState(int option)
\end{verbatim}
Finds out whether an option in a conversation is available to the player or
not.

OPTION is the option number within the dialog, from 1 to whatever the
highest option is for that topic.

The return value can have the following values:
\begin{verbatim}
eOptionOff
  The option is disabled - the player will not see it
eOptionOn
  The option is enabled - the player can now see and use it
eOptionOffForever
  The option is permanently disabled - no other command can ever turn
  it back on again.
\end{verbatim}
These are the same as the options passed to Dialog.SetOptionState.

\fcol{red}{Example:}
\begin{verbatim}
if (dJoeExcited.GetOptionState(2) != eOptionOn)
  Display("It's turned off");
\end{verbatim}
Will display a message if option 2 of dialog dJoeExcited is not currently switched on.

\it{See Also:} \helprefn{Dialog.HasOptionBeenChosen}{Dialog.HasOptionBeenChosen},
\helprefn{Dialog.SetOptionState}{Dialog.SetOptionState}


\subsection{GetOptionText (dialog)}\label{Dialog.GetOptionText}\index{Dialog.GetOptionText}%

\begin{verbatim}
String Dialog.GetOptionText(int option)
\end{verbatim}
Returns the text for the specified dialog option.

OPTION is the option number within the dialog, from 1 to whatever the
highest option is for that topic.

\fcol{red}{Example:}
\begin{verbatim}
String optionText = dJoeBloggs.GetOptionText(3);
Display("Option 3 of dialog dJoeBloggs is %s!", optionText);
\end{verbatim}
will display the text for the third option of the dJoeBloggs dialog.

\it{Compatibility:} Supported by \bf{AGS 3.0.2} and later versions.

\it{See Also:} \helprefn{Dialog.OptionCount}{Dialog.OptionCount},
\helprefn{Dialog.GetOptionState}{Dialog.GetOptionState}


\subsection{HasOptionBeenChosen}\label{Dialog.HasOptionBeenChosen}\index{Dialog.HasOptionBeenChosen}%

\begin{verbatim}
bool Dialog.HasOptionBeenChosen(int option)
\end{verbatim}
Finds out whether the player has already chosen the specified option in this
dialog. This is mainly useful when drawing your own custom dialog options
display, since it allows you to differentiate options that have already been chosen.

OPTION is the option number within the dialog, from 1 to whatever the
highest option is for that topic.

\fcol{red}{Example:}
\begin{verbatim}
if (dJoeExcited.HasOptionBeenChosen(2))
  Display("The player has chosen option 2 in dialog dJoeExcited!");
\end{verbatim}
will display a message if the player has used option 2 of the dialog before.

\it{Compatibility:} Supported by \bf{AGS 3.1.1} and later versions.

\it{See Also:} \helprefn{Dialog.GetOptionState}{Dialog.GetOptionState}


\subsection{ID property (dialog)}\label{Dialog.ID}\index{Dialog.ID}%

\begin{verbatim}
readonly int Dialog.ID;
\end{verbatim}
Gets the dialog ID number from the editor.

This might be useful if you need to interoperate with legacy scripts
that work with dialog ID numbers.

\fcol{red}{Example:}
\begin{verbatim}
Display("dFisherman is Dialog %d!", dFisherman.ID);
\end{verbatim}
will display the ID number of the dFisherman dialog

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.


\subsection{OptionCount property (dialog)}\label{Dialog.OptionCount}\index{Dialog.OptionCount}%

\begin{verbatim}
readonly int Dialog.OptionCount;
\end{verbatim}
Gets the number of options that this dialog has.

This might be useful in a script module if you want to iterate through all
the possible choices in the dialog.

\fcol{red}{Example:}
\begin{verbatim}
Display("dFisherman has %d options!", dFisherman.OptionCount);
\end{verbatim}
will display the number of options in the dFisherman dialog.

\it{Compatibility:} Supported by \bf{AGS 3.0.2} and later versions.

\it{See Also:} \helprefn{Dialog.GetOptionText}{Dialog.GetOptionText},
\helprefn{Dialog.GetOptionState}{Dialog.GetOptionState}


\subsection{SetOptionState (dialog)}\label{Dialog.SetOptionState}\index{Dialog.SetOptionState}\index{SetDialogOption}%

\it{(Formerly known as global function SetDialogOption, which is now obsolete)}

\begin{verbatim}
Dialog.SetOptionState(int option, DialogOptionState)
\end{verbatim}
Changes whether an option in a conversation is available to the player or
not. This allows you to add extra options to a conversation once the player
has done certain things.

OPTION is the option number within the topic, from 1 to whatever the
highest option is for that topic.

The DialogOptionState controls what happens to this option. It can have the following
values:
\begin{verbatim}
eOptionOff
  The option is disabled - the player will not see it
eOptionOn
  The option is enabled - the player can now see and use it
eOptionOffForever
  The option is permanently disabled - no other command can ever turn
  it back on again.
\end{verbatim}
These are equivalent to the option-off, option-on, and option-off-forever
dialog commands.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGlobalInt(10)==1)
    dialog[4].SetOptionState(2, eOptionOn);
\end{verbatim}
will enable option 2 of topic number 4 if the Global Integer 10 is 1.

\it{See Also:} \helprefn{Dialog.GetOptionState}{Dialog.GetOptionState},
\helprefn{Dialog.Start}{Dialog.Start}, \helprefn{StopDialog}{StopDialog}


\subsection{ShowTextParser property (dialog)}\label{Dialog.ShowTextParser}\index{Dialog.ShowTextParser}%

\begin{verbatim}
readonly bool Dialog.ShowTextParser;
\end{verbatim}
Gets whether this dialog shows a text box allowing the player to type in text.

This property is initially set in the Dialog Editor.

\fcol{red}{Example:}
\begin{verbatim}
if (dFisherman.ShowTextParser) 
{
  Display("dFisherman has a text box!");
}
\end{verbatim}
will display a message if dFisherman has the option enabled

\it{Compatibility:} Supported by \bf{AGS 3.2.1} and later versions.


\subsection{Start (dialog)}\label{Dialog.Start}\index{Dialog.Start}\index{RunDialog}%

\it{(Formerly known as global function RunDialog, which is now obsolete)}

\begin{verbatim}
Dialog.Start()
\end{verbatim}
Starts a conversation from the specified topic.

NOTE: The conversation will not start immediately; instead, it will be run
when the current script function finishes executing.

If you use this command from within the dialog_request function, it will
specify that the game should return to this new topic when the script finishes.

\fcol{red}{Example:}
\begin{verbatim}
dMerchant.Start();
\end{verbatim}
will start the conversation topic named dMerchant.

\it{See Also:} \helprefn{Dialog.DisplayOptions}{Dialog.DisplayOptions},
\helprefn{Dialog.SetOptionState}{Dialog.SetOptionState}


\subsection{StopDialog}\label{StopDialog}%

\begin{verbatim}
StopDialog ()
\end{verbatim}
This command can only be used from within the dialog_request function. It
tells AGS that when dialog_request finishes, the whole conversation should
stop rather than continuing with the dialog script.

You can use this function to end the conversation depending on whether the
player has/does a certain thing.

\fcol{red}{Example:}
\begin{verbatim}
 function dialog_request (int dr) {
 if (dr==1) {
   cEgo.AddInventory(iPoster);
   StopDialog();
 }
\end{verbatim}
will give the player the inventory item 3 and then end the conversation.

\it{See Also:} \helprefn{Dialog.SetOptionState}{Dialog.SetOptionState}



\section{DialogOptionsRenderingInfo functions and properties}\label{DialogOptionsRenderingInfoFunctions}%

The DialogOptionsRenderingInfo instance is used by the \helprefn{custom dialog options}{CustomDialogOptions}
system. You can never create one yourself, it will be passed in to the dialog option functions as
described in the linked page.


\subsection{ActiveOptionID property}\label{DialogOptionsRenderingInfo.ActiveOptionID}\index{DialogOptionsRenderingInfo.ActiveOptionID}%

\begin{verbatim}
int DialogOptionsRenderingInfo.ActiveOptionID;
\end{verbatim}
Gets/sets the currently active option on the dialog options screen. You set this in the
\verb$dialog_options_get_active$ function to tell AGS which option the mouse is hovering over.
This ensures that the correct option is activated when the player clicks the mouse button.

You can read this property in the \verb$dialog_options_render$ function in order to highlight
the selected option in a different manner to the others.

This property can be set to \bf{0} which indicates that no option is selected; otherwise it
will be the option number from 1 to the number of options in the dialog.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_active(DialogOptionsRenderingInfo *info)
{
  info.ActiveOptionID = 1;
}
\end{verbatim}
always selects the first option

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Dialog.GetOptionState}{Dialog.GetOptionState}


\subsection{DialogToRender property}\label{DialogOptionsRenderingInfo.DialogToRender}\index{DialogOptionsRenderingInfo.DialogToRender}%

\begin{verbatim}
Dialog* DialogOptionsRenderingInfo.DialogToRender;
\end{verbatim}
Gets the dialog that needs to be rendered. You can loop through all the options in the dialog
in order to decide what to display on the screen.

\fcol{red}{Example:}
For an example please see the \helprefn{custom dialog options}{CustomDialogOptions} page.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Dialog.GetOptionState}{Dialog.GetOptionState},
\helprefn{DialogOptionsRenderingInfo.Surface}{DialogOptionsRenderingInfo.Surface}


\subsection{Height property (DialogOptionsRenderingInfo)}\label{DialogOptionsRenderingInfo.Height}\index{DialogOptionsRenderingInfo.Height}%

\begin{verbatim}
int DialogOptionsRenderingInfo.Height;
\end{verbatim}
Gets/sets the height of the area needed to draw the dialog options.

This can only be set within the \verb$dialog_options_get_dimensions$ function, but
can be read in other functions in order to render the options.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.Width = 300;
  info.Height = 150;
}
\end{verbatim}
creates a 300x150 size area to draw the dialog options in

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.Width}{DialogOptionsRenderingInfo.Width}


\subsection{ParserTextBoxWidth property}\label{DialogOptionsRenderingInfo.ParserTextBoxWidth}\index{DialogOptionsRenderingInfo.ParserTextBoxWidth}%

\begin{verbatim}
int DialogOptionsRenderingInfo.ParserTextBoxWidth;
\end{verbatim}
Gets/sets the width of the text parser textbox on the dialog options.
If the text parser is not enabled for this dialog, this setting will be ignored.

This can only be set within the \verb$dialog_options_get_dimensions$ function.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.Width = 300;
  info.Height = 150;
  // Put the text parser at the bottom (if enabled)
  info.ParserTextBoxX = 10;
  info.ParserTextBoxY = 130;
  info.ParserTextBoxWidth = 180;
}
\end{verbatim}
positions the parser text box at (10,130) inside the 300x150 dialog options area

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.Width}{DialogOptionsRenderingInfo.Width},
\helprefn{DialogOptionsRenderingInfo.ParserTextBoxX}{DialogOptionsRenderingInfo.ParserTextBoxX},
\helprefn{DialogOptionsRenderingInfo.ParserTextBoxY}{DialogOptionsRenderingInfo.ParserTextBoxY}


\subsection{ParserTextBoxX property}\label{DialogOptionsRenderingInfo.ParserTextBoxX}\index{DialogOptionsRenderingInfo.ParserTextBoxX}%

\begin{verbatim}
int DialogOptionsRenderingInfo.ParserTextBoxX;
\end{verbatim}
Gets/sets the X-position of the text parser textbox on the dialog options.
If the text parser is not enabled for this dialog, this setting will be ignored.

This X-position is relative to the dialog options surface. That is, an X of 10
will position it 10 pixels within the dialog options area, not 10 pixels from
the edge of the screen.

This can only be set within the \verb$dialog_options_get_dimensions$ function.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.Width = 300;
  info.Height = 150;
  // Put the text parser at the bottom (if enabled)
  info.ParserTextBoxX = 10;
  info.ParserTextBoxY = 130;
  info.ParserTextBoxWidth = 180;
}
\end{verbatim}
positions the parser text box at (10,130) inside the 300x150 dialog options area

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.ParserTextBoxWidth}{DialogOptionsRenderingInfo.ParserTextBoxWidth},
\helprefn{DialogOptionsRenderingInfo.ParserTextBoxY}{DialogOptionsRenderingInfo.ParserTextBoxY}


\subsection{ParserTextBoxY property}\label{DialogOptionsRenderingInfo.ParserTextBoxY}\index{DialogOptionsRenderingInfo.ParserTextBoxY}%

\begin{verbatim}
int DialogOptionsRenderingInfo.ParserTextBoxY;
\end{verbatim}
Gets/sets the Y-position of the text parser textbox on the dialog options.
If the text parser is not enabled for this dialog, this setting will be ignored.

This Y-position is relative to the dialog options surface. That is, a Y of 10
will position it 10 pixels within the dialog options area, not 10 pixels from
the edge of the screen.

This can only be set within the \verb$dialog_options_get_dimensions$ function.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.Width = 300;
  info.Height = 150;
  // Put the text parser at the bottom (if enabled)
  info.ParserTextBoxX = 10;
  info.ParserTextBoxY = 130;
  info.ParserTextBoxWidth = 180;
}
\end{verbatim}
positions the parser text box at (10,130) inside the 300x150 dialog options area

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.ParserTextBoxX}{DialogOptionsRenderingInfo.ParserTextBoxX}


\subsection{Surface property (DialogOptionsRenderingInfo)}\label{DialogOptionsRenderingInfo.Surface}\index{DialogOptionsRenderingInfo.Surface}%

\begin{verbatim}
DrawingSurface* DialogOptionsRenderingInfo.Surface;
\end{verbatim}
Gets the drawing surface that can be used to draw the dialog options.

This can only be used within the \verb$dialog_options_render$ function; in all other
functions it will return \it{null}.

Unlike most other uses of the DrawingSurface, you do \bf{NOT} have to release this one.
AGS will automatically do that for you after the \verb$dialog_options_render$ function
has completed.

The size of the surface should correspond to the Width and Height requested in
the \verb$dialog_options_get_dimensions$ function.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_render(DialogOptionsRenderingInfo *info)
{
  info.Surface.Clear(14);
}
\end{verbatim}
clears the dialog options area to yellow.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DrawingSurface functions}{DrawingSurfaceFunctions}


\subsection{Width property (DialogOptionsRenderingInfo)}\label{DialogOptionsRenderingInfo.Width}\index{DialogOptionsRenderingInfo.Width}%

\begin{verbatim}
int DialogOptionsRenderingInfo.Width;
\end{verbatim}
Gets/sets the width of the area needed to draw the dialog options.

This can only be set within the \verb$dialog_options_get_dimensions$ function, but
can be read in other functions in order to render the options.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.Width = 300;
  info.Height = 150;
}
\end{verbatim}
creates a 300x150 size area to draw the dialog options in

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.Height}{DialogOptionsRenderingInfo.Height}


\subsection{X property (DialogOptionsRenderingInfo)}\label{DialogOptionsRenderingInfo.X}\index{DialogOptionsRenderingInfo.X}%

\begin{verbatim}
int DialogOptionsRenderingInfo.X;
\end{verbatim}
Gets/sets the horizontal co-ordinate of the top-left corner of the dialog options area.

This can only be set within the \verb$dialog_options_get_dimensions$ function, but
can be read in other functions in order to render the options.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.X = 50;
  info.Y = 20;
  info.Width = 200;
  info.Height = 150;
}
\end{verbatim}
creates a 200x150 size area at (50, 20) to draw the dialog options in

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.Y}{DialogOptionsRenderingInfo.Y}


\subsection{Y property (DialogOptionsRenderingInfo)}\label{DialogOptionsRenderingInfo.Y}\index{DialogOptionsRenderingInfo.Y}%

\begin{verbatim}
int DialogOptionsRenderingInfo.Y;
\end{verbatim}
Gets/sets the vertical co-ordinate of the top-left corner of the dialog options area.

This can only be set within the \verb$dialog_options_get_dimensions$ function, but
can be read in other functions in order to render the options.

\fcol{red}{Example:}
\begin{verbatim}
function dialog_options_get_dimensions(DialogOptionsRenderingInfo *info)
{
  info.X = 50;
  info.Y = 20;
  info.Width = 200;
  info.Height = 150;
}
\end{verbatim}
creates a 200x150 size area at (50, 20) to draw the dialog options in

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{DialogOptionsRenderingInfo.X}{DialogOptionsRenderingInfo.X}



\section{DrawingSurface functions and properties}\label{DrawingSurfaceFunctions}%

The DrawingSurface family of functions allow you to directly draw onto dynamic sprites
and room backgrounds in the game. You get a drawing surface by calling
\helprefn{DynamicSprite.GetDrawingSurface}{DynamicSprite.GetDrawingSurface} or
\helprefn{Room.GetDrawingSurfaceForBackground}{Room.GetDrawingSurfaceForBackground},
and you can then use the following methods to draw onto the surface.

\bf{IMPORTANT:} You \bf{MUST} call the \helprefn{Release}{DrawingSurface.Release} method
when you have finished drawing onto the surface. This allows AGS to update its cached
copies of the image and upload it to video memory if appropriate.


\subsection{Clear (drawing surface)}\label{DrawingSurface.Clear}\index{DrawingSurface.Clear}\index{RawClearScreen}%

\it{(Formerly known as RawClearScreen, which is now obsolete)}

\begin{verbatim}
DrawingSurface.Clear(optional int colour)
\end{verbatim}
Clears the surface to the specified COLOUR (this is a number you can find in 
the Colours pane of the editor). The current contents of the surface will be lost.

If you do not supply the COLOUR parameter, or use COLOR_TRANSPARENT, the surface
will be cleared to be fully transparent.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.Clear(14);
surface.DrawingColor = 13;
surface.DrawCircle(160,100,50); 
surface.Release();
\end{verbatim}
clears the room background to be fully yellow, then draws a pink circle in the middle of it.

\it{See Also:} \helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor}


\subsection{CreateCopy}\label{DrawingSurface.CreateCopy}\index{DrawingSurface.CreateCopy}\index{RawSaveScreen}%

\it{(Formerly known as RawSaveScreen, which is now obsolete)}

\begin{verbatim}
DrawingSurface* DrawingSurface.CreateCopy()
\end{verbatim}
Makes a backup copy of the current surface, in order that it can be
restored later. This could be useful to back up a background scene before
writing over it, or to save a certain state of your drawing to restore
later. 

Unlike the obsolete RawSaveScreen command in previous versions of AGS, backup
surfaces created with this command are not lost when the player changes room or
restores a game. However, surfaces containing a copy of room backgrounds can
be \bf{very large}, using up a large amount of memory and can increase the
save game sizes significantly. Therefore, it is \bf{strongly recommended} that
you Release any backup copy surfaces as soon as you are done with them.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
DrawingSurface *backup = surface.CreateCopy();
surface.DrawTriangle(0,0,160,100,0,200);
Wait(80);
surface.DrawSurface(backup);
backup.Release();
surface.Release();
\end{verbatim}
will save a copy of the room background, draw a triangle onto it, wait for
a while and then restore the original background.

\it{See Also:} \helprefn{DrawingSurface.DrawSurface}{DrawingSurface.DrawSurface}


\subsection{DrawCircle}\label{DrawingSurface.DrawCircle}\index{DrawingSurface.DrawCircle}\index{RawDrawCircle}%

\it{(Formerly known as RawDrawCircle, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawCircle(int x, int y, int radius)
\end{verbatim}
Draws a filled circle of radius RADIUS with its centre at (X,Y) in the current drawing colour.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawCircle(160,100,50); 
surface.Release();
\end{verbatim}
will draw a circle in the centre of the screen, of 50 pixels radius.

\it{See Also:} \helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine},
\helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor}


\subsection{DrawImage}\label{DrawingSurface.DrawImage}\index{DrawingSurface.DrawImage}\index{RawDrawImage}\index{RawDrawImageResized}\index{RawDrawImageTransparent}%

\it{(Formerly known as RawDrawImage, which is now obsolete)} ILBRK
\it{(Formerly known as RawDrawImageResized, which is now obsolete)} ILBRK
\it{(Formerly known as RawDrawImageTransparent, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawImage(int x, int y, int slot, optional int transparency,
                         optional int width, optional int height)
\end{verbatim}
Draws image SLOT from the sprite manager onto the surface at location (X,Y).

Optionally, you can also specify the transparency of the image. This is a number
from 0-100; using a \it{transparency} of 50 will draw the image semi-transparent;
using 0 means it will not be transparent.

You can also resize the image as you draw it. In order to do this, simply specify
a \it{width} and \it{height} that you wish to resize the image to when it is drawn.

\bf{NOTE:} This command only works if the image to be drawn is the same colour
depth as the surface that you are drawing onto.

\bf{NOTE:} Transparency does not work in 256-colour games, or with 256-colour sprites.

\bf{NOTE:} The X and Y co-ordinates given are ROOM co-ordinates, not SCREEN co-ordinates.
This means that in a scrolling room you can draw outside the current visible area.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, oDoor.Graphic, 40);
surface.Release();
\end{verbatim}
will draw the \it{oDoor} object's graphic onto the room background at (100, 100), at \verb$40%$
transparency.

\it{See Also:} 
\helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine}, 
\helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString},
\helprefn{DrawingSurface.DrawSurface}{DrawingSurface.DrawSurface},
\helprefn{Room.ColorDepth}{Room.ColorDepth}


\subsection{DrawLine}\label{DrawingSurface.DrawLine}\index{DrawingSurface.DrawLine}\index{RawDrawLine}%

\it{(Formerly known as RawDrawLine, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawLine(int from_x, int from_y, int to_x, int to_y,
                        optional int thickness) 
\end{verbatim}
Draws a line from (FROM_X, FROM_Y) to (TO_X, TO_Y) in the surface's current drawing colour.

The \it{thickness} parameter allows you to specify how thick the line is, the default being 1 pixel.

\bf{NOTE:} The X and Y co-ordinates given are ROOM co-ordinates, not SCREEN co-ordinates.
This means that in a scrolling room you can draw outside the current visible area.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 160, 100);
surface.Release();
\end{verbatim}
will draw a line from the left top of the screen (0,0) to the middle of the screen (160,100);

\it{See Also:} \helprefn{DrawingSurface.DrawCircle}{DrawingSurface.DrawCircle}, 
\helprefn{DrawingSurface.DrawRectangle}{DrawingSurface.DrawRectangle},
\helprefn{DrawingSurface.DrawTriangle}{DrawingSurface.DrawTriangle}, 
\helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor}


\subsection{DrawMessageWrapped}\label{DrawingSurface.DrawMessageWrapped}\index{DrawingSurface.DrawMessageWrapped}\index{RawPrintMessageWrapped}%

\it{(Formerly known as RawPrintMessageWrapped, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawMessageWrapped(int x, int y, int width,
                                  FontType font, int message_number)
\end{verbatim}
Draws the room message MESSAGE_NUMBER onto the surface at (x,y), using the
specified FONT.

WIDTH is the width of the virtual textbox enclosing the text, and is the point that
the text will wrap at. This command is designed for writing a long message to the
screen with it wrapping normally like a standard label would do.

The text will be printed using the current drawing colour.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawMessageWrapped(80, 40, 160, Game.NormalFont, 10); 
surface.Release();
\end{verbatim}
will display message 10 in the centre of the screen, starting from Y = 40.

\it{See Also:} \helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString}, 
\helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor},
\helprefn{DrawingSurface.DrawStringWrapped}{DrawingSurface.DrawStringWrapped}


\subsection{DrawPixel}\label{DrawingSurface.DrawPixel}\index{DrawingSurface.DrawPixel}%

\begin{verbatim}
DrawingSurface.DrawPixel(int x, int y) 
\end{verbatim}
Draws a single pixel onto the surface at (X,Y) in the current colour. The pixel
thickness respects the \helprefn{UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates}
property.

\bf{NOTE:} This command is not fast enough to use repeatedly to build up an image. Only
use it for single pixel adjustments.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawPixel(50, 50);
surface.Release();
\end{verbatim}
draws a yellow pixel in the top left of the room background

\it{See Also:} \helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor},
\helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine}, 
\helprefn{DrawingSurface.GetPixel}{DrawingSurface.GetPixel},
\helprefn{DrawingSurface.UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates}


\subsection{DrawRectangle}\label{DrawingSurface.DrawRectangle}\index{DrawingSurface.DrawRectangle}\index{RawDrawRectangle}%

\it{(Formerly known as RawDrawRectangle, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawRectangle(int x1, int y1, int x2, int y2)
\end{verbatim}
Draws a filled rectangle in the current colour with its top-left corner
at (x1,y1) and its bottom right corner at (x2, y2)

\bf{NOTE:} The X and Y co-ordinates given are ROOM co-ordinates, not SCREEN co-ordinates.
This means that in a scrolling room you can draw outside the current visible area.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawRectangle(0, 0, 160, 100);
surface.Release();
\end{verbatim}
will draw a rectangle over the top left hand quarter of the screen.

\it{See Also:} \helprefn{DrawingSurface.DrawImage}{DrawingSurface.DrawImage}, 
\helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine}


\subsection{DrawString}\label{DrawingSurface.DrawString}\index{DrawingSurface.DrawString}\index{RawPrint}%

\it{(Formerly known as RawPrint, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawString(int x, int y, FontType font, string text, ...)
\end{verbatim}
Draws the \it{text} onto the surface at (x, y), using the supplied font number.
The text will be drawn in the current drawing colour.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawString(0, 100, Game.NormalFont, "Text written into the background!");
surface.Release();
\end{verbatim}
will write some text onto the middle-left of the room background

\it{See Also:} \helprefn{GetTextWidth}{GetTextWidth},
\helprefn{DrawingSurface.DrawStringWrapped}{DrawingSurface.DrawStringWrapped},
\helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor}


\subsection{DrawStringWrapped}\label{DrawingSurface.DrawStringWrapped}\index{DrawingSurface.DrawStringWrapped}%

\begin{verbatim}
DrawingSurface.DrawStringWrapped(int x, int y, int width,
                                 FontType font, Alignment,
                                 const string text)
\end{verbatim}
Draws the \it{text} onto the surface at (x,y), using the specified FONT.

\it{width} is the width of the virtual textbox enclosing the text, and is the point
that the text will wrap at. You can use the \it{alignment} parameter to determine
how the text is horizontally aligned.

The text will be printed using the current drawing colour.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawStringWrapped(80, 40, 160, Game.NormalFont, eAlignCentre, "Hello, my name is Bob."); 
surface.Release();
\end{verbatim}
will display the text in the centre of the screen, starting from Y = 40.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString}, 
\helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor},
\helprefn{DrawingSurface.DrawMessageWrapped}{DrawingSurface.DrawMessageWrapped}


\subsection{DrawSurface}\label{DrawingSurface.DrawSurface}\index{DrawingSurface.DrawSurface}\index{RawDrawFrameTransparent}\index{RawRestoreScreen}%

\it{(Formerly known as RawDrawFrameTransparent, which is now obsolete)} ILBRK
\it{(Formerly known as RawRestoreScreen, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawSurface(DrawingSurface *source, optional int transparency)
\end{verbatim}
Draws the specified surface on top of this surface, optionally using \it{transparency}
percent transparency.

This allows you to perform day-to-night fading and other special effects.

\bf{NOTE:} You cannot use the \it{transparency} parameter with 256-colour surfaces.

\bf{NOTE:} This command can be a bit on the slow side, so don't call it from repeatedly_execute.

\bf{TIP:} If you want to gradually fade in a second background, create a copy of
the original surface and then restore it after each iteration, otherwise the backgrounds
will converge too quickly.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *mainBackground = Room.GetDrawingSurfaceForBackground(0);
DrawingSurface *nightBackground = Room.GetDrawingSurfaceForBackground(1);
mainBackground.DrawSurface(nightBackground, 50);
mainBackground.Release();
nightBackground.Release();
\end{verbatim}
this will draw background frame 1 onto frame 0 at 50\verb$%$ opacity.

\it{See Also:} \helprefn{DrawingSurface.DrawImage}{DrawingSurface.DrawImage},
\helprefn{SetAmbientTint}{SetAmbientTint}


\subsection{DrawTriangle}\label{DrawingSurface.DrawTriangle}\index{DrawingSurface.DrawTriangle}\index{RawDrawTriangle}%

\it{(Formerly known as RawDrawTriangle, which is now obsolete)}

\begin{verbatim}
DrawingSurface.DrawTriangle(int x1, int y1, int x2, int y2, int x3, int y3)
\end{verbatim}
Draws a filled triangle in the current colour with corners at the points
(x1,y1), (x2,y2) and (x3,y3).

Well, don't look at me, you might find it useful for something :-)

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawTriangle(0,0,160,100,0,200); 
surface.Release();
\end{verbatim}
will draw a triangle with corners at the points (0,0),(160,100),(0,200).

\it{See Also:} \helprefn{DrawingSurface.DrawImage}{DrawingSurface.DrawImage},
 \helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine},
\helprefn{DrawingSurface.DrawRectangle}{DrawingSurface.DrawRectangle}


\subsection{Release (drawing surface)}\label{DrawingSurface.Release}\index{DrawingSurface.Release}%

\begin{verbatim}
DrawingSurface.Release()
\end{verbatim}
Tells AGS that you have finished drawing onto this surface, and that AGS can now upload
the changed image into video memory.

After calling this method, you can no longer use the DrawingSurface instance. To do
any further drawing, you need to get the surface again.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 50, 50);
surface.Release();
\end{verbatim}
draws a yellow diagonal line across the top-left of the current room background,
then releases the image.

\it{See Also:} \helprefn{DynamicSprite.GetDrawingSurface}{DynamicSprite.GetDrawingSurface},
\helprefn{Room.GetDrawingSurfaceForBackground}{Room.GetDrawingSurfaceForBackground}


\subsection{DrawingColor property}\label{DrawingSurface.DrawingColor}\index{DrawingSurface.DrawingColor}\index{RawSetColor}%

\it{(Formerly known as RawSetColor, which is now obsolete)}

\begin{verbatim}
int DrawingSurface.DrawingColor
\end{verbatim}
Gets/sets the current drawing colour on this surface. Set this before using commands
like \helprefn{DrawLine}{DrawingSurface.DrawLine}, which use this colour for
their drawing.

You can set this either to an AGS Colour Number (as you'd get from the Colours pane
in the editor) or to the special constant COLOR_TRANSPARENT, which allows you
to draw transparent areas onto the surface.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 160, 100);
surface.DrawingColor = Game.GetColorFromRGB(255, 255, 255);
surface.DrawLine(0, 199, 160, 100);
surface.Release();
\end{verbatim}
will draw a yellow line from the left top of the screen (0,0) to the middle of the screen (160,100),
and a white line from the bottom left to the middle.

\it{See Also:} \helprefn{DrawingSurface.DrawCircle}{DrawingSurface.DrawCircle}, 
\helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine},
\helprefn{DrawingSurface.DrawRectangle}{DrawingSurface.DrawRectangle},
\helprefn{Game.GetColorFromRGB}{Game.GetColorFromRGB}


\subsection{GetPixel}\label{DrawingSurface.GetPixel}\index{DrawingSurface.GetPixel}%

\begin{verbatim}
int DrawingSurface.GetPixel(int x, int y) 
\end{verbatim}
Returns the AGS Colour Number of the pixel at (X,Y) on the surface.

\bf{NOTE:} In high-colour games, the first 32 colour numbers have a special meaning
due to an AGS feature which maintains compatibility with 8-bit games. Therefore, if 
you draw onto the surface using a blue colour number 0-31 you will get a different number
when you GetPixel -- and in fact the colour drawn may not be what you expect.
To get around this, add 1 Red or Green component to adjust the colour number out of this range.

\bf{NOTE:} This command is relatively slow. Don't use it to try and process an entire image.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
Display("The colour of the middle pixel is %d.", surface.GetPixel(160, 100));
surface.Release();
\end{verbatim}
displays the pixel colour of the centre pixel on the screen.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor},
\helprefn{DrawingSurface.DrawPixel}{DrawingSurface.DrawPixel}, 
\helprefn{DrawingSurface.UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates}


\subsection{Height property (drawing surface)}\label{DrawingSurface.Height}\index{DrawingSurface.Height}%

\begin{verbatim}
readonly int DrawingSurface.Height
\end{verbatim}
Gets the height of the surface.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
Display("The background is %d x %d!", surface.Width, surface.Height);
surface.Release();
\end{verbatim}
displays the size of the surface to the player

\it{See Also:} \helprefn{DrawingSurface.UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates},
\helprefn{DrawingSurface.Width}{DrawingSurface.Width}


\subsection{UseHighResCoordinates property}\label{DrawingSurface.UseHighResCoordinates}\index{DrawingSurface.UseHighResCoordinates}%

\begin{verbatim}
bool DrawingSurface.UseHighResCoordinates
\end{verbatim}
Gets/sets whether you want to use high-resolution co-ordinates with this surface.

By default, this property will be set such that drawing surface co-ordinates use the same
co-ordinate system as the rest of the game, as per the "Use low-res co-ordinates in script"
game setting. However, if your game is 640x400 or higher you can customize whether
this drawing surface uses native co-ordinates or the low-res 320x200 co-ordinates by
changing this property.

Setting this property affects \bf{ALL} other commands performed on this drawing
surface, including the \helprefn{Width}{DrawingSurface.Width} and \helprefn{Height}{DrawingSurface.Height}
properties.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.UseHighResCoordinates = true;
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 320, 200);
surface.Release();
\end{verbatim}
draws a yellow line from the top left of the screen to the middle of the screen. If we
hadn't set \it{UseHighResCoordinates} to true, this would draw a line from the top left
to the bottom right of the screen.

\it{See Also:} \helprefn{DrawingSurface.DrawCircle}{DrawingSurface.DrawCircle}, \helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine},
\helprefn{DrawingSurface.DrawRectangle}{DrawingSurface.DrawRectangle},
\helprefn{DrawingSurface.DrawTriangle}{DrawingSurface.DrawTriangle}


\subsection{Width property (drawing surface)}\label{DrawingSurface.Width}\index{DrawingSurface.Width}%

\begin{verbatim}
readonly int DrawingSurface.Width
\end{verbatim}
Gets the width of the surface.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
Display("The background is %d x %d!", surface.Width, surface.Height);
surface.Release();
\end{verbatim}
displays the size of the surface to the player

\it{See Also:} \helprefn{DrawingSurface.Height}{DrawingSurface.Height},
\helprefn{DrawingSurface.UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates}



\section{DynamicSprite functions and properties}%



\subsection{Create (dynamic sprite)}\label{DynamicSprite.Create}\index{DynamicSprite.Create}%

\begin{verbatim}
static DynamicSprite* DynamicSprite.Create(int width, int height,
                                           optional bool hasAlphaChannel)
\end{verbatim}
Creates a new blank dynamic sprite of the specified size. It will initially be
fully transparent, and can optionally have an alpha channel. This command is
useful if you just want to create a new sprite and then use the DrawingSurface
commands to draw onto it.

If the game colour depth is lower than 32-bit, then the \it{hasAlphaChannel}
parameter will be ignored.

Use the \helprefn{Graphic}{DynamicSprite.Graphic} property of the DynamicSprite to
interface with other commands and to use the new sprite in the game.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.Create(50, 30);
DrawingSurface *surface = sprite.GetDrawingSurface();
surface.DrawingColor = 14;
surface.DrawPixel(25, 15);
surface.Release();
sprite.Delete();
\end{verbatim}
creates a 50x30 sprite, draws a white dot in the middle, then deletes the sprite.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete},
\helprefn{DynamicSprite.Graphic}{DynamicSprite.Graphic},
\helprefn{DynamicSprite.GetDrawingSurface}{DynamicSprite.GetDrawingSurface}



\subsection{CreateFromBackground}\label{DynamicSprite.CreateFromBackground}\index{DynamicSprite.CreateFromBackground}%

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromBackground
                      (optional int frame, optional int x, optional int y,
                       optional int width, optional int height)
\end{verbatim}
Creates a new dynamic sprite containing a copy of the specified room background.

The most basic use of this function is to supply no parameters, in which case
the sprite will contain an exact copy of the current room background.

If you want, you can supply the \it{frame} only, in which case you will get a
complete copy of that background frame number from the current room.

Optionally, you can specify a portion of the background to grab. You must
either supply all or none of the x, y, width and height parameters; if you
do supply them, this allows you to just get a small portion of the background
image into the new sprite. All co-ordinates are in 320x200-resolution room co-ordinates.

Use the \helprefn{Graphic}{DynamicSprite.Graphic} property of the DynamicSprite to
interface with other commands and to use the new sprite in the game.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromBackground(GetBackgroundFrame(), 130, 70, 60, 60);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(0, 0, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
creates a copy of the centre 60x60 area on the background, and draws it onto the
top left corner of the background image.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}


\subsection{CreateFromDrawingSurface}\label{DynamicSprite.CreateFromDrawingSurface}\index{DynamicSprite.CreateFromDrawingSurface}%

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromDrawingSurface(
                        DrawingSurface* surface, int x, int y,
                        int width, int height)
\end{verbatim}
Creates a new dynamic sprite containing a copy of the specified portion of
the drawing surface. This allows you to easily create new sprites from portions
of other sprites.

\bf{NOTE:} The \it{x}, \it{y}, \it{width} and \it{height} parameters respect
the DrawingSurface's \helprefn{UseHighResCoordinates}{DrawingSurface.UseHighResCoordinates}
setting, so make sure that the type of co-ordinates that you are using match
up with what the drawing surface expects.

Use the \helprefn{Graphic}{DynamicSprite.Graphic} property of the DynamicSprite to
interface with other commands and to use the new sprite in the game.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(object[0].Graphic);
DrawingSurface *surface = sprite.GetDrawingSurface();
DynamicSprite *newSprite = DynamicSprite.CreateFromDrawingSurface(surface, 0, 0, 10, 10);
surface.Release();
sprite.Delete();
object[0].Graphic = newSprite.Graphic;
\end{verbatim}
changes object 0's image to be just the top-left corner of what it previously was.

\it{Compatibility:} Supported by \bf{AGS 3.0.2} and later versions.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}


\subsection{CreateFromExistingSprite}\label{DynamicSprite.CreateFromExistingSprite}\index{DynamicSprite.CreateFromExistingSprite}%

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromExistingSprite(
                        int slot, optional bool preserveAlphaChannel)
\end{verbatim}
Creates a new dynamic sprite containing a copy of the specified sprite \it{slot}.

Returns the DynamicSprite instance representing the new sprite. This function
is useful as it effectively allows you to apply transformations such as resizing to
any sprite in the game.

Use the \helprefn{Graphic}{DynamicSprite.Graphic} property of the DynamicSprite to
interface with other commands and to use the new sprite in the game.

\it{preserveAlphaChannel} determines whether the sprite's alpha channel will also
be copied across. It is false by default for backwards compatibility reasons, and
is useful because it allows you to strip the alpha channel in order to do whole image
transparency. This parameter has no effect with sprites that do not have an alpha
channel.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(object[0].Graphic);
sprite.Resize(20, 20);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 80, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
creates a copy of object 0's current sprite, resizes it down to 20x20, and then draws
the result onto the background.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}, 
\helprefn{DynamicSprite.Resize}{DynamicSprite.Resize}


\subsection{CreateFromFile}\label{DynamicSprite.CreateFromFile}\index{DynamicSprite.CreateFromFile}\index{LoadImageFile}%

\it{(Formerly known as LoadImageFile, which is now obsolete)}

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromFile(string filename)
\end{verbatim}
Loads an external image FILENAME into memory as a sprite.

Returns the DynamicSprite instance representing the sprite, or \it{null} if the image
could not be loaded (file not found or unsupported format).

Only BMP and PCX files can be loaded with this command.

Use the \helprefn{Graphic}{DynamicSprite.Graphic} property of the DynamicSprite to
interface with other commands and to use the new sprite in the game.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
if (sprite != null) {
  DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
  surface.DrawImage(100, 80, sprite.Graphic);
  surface.Release();
  sprite.Delete();
}
\end{verbatim}
will load the file "CustomAvatar.bmp" and if successful draw the image near the middle
of the screen.

Once the image is finished with, Delete should be called on it.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}, 
\helprefn{DynamicSprite.CreateFromSaveGame}{DynamicSprite.CreateFromSaveGame}


\subsection{CreateFromSaveGame}\label{DynamicSprite.CreateFromSaveGame}\index{DynamicSprite.CreateFromSaveGame}\index{LoadSaveSlotScreenshot}%

\it{(Formerly known as LoadSaveSlotScreenshot, which is now obsolete)}

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromSaveGame
                        (int saveSlot, int width, int height)
\end{verbatim}
Loads the screenshot for save game SAVESLOT into memory, resizing it to WIDTH x HEIGHT.

Returns the DynamicSprite instance of the image if successful, or returns \it{null} if
the screenshot could not be loaded (perhaps the save game didn't include one).

In order for this to work, the "Save screenshots in save games" option must be ticked
in the main Game Settings pane.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
// at top of script, outside event functions
DynamicSprite *buttonSprite;  

// inside an event function
buttonSprite = DynamicSprite.CreateFromSaveGame(1, 50, 50);
if (buttonSprite != null) {
  btnScrnshot.NormalGraphic = buttonSprite.Graphic;
}
\end{verbatim}
will load the screenshot for save game 1 and resize it to 50x50. It then places it onto
the btnScrnshot GUI button.

Once the GUI is disposed of, Delete should be called on the sprite.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}, 
\helprefn{Game.GetSaveSlotDescription}{Game.GetSaveSlotDescription},
\helprefn{DynamicSprite.CreateFromFile}{DynamicSprite.CreateFromFile},
\helprefn{DynamicSprite.CreateFromScreenShot}{DynamicSprite.CreateFromScreenShot}


\subsection{CreateFromScreenShot}\label{DynamicSprite.CreateFromScreenShot}\index{DynamicSprite.CreateFromScreenShot}%

\begin{verbatim}
static DynamicSprite* DynamicSprite.CreateFromScreenShot
                        (optional int width, optional int height)
\end{verbatim}
Creates a new DynamicSprite instance with a copy of the current screen in it,
resized to WIDTH x HEIGHT. If you do not supply the width or height, then a full screen
sized sprite will be created.

This command can be useful if you're creating a save game screenshots GUI, in order to
display the current game position as well as the saved slot positions.

\bf{NOTE:} This command can be slow when using the Direct3D graphics driver.

\bf{IMPORTANT:} This command loads an extra sprite into memory which is not controlled
by the normal AGS sprite cache and will not be automatically disposed of. Therefore, when
you are finished with the image you \bf{MUST} call Delete on it to free its memory.

\bf{IMPORTANT:} If the DynamicSprite instance is released from memory (ie. there is
no longer a DynamicSprite* variable pointing to it), then the sprite will also be
removed from memory. Make sure that you keep a global variable pointer to the sprite
until you are finished with it, and at that point call Delete.

\fcol{red}{Example:}
\begin{verbatim}
// at top of script, outside event functions
DynamicSprite *buttonSprite;  

// inside an event function
buttonSprite = DynamicSprite.CreateFromScreenShot(80, 50);
if (buttonSprite != null) {
  btnScrnshot.NormalGraphic = buttonSprite.Graphic;
}
\end{verbatim}
places a screen grab of the current game session onto btnScrnshot.

Once the GUI is disposed of, Delete should be called on the sprite.

\it{See Also:} \helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}, 
\helprefn{Game.GetSaveSlotDescription}{Game.GetSaveSlotDescription},
\helprefn{DynamicSprite.CreateFromFile}{DynamicSprite.CreateFromFile},
\helprefn{DynamicSprite.CreateFromSaveGame}{DynamicSprite.CreateFromSaveGame}


\subsection{ChangeCanvasSize}\label{DynamicSprite.ChangeCanvasSize}\index{DynamicSprite.ChangeCanvasSize}%

\begin{verbatim}
DynamicSprite.ChangeCanvasSize(int width, int height, int x, int y);
\end{verbatim}
Changes the sprite size to \it{width} x \it{height}, placing the current image
at offset (x, y) within the new canvas. Unlike the \helprefn{Resize}{DynamicSprite.Resize}
command, the current image is kept at its original size.

This function allows you to enlarge the sprite background in order to draw
more onto it than its current boundaries allow. It is effectively the
opposite of \helprefn{Crop}{DynamicSprite.Crop}. The additional surface area
will be transparent.

The width and height are specified in 320x200-resolution units.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(10);
sprite.ChangeCanvasSize(sprite.Width + 10, sprite.Height, 5, 0);
DrawingSurface *surface = sprite.GetDrawingSurface();
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 5, surface.Height);
surface.Release();
sprite.Delete();
\end{verbatim}
creates a dynamic sprite as a copy of sprite 10, enlarges it by 5 pixels to the
left and right, and draws a line in the new area to the left.

\it{See Also:} \helprefn{DynamicSprite.Crop}{DynamicSprite.Crop},
\helprefn{DynamicSprite.Resize}{DynamicSprite.Resize},
\helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{CopyTransparencyMask}\label{DynamicSprite.CopyTransparencyMask}\index{DynamicSprite.CopyTransparencyMask}%

\begin{verbatim}
DynamicSprite.CopyTransparencyMask(int fromSpriteSlot)
\end{verbatim}
Copies the transparency mask from the specified sprite slot onto the dynamic sprite.
The dynamic sprite's transparency and/or alpha channel will be replaced with the
one from the other sprite.

This command is designed for special effects. It is fairly slow since it involves
inspecting each pixel of the image, so it's not recommended that you use it often.

The source sprite must be the same size and colour depth as the dynamic sprite.

\bf{NOTE:} This command makes all pixels that are transparent in the source sprite
also transparent in the dynamic sprite. It does not make opaque pixels from the
source sprite into opaque pixels on the dynamic sprite (because it wouldn't know
what colour to make them).

If the source image has an alpha channel, then the dynamic sprite will have an
alpha channel created as a copy of the one from the source sprite.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(10);
sprite.CopyTransparencyMask(11);
object[0].Graphic = sprite.Graphic;
Wait(80);
sprite.Delete();
\end{verbatim}
creates a dynamic sprite as a copy of sprite 10, changes its transparency mask
to use that of sprite 11, and displays it on object 0.

\it{See Also:} \helprefn{DynamicSprite.CreateFromExistingSprite}{DynamicSprite.CreateFromExistingSprite}


\subsection{Crop (dynamic sprite)}\label{DynamicSprite.Crop}\index{DynamicSprite.Crop}%

\begin{verbatim}
DynamicSprite.Crop(int x, int y, int width, int height);
\end{verbatim}
Crops the sprite down to \it{width} x \it{height}, starting from (x,y) in the image.
The width and height are specified in 320x200-resolution units, as usual.

This allows you to trim the edges off a sprite, and perform related tasks. Only the area
with its top-left corner as (x,y) and of WIDTH x HEIGHT in size will remain.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
sprite.Crop(10, 10, sprite.Width - 10, sprite.Height - 10);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
will load the CustomAvatar.bmp image, cut off the left and top 10 pixels, and then
draw it onto the room background at (100,100).

\it{See Also:} \helprefn{DynamicSprite.ChangeCanvasSize}{DynamicSprite.ChangeCanvasSize},
\helprefn{DynamicSprite.Flip}{DynamicSprite.Flip},
\helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{Delete (dynamic sprite)}\label{DynamicSprite.Delete}\index{DynamicSprite.Delete}\index{DeleteSprite}%

\it{(Formerly known as DeleteSprite, which is now obsolete)}

\begin{verbatim}
DynamicSprite.Delete();
\end{verbatim}
Deletes the specified dynamic sprite from memory. Use this when you are no longer displaying
the sprite and it can be safely disposed of.

You do not normally need to delete sprites, since the AGS Sprite Cache manages loading
and deleting sprites automatically.

However, when an extra sprite has been loaded into the game (for example, with the
CreateFromFile or CreateFromScreenShot commands) then AGS does not delete it automatically,
and you must call this command instead.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
object[1].Graphic = sprite.Graphic;
Wait(200);
object[1].Graphic = 22;
sprite.Delete();
\end{verbatim}
will load the file "CustomAvatar.bmp", change Object 1 to display this graphic, wait 5
seconds, then change object 1 back to its old sprite 22 and free the new image.

\it{See Also:} \helprefn{DynamicSprite.CreateFromScreenShot}{DynamicSprite.CreateFromScreenShot},
\helprefn{DynamicSprite.Graphic}{DynamicSprite.Graphic}


\subsection{Flip (dynamic sprite)}\label{DynamicSprite.Flip}\index{DynamicSprite.Flip}%

\begin{verbatim}
DynamicSprite.Flip(eFlipDirection);
\end{verbatim}
Flips the dynamic sprite according to the parameter:

\it{eFlipLeftToRight} flips the image from left to right ILBRK
\it{eFlipUpsideDown} flips the image from top to bottom ILBRK
\it{eFlipBoth} flips the image from top to bottom and left to right

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
sprite.Flip(eFlipUpsideDown);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
will load the CustomAvatar.bmp image, flip it upside down, and then
draw it onto the room background at (100,100).

\it{See Also:} \helprefn{DynamicSprite.Crop}{DynamicSprite.Crop},
\helprefn{DynamicSprite.Resize}{DynamicSprite.Resize},
\helprefn{DynamicSprite.Rotate}{DynamicSprite.Rotate}


\subsection{GetDrawingSurface (dynamic sprite)}\label{DynamicSprite.GetDrawingSurface}\index{DynamicSprite.GetDrawingSurface}%

\begin{verbatim}
DrawingSurface* DynamicSprite.GetDrawingSurface();
\end{verbatim}
Gets the drawing surface for this dynamic sprite, which allows you to modify the sprite by
drawing onto it in various ways.

After calling this method, use the various \helprefn{DrawingSurface functions}{DrawingSurfaceFunctions} to modify the
sprite, then call Release on the surface when you are finished.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite *sprite = DynamicSprite.CreateFromExistingSprite(object[0].Graphic);
DrawingSurface *surface = sprite.GetDrawingSurface();
surface.DrawingColor = 13;
surface.DrawLine(0, 0, 20, 20);
surface.Release();
object[0].Graphic = sprite.Graphic;
Wait(40);
sprite.Delete();
\end{verbatim}
this creates a dynamic sprite as a copy of Object 0's existing sprite, draws 
a pink diagonal line across it, sets this new sprite onto the object for 1 second
and then removes it.

\it{See Also:} \helprefn{DynamicSprite.CreateFromExistingSprite}{DynamicSprite.CreateFromExistingSprite},
\helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine}, 
\helprefn{DrawingSurface.Release}{DrawingSurface.Release}


\subsection{Resize (dynamic sprite)}\label{DynamicSprite.Resize}\index{DynamicSprite.Resize}%

\begin{verbatim}
DynamicSprite.Resize(int width, int height);
\end{verbatim}
Resizes an existing dynamic sprite to WIDTH x HEIGHT pixels.

The width and height are specified in 320x200-resolution units, as usual.

\bf{NOTE:} Resizing is a relatively slow operation, so do not attempt to resize sprites
every game loop; only do it when necessary.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
sprite.Resize(sprite.Width * 2, sprite.Height * 2);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
will load the CustomAvatar.bmp image, stretch it to double its original size, and then
draw it onto the room background at (100,100).

\it{See Also:} \helprefn{DynamicSprite.ChangeCanvasSize}{DynamicSprite.ChangeCanvasSize},
\helprefn{DynamicSprite.Crop}{DynamicSprite.Crop},
\helprefn{DynamicSprite.Flip}{DynamicSprite.Flip},
\helprefn{DynamicSprite.Rotate}{DynamicSprite.Rotate},
\helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{Rotate (dynamic sprite)}\label{DynamicSprite.Rotate}\index{DynamicSprite.Rotate}%

\begin{verbatim}
DynamicSprite.Rotate(int angle, optional int width, optional int height)
\end{verbatim}
Rotates the dynamic sprite by the specified \it{angle}. The angle is in degrees,
and must lie between 1 and 359. The image will be rotated clockwise by the specified angle.

Optionally, you can specify the width and height of the rotated image. By default, AGS
will automatically calculate the new size required to hold the rotated image, but
you can override this by passing the parameters in.

Note that specifying a width/height does not stretch the image, it just allows you
to set the image dimensions to crop the rotation.

\bf{NOTE:} Rotating is a relatively slow operation, so do not attempt to rotate sprites
every game loop; only do it when necessary.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
sprite.Rotate(90);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
will load the CustomAvatar.bmp image, rotate it 90 degrees clockwise, draw the result
onto the screen, and then delete the image.

\it{See Also:} \helprefn{DynamicSprite.Flip}{DynamicSprite.Flip},
\helprefn{DynamicSprite.Resize}{DynamicSprite.Resize},
\helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{SaveToFile (dynamic sprite)}\label{DynamicSprite.SaveToFile}\index{DynamicSprite.SaveToFile}%

\begin{verbatim}
DynamicSprite.SaveToFile(string filename)
\end{verbatim}
Saves the dynamic sprite to the specified file.

The filename you supply must have a .PCX or .BMP extension; they are the only
two file types that the engine supports.

Returns 1 if the sprite was saved successfully, or 0 if it failed.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
sprite.Rotate(90);
sprite.SaveToFile("RotatedAvatar.bmp");
sprite.Delete();
\end{verbatim}
will load the CustomAvatar.bmp image, rotate it 90 degrees clockwise, then
save the result back to the disk.

\it{See Also:} \helprefn{DynamicSprite.CreateFromFile}{DynamicSprite.CreateFromFile},
\helprefn{SaveScreenShot}{SaveScreenShot}


\subsection{Tint (dynamic sprite)}\label{DynamicSprite.Tint}\index{DynamicSprite.Tint}%

\begin{verbatim}
DynamicSprite.Tint(int red, int green, int blue, int saturation, int luminance)
\end{verbatim}
Tints the dynamic sprite to (RED, GREEN, BLUE) with SATURATION percent
saturation. For the meaning of all the parameters, see \helprefn{SetAmbientTint}{SetAmbientTint}.

The tint set by this function is permanent for the dynamic sprite -- after the tint
has been set, it is not possible to remove it. If you call Tint again with different
parameters, it will apply the new tint to the already tinted sprite from the first call.

\bf{NOTE:} This function only works with hi-colour sprites.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromExistingSprite(object[0].Graphic);
sprite.Tint(255, 0, 0, 100, 100);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 80, sprite.Graphic);
surface.Release();
sprite.Delete();
\end{verbatim}
creates a copy of object 0's sprite, tints it red, and draws it onto the room background.

\it{See Also:} \helprefn{DynamicSprite.Flip}{DynamicSprite.Flip},
\helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width},
\helprefn{SetAmbientTint}{SetAmbientTint}


\subsection{ColorDepth property (dynamic sprite)}\label{DynamicSprite.ColorDepth}\index{DynamicSprite.ColorDepth}%

\begin{verbatim}
readonly int DynamicSprite.ColorDepth;
\end{verbatim}
Gets the colour depth of this dynamic sprite. This can be 8, 16 or 32 and is not necessarily the same
as the game colour depth (though this usually will be the case).

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
if (sprite != null) {
  Display("The image is %d x %d pixels, at %d-bit depth.", sprite.Width, sprite.Height, sprite.ColorDepth);
  sprite.Delete();
}
\end{verbatim}
displays the colour depth of the CustomAvatar.bmp image.

\it{See Also:} \helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{Graphic property (dynamic sprite)}\label{DynamicSprite.Graphic}\index{DynamicSprite.Graphic}%

\begin{verbatim}
readonly int DynamicSprite.Graphic;
\end{verbatim}
Gets the sprite slot number in which this dynamic sprite is stored.
This value can then be passed to other functions and properties, such as
\helprefn{Button.NormalGraphic}{Button.NormalGraphic}.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* ds = DynamicSprite.CreateFromScreenShot(50, 50);
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawImage(100, 100, ds.Graphic);
surface.Release();
ds.Delete();
\end{verbatim}
takes a screen shot, and draws it onto the background scene at (100,100).

\it{See Also:} \helprefn{DynamicSprite.CreateFromScreenShot}{DynamicSprite.CreateFromScreenShot},
\helprefn{DynamicSprite.Delete}{DynamicSprite.Delete}


\subsection{Height property (dynamic sprite)}\label{DynamicSprite.Height}\index{DynamicSprite.Height}%

\begin{verbatim}
readonly int DynamicSprite.Height;
\end{verbatim}
Gets the height of this dynamic sprite. The height is always returned in 320x200-resolution units.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
if (sprite != null) {
  Display("The image is %d x %d pixels.", sprite.Width, sprite.Height);
  sprite.Delete();
}
\end{verbatim}
displays the size of the CustomAvatar.bmp image.

\it{See Also:} \helprefn{DynamicSprite.Resize}{DynamicSprite.Resize},
\helprefn{DynamicSprite.Width}{DynamicSprite.Width}


\subsection{Width property (dynamic sprite)}\label{DynamicSprite.Width}\index{DynamicSprite.Width}%

\begin{verbatim}
readonly int DynamicSprite.Width;
\end{verbatim}
Gets the width of this dynamic sprite. The width is always returned in 320x200-resolution units.

\fcol{red}{Example:}
\begin{verbatim}
DynamicSprite* sprite = DynamicSprite.CreateFromFile("CustomAvatar.bmp");
if (sprite != null) {
  Display("The image is %d x %d pixels.", sprite.Width, sprite.Height);
  sprite.Delete();
}
\end{verbatim}
displays the size of the CustomAvatar.bmp image.

\it{See Also:} \helprefn{DynamicSprite.Height}{DynamicSprite.Height},
\helprefn{DynamicSprite.Resize}{DynamicSprite.Resize}



\section{File functions and properties}%


\subsection{Open}\label{File.Open}\index{File.Open}\index{FileOpen}%

\it{(Formerly known as FileOpen, which is now obsolete)}

\begin{verbatim}
static File* File.Open(string filename, FileMode)
\end{verbatim}
Opens a disk file for reading or writing. These disk I/O functions are only
intended for simple tasks like the way the QFG series export the character
when you complete it.

MODE is either eFileRead, eFileWrite or eFileAppend, depending on
whether you want to write to or read from the file. If you pass eFileWrite
and a file called FILENAME already exists, it will be overwritten.

eFileAppend opens an existing file for writing and starts adding information at
the end (ie. the existing contents are not deleted).

This function returns a File object, which you use to perform operations on the
file. \it{null} is returned if there was a problem (eg. file not existing when MODE
is eFileRead).

\bf{NOTE:} You \bf{MUST} close the file with the Close function when you have finished
using it. There are only a limited number of file handles, and forgetting to
close the file can lead to problems later on.

\bf{IMPORTANT}: If you open the file for writing, then you can ONLY work with
files in the game directory.
You CANNOT use a path, so any filename with "\verb$\$" or "\verb$/$" in it will
automatically be rejected, for security reasons.

The only exceptions to this rule are the special tags: ILBRK
\verb^$SAVEGAMEDIR$^, which allows you to access files in the save game directory. ILBRK
\verb^$APPDATADIR$^, which allows you to write/read files to a folder on the system which
is accessible by and shared by all users

\bf{IMPORTANT}: On Windows Vista, if your game is installed to Program Files then
it may not be able to write files into the game's installation directory. To be sure
that your game won't have problems, \bf{always} write files to the Save Game Folder
or the App Data Folder using the special tags. An example is below.

\bf{NOTE:} Open file pointers are not persisted across save games. That is, if you open
a file, then save the game; then when you restore the game, the File will not be usable
and you'll have to open it again to continue any I/O. The safest practice is not to
declare any global File variables.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("$SAVEGAMEDIR$/temp.tmp", eFileWrite);
if (output == null)
  Display("Error opening file.");
else {
  output.WriteString("test string");
  output.Close();
}
\end{verbatim}
will open the file temp.tmp in the save game folder for writing. An error message is
displayed if the file could not be created. Otherwise, it will write the string "test string"
to the file and close it.

\it{See Also:} \helprefn{File.Close}{File.Close}, \helprefn{File.Exists}{File.Exists},
\helprefn{File.ReadStringBack}{File.ReadStringBack}, \helprefn{File.WriteString}{File.WriteString}



\subsection{Close}\label{File.Close}\index{File.Close}\index{FileClose}%

\it{(Formerly known as FileClose, which is now obsolete)}

\begin{verbatim}
File.Close()
\end{verbatim}
Closes the file, and commits all changes to disk.
You \bf{must} call this function when you have finished reading/writing the file.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("test.dat", eFileWrite);
output.WriteString("test string");
output.Close();
\end{verbatim}
will open the file test.dat, write the string "test string", and close it.

\it{See Also:} \helprefn{File.Open}{File.Open}


\subsection{Delete (file)}\label{File.Delete}\index{File.Delete}%

\begin{verbatim}
static File.Delete(string filename)
\end{verbatim}
Deletes the specified file from the disk.

This command only works with files in the game directory.
You CANNOT use a path, so any filename with "\verb$\$" or "\verb$/$" in it will
automatically be rejected, for security reasons.

The only exception to this rule is the special tag \verb^$SAVEGAMEDIR$^, which allows
you to access files in the save game directory. This is especially important with
the move to Windows Vista, in which you may not have access to the main game folder.

\bf{NOTE:} This is a static function, therefore you don't need an open File pointer
to use it. See the example below.

\fcol{red}{Example:}
\begin{verbatim}
File.Delete("temp.tmp");
\end{verbatim}
will delete the file "temp.tmp" from the game directory, if it exists.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{File.Exists}{File.Exists}, \helprefn{File.Open}{File.Open}


\subsection{Exists}\label{File.Exists}\index{File.Exists}%

\begin{verbatim}
static bool File.Exists(string filename)
\end{verbatim}
Checks if the specified file exists on the file system.

This command supports the special tag \verb^$SAVEGAMEDIR$^, which allows
you to access files in the save game directory. This is especially important with
the move to Windows Vista, in which you may not have access to the main game folder.

\bf{NOTE:} This is a static function, therefore you don't need an open File pointer
to use it. See the example below.

\fcol{red}{Example:}
\begin{verbatim}
if (!File.Exists("temp.tmp"))
{
  File *output = File.Open("temp.tmp", eFileWrite);
  output.WriteString("some text");
  output.Close();
}
\end{verbatim}
will create the file "temp.tmp" if it doesn't exist

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{File.Delete}{File.Delete}, \helprefn{File.Open}{File.Open}


\subsection{ReadInt}\label{File.ReadInt}\index{File.ReadInt}\index{FileReadInt}%

\it{(Formerly known as FileReadInt, which is now obsolete)}

\begin{verbatim}
File.ReadInt()
\end{verbatim}
Reads an integer from the file, and returns it to the script.
Only integers written with File.WriteInt can be read back.

\fcol{red}{Example:}
\begin{verbatim}
int number;
File *input = File.Open("stats.dat", eFileRead);
number = input.ReadInt();
input.Close();
\end{verbatim}
will open the file stats.dat, read an integer into number and then close the file.

\it{See Also:} \helprefn{File.ReadStringBack}{File.ReadStringBack}, \helprefn{File.WriteInt}{File.WriteInt}


\subsection{ReadRawChar}\label{File.ReadRawChar}\index{File.ReadRawChar}\index{FileReadRawChar}%

\it{(Formerly known as FileReadRawChar, which is now obsolete)}

\begin{verbatim}
File.ReadRawChar()
\end{verbatim}
Reads a raw character from the input file and returns it. This function
allows you to read from files that weren't created by your game,
however it is recommended for expert users only.

\fcol{red}{Example:}
\begin{verbatim}
File *input = File.Open("stats.txt", eFileRead);
String buffer = String.Format("%c", input.ReadRawChar());
input.Close();
\end{verbatim}
will read a raw character from file stats.txt and writes it to the string 'buffer'.

\it{See Also:} \helprefn{File.ReadStringBack}{File.ReadStringBack}, \helprefn{File.ReadRawInt}{File.ReadRawInt},
\helprefn{File.WriteRawChar}{File.WriteRawChar}


\subsection{ReadRawInt}\label{File.ReadRawInt}\index{File.ReadRawInt}\index{FileReadRawInt}%

\it{(Formerly known as FileReadRawInt, which is now obsolete)}

\begin{verbatim}
File.ReadRawInt()
\end{verbatim}
Reads a raw 32-bit integer from the input file and returns it to the script.
This allows you to read from files created by other programs - however, it
should only be used by experts as no error-checking is performed.

\fcol{red}{Example:}
\begin{verbatim}
int number;
File *input = File.Open("stats.txt", eFileRead);
number = input.ReadRawInt();
input.Close();
\end{verbatim}
will read a raw integer from file stats.txt and put it into the integer number.

\it{See Also:} \helprefn{File.ReadStringBack}{File.ReadStringBack}, \helprefn{File.ReadRawChar}{File.ReadRawChar}


\subsection{ReadRawLineBack}\label{File.ReadRawLineBack}\index{File.ReadRawLineBack}\index{File.ReadRawLine}%

\it{(Formerly known as File.ReadRawLine, which is now obsolete)}

\begin{verbatim}
String File.ReadRawLineBack()
\end{verbatim}
Reads a line of text back in from the file and returns it. This enables you to 
read in lines from text files and use them in your game.

\bf{NOTE:} this command can only read back plain text lines from text files. If you 
attempt to use it with binary files or files written with commands like WriteString,
WriteInt, etc then the results are unpredictable.

\fcol{red}{Example:}
\begin{verbatim}
File *input = File.Open("error.log", eFileRead);
if (input != null) {
  while (!input.EOF) {
    String line = input.ReadRawLineBack();
    Display("%s", line);
  }
  input.Close();
}
\end{verbatim}
will display the contents of the 'error.log' file, if it exists

\it{See Also:} \helprefn{File.WriteRawLine}{File.WriteRawLine}


\subsection{ReadStringBack}\label{File.ReadStringBack}\index{File.ReadStringBack}\index{File.ReadString}\index{FileRead}%

\it{(Formerly known as FileRead, which is now obsolete)} ILBRK
\it{(Formerly known as File.ReadString, which is now obsolete)}

\begin{verbatim}
String File.ReadStringBack()
\end{verbatim}
Reads a string back in from a file previously opened with File.Open, and returns it.
You should only use this with files which you previously wrote out with
File.WriteString. Do NOT use this function with any other files, even text files.

\fcol{red}{Example:}
\begin{verbatim}
File *input = File.Open("test.dat", eFileRead);
String buffer = input.ReadStringBack();
input.Close();
\end{verbatim}
will open the file test.dat (which you have previously written with File.WriteString) and
read a string into the buffer. Then close the file.

\it{See Also:} \helprefn{File.Open}{File.Open}, \helprefn{File.WriteString}{File.WriteString}


\subsection{WriteInt}\label{File.WriteInt}\index{File.WriteInt}\index{FileWriteInt}%

\it{(Formerly known as FileWriteInt, which is now obsolete)}

\begin{verbatim}
File.WriteInt(int value)
\end{verbatim}
Writes VALUE to the file. This allows you to save the contents of
variables to disk. The file must have been previously opened with File.Open,
and you can read the value back later with File.ReadInt.

\fcol{red}{Example:}
\begin{verbatim}
int number = 6;
File *output = File.Open("stats.dat", eFileWrite);
output.WriteInt(number);
output.Close();
\end{verbatim}
will open the file stats.dat and write the integer number in it.

\it{See Also:} \helprefn{File.ReadInt}{File.ReadInt}, \helprefn{File.WriteString}{File.WriteString}


\subsection{WriteRawChar}\label{File.WriteRawChar}\index{File.WriteRawChar}\index{FileWriteRawChar}%

\it{(Formerly known as FileWriteRawChar, which is now obsolete)}

\begin{verbatim}
File.WriteRawChar(int value)
\end{verbatim}
Writes a single character to the specified file, in raw mode so that other
applications can read it back. If you are just creating a file for your
game to read back in, use File.WriteInt instead because it offers additional
protection. Only use this function if you need other applications to be
able to read the file in.

This command writes a single byte to the output file - therefore, VALUE can
contain any value from 0 to 255.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("output.txt", eFileWrite);
output.WriteRawChar('A');
output.WriteRawChar('B');
output.WriteRawChar(13);
output.Close();
\end{verbatim}
will write the text "AB", followed by a carriage return character, to the file.

\it{See Also:} \helprefn{File.ReadRawChar}{File.ReadRawChar}, \helprefn{File.WriteInt}{File.WriteInt}


\subsection{WriteRawLine}\label{File.WriteRawLine}\index{File.WriteRawLine}\index{FileWriteRawLine}%

\it{(Formerly known as FileWriteRawLine, which is now obsolete)}

\begin{verbatim}
File.WriteRawLine(string text)
\end{verbatim}
Writes a string of text to the file in plain text format. This enables
you to read it back in Notepad or any text editor. This is useful for generating
logs and such like.

The TEXT will be printed to the file, followed by the standard newline characters.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("error.log", eFileAppend);
output.WriteRawLine("There was an error playing sound1.wav");
output.Close();
\end{verbatim}
will write an error line in the file error.log.

\it{See Also:} \helprefn{File.ReadRawLineBack}{File.ReadRawLineBack},
\helprefn{File.WriteString}{File.WriteString}


\subsection{WriteString}\label{File.WriteString}\index{File.WriteString}\index{FileWrite}%

\it{(Formerly known as FileWrite, which is now obsolete)}

\begin{verbatim}
File.WriteString(string text)
\end{verbatim}
Writes TEXT to the file, which must have been previously opened with
File.Open for writing. The string is written using a custom format to
the file, which can only be read back by using File.ReadStringBack.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("temp.tmp", eFileWrite);
if (output == null) Display("Error opening file.");
else {
  output.WriteString("test string");
  output.Close();
}
\end{verbatim}
will open the file temp.tmp for writing. If it cannot create the file, it will display
an error message. Otherwise, it will write the string "test string" and close it.

\it{See Also:} \helprefn{File.ReadStringBack}{File.ReadStringBack}, \helprefn{File.Open}{File.Open},
\helprefn{File.WriteRawLine}{File.WriteRawLine}


\subsection{EOF property}\label{File.EOF}\index{File.EOF}\index{FileIsEOF}%

\it{(Formerly known as FileIsEOF, which is now obsolete)}

\begin{verbatim}
readonly bool File.EOF
\end{verbatim}
Checks whether the specified file has had all its data read. This is only useful
with files opened for \bf{reading}. It returns 1 if the entire contents of the file
has now been read, or 0 if not.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("test.dat", eFileRead);
while (!output.EOF) {
  int temp = output.ReadRawChar();
  Display("%c", temp);
}
output.Close();
\end{verbatim}
will display every character in the file test.dat, one by one, to the screen.

\it{See Also:} \helprefn{File.Error}{File.Error}, \helprefn{File.Open}{File.Open},
\helprefn{File.ReadStringBack}{File.ReadStringBack}


\subsection{Error property}\label{File.Error}\index{File.Error}\index{FileIsError}%

\it{(Formerly known as FileIsError, which is now obsolete)}

\begin{verbatim}
readonly bool File.Error
\end{verbatim}
Checks whether an error has occurred reading from or writing to the specified file.

An error can occur if, for example, you run out of disk space or the user removes the
disk that is being read from.

This function only checks for errors while actually reading/writing data. The File.Open
function will return null if there was an error actually opening or creating the file.

To find out whether all data has been read from a file, use \helprefn{EOF}{File.EOF} instead.

\fcol{red}{Example:}
\begin{verbatim}
File *output = File.Open("test.dat", eFileWrite);
output.WriteInt(51);
if (output.Error) {
  Display("Error writing the data!");
}
output.Close();
\end{verbatim}
will write a number to the file 'test.dat', and display a message if there was a problem.

\it{See Also:} \helprefn{File.EOF}{File.EOF}, \helprefn{File.ReadStringBack}{File.ReadStringBack}



\section{Game / Global functions}%



\subsection{AbortGame}\label{AbortGame}%

\begin{verbatim}
AbortGame(string message, ...)
\end{verbatim}
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 \it{message} (which can include \verb$%d$ and \verb$%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.

\fcol{red}{Example:}
\begin{verbatim}
function MakeWider(int newWidth) {
  if (newWidth < 10)
    AbortGame("newWidth expects a width of at least 10!");
}
\end{verbatim}
will abort the game if MakeWider is called with a parameter less than 10.

SeeAlso: \helprefn{QuitGame}{QuitGame}


\subsection{CallRoomScript}\label{CallRoomScript}%

\begin{verbatim}
CallRoomScript (int value)
\end{verbatim}

Calls the \verb$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 \verb$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:
\begin{verbatim}
function on_call (int value) {
  if (value == 1) {
    // Check text input
    if (Parser.Said("get apple"))
      Display("No, leave the tree alone.");
  }
}
\end{verbatim}

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: \helpref{The text parser documentation}{TextParser}


\subsection{ChangeTranslation}\label{Game.ChangeTranslation}\index{Game.ChangeTranslation}%

\begin{verbatim}
static bool Game.ChangeTranslation(string newTranslationName)
\end{verbatim}
Changes the active translation to \it{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 \it{true} if the translation was changed successfully, or \it{false} if there was a
problem (for example, you specified an invalid translation).

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example below.

\fcol{red}{Example:}
\begin{verbatim}
if (Game.ChangeTranslation("Spanish") == true)
{
  Display("Changed the translation to Spanish!");
}
else
{
  Display("Unable to change the translation");
}
\end{verbatim}
will attempt to change the translation to Spanish

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Game.TranslationFilename}{Game.TranslationFilename},
\helprefn{IsTranslationAvailable}{IsTranslationAvailable}


\subsection{ClaimEvent}\label{ClaimEvent}%

\begin{verbatim}
ClaimEvent()
\end{verbatim}

This command is used in a room script or script module's \it{on_key_press} or
\it{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 \it{on_key_press} and \it{on_mouse_click}
is as follows:
\begin{itemize}
\item room script
\item script modules, in order
\item global script
\end{itemize}
If any of these scripts calls ClaimEvent, then the chain is aborted at that point.

\fcol{red}{Example:}
\begin{verbatim}
if (keycode == ' ') {
  Display("You pressed space in this room!");
  ClaimEvent();
}
\end{verbatim}
prevents the global script on_key_press from running if the player pressed the space bar.

SeeAlso: \helprefn{Script events}{TextScriptEvents}



\subsection{Debug}\label{Debug}%

\begin{verbatim}
Debug (int command, int data)
\end{verbatim}
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 AGS 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:
\begin{verbatim}
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. All walkable areas are drawn in
    their respective colours, but with blocking areas at characters feet
    removed.
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.
\end{verbatim}

\it{See Also:} \helprefn{Debugging features}{Debuggingfeatures}


\subsection{DeleteSaveSlot}\label{DeleteSaveSlot}%

\begin{verbatim}
DeleteSaveSlot (int slot)
\end{verbatim}
Deletes the save game in save slot number SLOT.

NOTE: if you specify one of the standard slots (1-50), 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.

\fcol{red}{Example:}
\begin{verbatim}
DeleteSaveSlot (130);
\end{verbatim}
deletes save game slot 130 (which we should have saved earlier).

\it{See Also:} \helprefn{RestoreGameSlot}{RestoreGameSlot}, \helprefn{SaveGameSlot}{SaveGameSlot}


\subsection{DisableInterface}\label{DisableInterface}%

\begin{verbatim}
DisableInterface ()
\end{verbatim}
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.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
DisableInterface();
\end{verbatim}
will disable the user's interface.

\it{See Also:} \helprefn{EnableInterface}{EnableInterface}, \helprefn{IsInterfaceEnabled}{IsInterfaceEnabled}


\subsection{DoOnceOnly}\label{Game.DoOnceOnly}\index{Game.DoOnceOnly}%

\begin{verbatim}
static bool Game.DoOnceOnly(const string token)
\end{verbatim}
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 \it{token} parameter is an arbitrary string. You can pass whatever you like in
for this, but \bf{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 \bf{you do not use the same token string in two different places in your game}.

Returns \it{true} the first time that it is called with this token, and \it{false} thereafter.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example below.

\fcol{red}{Example:}
\begin{verbatim}
if (Game.DoOnceOnly("open cupboard")) {
  GiveScore(5);
}
\end{verbatim}
will give the player 5 points the first time this script is run.

\it{See Also:} \helprefn{GiveScore}{GiveScore}


\subsection{EnableInterface}\label{EnableInterface}%

\begin{verbatim}
EnableInterface ()
\end{verbatim}
Re-enables the player interface, which was previously disabled with
the DisableInterface function. Everything which was disabled is returned
to normal.

\fcol{red}{Example:}
\begin{verbatim}
EnableInterface();
\end{verbatim}
will enable the user's interface.

\it{See Also:} \helprefn{DisableInterface}{DisableInterface}, \helprefn{IsInterfaceEnabled}{IsInterfaceEnabled}


\subsection{EndCutscene}\label{EndCutscene}%

\begin{verbatim}
EndCutscene()
\end{verbatim}

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.

\it{See Also:} \helprefn{StartCutscene}{StartCutscene},
\helprefn{Game.InSkippableCutscene}{Game.InSkippableCutscene},
\helprefn{Game.SkippingCutscene}{Game.SkippingCutscene}


\subsection{GetColorFromRGB}\label{Game.GetColorFromRGB}\index{Game.GetColorFromRGB}\index{RawSetColorRGB}%

\it{(Formerly known as RawSetColorRGB, which is now obsolete)}

\begin{verbatim}
static int Game.GetColorFromRGB(int red, int green, int blue)
\end{verbatim}
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.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example below.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = Game.GetColorFromRGB(0, 255, 0);
surface.DrawLine(0, 0, 50, 50);
surface.Release();
\end{verbatim}
will draw a bright green line onto the room background

\it{See Also:} \helprefn{DrawingSurface.DrawingColor}{DrawingSurface.DrawingColor}


\subsection{GetFrameCountForLoop}\label{Game.GetFrameCountForLoop}\index{Game.GetFrameCountForLoop}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
static int Game.GetFrameCountForLoop(int view, int loop)
\end{verbatim}
Returns the number of frames in the specified loop of the specified view.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example for more.

\fcol{red}{Example:}
\begin{verbatim}
int frameCount = Game.GetFrameCountForLoop(SWIMMING, 2);
Display("Loop 2 in SWIMMING view has %d frames.", frameCount);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetLoopCountForView}{Game.GetLoopCountForView},
\helprefn{Game.GetRunNextSettingForLoop}{Game.GetRunNextSettingForLoop},
\helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{GetGameOption}\label{GetGameOption}%

\begin{verbatim}
GetGameOption (option)
\end{verbatim}

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 \helprefn{SetGameOption}{SetGameOption}.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGameOption(OPT_PIXELPERFECT) == 1) {
  Display("pixel-perfect click deteciton is on!");
}
\end{verbatim}

\it{See Also:} \helprefn{SetGameOption}{SetGameOption}



\subsection{GetGameParameter}\label{GetGameParameter}%

The \it{GetGameParameter} function is now obsolete.

It has been replaced with the following functions and properties:

\helprefn{Game.SpriteWidth}{Game.SpriteWidth} (was GP_SPRITEWIDTH) ILBRK
\helprefn{Game.SpriteHeight}{Game.SpriteHeight} (was GP_SPRITEHEIGHT) ILBRK
\helprefn{Game.GetLoopCountForView}{Game.GetLoopCountForView} (was GP_NUMLOOPS) ILBRK
\helprefn{Game.GetFrameCountForLoop}{Game.GetFrameCountForLoop} (was GP_NUMFRAMES) ILBRK
\helprefn{Game.GetRunNextSettingForLoop}{Game.GetRunNextSettingForLoop} (was GP_ISRUNNEXTLOOP) ILBRK
\helprefn{Game.GetViewFrame}{Game.GetViewFrame} (was GP_FRAMExxx, GP_ISFRAMEFLIPPED) ILBRK
\helprefn{Game.GUICount}{Game.GUICount} (was GP_NUMGUIS) ILBRK
\helprefn{Room.ObjectCount}{Room.ObjectCount} (was GP_NUMOBJECTS) ILBRK
\helprefn{Game.CharacterCount}{Game.CharacterCount} (was GP_NUMCHARACTERS) ILBRK
\helprefn{Game.InventoryItemCount}{Game.InventoryItemCount}(was GP_NUMINVITEMS) 


\subsection{GetGameSpeed}\label{GetGameSpeed}%

\begin{verbatim}
GetGameSpeed ()
\end{verbatim}
Returns the current game speed (number of cycles per second).

\fcol{red}{Example:}
\begin{verbatim}
if (GetGameSpeed() > 40) {
  SetGameSpeed(40);
}
\end{verbatim}
will always keep the game speed at 40 cycles per second (in case the user has raised it )	

\it{See Also:} \helprefn{SetGameSpeed}{SetGameSpeed}


\subsection{GetGlobalInt}\label{GetGlobalInt}%

\begin{verbatim}
GetGlobalInt (int index)
\end{verbatim}
Returns the value of global int INDEX.

\bf{NOTE:} GlobalInts are now considered obsolete. Consider using
\helprefn{global variables}{GlobalVariables} instead, which allow you to name
the variables.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGlobalInt(20) == 1) {
  // code here
}
\end{verbatim}
will execute the code only if Global Integer 20 is 1.

\it{See Also:} \helprefn{SetGlobalInt}{SetGlobalInt}, \helprefn{Game.GlobalStrings}{Game.GlobalStrings}



\subsection{GetGraphicalVariable}\label{GetGraphicalVariable}%

\begin{verbatim}
GetGraphicalVariable (string variable_name);
\end{verbatim}
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.

\bf{NOTE:} This command is obsolete, and is only provided for backwards compatibility
with AGS 2.x. When writing new code, use \helprefn{global variables}{GlobalVariables}
instead.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGraphicalVariable("climbed rock")==1)
   { code here }
\end{verbatim}
will execute the code only if interaction variable "climbed rock" is 1.

\it{See Also:} \helprefn{GetGlobalInt}{GetGlobalInt}, \helprefn{SetGraphicalVariable}{SetGraphicalVariable}


\subsection{GetLocationName}\label{Game.GetLocationName}\index{Game.GetLocationName}%

\it{(Formerly known as global function GetLocationName, which is now obsolete)}

\begin{verbatim}
static String Game.GetLocationName(int x, int y)
\end{verbatim}
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.

\bf{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.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
String location = Game.GetLocationName(mouse.x, mouse.y);
\end{verbatim}
will get the name of whatever the mouse is over into the string variable.

\it{See Also:} \helprefn{Hotspot.Name}{Hotspot.Name}, \helprefn{InventoryItem.Name}{InventoryItem.Name},
\helprefn{GetLocationType}{GetLocationType}, \helprefn{Object.Name}{Object.Name}


\subsection{GetLocationType}\label{GetLocationType}%

\begin{verbatim}
GetLocationType(int x, int y)
\end{verbatim}
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.

\bf{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:
\begin{verbatim}
eLocationNothing    nothing, GUI or inventory
eLocationHotspot    a hotspot
eLocationCharacter  a character
eLocationObject     an object
\end{verbatim}

\fcol{red}{Example:}
\begin{verbatim}
if (GetLocationType(mouse.x,mouse.y) == eLocationCharacter)
    mouse.Mode = eModeTalk;
\end{verbatim}	
will set the cursor mode to talk if the cursor is over a character.

\it{See Also:} \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY},
\helprefn{Game.GetLocationName}{Game.GetLocationName},
\helprefn{Object.GetAtScreenXY}{Object.GetAtScreenXY}


\subsection{GetLoopCountForView}\label{Game.GetLoopCountForView}\index{Game.GetLoopCountForView}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
static int Game.GetLoopCountForView(int view)
\end{verbatim}
Returns the number of loops in the specified view.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example for more.

\fcol{red}{Example:}
\begin{verbatim}
int loops = Game.GetLoopCountForView(SWIMMING);
Display("The SWIMMING view (view %d) has %d loops.", SWIMMING, loops);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetRunNextSettingForLoop}{Game.GetRunNextSettingForLoop},
\helprefn{Game.GetFrameCountForLoop}{Game.GetFrameCountForLoop},
\helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{GetRunNextSettingForLoop}\label{Game.GetRunNextSettingForLoop}\index{Game.GetRunNextSettingForLoop}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
static bool Game.GetRunNextSettingForLoop(int view, int loop)
\end{verbatim}
Returns whether the specified loop in the specified view has the "Run the next loop after this one" option checked.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example for more.

\fcol{red}{Example:}
\begin{verbatim}
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.");
}
\end{verbatim}

\it{See Also:} \helprefn{Game.GetLoopCountForView}{Game.GetLoopCountForView},
\helprefn{Game.GetFrameCountForLoop}{Game.GetFrameCountForLoop},
\helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{GetSaveSlotDescription}\label{Game.GetSaveSlotDescription}\index{Game.GetSaveSlotDescription}%

\it{(Formerly known as global function GetSaveSlotDescription, which is now obsolete)}

\begin{verbatim}
static String Game.GetSaveSlotDescription(int slot)
\end{verbatim}
Gets the text description of save game slot SLOT.

If the slot number provided does not exist, returns \it{null}.

\fcol{red}{Example:}
\begin{verbatim}
String description = Game.GetSaveSlotDescription(10);
\end{verbatim}
will get the description of save slot 10 into the variable.

\it{See Also:} \helprefn{DynamicSprite.CreateFromSaveGame}{DynamicSprite.CreateFromSaveGame},
\helprefn{RestoreGameSlot}{RestoreGameSlot}, \helprefn{SaveGameSlot}{SaveGameSlot}


\subsection{GetTextHeight}\label{GetTextHeight}%

\begin{verbatim}
GetTextHeight(string text, FontType font, int width)
\end{verbatim}
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
\helprefn{DrawMessageWrapped}{DrawingSurface.DrawMessageWrapped} 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.

\fcol{red}{Example:}
\begin{verbatim}
int height = GetTextHeight("The message on the GUI!", Game.NormalFont, 100);
gBottomLine.SetPosition(0, 200 - height);
\end{verbatim}
will move the BOTTOMLINE GUI so that it can display the text within the screen.

\it{See Also:} \helprefn{GetTextWidth}{GetTextWidth}, \helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString}



\subsection{GetTextWidth}\label{GetTextWidth}%

\begin{verbatim}
GetTextWidth(string text, FontType font)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
int width = GetTextWidth("Hello!", Game.NormalFont);
surface.DrawString(160 - (width / 2), 100, Game.NormalFont, "Hello!");
surface.Release();
\end{verbatim}
will print "Hello!" onto the middle of the background scene.

\it{See Also:} \helprefn{GetTextHeight}{GetTextHeight}, \helprefn{DrawingSurface.DrawString}{DrawingSurface.DrawString}


\subsection{GetTranslation}\label{GetTranslation}%

\begin{verbatim}
String GetTranslation(string original)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
String buffer = Game.InputBox("Enter the password:");
if (buffer.CompareTo(GetTranslation("secret")) == 0) {
  // it matched the current translation of "secret"
}
\end{verbatim}
If there is no translation for the supplied string, it will be returned
unchanged, so it is always safe to use this function.

\it{See Also:} \helprefn{IsTranslationAvailable}{IsTranslationAvailable}


\subsection{GetViewFrame}\label{Game.GetViewFrame}\index{Game.GetViewFrame}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
static ViewFrame* Game.GetViewFrame(int view, int loop, int frame)
\end{verbatim}
Returns a \it{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.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example for more.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(SWIMMING, 2, 3);
Display("Frame 3 in loop 2 of view SWIMMING has sprite slot %d.", frame.Graphic);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetLoopCountForView}{Game.GetLoopCountForView},
\helprefn{Game.GetRunNextSettingForLoop}{Game.GetRunNextSettingForLoop},
\helprefn{Game.GetFrameCountForLoop}{Game.GetFrameCountForLoop},
\helprefn{ViewFrame.Graphic}{ViewFrame.Graphic}, \helprefn{ViewFrame.Speed}{ViewFrame.Speed}


\subsection{GiveScore}\label{GiveScore}%

\begin{verbatim}
GiveScore (int score)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
GiveScore(5);
\end{verbatim}
will give 5 points to the player.

\it{See Also:} \helprefn{Game.DoOnceOnly}{Game.DoOnceOnly}


\subsection{InputBox}\label{Game.InputBox}\index{Game.InputBox}%

\it{(Formerly known as global function InputBox, which is now obsolete)}

\begin{verbatim}
static String Game.InputBox(string prompt)
\end{verbatim}
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.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
String name = Game.InputBox("!What is your name?");
\end{verbatim}
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.

\it{See Also:} \helprefn{String.AsInt}{String.AsInt}


\subsection{InventoryScreen}\label{InventoryScreen}%

\begin{verbatim}
InventoryScreen ()
\end{verbatim}

This command is obsolete. 

\bf{This command was used for displaying a default inventory window
in previous versions of AGS, but is no longer supported.}

Instead of using this command, you should create your own Inventory GUI.
The Default Game template comes with an example.


\subsection{IsGamePaused}\label{IsGamePaused}%

\begin{verbatim}
IsGamePaused ()
\end{verbatim}
Returns \it{true} if the game is currently paused, or \it{false} 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.

\fcol{red}{Example:}
\begin{verbatim}
if (IsGamePaused()) UnPauseGame();
\end{verbatim}
will unpause the game if it's paused.

\it{See Also:} \helprefn{GUI.Visible}{GUI.Visible}


\subsection{IsInterfaceEnabled}\label{IsInterfaceEnabled}%

\begin{verbatim}
IsInterfaceEnabled()
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (IsInterfaceEnabled())
    DisableInterface();
\end{verbatim}
will disable the user interface if it's enabled.

\it{See Also:} \helprefn{DisableInterface}{DisableInterface}, \helprefn{EnableInterface}{EnableInterface}


\subsection{IsInteractionAvailable}\label{IsInteractionAvailable}%

\begin{verbatim}
IsInteractionAvailable (int x, int y, int mode)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (IsInteractionAvailable(mouse.x,mouse.y, eModeLookat) == 0)
  Display("looking here would not do anything.");
\end{verbatim}

\it{See Also:} \helprefn{InventoryItem.IsInteractionAvailable}{InventoryItem.IsInteractionAvailable},
\helprefn{ProcessClick}{ProcessClick}


\subsection{IsKeyPressed}\label{IsKeyPressed}%

\begin{verbatim}
IsKeyPressed(eKeyCode)
\end{verbatim}
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 \helprefn{ASCII codes}{ASCIIcodes}, 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.

\bf{NOTE:} The numeric keypad can have inconsistent 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.

\fcol{red}{Example:}
\begin{verbatim}
if (IsKeyPressed(eKeyUpArrow) == 1)
  cEgo.Walk(cEgo.x, cEgo.y+3);
\end{verbatim}
will move the character EGO upwards 3 pixels when the up arrow is pressed.

\it{See Also:} \helprefn{Mouse.IsButtonDown}{Mouse.IsButtonDown}


\subsection{IsTimerExpired}\label{IsTimerExpired}%

\begin{verbatim}
bool IsTimerExpired(int timer_id)
\end{verbatim}
Checks whether the timer TIMER_ID has expired.
If the timeout set with SetTimer has elapsed, returns \it{true}.
Otherwise, returns \it{false}.

Note that this function will only return \it{true} once - after that, the timer
is placed into an OFF state where it will always return \it{false} until restarted.

\fcol{red}{Example:}
\begin{verbatim}
if (IsTimerExpired(1)) {
  Display("Timer 1 expired");
}
\end{verbatim}
will display a message when timer 1 expires.

\it{See Also:} \helprefn{SetTimer}{SetTimer}


\subsection{IsTranslationAvailable}\label{IsTranslationAvailable}%

\begin{verbatim}
IsTranslationAvailable ()
\end{verbatim}
Finds out whether the player is using a game translation or not.

Returns 1 if a translation is in use, 0 if not.

\it{See Also:} \helprefn{GetTranslation}{GetTranslation},
\helprefn{Game.ChangeTranslation}{Game.ChangeTranslation},
\helprefn{Game.TranslationFilename}{Game.TranslationFilename}


\subsection{MoveCharacterToHotspot}\label{MoveCharacterToHotspot}%

\bf{This function is now obsolete. Use Character.Walk instead}

\begin{verbatim}
MoveCharacterToHotspot (CHARID, int hotspot)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
MoveCharacterToHotspot(EGO,6);
\end{verbatim}
will move the character EGO to the hotspot's 6 "walk to point".

\it{See Also:} \helprefn{Hotspot.WalkToX}{Hotspot.WalkToX}, \helprefn{Hotspot.WalkToY}{Hotspot.WalkToY}, 
\helprefn{Character.Walk}{Character.Walk}, \helprefn{MoveCharacterToObject}{MoveCharacterToObject}


\subsection{MoveCharacterToObject}\label{MoveCharacterToObject}%

\bf{This function is now obsolete. Use Character.Walk instead}

\begin{verbatim}
MoveCharacterToObject (CHARID, int object)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
MoveCharacterToObject (EGO, 0);
object[0].Visible = false;
\end{verbatim}
Will move the character EGO below object number 0, then turn off object 0.

\it{See Also:} \helprefn{Character.Walk}{Character.Walk},
\helprefn{MoveCharacterToHotspot}{MoveCharacterToHotspot}



\subsection{PauseGame}\label{PauseGame}%

\begin{verbatim}
PauseGame ()
\end{verbatim}
Stops AGS processing character movement and animations. This has the same
effect on the game as happens when a modal GUI is popped up. Game processing
will not resume until you call the UnPauseGame function.

\bf{NOTE:} When the game is paused, game cycles will continue to run but
no animations or movement will be performed, and timers will not count down. Apart
from that, your scripts will continue to run as normal.

\bf{NOTE:} GUI button animations will not be paused by this command, so that
you can run animations on a pop-up GUI while the rest of the game is paused.

\fcol{red}{Example:}
\begin{verbatim}
if (IsKeyPressed(32)==1) PauseGame();
\end{verbatim}
will pause the game if the player presses the space bar

\it{See Also:} \helprefn{UnPauseGame}{UnPauseGame}


\subsection{ProcessClick}\label{ProcessClick}%

\begin{verbatim}
ProcessClick (int x, int y, CursorMode)
\end{verbatim}
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,
\begin{verbatim}
ProcessClick (100, 50, eModeLookat);
\end{verbatim}
will simulate clicking the mouse on co-ordinates (100,50) in the Look mode.

\bf{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, eModeLookat, etc.

\fcol{red}{Example:}
\begin{verbatim}
ProcessClick(mouse.x,mouse.y, eModeLookat);
\end{verbatim}
will simulate a click in the LOOK MODE where the cursor is.

\it{See Also:} \helprefn{IsInteractionAvailable}{IsInteractionAvailable},
\helprefn{Hotspot.RunInteraction}{Hotspot.RunInteraction}


\subsection{QuitGame}\label{QuitGame}%

\begin{verbatim}
QuitGame(int ask_first)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
QuitGame(0);
\end{verbatim}
will quit the game without asking the player to confirm.

\it{See Also:} \helprefn{AbortGame}{AbortGame}


\subsection{Random}\label{Random}%

\begin{verbatim}
Random (int max)
\end{verbatim}
Returns a random number between 0 and MAX. This could be useful to do
various effects in your game.

\bf{NOTE:} The range returned is inclusive - ie. if you do  Random(3);  then it
can return 0, 1, 2 or 3.

\fcol{red}{Example:}
\begin{verbatim}
int ran=Random(2);
if (ran==0) cEgo.ChangeRoom(1);
else if (ran==1) cEgo.ChangeRoom(2);
else cEgo.ChangeRoom(3);
\end{verbatim}
will change the current room to room 1,2 or 3 depending on a random result.


\subsection{RestartGame}\label{RestartGame}%

\begin{verbatim}
RestartGame ()
\end{verbatim}
Restarts the game from the beginning.

\fcol{red}{Example:}
\begin{verbatim}
if (IsKeyPressed(365) == 1) RestartGame(); 
\end{verbatim}
will restart the game if the player presses the F7 key.

\it{SeeAlso:} \helprefn{SetRestartPoint}{SetRestartPoint}


\subsection{RestoreGameDialog}\label{RestoreGameDialog}%

\begin{verbatim}
RestoreGameDialog ()
\end{verbatim}
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.


\fcol{red}{Example:}
\begin{verbatim}
if (IsKeyPressed(363) == 1) RestoreGameDialog();
\end{verbatim}
will bring up the restore game dialog if the player presses the F5 key.

\it{See Also:} \helprefn{RestoreGameSlot}{RestoreGameSlot}, \helprefn{SaveGameDialog}{SaveGameDialog}


\subsection{RestoreGameSlot}\label{RestoreGameSlot}%

\begin{verbatim}
RestoreGameSlot (int slot)
\end{verbatim}
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.

\bf{NOTE:} The game will not be restored immediately; instead, it will be
restored when the script function finishes executing.

\fcol{red}{Example:}
\begin{verbatim}
RestoreGameSlot(30);
\end{verbatim}
will restore game slot 30 if this slot number exists.

\it{See Also:} \helprefn{Game.GetSaveSlotDescription}{Game.GetSaveSlotDescription},
\helprefn{RestoreGameDialog}{RestoreGameDialog}, \helprefn{SaveGameSlot}{SaveGameSlot}


\subsection{RunAGSGame}\label{RunAGSGame}%

\begin{verbatim}
RunAGSGame (string filename, int mode, int data)
\end{verbatim}
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:
\begin{verbatim}
0   Current game is completely exited, new game runs as if it had been launched separately
1   GlobalInt values are preserved and are not set to 0 for the new game.
\end{verbatim}

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 audio.vox, speech.vox and so forth. This is a limitation of this command.

\bf{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.

\bf{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.

\bf{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).

\fcol{red}{Example:}
\begin{verbatim}
RunAGSGame ("MyGame.exe", 0, 51);
\end{verbatim}
will run the MyGame game, passing it the value 51.


\subsection{SaveGameDialog}\label{SaveGameDialog}%

\begin{verbatim}
SaveGameDialog ()
\end{verbatim}
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.

\bf{NOTE:} The dialog will not be displayed immediately; instead, it will be
shown when the script function finishes executing.

\fcol{red}{Example:}
\begin{verbatim}
if (keycode == 361) SaveGameDialog();
\end{verbatim}
will bring up the save game dialog if the player presses the F3 key.

\it{See Also:} \helprefn{RestoreGameDialog}{RestoreGameDialog}, \helprefn{SaveGameSlot}{SaveGameSlot}


\subsection{SaveGameSlot}\label{SaveGameSlot}%

\begin{verbatim}
SaveGameSlot (int slot, string description)
\end{verbatim}
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.

\bf{NOTE:} The game will not be saved immediately; instead, it will be
saved when the script function finishes executing.

\fcol{red}{Example:}
\begin{verbatim}
SaveGameSlot(30, "save game");
\end{verbatim}
will save the current game position to slot 30 with the description "Save game".

\it{See Also:} \helprefn{DeleteSaveSlot}{DeleteSaveSlot}, \helprefn{RestoreGameSlot}{RestoreGameSlot}, \helprefn{SaveGameDialog}{SaveGameDialog}


\subsection{SaveScreenShot}\label{SaveScreenShot}%

\begin{verbatim}
SaveScreenShot (string filename)
\end{verbatim}
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.

\bf{NOTE:} The screenshot will be saved to the Saved Games folder.

\bf{NOTE:} This command can be slow when using the Direct3D graphics driver.

\fcol{red}{Example:}
\begin{verbatim}
String input = Game.InputBox("Type the filename:");
input = input.Append(".pcx");
SaveScreenShot(input);
\end{verbatim}
will prompt the player for a filename and then save the screenshot with the filename the player typed.

\it{See Also:} \helprefn{DynamicSprite.SaveToFile}{DynamicSprite.SaveToFile}


\subsection{SetAmbientTint}\label{SetAmbientTint}%

\begin{verbatim}
SetAmbientTint(int red, int green, int blue, int saturation, int luminance)
\end{verbatim}

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.

\bf{NOTE:} This function only works in hi-colour games and with hi-colour sprites.

\bf{NOTE:} This function overrides any specific region light levels or tints on the screen.

\fcol{red}{Example:}
\begin{verbatim}
SetAmbientTint(0, 0, 250, 30, 100);
\end{verbatim}
will tint everything on the screen with a hint of blue.

\it{See Also:} \helprefn{DrawingSurface.DrawSurface}{DrawingSurface.DrawSurface},
\helprefn{Character.Tint}{Character.Tint}, \helprefn{Object.Tint}{Object.Tint}



\subsection{SetGameOption}\label{SetGameOption}%

\begin{verbatim}
SetGameOption (option, int value)
\end{verbatim}

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:

\begin{tabular}{|l|l|}
\row{ \bf{ Option } & \bf{ Values }
}\row{{ OPT_WALKONLOOK } & { Walk to hotspot in look mode (0 or 1) }
}\row{{ OPT_DIALOGOPTIONSGUI } & { Dialog options on GUI (0=none, otherwise GUI name/number) }
}\row{{ OPT_DIALOGOPTIONSGAP } & { Pixel gap between options (0=none, otherwise num pixels) }
}\row{{ OPT_WHENGUIDISABLED } & { When GUI is disabled, 0=grey out, 1=go black, 2=unchanged, 3=turn off }
}\row{{ OPT_ALWAYSSPEECH } & { Always display text as speech (0 or 1) }
}\row{{ OPT_PIXELPERFECT } & { Pixel-perfect click detection (0 or 1) }
}\row{{ OPT_NOWALKMODE } & { Don't automatically move character in Walk mode (0 or 1) }
}\row{{ OPT_FIXEDINVCURSOR } & { Don't use inventory graphics as cursors (0 or 1) }
}\row{{ OPT_DONTLOSEINV } & { Don't automatically lose inventory items (0 or 1) }
}\row{{ OPT_TURNBEFOREWALK } & { Characters turn before walking (0 or 1) }
}\row{{ OPT_HANDLEINVCLICKS } & { Handle inventory clicks in script (0 or 1) }
}\row{{ OPT_MOUSEWHEEL } & { Enable mouse wheel support (0 or 1) }
}\row{{ OPT_DIALOGNUMBERED } & { Number dialog options (0 or 1) }
}\row{{ OPT_DIALOGUPWARDS } & { Dialog options go upwards on GUI (0 or 1) }
}\row{{ OPT_CROSSFADEMUSIC } & { Crossfade music tracks (0=no, 1=slow, 2=slowish, 3=medium, 4=fast) }
}\row{{ OPT_ANTIALIASFONTS } & { Anti-alias rendering of TTF fonts (0 or 1) }
}\row{{ OPT_THOUGHTGUI } & { Thought uses bubble GUI (GUI name/number) }
}\row{{ OPT_TURNWHENFACING } & { Characters turn to face direction (0 or 1) }
}\row{{ OPT_LIPSYNCTEXT } & { Whether lip-sync text reading is enabled (0 or 1) }
}\row{{ OPT_RIGHTTOLEFT } & { Right-to-left text writing (0 or 1) }
}\row{{ OPT_MULTIPLEINV } & { Display multiple inv items multiple times (0 or 1) }
}\row{{ OPT_SAVEGAMESCREENSHOTS } & { Save screenshots into save games (0 or 1) }
}\row{{ OPT_PORTRAITPOSITION } & { Speech portrait side (0=left, 1=right, 2=alternate, 3=xpos) }
}\end{tabular}

The game settings which are not listed here either have a separate 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.

\fcol{red}{Example:}
\begin{verbatim}
SetGameOption (OPT_PIXELPERFECT, 0);
\end{verbatim}
will disable pixel-perfect click detection.

\it{See Also:} \helprefn{GetGameOption}{GetGameOption},
\helprefn{SetSpeechStyle}{SetSpeechStyle}, \helprefn{SetTextWindowGUI}{SetTextWindowGUI}


\subsection{SetGameSpeed}\label{SetGameSpeed}%

\begin{verbatim}

SetGameSpeed (int new_speed)
\end{verbatim}
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 \helprefn{System.VSync}{System.VSync} property to \it{true}, 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).

\fcol{red}{Example:}
\begin{verbatim}
SetGameSpeed(80);
\end{verbatim}
will set the game speed to 80.

\it{See Also:} \helprefn{GetGameSpeed}{GetGameSpeed}


\subsection{SetGlobalInt}\label{SetGlobalInt}%

\begin{verbatim}
SetGlobalInt (int index, int value)
\end{verbatim}
Sets the global int 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.

\bf{NOTE:} GlobalInts are now considered obsolete. Consider using
\helprefn{global variables}{GlobalVariables} instead, which allow you to name
the variables.

\fcol{red}{Example:}
\begin{verbatim}
SetGlobalInt(10,1);
\end{verbatim}
will set the Global Integer 10 to 1.

\it{See Also:} \helprefn{GetGlobalInt}{GetGlobalInt}


\subsection{SetGraphicalVariable}\label{SetGraphicalVariable}%

\begin{verbatim}
SetGraphicalVariable(string variable_name, int value);
\end{verbatim}
Sets the interaction editor VARIABLE_NAME variable to VALUE. This allows your
script to change the values of variables set in the interaction editor.

\bf{NOTE:} This command is obsolete, and is only provided for backwards compatibility
with AGS 2.x. When writing new code, use \helprefn{global variables}{GlobalVariables}
instead.

\fcol{red}{Example:}
\begin{verbatim}
SetGraphicalVariable("climbed rock", 1);
\end{verbatim}
will set the interaction editor "climbed rock" variable to 1.

\it{See Also:} \helprefn{GetGraphicalVariable}{GetGraphicalVariable}


\subsection{SetMultitaskingMode}\label{SetMultitaskingMode}%

\begin{verbatim}
SetMultitaskingMode (int mode)
\end{verbatim}
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.

\bf{Cross-Platform Support}

Windows: \bf{ Yes }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ Yes }ILBRK
MacOS: \bf{ Yes }


\fcol{red}{Example:}
\begin{verbatim}
SetMultitaskingMode (1);
\end{verbatim}
will mean that the game continues to run in the background.


\subsection{SetRestartPoint}\label{SetRestartPoint}%

\begin{verbatim}
SetRestartPoint ()
\end{verbatim}
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.

\bf{NOTE:} The restart point cannot be set while a script is running -- therefore,
when you call this it will actually set the restart point at the next game
loop where there is not a blocking script running in the background.

\it{SeeAlso:} \helprefn{RestartGame}{RestartGame}


\subsection{SetSaveGameDirectory}\label{Game.SetSaveGameDirectory}\index{Game.SetSaveGameDirectory}%

\begin{verbatim}
static bool Game.SetSaveGameDirectory(string directory)
\end{verbatim}
Changes the directory where save game files are stored to the supplied \it{directory}.
If the directory does not exist, AGS will attempt to create it. 

You cannot use fully qualified directories with this command (eg. \verb$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: ILBRK
1. Relative paths (eg. "Saves"). This will create a "Saves" folder inside your game folder ILBRK
2. The special tag \verb!$MYDOCS$! which allows you to create a folder for your save games
inside the user's documents folder. On Vista, this is the "Saved Games" folder;
on Windows XP and earlier, this is "My Documents". On Mac and Linux, currently this just points
to the game folder.

Returns \it{true} if the save game directory has been changed successfully; \it{false} if not.

\bf{NOTE:} It is recommended that you do not use this function. Instead, set the "Save games
folder name" property in the General Settings of the editor, which allows the save games to be
detected by Vista's Game Explorer, and avoids problems writing to the Program Files folder.

\fcol{red}{Example:}
\begin{verbatim}
Game.SetSaveGameDirectory("$MYDOCS$/My Cool Game Saves");
\end{verbatim}
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).

\it{See Also:} \helprefn{ListBox.FillSaveGameList}{ListBox.FillSaveGameList},
\helprefn{RestoreGameDialog}{RestoreGameDialog}


\subsection{SetTextWindowGUI}\label{SetTextWindowGUI}%

\begin{verbatim}
SetTextWindowGUI (int gui)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
SetTextWindowGUI (4);
\end{verbatim}
will change Textwindow GUI 4 to be used for displaying text windows in future.


\subsection{SetTimer}\label{SetTimer}%

\begin{verbatim}
SetTimer (int timer_id, int timeout)
\end{verbatim}
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.

\bf{NOTE:} the timer will not tick while the game is paused.

\fcol{red}{Example:}
\begin{verbatim}
SetTimer(1,1000); 
\end{verbatim}
will set the timer 1 to expire after 1000 game cycles.

\it{See Also:} \helprefn{IsTimerExpired}{IsTimerExpired}


\subsection{SkipUntilCharacterStops}\label{SkipUntilCharacterStops}%

\begin{verbatim}
SkipUntilCharacterStops(CHARID)
\end{verbatim}

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.

\fcol{red}{Example: (in on_key_press)}
\begin{verbatim}
if (keycode == eKeyEscape) SkipUntilCharacterStops(EGO);
\end{verbatim}
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.

\it{See Also:} \helprefn{StartCutscene}{StartCutscene}



\subsection{StartCutscene}\label{StartCutscene}%

\begin{verbatim}
StartCutscene(CutsceneSkipType)
\end{verbatim}

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:
\begin{verbatim}
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 button
\end{verbatim}
You need to mark the end of the cutscene with the EndCutscene command.

Be \bf{very careful} with where you place the corresponding EndCutscene command.
The script \bf{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.

\it{See Also:} \helprefn{EndCutscene}{EndCutscene},
\helprefn{SkipUntilCharacterStops}{SkipUntilCharacterStops},
\helprefn{Game.InSkippableCutscene}{Game.InSkippableCutscene},
\helprefn{Game.SkippingCutscene}{Game.SkippingCutscene}


\subsection{UpdateInventory}\label{UpdateInventory}%

\begin{verbatim}
UpdateInventory ()
\end{verbatim}
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.

\it{See Also:} \helprefn{Character.AddInventory}{Character.AddInventory},
\helprefn{Character.LoseInventory}{Character.LoseInventory},
\helprefn{Character.InventoryQuantity}{Character.InventoryQuantity}


\subsection{UnPauseGame}\label{UnPauseGame}%

\begin{verbatim}
UnPauseGame ()
\end{verbatim}
Resumes the game.

\fcol{red}{Example:}
\begin{verbatim}
if (IsGamePaused() == 1)
    UnPauseGame();
\end{verbatim}
will unpause the game if it is paused.

\it{See Also:} \helprefn{PauseGame}{PauseGame}

\subsection{Wait}\label{Wait}%

\begin{verbatim}
Wait (int time)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
cEgo.Walk(120, 140, eBlock, eWalkableAreas);
Wait(80);
cEgo.FaceLocation(1000,100);
\end{verbatim}
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.

\it{See Also:} \helprefn{WaitKey}{WaitKey}, \helprefn{WaitMouseKey}{WaitMouseKey}

\subsection{WaitKey}\label{WaitKey}%

\begin{verbatim}
WaitKey (int time)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
WaitKey(200);
\end{verbatim}
will pause the script and wait until 5 seconds have passed or the player presses a key.

\it{See Also:} \helprefn{Wait}{Wait}, \helprefn{WaitMouseKey}{WaitMouseKey}

\subsection{WaitMouseKey}\label{WaitMouseKey}%

\begin{verbatim}
WaitMouseKey (int time)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
WaitMouseKey(200);
\end{verbatim}
will pause the script and wait until 5 seconds have passed or the player presses a key or
clicks the mouse.

\it{See Also:} \helprefn{Wait}{Wait}, \helprefn{WaitKey}{WaitKey}


\subsection{CharacterCount property}\label{Game.CharacterCount}\index{Game.CharacterCount}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.CharacterCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d characters.", Game.CharacterCount);
\end{verbatim}


\subsection{DialogCount property}\label{Game.DialogCount}\index{Game.DialogCount}%

\begin{verbatim}
readonly static int Game.DialogCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d dialogs.", Game.DialogCount);
\end{verbatim}

\it{Compatibility:} Supported by \bf{AGS 3.0.2} and later versions.


\subsection{FileName property}\label{Game.FileName}\index{Game.FileName}%

\begin{verbatim}
readonly static String Game.FileName
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The main game file is: %s", Game.FileName);
\end{verbatim}
will display the game filename.

\it{See Also:} \helprefn{Game.Name}{Game.Name}


\subsection{FontCount property}\label{Game.FontCount}\index{Game.FontCount}%

\begin{verbatim}
readonly static int Game.FontCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d fonts.", Game.FontCount);
\end{verbatim}


\subsection{GlobalMessages property}\label{Game.GlobalMessages}\index{Game.GlobalMessages}\index{GetMessageText}%

\it{(Formerly known as global function GetMessageText, which is now obsolete)}

\begin{verbatim}
readonly static String Game.GlobalMessages[int message]
\end{verbatim}
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, \it{null} will be returned. Otherwise, the
message contents will be returned.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
String message = Game.GlobalMessages[997];
Display("Global message 997 says: %s", message);
\end{verbatim}
will display global message 997.


\subsection{GlobalStrings property}\label{Game.GlobalStrings}\index{Game.GlobalStrings}\index{GetGlobalString}\index{SetGlobalString}%

\it{(Formerly known as GetGlobalString, which is now obsolete)} ILBRK
\it{(Formerly known as SetGlobalString, which is now obsolete)}

\begin{verbatim}
static String Game.GlobalStrings[index]
\end{verbatim}
Gets/sets global string \it{index}. Global strings provide you with an easy way to share
string variables between scripts. There are 50 available global strings, with \it{index}
values from 0 to 49.

\fcol{red}{Example:}
\begin{verbatim}
Game.GlobalStrings[15] = "Joe";
Display("Global string 15 is now: %s", Game.GlobalStrings[15]);
\end{verbatim}
will set global string 15 to contain "Joe".

\it{See Also:} \helprefn{GetGlobalInt}{GetGlobalInt}, \helprefn{SetGlobalInt}{SetGlobalInt}


\subsection{GUICount property}\label{Game.GUICount}\index{Game.GUICount}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.GUICount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d GUIs.", Game.GUICount);
\end{verbatim}


\subsection{IgnoreUserInputAfterTextTimeoutMs property}\label{Game.IgnoreUserInputAfterTextTimeoutMs}\index{Game.IgnoreUserInputAfterTextTimeoutMs}%

\begin{verbatim}
static int Game.IgnoreUserInputAfterTextTimeoutMs;
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Game.IgnoreUserInputAfterTextTimeoutMs = 1000;
\end{verbatim}
will tell AGS to ignore mouse clicks and key presses for 1 second after text is automatically
removed from the screen.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.MinimumTextDisplayTimeMs}{Game.MinimumTextDisplayTimeMs},
\helprefn{Game.TextReadingSpeed}{Game.TextReadingSpeed}, \helprefn{SetSkipSpeech}{SetSkipSpeech}


\subsection{InSkippableCutscene property}\label{Game.InSkippableCutscene}\index{Game.InSkippableCutscene}%

\it{(Formerly known as game.in_cutscene, which is now obsolete)}

\begin{verbatim}
static bool Game.InSkippableCutscene
\end{verbatim}
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.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example below.

\fcol{red}{Example:}
\begin{verbatim}
if (Game.InSkippableCutscene)
{
  Display("The player might never see this message!");
}
\end{verbatim}
will display a message if we are within a cutscene

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{StartCutscene}{StartCutscene}, \helprefn{EndCutscene}{EndCutscene},
\helprefn{Game.SkippingCutscene}{Game.SkippingCutscene}


\subsection{InventoryItemCount property}\label{Game.InventoryItemCount}\index{Game.InventoryItemCount}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.InventoryItemCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d inventory items.", Game.InventoryItemCount);
\end{verbatim}


\subsection{MinimumTextDisplayTimeMs property}\label{Game.MinimumTextDisplayTimeMs}\index{Game.MinimumTextDisplayTimeMs}%

\begin{verbatim}
static int Game.MinimumTextDisplayTimeMs;
\end{verbatim}
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 \helprefn{Game.TextReadingSpeed}{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.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
Game.MinimumTextDisplayTimeMs = 2000;
\end{verbatim}
will ensure that even the shortest "Hi!" text line will be displayed for at least 2 seconds

\it{Compatibility:} Supported by \bf{AGS 3.1.2} and later versions.

\it{See Also:} \helprefn{Character.SpeechAnimationDelay}{Character.SpeechAnimationDelay},
\helprefn{Game.IgnoreUserInputAfterTextTimeoutMs}{Game.IgnoreUserInputAfterTextTimeoutMs}
\helprefn{Game.TextReadingSpeed}{Game.TextReadingSpeed}


\subsection{MouseCursorCount property}\label{Game.MouseCursorCount}\index{Game.MouseCursorCount}%

\begin{verbatim}
readonly static int Game.MouseCursorCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d cursors.", Game.MouseCursorCount);
\end{verbatim}


\subsection{Name property (game)}\label{Game.Name}\index{Game.Name}%

\begin{verbatim}
static String Game.Name
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game name is: %s", Game.Name);
\end{verbatim}
will display the game name.

\it{See Also:} \helprefn{Game.FileName}{Game.FileName}


\subsection{NormalFont property}\label{Game.NormalFont}\index{Game.NormalFont}\index{SetNormalFont}%

\it{(Formerly known as global function SetNormalFont, which is now obsolete)}

\begin{verbatim}
static FontType Game.NormalFont
\end{verbatim}
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:
\begin{itemize}
\item Display
\item DisplayTopBar
\item dialog options text
\item the built-in save and restore dialogs
\end{itemize}

The Normal Font is font 0 by default.

\fcol{red}{Example:}
\begin{verbatim}
Game.NormalFont = eFontSpecial;
\end{verbatim}
will change the normal font to the font "Special".

\it{See Also:} \helprefn{Game.SpeechFont}{Game.SpeechFont}


\subsection{SkippingCutscene property}\label{Game.SkippingCutscene}\index{Game.SkippingCutscene}%

\it{(Formerly known as game.skipping_cutscene, which is now obsolete)}

\begin{verbatim}
static bool Game.SkippingCutscene
\end{verbatim}
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.

\bf{NOTE:} This is a static function, and thus need to be called with \verb$Game.$ in front of it. See
the example below.

\fcol{red}{Example:}
\begin{verbatim}
if (!Game.SkippingCutscene)
{
  aScaryMusic.Play();
  Wait(100);
  Game.StopAudio();
}
\end{verbatim}
will only attempt to play the music if the player is not skipping the cutscene.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{StartCutscene}{StartCutscene}, \helprefn{EndCutscene}{EndCutscene},
\helprefn{Game.InSkippableCutscene}{Game.InSkippableCutscene}


\subsection{SpeechFont property}\label{Game.SpeechFont}\index{Game.SpeechFont}\index{SetSpeechFont}%

\it{(Formerly known as global function SetSpeechFont, which is now obsolete)}

\begin{verbatim}
static FontType Game.SpeechFont;
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Game.SpeechFont = eFontStandard;
\end{verbatim}
will change the speech font to "Standard".

\it{See Also:} \helprefn{Game.NormalFont}{Game.NormalFont}


\subsection{SpriteHeight property}\label{Game.SpriteHeight}\index{Game.SpriteHeight}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.SpriteHeight[int slot]
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object 0's sprite is sized %d x %d.", Game.SpriteWidth[object[0].Graphic],
                                               Game.SpriteHeight[object[0].Graphic]);
\end{verbatim}

\it{See Also:} \helprefn{Game.SpriteWidth}{Game.SpriteWidth}


\subsection{SpriteWidth property}\label{Game.SpriteWidth}\index{Game.SpriteWidth}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.SpriteWidth[int slot]
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object 0's sprite is sized %d x %d.", Game.SpriteWidth[object[0].Graphic],
                                               Game.SpriteHeight[object[0].Graphic]);
\end{verbatim}

\it{See Also:} \helprefn{Game.SpriteHeight}{Game.SpriteHeight}


\subsection{TextReadingSpeed property}\label{Game.TextReadingSpeed}\index{Game.TextReadingSpeed}\index{game.text_speed}%

\it{(Formerly known as game.text_speed, which is now obsolete)}

\begin{verbatim}
static int Game.TextReadingSpeed;
\end{verbatim}
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.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
Game.TextReadingSpeed = 7;
\end{verbatim}
sets the text reading speed to half the default, which will leave speech on-screen
for twice as long as usual.

\it{Compatibility:} Supported by \bf{AGS 3.1.2} and later versions.

\it{See Also:} \helprefn{Character.SpeechAnimationDelay}{Character.SpeechAnimationDelay},
\helprefn{Game.MinimumTextDisplayTimeMs}{Game.MinimumTextDisplayTimeMs},
\helprefn{SetSkipSpeech}{SetSkipSpeech}


\subsection{TranslationFilename property}\label{Game.TranslationFilename}\index{Game.TranslationFilename}\index{GetTranslationName}%

\it{(Formerly known as GetTranslationName, which is now obsolete)}

\begin{verbatim}
readonly static String Game.TranslationFilename;
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (Game.TranslationFilename == "German") {
  Display("You are using the German translation.");
}
\end{verbatim}

\it{See Also:} \helprefn{Game.ChangeTranslation}{Game.ChangeTranslation},
\helprefn{IsTranslationAvailable}{IsTranslationAvailable}


\subsection{UseNativeCoordinates property}\label{Game.UseNativeCoordinates}\index{Game.UseNativeCoordinates}%

\begin{verbatim}
readonly static bool Game.UseNativeCoordinates
\end{verbatim}
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 \it{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.

\fcol{red}{Example:}
\begin{verbatim}
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);
}
\end{verbatim}

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.


\subsection{ViewCount property}\label{Game.ViewCount}\index{Game.ViewCount}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Game.ViewCount
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
Display("The game has %d views.", Game.ViewCount);
\end{verbatim}



\section{GUI functions and properties}\label{GUIFuncsAndProps}%



\subsection{Centre}\label{GUI.Centre}\index{GUI.Centre}\index{CentreGUI}%

\it{(Formerly known as CentreGUI, which is now obsolete)}

\begin{verbatim}
GUI.Centre()
\end{verbatim}
Centres the specified GUI in the middle of the screen. Useful if you've been moving
it around with SetPosition and just want to return it to the centre.

\fcol{red}{Example:}
\begin{verbatim}
gControlpanel.Centre();
\end{verbatim}
will centre the CONTROLPANEL GUI in the middle of the screen.

\it{See Also:} \helprefn{GUI.SetPosition}{GUI.SetPosition}


\subsection{GetAtScreenXY (GUI)}\label{GUI.GetAtScreenXY}\index{GUI.GetAtScreenXY}\index{GetGUIAt}%

\it{(Formerly known as GetGUIAt, which is now obsolete)}

\begin{verbatim}
static GUI* GUI.GetAtScreenXY(int x, int y)
\end{verbatim}
Checks whether there is currently a GUI at screen co-ordinates (X,Y). If
there is, returns its GUI. If two GUIs overlap, the frontmost one will
be returned - this can be changed with the GUI.ZOrder property.

If there is not currently a displayed, clickable GUI at the location then
\it{null} is returned. If null is returned, do NOT attempt to call any methods
or use any properties of the GUI (since it does not actually exist).

\bf{NOTE:} This command will not find any GUIs that are set as Non-Clickable (ie.
the "Clickable" checkbox not checked).

\fcol{red}{Example:}
\begin{verbatim}
GUI *theGui = GUI.GetAtScreenXY(mouse.x, mouse.y);
if (theGui == gInventory) {
  Display("Inventory GUI at mouse location.");
}
else if (theGui == null) {
  Display("No GUI at mouse location");
}
else {
  Display("GUI %d at mouse location.", theGui.ID);
}
\end{verbatim}
will display the number of the GUI that the mouse is over.

\it{See Also:} \helprefn{GUIControl.GetAtScreenXY}{GUIControl.GetAtScreenXY}, \helprefn{GUI.ID}{GUI.ID},
\helprefn{GUI.ZOrder}{GUI.ZOrder}


\subsection{SetPosition (GUI)}\label{GUI.SetPosition}\index{GUI.SetPosition}\index{SetGUIPosition}%

\it{(Formerly known as SetGUIPosition, which is now obsolete)}

\begin{verbatim}
GUI.SetPosition(int x, int y)
\end{verbatim}
Moves the top-left corner of GUI to the new location (X,Y) on the screen.
This allows you to dynamically move GUIs around on the screen while the
game is running. The co-ordinates are screen co-ordinates, not room
co-ordinates, and use the same scale as in the editor.

\fcol{red}{Example:}
\begin{verbatim}
gVerbcoin.SetPosition(mouse.x, mouse.y);
\end{verbatim}
will move the VERBCOIN GUI to the position where the cursor is.

\it{See Also:} \helprefn{GUI.Centre}{GUI.Centre}, \helprefn{GUI.BackgroundGraphic}{GUI.BackgroundGraphic},
\helprefn{GUIControl.SetPosition}{GUIControl.SetPosition}, \helprefn{GUI.SetSize}{GUI.SetSize},
\helprefn{GUI.X}{GUI.X}, \helprefn{GUI.Y}{GUI.Y}



\subsection{SetSize (GUI)}\label{GUI.SetSize}\index{GUI.SetSize}\index{SetGUISize}%

\it{(Formerly known as SetGUISize, which is now obsolete)}

\begin{verbatim}
GUI.SetSize(int width, int height)
\end{verbatim}
Changes the GUI to have the new size  WIDTH x HEIGHT

This could be useful for initially hiding an 'Advanced' part of an options screen
and such like.

The size is in the normal 320x200-resolution pixels. Setting the size to 320, 200 will
cause the GUI to take up the entire screen.

\fcol{red}{Example:}
\begin{verbatim}
gIconbar.SetSize(160, 100);
\end{verbatim}
changes the ICONBAR GUI to be the size of half the screen

\it{See Also:} \helprefn{GUI.Centre}{GUI.Centre},
\helprefn{GUI.Height}{GUI.Height},
\helprefn{GUIControl.SetPosition}{GUIControl.SetPosition},
\helprefn{GUI.SetPosition}{GUI.SetPosition},
\helprefn{GUI.Width}{GUI.Width}



\subsection{BackgroundGraphic property (GUI)}\label{GUI.BackgroundGraphic}\index{GUI.BackgroundGraphic}\index{SetGUIBackgroundPic}%

\it{(Formerly known as SetGUIBackgroundPic, which is now obsolete)}

\begin{verbatim}
int GUI.BackgroundGraphic
\end{verbatim}
Gets/sets the background image of the GUI.

You can set this to 0 to remove the background image from the GUI.

\it{See Also:} \helprefn{GUI.SetPosition}{GUI.SetPosition},
\helprefn{Button.NormalGraphic}{Button.NormalGraphic}



\subsection{Clickable property (GUI)}\label{GUI.Clickable}\index{GUI.Clickable}\index{SetGUIClickable}%

\it{(Formerly known as SetGUIClickable, which is now obsolete)}

\begin{verbatim}
bool GUI.Clickable
\end{verbatim}
Gets/sets whether the GUI is clickable or not. This allows you to modify the "Clickable"
checkbox from the GUI Editor.

If this is set to 1, then the GUI will respond to mouse clicks as normal.

If this is set to 0, then this GUI cannot be clicked on by the mouse. This might be
useful for a transparent overlay GUI which displays information, and you want the
player to be able to click on whatever is underneath.

\fcol{red}{Example:}
\begin{verbatim}
gStatusline.Clickable = false;
\end{verbatim}
sets the STATUSLINE GUI to no longer respond to mouse clicks.

\it{See Also:} \helprefn{GUI.GetAtScreenXY}{GUI.GetAtScreenXY}


\subsection{ControlCount property}\label{GUI.ControlCount}\index{GUI.ControlCount}%

\begin{verbatim}
readonly int GUI.ControlCount;
\end{verbatim}
Gets the number of controls on the GUI. You won't normally need to use this property,
but in some circumstances you may wish to iterate through all the GUI's controls,
and this allows you to determine where to stop.

\fcol{red}{Example:}
\begin{verbatim}
int i = 0;
while (i < gInventory.ControlCount) {
  gInventory.Controls[i].Enabled = false;
  i++;
}
\end{verbatim}
disables all controls on the INVENTORY GUI.

\it{See Also:} \helprefn{GUI.Controls}{GUI.Controls}


\subsection{Controls property (GUI)}\label{GUI.Controls}\index{GUI.Controls}%

\begin{verbatim}
GUIControl* GUI.Controls[index]
\end{verbatim}
Provides an array which allows you to access controls on the GUI by their index. You should
not normally need to do this, since accessing the controls by their name is far easier;
however, if you need to interoperate with legacy code that uses the control number, this
can come in useful.

Returns the GUIControl object for the specified control index, or \it{null} if you
give an invalid control index.

You can cast the GUIControl to the appropriate type using the AsButton, AsListBox, etc
methods on it.

\fcol{red}{Example:}
\begin{verbatim}
GUIControl *control = gInventory.Controls[4];
if (control == null) {
  Display("The inventory GUI doesn't have a control number 4.");
}
else {
  control.Enabled = true;
  control.AsListBox.AddItem("New item!!");
}
\end{verbatim}
gets list box number 4 from the INVENTORY GUI, and then adds an item to it.
If control 4 isn't a listbox, you will get a Null Reference error.

\it{See Also:} \helprefn{GUIControl.As*}{GUIControl.AsType},
\helprefn{GUI.ControlCount}{GUI.ControlCount}


\subsection{Height property (GUI)}\label{GUI.Height}\index{GUI.Height}%

\begin{verbatim}
int GUI.Height
\end{verbatim}
Gets/sets the height of the GUI. This allows you to dynamically change the size
of the GUI on the screen.

The height is specified in the normal 320-resolution style.

\fcol{red}{Example:}
\begin{verbatim}
Display("The icon bar GUI is %d pixels high.", gIconbar.Height);
\end{verbatim}
displays the height of the ICONBAR GUI.

\it{See Also:} \helprefn{GUI.SetSize}{GUI.SetSize}, \helprefn{GUI.Width}{GUI.Width}


\subsection{ID property (GUI)}\label{GUI.ID}\index{GUI.ID}%

\begin{verbatim}
readonly int GUI.ID
\end{verbatim}
Gets the GUI's ID number. This is the GUI's number from the editor, and is useful
if you need to interoperate with legacy code that uses the GUI's number rather than
object name.

\fcol{red}{Example:}
\begin{verbatim}
SetGUIClickable(gIconbar.ID, 1);
gIconbar.Clickable = false;
\end{verbatim}
uses the obsolete SetGUIClickable function to make the ICONBAR GUI clickable,
and then uses the equivalent modern property to stop it being clickable.

\it{See Also:} \helprefn{GUIControl.ID}{GUIControl.ID}


\subsection{Transparency property (GUI)}\label{GUI.Transparency}\index{GUI.Transparency}\index{SetGUITransparency}%

\it{(Formerly known as SetGUITransparency, which is now obsolete)}

\begin{verbatim}
int GUI.Transparency
\end{verbatim}
Gets/sets the GUI translucency, in percent.

Setting this to 100 means the GUI is totally invisible, and lower values
represent varying levels of translucency. Set it to 0 to stop the
GUI being translucent.

\bf{NOTE:} Transparency only works in 16-bit and 32-bit colour games.

\bf{NOTE:} When using the DirectX 5 driver, a large transparent GUI can significantly slow
down AGS.

Some rounding is done internally when the transparency is stored -- therefore, if you get
the transparency after setting it, the value you get back might be one out. Therefore, using
a loop with \verb$gInventory.Transparency++;$ is not recommended as it will probably
end too quickly.

In order to fade a GUI in/out, the best approach is shown in the example below:

\fcol{red}{Example:}
\begin{verbatim}
int trans = gInventory.Transparency;
while (trans < 100) {
  trans++;
  gInventory.Transparency = trans;
  Wait(1);
}
\end{verbatim}
will gradually fade the INVENTORY GUI out until it is invisible.

\it{See Also:} \helprefn{Object.Transparency}{Object.Transparency}


\subsection{Visible property (GUI)}\label{GUI.Visible}\index{GUI.Visible}\index{InterfaceOff}\index{InterfaceOn}\index{GUIOff}\index{GUIOn}\index{IsGUIOn}%

\it{(Formerly known as GUIOff, which is now obsolete)}ILBRK
\it{(Formerly known as GUIOn, which is now obsolete)}ILBRK
\it{(Formerly known as InterfaceOff, which is now obsolete)}ILBRK
\it{(Formerly known as InterfaceOn, which is now obsolete)}ILBRK
\it{(Formerly known as IsGUIOn, which is now obsolete)}

\begin{verbatim}
bool GUI.Visible
\end{verbatim}
Gets/sets whether the GUI is visible or not. This property has behaves
differently depending on the GUI popup style.

For "Normal" and "Persistent" GUIs, this property simply switches the GUI
on and off, and has no further effects.

For "Popup modal" GUIs, setting Visible to true causes the game to become paused
until the GUI is removed by setting Visible back to false (eg. when the user
presses an OK button or something similar).

For "Mouse Ypos" GUIs, the Visible property does not actually determine whether
the GUI can be seen, but instead it controls whether the GUI \bf{is allowed to} pop up.
If Visible is \it{false}, then moving the mouse to the top of the screen will not activate
the GUI; if it is \it{true}, then the GUI will be allowed to be popped up.

\fcol{red}{Example:}
\begin{verbatim}
gSettings.Visible = true;
\end{verbatim}
will turn on the SETTINGS GUI.

\it{See Also:} \helprefn{IsGamePaused}{IsGamePaused}


\subsection{Width property (GUI)}\label{GUI.Width}\index{GUI.Width}%

\begin{verbatim}
int GUI.Width
\end{verbatim}
Gets/sets the width of the GUI. This allows you to dynamically change the size
of the GUI on the screen.

The width is specified in the normal 320-resolution style.

\fcol{red}{Example:}
\begin{verbatim}
gInventory.Width += 5;
\end{verbatim}

makes the INVENTORY GUI 5 pixels wider.

\it{See Also:} \helprefn{GUI.Height}{GUI.Height}, \helprefn{GUI.SetSize}{GUI.SetSize}


\subsection{X property (GUI)}\label{GUI.X}\index{GUI.X}%

\begin{verbatim}
int GUI.X
\end{verbatim}
Gets/sets the X position of the GUI. This allows you to dynamically change the position
of the GUI on the screen.

The X position is the left-hand side of the GUI, and can be between 0 and 320. The
co-ordinates used are screen co-ordinates, not room co-ordinates, and are in the normal
320-resolution style.

\fcol{red}{Example:}
\begin{verbatim}
gVerbcoin.X += 5;
\end{verbatim}

moves the VERBCOIN GUI right 5 pixels.

\it{See Also:} \helprefn{GUI.SetPosition}{GUI.SetPosition}, \helprefn{GUI.Y}{GUI.Y}


\subsection{Y property (GUI)}\label{GUI.Y}\index{GUI.Y}%

\begin{verbatim}
int GUI.Y
\end{verbatim}
Gets/sets the Y position of the GUI. This allows you to dynamically change the position
of the GUI on the screen.

The Y position is the top edge of the GUI, and can be between 0 and 200 (or 240, depending
on room height). The co-ordinates used are screen co-ordinates, not room co-ordinates,
and are in the normal 320x200-resolution style.

\fcol{red}{Example:}
\begin{verbatim}
gVerbcoin.Y += 5;
\end{verbatim}

moves the VERBCOIN GUI down 5 pixels.

\it{See Also:} \helprefn{GUI.SetPosition}{GUI.SetPosition}, \helprefn{GUI.X}{GUI.X}


\subsection{ZOrder property}\label{GUI.ZOrder}\index{GUI.ZOrder}\index{SetGUIZOrder}%

\it{(Formerly known as SetGUIZOrder, which is now obsolete)}

\begin{verbatim}
int GUI.ZOrder
\end{verbatim}
Gets/sets the z-order of the GUI. This allows you to dynamically change the ordering
of GUIs on the screen.

The Z-order setting is an arbitrary number between 0 and 1000. AGS draws the GUIs
in order, from the lowest numbered at the back to the highest numbered at the front.

\fcol{red}{Example:}
\begin{verbatim}
gStatusline.ZOrder = 0;
\end{verbatim}

sets the STATUSLINE GUI to be behind all other GUIs.

\it{See Also:} \helprefn{GUI.GetAtScreenXY}{GUI.GetAtScreenXY}




\section{GUI control functions and properties}

This section lists the functions and properties common to all types of GUI control.
Each individual control type (Button, ListBox, etc) also has its own specific section.


\subsection{GetAtScreenXY (GUI control)}\label{GUIControl.GetAtScreenXY}\index{GUIControl.GetAtScreenXY}\index{GetGUIObjectAt}%

\it{(Formerly known as GetGUIObjectAt, which is now obsolete)}

\begin{verbatim}
static GUIControl* GUIControl.GetAtScreenXY(int x, int y)
\end{verbatim}
Checks whether there is a GUI control at screen co-ordinates (X,Y). Returns
the control object if there is, or null if there is not. You probably
want to use this in conjunction with GetGUIAtLocation.

\fcol{red}{Example:}
\begin{verbatim}
GUIControl *theControl = GUIControl.GetAtScreenXY(mouse.x, mouse.y);
if (theControl == lstSaveGames) {
  Display("The mouse is over the Save Games list box.");
}
else if (theControl == null) {
  Display("The mouse is not over a control.");
}
else {
  GUI *onGui = theControl.OwningGUI;
  Display("The mouse is over control %d on GUI %d.", theControl.ID, onGui.ID);
}
\end{verbatim}
will display what control the mouse is over.

\it{See Also:} \helprefn{GUI.GetAtScreenXY}{GUI.GetAtScreenXY}


\subsection{AsType properties (GUI controls)}\label{GUIControl.AsType}\index{GUIControl.AsButton}\index{GUIControl.AsInvWindow}\index{GUIControl.AsLabel}\index{GUIControl.AsListBox}\index{GUIControl.AsSlider}\index{GUIControl.AsTextBox}%

\begin{verbatim}
Button*  GUIControl.AsButton;
InvWindow* GUIControl.AsInvWindow;
Label*   GUIControl.AsLabel;
ListBox* GUIControl.AsListBox;
Slider*  GUIControl.AsSlider;
TextBox* GUIControl.AsTextBox;
\end{verbatim}
Converts a generic GUIControl* pointer into a variable of the correct type, and returns
it. If the control is not of the requested type, returns \it{null}.

\fcol{red}{Example:}
\begin{verbatim}
Button *theButton = gIconbar.Controls[2].AsButton;
if (theButton == null) {
  Display("Control 2 is not a button!!!!");
}
else {
  theButton.NormalGraphic = 44;
}
\end{verbatim}
attempts to set Button 2 on GUI ICONBAR to have NormalGraphic 44, but if that
control is not a button, prints a message.

\it{See Also:} \helprefn{GUI.Controls}{GUI.Controls}


\subsection{BringToFront (GUI controls)}\label{GUIControl.BringToFront}\index{Button.BringToFront}\index{InvWindow.BringToFront}\index{Label.BringToFront}\index{ListBox.BringToFront}\index{Slider.BringToFront}\index{TextBox.BringToFront}%

\begin{verbatim}
GUIControl.BringToFront()
\end{verbatim}
Brings this control to the front of the Z-order. This allows you to rearrange the display order
of controls within the GUI.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnBigButton.BringToFront();
\end{verbatim}
will move the \it{btnBigButton} button to be in front of all other controls on the GUI.

\it{See Also:} \helprefn{GUIControl.SendToBack}{GUIControl.SendToBack}


\subsection{Clickable property (GUI controls)}\label{GUIControl.Clickable}\index{Button.Clickable}\index{InvWindow.Clickable}\index{Label.Clickable}\index{ListBox.Clickable}\index{Slider.Clickable}\index{TextBox.Clickable}%

\begin{verbatim}
bool GUIControl.Clickable
\end{verbatim}
Gets/sets whether the GUI control is clickable.

This property determines whether the player can click the mouse on the control. If it is set to \it{false},
then any mouse clicks will go straight through the control onto whatever is behind it. Unlike the Enabled
property though, setting Clickable to false does not alter the appearance of the control.

Note that disabling the control by setting Enabled to false overrides this setting -- that is, if Enabled
is false then the control will not be clickable, regardless of the \it{Clickable} setting.

Also, bear in mind that if you set \it{Clickable} to false then any mouse clicks will go through the control
onto whatever is behind. On the other hand, if \it{Enabled} is set to false then the control "absorbs"
the mouse click but does not do anything with it.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnSaveGame.Clickable = false;
\end{verbatim}
will make the \it{btnSaveGame} button non-clickable.

\it{See Also:} \helprefn{GUIControl.Enabled}{GUIControl.Enabled}


\subsection{Enabled property (GUI controls)}\label{GUIControl.Enabled}\index{Button.Enabled}\index{InvWindow.Enabled}\index{Label.Enabled}\index{ListBox.Enabled}\index{Slider.Enabled}\index{TextBox.Enabled}\index{SetGUIObjectEnabled}%

\it{(Formerly known as SetGUIObjectEnabled, which is now obsolete)}

\begin{verbatim}
bool GUIControl.Enabled
\end{verbatim}
Enables or disables a GUI control. 

Normally, all your GUI controls (such as buttons, sliders, etc) are enabled at all times
except during a cutscene, when they are disabled. This command allows you to explicitly
disable a control at your script's discretion.

If you set this to true, the control will be enabled; set to false to disable it.

Whether you set it as enabled or not, it will \bf{always} be disabled during a blocking
cutscene, along with all the other controls.

While a control is disabled, it will not respond to mouse clicks. If it is a button, its
mouseover and pushed pictures will not be shown. The control will be drawn according to
the game "When GUI Disabled" settings, as usual.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnSaveGame.Enabled = false;
\end{verbatim}
will disable the \it{btnSaveGame} button.

\it{See Also:} \helprefn{GUIControl.Clickable}{GUIControl.Clickable},
\helprefn{GUIControl.Visible}{GUIControl.Visible}


\subsection{Height property (GUI controls)}\label{GUIControl.Height}\index{Button.Height}\index{InvWindow.Height}\index{Label.Height}\index{ListBox.Height}\index{Slider.Height}\index{TextBox.Height}%

\begin{verbatim}
int GUIControl.Height;
\end{verbatim}
Gets/sets the height of the GUI control.  This allows you to dynamically
resize GUI controls while the game is running.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnConfirm.Height = 20;
\end{verbatim}
makes the \it{btnConfirm} button 20 pixels high.

\it{See Also:} \helprefn{GUIControl.SetSize}{GUIControl.SetSize},
\helprefn{GUIControl.Width}{GUIControl.Width}


\subsection{ID property (GUI controls)}\label{GUIControl.ID}\index{Button.ID}\index{InvWindow.ID}\index{Label.ID}\index{ListBox.ID}\index{Slider.ID}\index{TextBox.ID}%

\begin{verbatim}
readonly int GUIControl.ID
\end{verbatim}
Gets the GUI control's ID number. This is the control's object number from the GUI editor,
and is useful if you need to interoperate with legacy code that uses the control's number
rather than object name.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
SetGUIObjectEnabled(lstSaves.OwningGUI.ID, lstSaves.ID, 1);
lstSaves.Enabled = false;
\end{verbatim}
uses the obsolete SetGUIObjectEnabled function to enable the lstSaves list box,
and then uses the equivalent modern property to disable it.

\it{See Also:} \helprefn{GUIControl.OwningGUI}{GUIControl.OwningGUI}, \helprefn{GUI.ID}{GUI.ID}



\subsection{OwningGUI property (GUI controls)}\label{GUIControl.OwningGUI}\index{Button.OwningGUI}\index{InvWindow.OwningGUI}\index{Label.OwningGUI}\index{ListBox.OwningGUI}\index{Slider.OwningGUI}\index{TextBox.OwningGUI}%

\begin{verbatim}
readonly GUI* GUIControl.OwningGUI
\end{verbatim}
Gets the GUI control's owning GUI, which is the GUI that contains the control.

Returns a GUI, which allows you to use all the usual
\helprefn{GUI functions and properties}{GUIFuncsAndProps}.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
GUI *thegui = lstSaves.OwningGUI;
thegui.Visible = false;

lstSaves.OwningGUI.Visible = true;
\end{verbatim}
turns off the GUI that contains the lstSaves list box, then turns it on again using
the niftier full pathing approach.

\it{See Also:} \helprefn{GUIControl.ID}{GUIControl.ID}, \helprefn{GUI.ID}{GUI.ID}


\subsection{SendToBack (GUI controls)}\label{GUIControl.SendToBack}\index{Button.SendToBack}\index{InvWindow.SendToBack}\index{Label.SendToBack}\index{ListBox.SendToBack}\index{Slider.SendToBack}\index{TextBox.SendToBack}%

\begin{verbatim}
GUIControl.SendToBack()
\end{verbatim}
Sends this control to the back of the Z-order. This allows you to rearrange the display order
of controls within the GUI.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnBigButton.SendToBack();
\end{verbatim}
will move the \it{btnBigButton} button to be behind all other controls on the GUI.

\it{See Also:} \helprefn{GUIControl.BringToFront}{GUIControl.BringToFront}


\subsection{SetPosition (GUI controls)}\label{GUIControl.SetPosition}\index{Button.SetPosition}\index{InvWindow.SetPosition}\index{Label.SetPosition}\index{ListBox.SetPosition}\index{Slider.SetPosition}\index{TextBox.SetPosition}\index{SetGUIObjectPosition}%

\it{(Formerly known as SetGUIObjectPosition, which is now obsolete)}

\begin{verbatim}
GUIControl.SetPosition(int x, int y)
\end{verbatim}
Moves the top-left corner of the GUI control to be at (X,Y). These co-ordinates
are relative to the GUI which contains the control.

This allows you to dynamically move GUI controls around on the screen while the
game is running, and this may well be useful in conjunction with GUI.SetSize if you
want to create dynamically resizable GUIs.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnConfirm.SetPosition(40, 10);
\end{verbatim}
will move the \it{btnConfirm} button to be positioned at (40,10) within the GUI.

\it{See Also:} \helprefn{GUIControl.Enabled}{GUIControl.Enabled},
\helprefn{GUI.SetPosition}{GUI.SetPosition}, \helprefn{GUIControl.SetSize}{GUIControl.SetSize},
\helprefn{GUIControl.X}{GUIControl.X}, \helprefn{GUIControl.Y}{GUIControl.Y}


\subsection{SetSize (GUI controls)}\label{GUIControl.SetSize}\index{Button.SetSize}\index{InvWindow.SetSize}\index{Label.SetSize}\index{ListBox.SetSize}\index{Slider.SetSize}\index{TextBox.SetSize}\index{SetGUIObjectSize}%

\it{(Formerly known as SetGUIObjectSize, which is now obsolete)}

\begin{verbatim}
GUIControl.SetSize(int width, int height)
\end{verbatim}
Adjusts the specified GUI control to have the new size WIDTH x HEIGHT.

This allows you to dynamically resize GUI controls on the screen while the
game is running, and this may well be useful in conjunction with GUI.SetSize and
GUIControl.SetPosition if you want to create dynamically resizable GUIs.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
invMain.SetSize(160, 100);
\end{verbatim}
will resize the \it{invMain} control to have a size of 160 x 100.

\it{See Also:} \helprefn{GUIControl.Height}{GUIControl.Height},
\helprefn{GUIControl.SetPosition}{GUIControl.SetPosition},
\helprefn{GUI.SetSize}{GUI.SetSize},
\helprefn{GUIControl.Width}{GUIControl.Width},


\subsection{Visible property (GUI controls)}\label{GUIControl.Visible}\index{Button.Visible}\index{InvWindow.Visible}\index{Label.Visible}\index{ListBox.Visible}\index{Slider.Visible}\index{TextBox.Visible}%

\begin{verbatim}
bool GUIControl.Visible
\end{verbatim}
Gets/sets whether the GUI control is visible. This is \it{true} by default, but you
can set it to \it{false} in order to temporarily remove the GUI control from the GUI.

While the control is invisible, it will not be drawn on the screen, and will not register
clicks or otherwise respond to any user input.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnSaveGame.Visible = false;
\end{verbatim}
will make the \it{btnSaveGame} button invisible.

\it{See Also:} \helprefn{GUIControl.Enabled}{GUIControl.Enabled}


\subsection{Width property (GUI controls)}\label{GUIControl.Width}\index{Button.Width}\index{InvWindow.Width}\index{Label.Width}\index{ListBox.Width}\index{Slider.Width}\index{TextBox.Width}%

\begin{verbatim}
int GUIControl.Width;
\end{verbatim}
Gets/sets the width of the GUI control.  This allows you to dynamically
resize GUI controls while the game is running.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnConfirm.Width = 110;
\end{verbatim}
makes the \it{btnConfirm} button 110 pixels wide.

\it{See Also:} \helprefn{GUIControl.Height}{GUIControl.Height},
\helprefn{GUIControl.SetSize}{GUIControl.SetSize}


\subsection{X property (GUI controls)}\label{GUIControl.X}\index{Button.X}\index{InvWindow.X}\index{Label.X}\index{ListBox.X}\index{Slider.X}\index{TextBox.X}%

\begin{verbatim}
int GUIControl.X;
\end{verbatim}
Gets/sets the X position of the GUI control. This specifies its left edge, and is
relative to the GUI which contains the control.

This allows you to dynamically move GUI controls around on their parent GUI while the
game is running.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnConfirm.X = 10;
\end{verbatim}
will move the \it{btnConfirm} button to be positioned 10 pixels from the left of its GUI.

\it{See Also:} \helprefn{GUIControl.SetPosition}{GUIControl.SetPosition},
\helprefn{GUIControl.Y}{GUIControl.Y}


\subsection{Y property (GUI controls)}\label{GUIControl.Y}\index{Button.Y}\index{InvWindow.Y}\index{Label.Y}\index{ListBox.Y}\index{Slider.Y}\index{TextBox.Y}%

\begin{verbatim}
int GUIControl.Y;
\end{verbatim}
Gets/sets the Y position of the GUI control. This specifies its top edge, and is
relative to the GUI which contains the control.

This allows you to dynamically move GUI controls around on their parent GUI while the
game is running.

\bf{Applies To}

Inherited by the Button, InvWindow, Label, ListBox, Slider and TextBox.

\fcol{red}{Example:}
\begin{verbatim}
btnConfirm.Y = 20;
\end{verbatim}
will move the \it{btnConfirm} button to be positioned 20 pixels from the top of its GUI.

\it{See Also:} \helprefn{GUIControl.SetPosition}{GUIControl.SetPosition},
\helprefn{GUIControl.X}{GUIControl.X}



\section{GUI Button functions and properties}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{Animate (button)}\label{Button.Animate}\index{Button.Animate}\index{AnimateButton}%

\it{(Formerly known as AnimateButton, which is now obsolete)}

\begin{verbatim}
Button.Animate(int view, int loop, int delay, RepeatStyle)
\end{verbatim}
Animates a GUI button by playing the specified view loop on it. This could be
useful for Sierra-style death animations and other effects.

LOOP from VIEW will be played on the button. The DELAY specifies the speed of
the animation - larger numbers are slower. This has the same values you use
with the Character.Animate and Object.Animate commands.

REPEAT determines whether the animation will loop repeatedly, or just play once and stop
with the last frame showing (eOnce or eRepeat are the possible values).

You can abort an animation at any time by setting the button's NormalGraphic property, or
starting a new animation on the same button.

\bf{NOTE:} This command destroys the button's normal, pushed and mouseover images. If you
want to return the button to normal usage after playing an animation, you will have to set
the Graphic properties to restore the images.

\bf{NOTE:} This command does not support flipped view frames. Any frames marked as "Flipped"
will in fact be drawn normally when on a button.

\fcol{red}{Example:}
\begin{verbatim}
btnDeathAnim.Animate(6, 2, 4, eRepeat);
\end{verbatim}
will animate the 'btnDeathAnim' button using loop 2 of view 6, with a delay of 4
cycles per frame, and repeat the animation continually.

\it{See Also:} \helprefn{Button.NormalGraphic}{Button.NormalGraphic}


\subsection{ClipImage property}\label{Button.ClipImage}\index{Button.ClipImage}%

\begin{verbatim}
bool Button.ClipImage;
\end{verbatim}
Gets/sets whether the button clips its image to the button boundaries.

For example, if the button is sized 30x30, but its Graphic is a 50x50 image, then
this property controls whether the image is allowed to spill over the edge of the button.

The default is false, ie. the image is not clipped.

Setting this to true can be useful in that it ensures that the button's image is not larger
than the button's clickable area, which can cause confusion when it happens.

\fcol{red}{Example:}
\begin{verbatim}
btnOK.ClipImage = true;
\end{verbatim}
sets the \it{btnOK} button so that its image will be restrained to the button's clickable area.

\it{See Also:} \helprefn{Button.Graphic}{Button.Graphic}


\subsection{Font property (button)}\label{Button.Font}\index{Button.Font}%

\begin{verbatim}
FontType Button.Font
\end{verbatim}
Gets/sets the font used by the button to display text.

The font number must correspond to one of the fonts from the Fonts pane in the AGS Editor.

\fcol{red}{Example:}
\begin{verbatim}
btnOK.Font = eFontMain;
\end{verbatim}
will change the \it{btnOK} button to use Font "Main".

\it{See Also:} \helprefn{Label.Font}{Label.Font}, \helprefn{TextBox.Font}{TextBox.Font}


\subsection{Graphic property (button)}\label{Button.Graphic}\index{Button.Graphic}\index{GetButtonPic}%

\it{(Formerly part of GetButtonPic, which is now obsolete)}

\begin{verbatim}
readonly int Button.Graphic;
\end{verbatim}
Gets the current image on a GUI button. If a value less than 1 is returned,
then no image is currently displayed on the button.

This property is read-only; in order to set the image, you must use one of the 
\helprefn{NormalGraphic}{Button.NormalGraphic},
\helprefn{MouseOverGraphic}{Button.MouseOverGraphic} or
\helprefn{PushedGraphic}{Button.PushedGraphic} properties.

\fcol{red}{Example:}
\begin{verbatim}
Display("The button is currently using sprite %d.", btnPlay.Graphic);
\end{verbatim}
will display btnPlay's current sprite number.

\it{See Also:} \helprefn{Button.ClipImage}{Button.ClipImage},
\helprefn{Button.MouseOverGraphic}{Button.MouseOverGraphic},
\helprefn{Button.NormalGraphic}{Button.NormalGraphic},
\helprefn{Button.PushedGraphic}{Button.PushedGraphic}


\subsection{MouseOverGraphic property (button)}\label{Button.MouseOverGraphic}\index{Button.MouseOverGraphic}\index{GetButtonPic}\index{SetButtonPic}%

\it{(Formerly part of GetButtonPic, which is now obsolete)} ILBRK
\it{(Formerly part of SetButtonPic, which is now obsolete)}

\begin{verbatim}
int Button.MouseOverGraphic;
\end{verbatim}
Gets/sets the button's mouse-over sprite. This can be -1, which indicates that the button
does not have a mouse-over graphic.

\fcol{red}{Example:}
\begin{verbatim}
Display("The button's mouse-over image is sprite %d.", btnPlay.MouseOverGraphic);
\end{verbatim}
will display btnPlay's mouse-over sprite number.

\it{See Also:} \helprefn{Button.Graphic}{Button.Graphic},
\helprefn{Button.NormalGraphic}{Button.NormalGraphic},
\helprefn{Button.PushedGraphic}{Button.PushedGraphic}


\subsection{NormalGraphic property (button)}\label{Button.NormalGraphic}\index{Button.NormalGraphic}\index{GetButtonPic}\index{SetButtonPic}%

\it{(Formerly part of GetButtonPic, which is now obsolete)} ILBRK
\it{(Formerly part of SetButtonPic, which is now obsolete)}

\begin{verbatim}
int Button.NormalGraphic;
\end{verbatim}
Gets/sets the button's normal sprite (ie. the graphic used when the button is not pushed
and the mouse is not over it).

Note that setting this to a different sprite will change the button's size to match the size of the new sprite.

\fcol{red}{Example:}
\begin{verbatim}
Display("The button's normal image is sprite %d.", btnPlay.NormalGraphic);
\end{verbatim}
will display btnPlay's normal sprite number.

\it{See Also:} \helprefn{Button.ClipImage}{Button.ClipImage}
\helprefn{Button.Graphic}{Button.Graphic},
\helprefn{Button.MouseOverGraphic}{Button.MouseOverGraphic},
\helprefn{Button.PushedGraphic}{Button.PushedGraphic},
\helprefn{Button.TextColor}{Button.TextColor}


\subsection{PushedGraphic property (button)}\label{Button.PushedGraphic}\index{Button.PushedGraphic}\index{GetButtonPic}\index{SetButtonPic}%

\it{(Formerly part of GetButtonPic, which is now obsolete)} ILBRK
\it{(Formerly part of SetButtonPic, which is now obsolete)}

\begin{verbatim}
int Button.PushedGraphic;
\end{verbatim}
Gets/sets the button's pushed sprite (ie. the graphic used when the button is pushed
in by the user). This can be -1, which indicates that the button does not have a pushed
image.

\fcol{red}{Example:}
\begin{verbatim}
Display("The button's pushed image is sprite %d.", btnPlay.PushedGraphic);
\end{verbatim}
will display btnPlay's pushed sprite number.

\it{See Also:} \helprefn{Button.Graphic}{Button.Graphic},
\helprefn{Button.MouseOverGraphic}{Button.MouseOverGraphic},
\helprefn{Button.NormalGraphic}{Button.NormalGraphic}


\subsection{Text property (button)}\label{Button.Text}\index{Button.Text}\index{SetButtonText}\index{Button.SetText}\index{Button.GetText}%

\it{(Formerly known as SetButtonText, which is now obsolete)} ILBRK
\it{(Formerly known as Button.GetText, which is now obsolete)} ILBRK
\it{(Formerly known as Button.SetText, which is now obsolete)}

\begin{verbatim}
String Button.Text;
\end{verbatim}
Gets/sets the text displayed on the button.

\fcol{red}{Example:}
\begin{verbatim}
Display("Button displayed: %s", btnController.Text);
btnController.Text = "Enable jibble";
\end{verbatim}
will display the old text, then change button btnController to read 'Enable jibble'.

\it{See Also:} \helprefn{Button.NormalGraphic}{Button.NormalGraphic}, \helprefn{Label.Text}{Label.Text}


\subsection{TextColor property (button)}\label{Button.TextColor}\index{Button.TextColor}%

\begin{verbatim}
int Button.TextColor;
\end{verbatim}
Gets/sets the text colour used to display the button's text. 

If the button is displaying an image rather than text, then this property has no effect.

\fcol{red}{Example:}
\begin{verbatim}
btnRestart.TextColor = 15;
\end{verbatim}
will change button 'btnRestart' to have white text.

\it{See Also:} \helprefn{Button.NormalGraphic}{Button.NormalGraphic}



\section{GUI InvWindow functions and properties}\label{GUIInvFuncs}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{ScrollDown (inv window)}\label{InvWindow.ScrollDown}\index{InvWindow.ScrollDown}%

\begin{verbatim}
InvWindow.ScrollDown()
\end{verbatim}
Scrolls the inventory window down one line, if there are more items to display.
If the inventory window is already at the bottom, then nothing happens.

You would usually use this in response to a GUI button press on a Down arrow button
on your GUI.

\fcol{red}{Example:}
\begin{verbatim}
invMain.ScrollDown();
\end{verbatim}
will scroll the \it{invMain} inv window down one row.

\it{See Also:} \helprefn{InvWindow.ScrollUp}{InvWindow.ScrollUp},
\helprefn{InvWindow.TopItem}{InvWindow.TopItem}


\subsection{ScrollUp (inv window)}\label{InvWindow.ScrollUp}\index{InvWindow.ScrollUp}%

\begin{verbatim}
InvWindow.ScrollUp()
\end{verbatim}
Scrolls the inventory window up one line, if there are more items to display.
If the inventory window is already at the top, then nothing happens.

You would usually use this in response to a GUI button press on an Up arrow button
on your GUI.

\fcol{red}{Example:}
\begin{verbatim}
invMain.ScrollUp();
\end{verbatim}
will scroll the \it{invMain} inv window up one row.

\it{See Also:} \helprefn{InvWindow.ScrollDown}{InvWindow.ScrollDown},
\helprefn{InvWindow.TopItem}{InvWindow.TopItem}


\subsection{CharacterToUse property}\label{InvWindow.CharacterToUse}\index{InvWindow.CharacterToUse}%

\begin{verbatim}
Character* InvWindow.CharacterToUse;
\end{verbatim}
Gets/sets which character the inventory window is currently displaying the inventory
for. This is either set to a specific character, or it can be set to \it{null}, in which
case the inventory window will track the current player character (this is the default).

\fcol{red}{Example:}
\begin{verbatim}
invMain.CharacterToUse = cJack;
\end{verbatim}
will change the \it{invMain} inventory window to display character JACK's inventory.


\subsection{ItemAtIndex property}\label{InvWindow.ItemAtIndex}\index{InvWindow.ItemAtIndex}%

\begin{verbatim}
readonly InventoryItem* InvWindow.ItemAtIndex[];
\end{verbatim}
Gets the inventory item that is currently displayed at the specified index in this
inventory window. The number of items in the window can be retrieved with the
\helprefn{ItemCount}{InvWindow.ItemCount} property. Indexes range from 0 to ItemCount - 1.

If an invalid index is supplied, \it{null} is returned.

\fcol{red}{Example:}
\begin{verbatim}
String firstOne = invMain.ItemAtIndex[0].Name;
Display("First item is %s.", firstOne);
\end{verbatim}
will display the name of the first item displayed in the \it{invMain} inventory window.

\it{See Also:} \helprefn{InvWindow.ItemCount}{InvWindow.ItemCount}


\subsection{ItemCount property (inv window)}\label{InvWindow.ItemCount}\index{InvWindow.ItemCount}%

\it{(Formerly known as game.num_inv_items, which is now obsolete)}

\begin{verbatim}
readonly int InvWindow.ItemCount;
\end{verbatim}
Gets the total number of items contained in the inventory window. This will tend
to equal the total number of items that the character has (though it may not if
the "Display multiple items multiple times" game setting is not checked).

\fcol{red}{Example:}
\begin{verbatim}
if (invMain.ItemCount > (invMain.ItemsPerRow * invMain.RowCount)) {
  btnInvUp.Enabled = true;
  btnInvDown.Enabled = false;
}
\end{verbatim}
will enable the GUI buttons \it{btnInvUp} and \it{btnInvDown} if there are more
inventory items than will fit in the inventory window.

\it{See Also:} \helprefn{InvWindow.ItemAtIndex}{InvWindow.ItemAtIndex},
\helprefn{InvWindow.ItemsPerRow}{InvWindow.ItemsPerRow},
\helprefn{InvWindow.RowCount}{InvWindow.RowCount}


\subsection{ItemHeight property}\label{InvWindow.ItemHeight}\index{InvWindow.ItemHeight}\index{SetInvDimensions}%

\it{(Formerly known as SetInvDimensions, which is now obsolete)}

\begin{verbatim}
int InvWindow.ItemHeight;
\end{verbatim}
Gets/sets the height of the rows in the inventory window. You should generally set this
up in game_start to the height of your largest inventory item. The default is 22.

\fcol{red}{Example:}
\begin{verbatim}
invMain.ItemWidth = 50;
invMain.ItemHeight = 30;
\end{verbatim}
sets the \it{invMain} inventory window to use item cells 50x30 large.

\it{See Also:} \helprefn{InvWindow.ItemWidth}{InvWindow.ItemWidth},
\helprefn{InvWindow.RowCount}{InvWindow.RowCount}


\subsection{ItemWidth property}\label{InvWindow.ItemWidth}\index{InvWindow.ItemWidth}\index{SetInvDimensions}%

\it{(Formerly known as SetInvDimensions, which is now obsolete)}

\begin{verbatim}
int InvWindow.ItemWidth;
\end{verbatim}
Gets/sets the width of the items in the inventory window. You should generally set this
up in game_start to the width of your largest inventory item. The default is 40.

\fcol{red}{Example:}
\begin{verbatim}
invMain.ItemWidth = 50;
invMain.ItemHeight = 30;
\end{verbatim}
sets the \it{invMain} inventory window to use item cells 50x30 large.

\it{See Also:} \helprefn{InvWindow.ItemHeight}{InvWindow.ItemHeight},
\helprefn{InvWindow.ItemsPerRow}{InvWindow.ItemsPerRow}


\subsection{ItemsPerRow property}\label{InvWindow.ItemsPerRow}\index{InvWindow.ItemsPerRow}%

\it{(Formerly known as game.items_per_line, which is now obsolete)}

\begin{verbatim}
readonly int InvWindow.ItemsPerRow;
\end{verbatim}
Gets the number of items that can be displayed in each row of the inventory window.
This is calculated by the width of the inventory window divided by the individual ItemWidth.

\fcol{red}{Example:}
\begin{verbatim}
Display("The inventory window can show %d items at a time", invMain.ItemsPerRow * invMain.RowCount);
\end{verbatim}
displays how many items can be visible in the invMain window at once.

\it{See Also:} \helprefn{InvWindow.ItemWidth}{InvWindow.ItemWidth},
\helprefn{InvWindow.RowCount}{InvWindow.RowCount}


\subsection{RowCount property (inv window)}\label{InvWindow.RowCount}\index{InvWindow.RowCount}%

\begin{verbatim}
readonly int InvWindow.RowCount;
\end{verbatim}
Gets the number of rows that can be displayed within the inventory window. This is
calculated by dividing the height of the window by the individual ItemHeight.

\fcol{red}{Example:}
\begin{verbatim}
Display("The inventory window can show %d items at a time", invMain.ItemsPerRow * invMain.RowCount);
\end{verbatim}
displays how many items can be visible in the invMain window at once.

\it{See Also:} \helprefn{InvWindow.ItemHeight}{InvWindow.ItemHeight},
\helprefn{InvWindow.ItemsPerRow}{InvWindow.ItemsPerRow}


\subsection{TopItem property (inv window)}\label{InvWindow.TopItem}\index{InvWindow.TopItem}%

\it{(Formerly known as game.top_inv_item, which is now obsolete)}

\begin{verbatim}
int InvWindow.TopItem;
\end{verbatim}
Gets/sets the index of the first item currently displayed in the inventory window.
The first item is represented by 0, and the last item is has an index of
\helprefn{ItemCount}{InvWindow.ItemCount} - 1.

You can use this to work out whether to display scroll arrows or not.

\fcol{red}{Example:}
\begin{verbatim}
if (invMain.TopItem > 0) {
  btnScrollUp.Visible = true;
}
else {
  btnScrollUp.Visible = false;
}
\end{verbatim}
makes the \it{btnScrollUp} button visible or invisible depending on whether the
inventory list can be scrolled up.

\it{See Also:} \helprefn{InvWindow.ItemCount}{InvWindow.ItemCount}



\section{GUI Label functions and properties}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{Font property (label)}\label{Label.Font}\index{Label.Font}\index{SetLabelFont}%

\it{(Formerly known as SetLabelFont, which is now obsolete)}

\begin{verbatim}
FontType Label.Font;
\end{verbatim}
Gets/sets the font used to display the label's text. This is useful if you
have a standard SCI font for your English version, but want to change to
a TTF font for foreign language versions.

\fcol{red}{Example:}
\begin{verbatim}
if (IsTranslationAvailable()) {
  lblStatus.Font = eFontForeign;
}
\end{verbatim}

will change label 'lblStatus' to use font "Foreign" if a game translation is in use.

\it{See Also:} \helprefn{IsTranslationAvailable}{IsTranslationAvailable},
\helprefn{Label.Text}{Label.Text}, \helprefn{TextBox.Font}{TextBox.Font}


\subsection{Text property (label)}\label{Label.Text}\index{Label.Text}\index{SetLabelText}\index{Label.GetText}\index{Label.SetText}%

\it{(Formerly known as SetLabelText, which is now obsolete)} ILBRK
\it{(Formerly known as Label.GetText, which is now obsolete)} ILBRK
\it{(Formerly known as Label.SetText, which is now obsolete)}

\begin{verbatim}
String Label.Text;
\end{verbatim}
Gets/sets the text displayed in the specified label.  This allows you to change
the text during the game, for example to create a Lucasarts-style status line.

\fcol{red}{Example:}
\begin{verbatim}
lblStatus.Text = Game.GetLocationName(mouse.x, mouse.y);
\end{verbatim}
will display the name of the location the cursor is over on label 'lblStatus'

\it{See Also:} \helprefn{Button.NormalGraphic}{Button.NormalGraphic},
\helprefn{Button.Text}{Button.Text},
\helprefn{Label.TextColor}{Label.TextColor}, \helprefn{Label.Font}{Label.Font}


\subsection{TextColor property (label)}\label{Label.TextColor}\index{Label.TextColor}\index{SetLabelColor}%

\it{(Formerly known as SetLabelColor, which is now obsolete)}

\begin{verbatim}
int Label.TextColor;
\end{verbatim}
Gets/sets the text colour used to display the label's text. 

\fcol{red}{Example:}
\begin{verbatim}
lblStatus.TextColor = 14;
\end{verbatim}

will change label 'lblStatus' to have yellow text.

\it{See Also:} \helprefn{Label.Font}{Label.Font}, \helprefn{Label.Text}{Label.Text}



\section{GUI List Box functions and properties}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{AddItem}\label{ListBox.AddItem}\index{ListBox.AddItem}\index{ListBoxAdd}%

\it{(Formerly known as ListBoxAdd, which is now obsolete)}

\begin{verbatim}
ListBox.AddItem(string newitem)
\end{verbatim}
Adds NEWITEM to the specified list box. The item will be appended to
the end of the list.

\bf{NOTE:} List boxes have a limit of 200 items. If you try to add more than that,
this function will return \it{false} and the item will not be added.

\fcol{red}{Example:}
\begin{verbatim}
String input = txtUserInput.Text;
lstChoices.AddItem(input);
\end{verbatim}
will take the input from the user and add it to the listbox.

\it{See Also:} \helprefn{ListBox.Clear}{ListBox.Clear},
\helprefn{ListBox.FillDirList}{ListBox.FillDirList},
\helprefn{ListBox.InsertItemAt}{ListBox.InsertItemAt},
\helprefn{ListBox.Items}{ListBox.Items},
\helprefn{ListBox.RemoveItem}{ListBox.RemoveItem}


\subsection{Clear (list box)}\label{ListBox.Clear}\index{ListBox.Clear}\index{ListBoxClear}%

\it{(Formerly known as ListBoxClear, which is now obsolete)}

\begin{verbatim}
ListBox.Clear()
\end{verbatim}
Removes all items from the specified list box.

\fcol{red}{Example:}
\begin{verbatim}
lstNoteBook.Clear();
\end{verbatim}
will remove all the items from listbox \it{lstNoteBook}.

\it{See Also:} \helprefn{ListBox.AddItem}{ListBox.AddItem}


\subsection{FillDirList}\label{ListBox.FillDirList}\index{ListBox.FillDirList}\index{ListBoxDirList}%

\it{(Formerly known as ListBoxDirList, which is now obsolete)}

\begin{verbatim}
ListBox.FillDirList(string filemask)
\end{verbatim}
Fills the list box with a list of filenames matching FILEMASK in
the current directory. This could be useful if you have various
data files and the player can choose which one to load.

FILEMASK is a standard DOS/Windows search expression such as "*.dat"
or "data*.*"

This command supports the special tag \verb^$SAVEGAMEDIR$^, which allows
you to access files in the save game directory. This is especially important with
the move to Windows Vista, in which you may not have access to the main game folder.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.FillDirList("agssave.*");
\end{verbatim}
will fill the listbox with the list of the saved games. Note that actually for this
task you would use FillSaveGameList instead.

\it{See Also:} \helprefn{ListBox.AddItem}{ListBox.AddItem}, \helprefn{ListBox.Clear}{ListBox.Clear},
\helprefn{ListBox.FillSaveGameList}{ListBox.FillSaveGameList}


\subsection{FillSaveGameList}\label{ListBox.FillSaveGameList}\index{ListBox.FillSaveGameList}\index{ListBoxSaveGameList}%

\it{(Formerly known as ListBoxSaveGameList, which is now obsolete)}

\begin{verbatim}
ListBox.FillSaveGameList()
\end{verbatim}
Fills the specified listbox with the save game list, sorted correctly
with the most recent game at the top of the list.

The \helprefn{SaveGameSlots}{ListBox.SaveGameSlots} property is updated to
contain the save game slot number for each index in the list, so that you can do:
\begin{verbatim}
int index = lstSaveGames.SelectedIndex;
RestoreGameSlot(lstSaveGames.SaveGameSlots[index]);
\end{verbatim}
\bf{NOTE:} The save game list can only hold 50 save games. If ListBox.ItemCount
returns 50 and you are doing a Save dialog box, you may want to make the
user replace an existing file rather than saving a new one.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.FillSaveGameList();
\end{verbatim}
will fill listbox \it{lstSaveGames} with the list of the saved games.

\it{See Also:} \helprefn{ListBox.FillDirList}{ListBox.FillDirList},
\helprefn{ListBox.ItemCount}{ListBox.ItemCount},
\helprefn{ListBox.SaveGameSlots}{ListBox.SaveGameSlots},
\helprefn{ListBox.SelectedIndex}{ListBox.SelectedIndex}


\subsection{GetItemAtLocation}\label{ListBox.GetItemAtLocation}\index{ListBox.GetItemAtLocation}%

\begin{verbatim}
ListBox.GetItemAtLocation(int x, int y)
\end{verbatim}
Determines which item in the list box is at the screen co-ordinates (X,Y).
This allows you to find out which item the mouse is hovering over, for instance.

Returns the item index (where the first item is 0), or -1 if the specified co-ordinates
are not over any item or are outside the list box.

\fcol{red}{Example:}
\begin{verbatim}
int index = lstOptions.GetItemAtLocation(mouse.x, mouse.y);
if (index < 0) {
  Display("The mouse is not over an item!");
}
else {
  String selectedItem = lstOptions.Items[index];
  Display("The mouse is over item '%s'.", selectedItem);
}
\end{verbatim}
will display the item text that the mouse is currently hovering over.

\it{See Also:} \helprefn{ListBox.SelectedIndex}{ListBox.SelectedIndex}


\subsection{InsertItemAt}\label{ListBox.InsertItemAt}\index{ListBox.InsertItemAt}%

\begin{verbatim}
ListBox.InsertItemAt(int index, string newitem)
\end{verbatim}
Inserts NEWITEM into the specified list box. The item will be inserted \bf{before}
the specified index.

Listbox indexes go from 0 (the first item) to ItemCount - 1 (the last item). The new
item will be inserted before the index you specify.

\bf{NOTE:} List boxes have a limit of 200 items. If you try to add more than that,
this function will return \it{false} and the item will not be added.

\fcol{red}{Example:}
\begin{verbatim}
lstChoices.AddItem("First item");
lstChoices.AddItem("Second item");
lstChoices.InsertItemAt(1, "Third item");
\end{verbatim}
will insert the Third Item in between the First and Second items.

\it{See Also:} \helprefn{ListBox.AddItem}{ListBox.AddItem},
\helprefn{ListBox.RemoveItem}{ListBox.RemoveItem}


\subsection{RemoveItem}\label{ListBox.RemoveItem}\index{ListBox.RemoveItem}\index{ListBoxRemove}%

\it{(Formerly known as ListBoxRemove, which is now obsolete)}

\begin{verbatim}
ListBox.RemoveItem(int item)
\end{verbatim}
Removes ITEM from the specified list box. ITEM is the list index of the item to
remove, starting with 0 for the top item.

If you want to remove all items from the list, then use \helprefn{ListBox.Clear}{ListBox.Clear}
instead.

\bf{NOTE:} Calling this function causes other items in the list to get re-numbered, so
make sure you don't keep around any references from ListBox.SelectedIndex and related functions
while using this command.

\fcol{red}{Example:}
\begin{verbatim}
lstTest.AddItem("First item");
lstTest.AddItem("Second item");
lstTest.RemoveItem(0);
\end{verbatim}
the list box will now just contain "Second item".

\it{See Also:} \helprefn{ListBox.Clear}{ListBox.Clear}, \helprefn{ListBox.FillDirList}{ListBox.FillDirList}


\subsection{ScrollDown (list box)}\label{ListBox.ScrollDown}\index{ListBox.ScrollDown}%

\begin{verbatim}
ListBox.ScrollDown()
\end{verbatim}
Scrolls the list box down one row. If it is already at the bottom, nothing happens.

\fcol{red}{Example:}
\begin{verbatim}
lstTest.ScrollDown();
\end{verbatim}
will scroll the \it{lstTest} list box down one row.

\it{See Also:} \helprefn{ListBox.ScrollUp}{ListBox.ScrollUp}


\subsection{ScrollUp (list box)}\label{ListBox.ScrollUp}\index{ListBox.ScrollUp}%

\begin{verbatim}
ListBox.ScrollUp()
\end{verbatim}
Scrolls the list box up one row. If it is already at the top, nothing happens.

\fcol{red}{Example:}
\begin{verbatim}
lstTest.ScrollUp();
\end{verbatim}
will scroll the \it{lstTest} list box up one row.

\it{See Also:} \helprefn{ListBox.ScrollDown}{ListBox.ScrollDown}


\subsection{Font property (list box)}\label{ListBox.Font}\index{ListBox.Font}%

\begin{verbatim}
FontType ListBox.Font
\end{verbatim}

Gets/sets the font used by the specified list box.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.Font = eFontSpeech;
\end{verbatim}
will change the \it{lstSaveGames} list box to use Font "Speech".

\it{See Also:} \helprefn{Label.Font}{Label.Font}, \helprefn{TextBox.Text}{TextBox.Text}


\subsection{HideBorder property (list box)}\label{ListBox.HideBorder}\index{ListBox.HideBorder}%

\begin{verbatim}
bool ListBox.HideBorder
\end{verbatim}
Gets/sets whether the list box's border is hidden.

Note that hiding the border will also implicitly hide the up/down scroll arrows for the list box.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.HideBorder = true;
\end{verbatim}
will hide the border around the Save Games list box.

\it{See Also:} \helprefn{ListBox.HideScrollArrows}{ListBox.HideScrollArrows}


\subsection{HideScrollArrows property (list box)}\label{ListBox.HideScrollArrows}\index{ListBox.HideScrollArrows}%

\begin{verbatim}
bool ListBox.HideScrollArrows
\end{verbatim}
Gets/sets whether the built-in up/down scroll arrows are hidden.

Because the appearance of the scroll arrows is not customizable, you may wish to use
this to hide them and provide your own arrows using GUI Button controls.

\bf{NOTE:} If the list box's "Hide Border" setting is enabled, then the scroll arrows will
also be hidden, since "Hide Border" supersedes "Hide Scroll Arrows". You only need to 
use this HideScrollArrows property if you want the border to be shown but the arrows hidden.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.HideScrollArrows = true;
\end{verbatim}
will hide the built-in scroll arrows on the list box.

\it{See Also:} \helprefn{ListBox.HideBorder}{ListBox.HideBorder}


\subsection{ItemCount property (list box)}\label{ListBox.ItemCount}\index{ListBox.ItemCount}\index{ListBoxGetNumItems}%

\it{(Formerly known as ListBoxGetNumItems, which is now obsolete)}

\begin{verbatim}
readonly int ListBox.ItemCount
\end{verbatim}
Gets the number of items in the specified listbox. Valid item indexes
range from 0 to (numItems - 1).

This property is read-only. To change the item count, use the AddItem and RemoveItem methods.

\fcol{red}{Example:}
\begin{verbatim}
int saves = lstSaveGames.ItemCount;
\end{verbatim}
will pass the number of saved games to the int saves.

\it{See Also:} \helprefn{ListBox.Items}{ListBox.Items}


\subsection{Items property}\label{ListBox.Items}\index{ListBox.Items}\index{ListBoxGetItemText}\index{ListBox.GetItemText}\index{ListBox.SetItemText}%

\it{(Formerly known as ListBoxGetItemText, which is now obsolete)} ILBRK
\it{(Formerly known as ListBox.GetItemText, which is now obsolete)} ILBRK
\it{(Formerly known as ListBox.SetItemText, which is now obsolete)}

\begin{verbatim}
String ListBox.Items[index]
\end{verbatim}
Gets/sets the text of the list box item at INDEX.

List box items are numbered starting from 0, so the first item is 0, the
second is 1, and so on. The highest allowable index is ItemCount minus 1.

If you want to add a new item to the listbox, use the \helprefn{ListBox.AddItem}{ListBox.AddItem} method.

\fcol{red}{Example:}
\begin{verbatim}
String selectedItemText = lstOptions.Items[lstOptions.SelectedIndex];
\end{verbatim}
will get the text of the selected item in the list box.

\it{See Also:} \helprefn{ListBox.SelectedIndex}{ListBox.SelectedIndex},
\helprefn{ListBox.ItemCount}{ListBox.ItemCount},
\helprefn{ListBox.AddItem}{ListBox.AddItem}


\subsection{RowCount property (list box)}\label{ListBox.RowCount}\index{ListBox.RowCount}%

\begin{verbatim}
readonly int ListBox.RowCount
\end{verbatim}
Gets the number of rows that can be shown within the list box. This depends on the size of
the list box, and \bf{does not} depend on how many items are actually stored in the list box.

This property is read-only. To change the row count, adjust the height of the list box.

\fcol{red}{Example:}
\begin{verbatim}
Display("You can currently see %d items from the listbox's contents", lstSaveGames.RowCount);
\end{verbatim}
will display the number of rows that the listbox can display.

\it{See Also:} \helprefn{ListBox.ItemCount}{ListBox.ItemCount}, \helprefn{ListBox.ScrollDown}{ListBox.ScrollDown},
\helprefn{ListBox.ScrollUp}{ListBox.ScrollUp}


\subsection{SaveGameSlots property}\label{ListBox.SaveGameSlots}\index{ListBox.SaveGameSlots}\index{savegameindex}%

\it{(Formerly known as global array savegameindex, which is now obsolete)}

\begin{verbatim}
readonly int ListBox.SaveGameSlots[];
\end{verbatim}
Contains the corresponding save game slot for each item in the list.

This is necessary because the FillSaveGameList command sorts the list
of save games to put the most recent first. Therefore, you can use this
array to map the list box indexes back to the corresponding save game slot.

\bf{NOTE:} You must use the FillSaveGameList command in order to populate
this array. 

\fcol{red}{Example:}
\begin{verbatim}
int index = lstSaveGames.SelectedIndex;
RestoreGameSlot(lstSaveGames.SaveGameSlots[index]);
\end{verbatim}
will restore the currently selected game in the list, assuming FillSaveGameList
had been used previously.

\it{See Also:} \helprefn{ListBox.FillSaveGameList}{ListBox.FillSaveGameList},
\helprefn{ListBox.SelectedIndex}{ListBox.SelectedIndex}


\subsection{SelectedIndex property}\label{ListBox.SelectedIndex}\index{ListBox.SelectedIndex}\index{ListBoxGetSelected}\index{ListBoxSetSelected}%

\it{(Formerly known as ListBoxGetSelected, which is now obsolete)} ILBRK
\it{(Formerly known as ListBoxSetSelected, which is now obsolete)}

\begin{verbatim}
int ListBox.SelectedIndex
\end{verbatim}
Gets/sets the index into the list of the currently selected item. The first
item is 0, second is 1, and so on. If no item is selected, this is set to -1.

You can set this to -1 to remove the highlight (ie. un-select all items).

\fcol{red}{Example:}
\begin{verbatim}
String selectedText = lstOptions.Items[lstOptions.SelectedIndex];
\end{verbatim}
will get the text of the selected item in the listbox.


\subsection{TopItem property (list box)}\label{ListBox.TopItem}\index{ListBox.TopItem}\index{ListBoxSetTopItem}%

\it{(Formerly known as ListBoxSetTopItem, which is now obsolete)}

\begin{verbatim}
int ListBox.TopItem
\end{verbatim}
Gets/sets the top item in the list box. The top item is the first item that is visible
within the list box, so changing this effectively scrolls the list up and down.

Indexes for TopItem start from 0 for the first item in the list.

\fcol{red}{Example:}
\begin{verbatim}
lstSaveGames.TopItem = 0;
\end{verbatim}
will automatically scroll listbox \it{lstSaveGames} back to the top of the list.



\section{GUI Slider properties}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{BackgroundGraphic property (slider)}\label{Slider.BackgroundGraphic}\index{Slider.BackgroundGraphic}%

\begin{verbatim}
int Slider.BackgroundGraphic;
\end{verbatim}
Gets/sets the sprite used to draw the slider background. This image is tiled along the length
of the slider.

The background graphic can be set to 0, which will draw the default grey slider background.

\fcol{red}{Example:}
\begin{verbatim}
Display("sldHealth's background is sprite %d", sldHealth.BackgroundGraphic);
\end{verbatim}
displays the \it{sldHealth} slider's background image

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Slider.HandleGraphic}{Slider.HandleGraphic}


\subsection{HandleGraphic property}\label{Slider.HandleGraphic}\index{Slider.HandleGraphic}%

\begin{verbatim}
int Slider.HandleGraphic;
\end{verbatim}
Gets/sets the sprite used to draw the handle on the slider. The handle represents the
slider's current position, and can be dragged around by the player.

The handle graphic can be set to 0, which will draw the default grey handle.

\fcol{red}{Example:}
\begin{verbatim}
Display("sldHealth's handle is sprite %d", sldHealth.HandleGraphic);
\end{verbatim}
displays the \it{sldHealth} slider's handle image

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Slider.BackgroundGraphic}{Slider.BackgroundGraphic},
\helprefn{Slider.HandleOffset}{Slider.HandleOffset}


\subsection{HandleOffset property}\label{Slider.HandleOffset}\index{Slider.HandleOffset}%

\begin{verbatim}
int Slider.HandleOffset;
\end{verbatim}
Gets/sets the offset at which the handle image is drawn. This value is initially
set up in the editor.

\fcol{red}{Example:}
\begin{verbatim}
sldHealth.HandleOffset = 2;
\end{verbatim}
sets the \it{sldHealth} slider's handle to be drawn an extra 2 pixels to the right.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Slider.HandleGraphic}{Slider.HandleGraphic}


\subsection{Max property}\label{Slider.Max}\index{Slider.Max}%

\begin{verbatim}
int Slider.Max;
\end{verbatim}
Gets/sets the maximum value of the specified GUI slider.

When changing the maximum, the slider's Value will be adjusted if
necessary so that it lies within the Min - Max range.

An error occurs if you try to set the Max to a lower value than the Min.

\fcol{red}{Example:}
\begin{verbatim}
sldHealth.Max = 200;
\end{verbatim}
sets the maximum value of the \it{sldHealth} slider to 200.

\it{See Also:} \helprefn{Slider.Min}{Slider.Min},
\helprefn{Slider.Value}{Slider.Value}


\subsection{Min property}\label{Slider.Min}\index{Slider.Min}%

\begin{verbatim}
int Slider.Min;
\end{verbatim}
Gets/sets the minimum value of the specified GUI slider.

When changing the minimum, the slider's Value will be adjusted if
necessary so that it lies within the Min - Max range.

An error occurs if you try to set the Min to a higher value than the Max.

\fcol{red}{Example:}
\begin{verbatim}
sldHealth.Min = 0;
\end{verbatim}
sets the minimum value of the \it{sldHealth} slider to 0.

\it{See Also:} \helprefn{Slider.Max}{Slider.Max},
\helprefn{Slider.Value}{Slider.Value}


\subsection{Value property}\label{Slider.Value}\index{Slider.Value}\index{GetSliderValue}\index{SetSliderValue}%

\it{(Formerly known as GetSliderValue, which is now obsolete)} ILBRK
\it{(Formerly known as SetSliderValue, which is now obsolete)}

\begin{verbatim}
int Slider.Value;
\end{verbatim}
Gets/sets the value of the specified GUI slider. You would usually
use this in the slider's OnChange event handler to find out what value the
player has changed the slider to, in order to process their command.

When setting the value, the new value must lie between the MIN and MAX settings
for the slider, as set up in the GUI editor.

\fcol{red}{Example:}
\begin{verbatim}
System.Volume = sldVolume.Value;
\end{verbatim}
will set the audio volume to the value of the slider \it{sldVolume}.

\it{See Also:} \helprefn{Label.Text}{Label.Text}



\section{GUI Text Box functions and properties}%

\helprefn{BringToFront (inherited)}{GUIControl.BringToFront}ILBRK
\helprefn{Clickable property (inherited)}{GUIControl.Clickable}ILBRK
\helprefn{Enabled property (inherited)}{GUIControl.Enabled}ILBRK
\helprefn{Height property (inherited)}{GUIControl.Height}ILBRK
\helprefn{ID property (inherited)}{GUIControl.ID}ILBRK
\helprefn{OwningGUI property (inherited)}{GUIControl.OwningGUI}ILBRK
\helprefn{SendToBack (inherited)}{GUIControl.SendToBack}ILBRK
\helprefn{SetPosition (inherited)}{GUIControl.SetPosition}ILBRK
\helprefn{SetSize (inherited)}{GUIControl.SetSize}ILBRK
\helprefn{Visible property (inherited)}{GUIControl.Visible}ILBRK
\helprefn{Width property (inherited)}{GUIControl.Width}ILBRK
\helprefn{X property (inherited)}{GUIControl.X}ILBRK
\helprefn{Y property (inherited)}{GUIControl.Y}


\subsection{Font property (text box)}\label{TextBox.Font}\index{TextBox.Font}\index{SetTextBoxFont}%

\it{(Formerly known as SetTextBoxFont, which is now obsolete)}

\begin{verbatim}
FontType TextBox.Font
\end{verbatim}

Gets/sets the font used by the specified text box.
This might be useful if you need a player input text box to use a different
font with foreign language translations, for example.

\fcol{red}{Example:}
\begin{verbatim}
txtUserInput.Font = eFontNormal;
\end{verbatim}
will change the \it{txtUserInput} text box to use Font "Normal".

\it{See Also:} \helprefn{Label.Font}{Label.Font}, \helprefn{TextBox.Text}{TextBox.Text}


\subsection{Text property (text box)}\label{TextBox.Text}\index{TextBox.Text}\index{SetTextBoxText}\index{TextBox.SetText}\index{TextBox.GetText}\index{GetTextBoxText}%

\it{(Formerly known as GetTextBoxText, which is now obsolete)} ILBRK
\it{(Formerly known as SetTextBoxText, which is now obsolete)} ILBRK
\it{(Formerly known as TextBox.GetText, which is now obsolete)} ILBRK
\it{(Formerly known as TextBox.SetText, which is now obsolete)}

\begin{verbatim}
String TextBox.Text;
\end{verbatim}

Gets/sets the text box contents. This might be useful to reset
the text box to blank after the user has typed something in, or to fill
in a default value.

\fcol{red}{Example:}
\begin{verbatim}
txtUserInput.Text = "";
\end{verbatim}
will clear the txtUserInput text box.

\it{See Also:} \helprefn{TextBox.Font}{TextBox.Font},
\helprefn{String.CompareTo}{String.CompareTo},
\helprefn{Label.Text}{Label.Text}


\subsection{TextColor property (text box)}\label{TextBox.TextColor}\index{TextBox.TextColor}%

\begin{verbatim}
int TextBox.TextColor;
\end{verbatim}
Gets/sets the text colour used to draw the text box. This affects both the text in the text
box, and also the text box's border.

\fcol{red}{Example:}
\begin{verbatim}
txtInput.TextColor = 14;
\end{verbatim}

will change text box 'txtInput' to have yellow text.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{TextBox.Text}{TextBox.Text}



\section{Hotspot functions and properties}%


\subsection{GetAtScreenXY (hotspot)}\label{Hotspot.GetAtScreenXY}\index{Hotspot.GetAtScreenXY}\index{GetHotspotAt}%

\it{(Formerly known as global function GetHotspotAt, which is now obsolete)}

\begin{verbatim}
static Hotspot* Hotspot.GetAtScreenXY(int x, int y)
\end{verbatim}
Returns the hotspot at SCREEN co-ordinates (X,Y).
If there is no hotspot there, or if invalid co-ordinates are specified,
the Hotspot* representing hotspot 0 will be returned.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
if (Hotspot.GetAtScreenXY(mouse.x, mouse.y) == hDoor)
  Display("Mouse on the door");
else if (Hotspot.GetAtScreenXY(mouse.x, mouse.y) != hotspot[0])
  Display("Mouse is on something (but not the door)!");
else
  Display("Mouse not on a hotspot");
\end{verbatim}
will display a message depending on what the mouse is on.

\it{See Also:} \helprefn{Game.GetLocationName}{Game.GetLocationName}, \helprefn{GetLocationType}{GetLocationType}


\subsection{GetProperty (hotspot)}\label{Hotspot.GetProperty}\index{Hotspot.GetProperty}\index{GetHotspotProperty}%

\it{(Formerly known as GetHotspotProperty, which is now obsolete)}

\begin{verbatim}
Hotspot.GetProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the hotspot.

This command works with Number properties (it returns the number), and with Boolean
properties (returns 1 if the box was checked, 0 if not).

Use the equivalent GetTextProperty function to get a text property.

\fcol{red}{Example:}
\begin{verbatim}
if (hotspot[1].GetProperty("Value") > 200)
  Display("Hotspot 1's value is over 200!");
\end{verbatim}
will print the message if hotspot 1 has its "Value" property set to more than 200.

\it{See Also:} \helprefn{Hotspot.GetTextProperty}{Hotspot.GetTextProperty}


\subsection{GetTextProperty (hotspot)}\label{Hotspot.GetTextProperty}\index{Hotspot.GetTextProperty}\index{Hotspot.GetPropertyText}\index{GetHotspotPropertyText}%

\it{(Formerly known as GetHotspotPropertyText, which is now obsolete)} ILBRK
\it{(Formerly known as Hotspot.GetPropertyText, which is now obsolete)}

\begin{verbatim}
String Hotspot.GetTextProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the hotspot.

This command works with Text properties only. The property's text will be
returned from this function.

Use the equivalent GetProperty function to get a non-text property.

\fcol{red}{Example:}
\begin{verbatim}
String description = hotspot[2].GetTextProperty("Description");
Display("Hotspot 2's description: %s", description);
\end{verbatim}
will retrieve hotspot 2's "description" property and display it.

\it{See Also:} \helprefn{Hotspot.GetProperty}{Hotspot.GetProperty}



\subsection{RunInteraction (hotspot)}\label{Hotspot.RunInteraction}\index{Hotspot.RunInteraction}\index{RunHotspotInteraction}%

\it{(Formerly known as RunHotspotInteraction, which is now obsolete)}

\begin{verbatim}
Hotspot.RunInteraction(CursorMode)
\end{verbatim}
Processes the event handler as if the player had clicked the mouse
on the hotspot using the specified cursor mode.

\fcol{red}{Example:}
\begin{verbatim}
hDoor.RunInteraction(eModeLookat);
\end{verbatim}
will run the code defined in the "LOOK AT HOTSPOT" event for hotspot hDoor.

\it{See Also:} \helprefn{ProcessClick}{ProcessClick},
\helprefn{Character.RunInteraction}{Character.RunInteraction},
\helprefn{Object.RunInteraction}{Object.RunInteraction}


\subsection{Enabled property (hotspot)}\label{Hotspot.Enabled}\index{Hotspot.Enabled}\index{DisableHotspot}\index{EnableHotspot}%

\it{(Formerly known as DisableHotspot, which is now obsolete)} ILBRK
\it{(Formerly known as EnableHotspot, which is now obsolete)}

\begin{verbatim}
bool Hotspot.Enabled
\end{verbatim}
Enables/disables the specified hotspot. If you set this to false, then all areas of the screen
that were previously made up of the hotspot now act as type 0 (no hotspot). You can turn the
hotspot back on later by setting this back to true.

This setting is persisted in-game; that is, it will not be reset when the player
re-enters the room.

The default value of this property is always \it{true}.

\fcol{red}{Example:}
\begin{verbatim}
hBrownTree.Enabled = false;
\end{verbatim}
will disable the hBrownTree hotspot.

\it{See Also:} \helprefn{Region.Enabled}{Region.Enabled},
\helprefn{RemoveWalkableArea}{RemoveWalkableArea},
\helprefn{RestoreWalkableArea}{RestoreWalkableArea}


\subsection{ID property (hotspot)}\label{Hotspot.ID}\index{Hotspot.ID}%

\begin{verbatim}
readonly int Hotspot.ID
\end{verbatim}
Gets the hotspot number of this hotspot. This allows you to interoperate with old
script using the number-based hotspot functions.

\fcol{red}{Example:}
\begin{verbatim}
Display("Hotspot hDoor is hotspot number %d.", hDoor.ID);
Display("Hotspot 3 is number %d.", hotspot[3].ID);
\end{verbatim}
displays hDoor's hotspot number, and then displays hotspot 3's number (which will be 3).

\it{See Also:} \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY}


\subsection{Name property (hotspot)}\label{Hotspot.Name}\index{Hotspot.Name}\index{Hotspot.GetName}\index{GetHotspotName}%

\it{(Formerly known as GetHotspotName, which is now obsolete)} ILBRK
\it{(Formerly known as Hotspot.GetName, which is now obsolete)}

\begin{verbatim}
readonly String Hotspot.Name;
\end{verbatim}
Gets the name of the hotspot.

This property is read-only; it is currently not possible to change hotspot names at run-time.

\fcol{red}{Example:}
\begin{verbatim}
Display("Hotspot 3's name is %s.", hotspot[3].Name);
\end{verbatim}
will retrieve and then display hotspot 3's name.

\it{See Also:} \helprefn{Game.GetLocationName}{Game.GetLocationName}


\subsection{WalkToX property}\label{Hotspot.WalkToX}\index{Hotspot.WalkToX}\index{GetHotspotPointX}%

\it{(Formerly known as GetHotspotPointX, which is now obsolete)}

\begin{verbatim}
readonly int Hotspot.WalkToX
\end{verbatim}
Gets the X room co-ordinate of the hotspot's walk-to point. If the hotspot
does not have a walk-to point, returns -1.

\fcol{red}{Example:}
\begin{verbatim}
player.Walk(hTable.WalkToX, hTable.WalkToY, eBlock, eWalkableAreas);
\end{verbatim}
will move the character to hotspot hTable's walk-to point.

\it{See Also:} \helprefn{Hotspot.WalkToY}{Hotspot.WalkToY},
\helprefn{MoveCharacterToHotspot}{MoveCharacterToHotspot}


\subsection{WalkToY property}\label{Hotspot.WalkToY}\index{Hotspot.WalkToY}\index{GetHotspotPointY}%

\it{(Formerly known as GetHotspotPointY, which is now obsolete)}

\begin{verbatim}
readonly int Hotspot.WalkToY
\end{verbatim}
Gets the Y room co-ordinate of the hotspot's walk-to point. If the hotspot
does not have a walk-to point, returns -1.

\fcol{red}{Example:}
\begin{verbatim}
player.Walk(hTable.WalkToX, hTable.WalkToY, eBlock, eWalkableAreas);
\end{verbatim}
will move the character to hotspot hTable's walk-to point.

\it{See Also:} \helprefn{Hotspot.WalkToX}{Hotspot.WalkToX},
\helprefn{MoveCharacterToHotspot}{MoveCharacterToHotspot}



\section{Inventory item functions and properties}%


\subsection{GetAtScreenXY (inventory)}\label{InventoryItem.GetAtScreenXY}\index{InventoryItem.GetAtScreenXY}\index{GetInvAt}%

\it{(Formerly known as global function GetInvAt, which is now obsolete)}

\begin{verbatim}
static InventoryItem* InventoryItem.GetAtScreenXY(int x, int y)
\end{verbatim}
Returns the inventory item at SCREEN co-ordinates (X,Y). Note that this
only detects inventory items on custom Inventory windows (that are switched on when
this function is called), and is intended to allow you to do Verb Coin style GUIs and so on.

If there is no inventory item there, or if invalid co-ordinates are specified,
returns null.

\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
InventoryItem *item = InventoryItem.GetAtScreenXY(mouse.x, mouse.y);
if (item == null) {
  Display("No inventory item at the mouse co-ordinates");
}
else {
  Display("Inventory item number %d at the mouse.", item.ID);
}
\end{verbatim}
will display the number of the inv item that the mouse is over

\it{See Also:} \helprefn{InventoryItem.Name}{InventoryItem.Name},
\helprefn{Game.GetLocationName}{Game.GetLocationName}


\subsection{GetProperty (inventory)}\label{InventoryItem.GetProperty}\index{InventoryItem.GetProperty}\index{GetInvProperty}%

\it{(Formerly known as GetInvProperty, which is now obsolete)}

\begin{verbatim}
InventoryItem.GetProperty(string property)
\end{verbatim}
Returns the custom property setting PROPERTY for the inventory item.

This command works with Number properties (it returns the number), and with Boolean
properties (returns 1 if the box was checked, 0 if not).

Use the equivalent GetTextProperty function to get a text property.

\fcol{red}{Example:}
\begin{verbatim}
if (inventory[1].GetProperty("Value") > 200)
  Display("Inventory item 1's value is over 200!");
\end{verbatim}
will print the message if inventory item 1 has its "Value" property set to more than 200.

\it{See Also:} \helprefn{InventoryItem.GetTextProperty}{InventoryItem.GetTextProperty}


\subsection{GetTextProperty (inventory)}\label{InventoryItem.GetTextProperty}\index{InventoryItem.GetTextProperty}\index{InventoryItem.GetPropertyText}\index{GetInvPropertyText}%

\it{(Formerly known as GetInvPropertyText, which is now obsolete)} ILBRK
\it{(Formerly known as InventoryItem.GetPropertyText, which is now obsolete)}

\begin{verbatim}
String InventoryItem.GetTextProperty(string property)
\end{verbatim}
Returns the custom property setting PROPERTY for the inventory item.

This command works with Text properties only. The property's text will be
returned from this function.

Use the equivalent GetProperty function to get a non-text property.

\fcol{red}{Example:}
\begin{verbatim}
String description = inventory[2].GetTextProperty("Description");
Display("Inv item 2's description: %s", description);
\end{verbatim}
will retrieve inv item 2's "description" property and display it.

\it{See Also:} \helprefn{InventoryItem.GetProperty}{InventoryItem.GetProperty}


\subsection{IsInteractionAvailable (inventory)}\label{InventoryItem.IsInteractionAvailable}\index{InventoryItem.IsInteractionAvailable}\index{IsInventoryInteractionAvailable}%

\it{(Formerly known as IsInventoryInteractionAvailable, which is now obsolete)}

\begin{verbatim}
InventoryItem.IsInteractionAvailable(CursorMode)
\end{verbatim}
Checks whether there is an event handler defined for activating the inventory item
in cursor mode MODE.

This function is very similar to RunInteraction, except that rather than run the event
handler script function, it simply returns \it{true} if something would have happened,
or \it{false} if unhandled_event would have been run.

This is useful for enabling options on a verb-coin style GUI, for example.

\fcol{red}{Example:}
\begin{verbatim}
if (iKeyring.IsInteractionAvailable(eModeLookat) == 0)
  Display("looking at this item would not do anything.");
\end{verbatim}

\it{See Also:} \helprefn{IsInteractionAvailable}{IsInteractionAvailable},
\helprefn{InventoryItem.RunInteraction}{InventoryItem.RunInteraction}


\subsection{RunInteraction (inventory)}\label{InventoryItem.RunInteraction}\index{InventoryItem.RunInteraction}\index{RunInventoryInteraction}%

\it{(Formerly known as RunInventoryInteraction, which is now obsolete)}

\begin{verbatim}
InventoryItem.RunInteraction(CursorMode)
\end{verbatim}
Runs the event handler as if the player had clicked the mouse
on the inventory item, using the specified cursor mode.

\fcol{red}{Example:}
\begin{verbatim}
if (button == eMouseLeftInv)
  inventory[game.inv_activated].RunInteraction(mouse.Mode);
\end{verbatim}
will run the inventory event handler for the current cursor mode when the player clicks
on the item (Handle Inv Clicks needs to be enabled for this to work)

\it{See Also:} \helprefn{InventoryItem.IsInteractionAvailable}{InventoryItem.IsInteractionAvailable},
\helprefn{ProcessClick}{ProcessClick}, \helprefn{Character.RunInteraction}{Character.RunInteraction}


\subsection{CursorGraphic property (inventory)}\label{InventoryItem.CursorGraphic}\index{InventoryItem.CursorGraphic}%

\begin{verbatim}
int InventoryItem.CursorGraphic
\end{verbatim}
Gets/sets the sprite slot number of the inventory item's mouse cursor. This is
the sprite used as the mouse cursor when this inventory item is selected.

\bf{NOTE:} This property is only used if the "Use selected inventory graphic for cursor"
setting in General Settings is turned on.

\fcol{red}{Example:}
\begin{verbatim}
Display("The key's cursor graphic is %d", iKey.CursorGraphic);
\end{verbatim}
will display inventory item \it{iKey}'s cursor graphic.

\it{Compatibility:} Supported by \bf{AGS 3.1.2} and later versions.

\it{See Also:} \helprefn{InventoryItem.Graphic}{InventoryItem.Graphic}


\subsection{Graphic property (inventory)}\label{InventoryItem.Graphic}\index{InventoryItem.Graphic}\index{SetInvItemPic}\index{GetInvGraphic}%

\it{(Formerly known as GetInvGraphic, which is now obsolete)}ILBRK
\it{(Formerly known as SetInvItemPic, which is now obsolete)}

\begin{verbatim}
int InventoryItem.Graphic
\end{verbatim}
Gets/sets the sprite slot number of the inventory item. You could use this
with the Object.Graphic property as a means of the player 'dropping' an inventory item, or
it may be useful if you want to do a Raw Drawn inventory window.

\bf{NOTE:} For backwards compatibility, if you change this property and the CursorGraphic
currently has the same sprite as the main Graphic, then the CursorGraphic will be changed
too.

\fcol{red}{Example:}
\begin{verbatim}
int slot = player.ActiveInventory.Graphic;
\end{verbatim}
will place the sprite number of the player's current inventory item into slot.

\it{See Also:} \helprefn{InventoryItem.CursorGraphic}{InventoryItem.CursorGraphic},
\helprefn{InventoryItem.GetAtScreenXY}{InventoryItem.GetAtScreenXY},
\helprefn{InventoryItem.Name}{InventoryItem.Name}


\subsection{ID property (inventory)}\label{InventoryItem.ID}\index{InventoryItem.ID}%

\begin{verbatim}
readonly int InventoryItem.ID
\end{verbatim}
Gets the inventory item's ID number. This is the item's number from the editor, and is
useful with commands such as Character.AddInventory which require an inventory number
to add.

\fcol{red}{Example:}
\begin{verbatim}
AddInventory(EGO, iShovel.ID);
\end{verbatim}
uses the obsolete AddInventory command to add the shovel to EGO's inventory

\it{See Also:} \helprefn{Character.AddInventory}{Character.AddInventory},
\helprefn{Character.LoseInventory}{Character.LoseInventory}


\subsection{Name property (inventory)}\label{InventoryItem.Name}\index{InventoryItem.Name}\index{InventoryItem.GetName}\index{GetInvName}\index{InventoryItem.SetName}\index{SetInvItemName}%

\it{(Formerly known as GetInvName, which is now obsolete)} ILBRK
\it{(Formerly known as SetInvItemName, which is now obsolete)} ILBRK
\it{(Formerly known as InventoryItem.GetName, which is now obsolete)} ILBRK
\it{(Formerly known as InventoryItem.SetName, which is now obsolete)}

\begin{verbatim}
String InventoryItem.Name;
\end{verbatim}
Gets/sets the name of the inventory item. This is the name which is
initially set under the Game tab, Inventory mode of the AGS Editor.

You can change this property if for example you want to change a 'bowl'
to a 'bowl with water in' but want to use the same inventory item for it.

Note that the maximum length for the name of an inventory item is 24 characters - if the
name you set is longer than this, it will be truncated.

\fcol{red}{Example:}
\begin{verbatim}
Display("Active inventory: %s", player.ActiveInventory.Name);
\end{verbatim}
will display the name of the player's current inventory item.

\it{See Also:} \helprefn{InventoryItem.GetAtScreenXY}{InventoryItem.GetAtScreenXY},
\helprefn{InventoryItem.Graphic}{InventoryItem.Graphic},
\helprefn{Game.GetLocationName}{Game.GetLocationName}



\section{Maths functions and properties}%



\subsection{FloatToInt}\label{FloatToInt}\index{FloatToInt}%

\begin{verbatim}
int FloatToInt(float value, optional RoundDirection)
\end{verbatim}
Converts the supplied floating point value into an integer.

This function is necessary because implicit conversions in the script are not supported.

RoundDirection can be either \it{eRoundDown} (the default), \it{eRoundUp} or \it{eRoundNearest},
which specifies what direction to round the floating point number in.

\fcol{red}{Example:}
\begin{verbatim}
Display("Round down: %d", FloatToInt(10.7));
Display("Round up: %d", FloatToInt(10.7, eRoundUp));
Display("Round nearest: %d", FloatToInt(10.7, eRoundNearest));
\end{verbatim}
displays the integer value of 10.7, rounded in the three different ways.

\it{See Also:} \helprefn{IntToFloat}{IntToFloat}


\subsection{IntToFloat}\label{IntToFloat}\index{IntToFloat}%

\begin{verbatim}
float IntToFloat(int value)
\end{verbatim}
Converts the supplied integer value into a floating point number.

This function is necessary because implicit conversions in the script are not supported.

\fcol{red}{Example:}
\begin{verbatim}
float number = IntToFloat(10);
\end{verbatim}
loads 10.0 into the variable \it{number}.

\it{See Also:} \helprefn{FloatToInt}{FloatToInt}


\subsection{ArcCos}\label{Maths.ArcCos}\index{Maths.ArcCos}%

\begin{verbatim}
float Maths.ArcCos(float value)
\end{verbatim}
Calculates the arc-cosine, in radians, of the specified value.

To convert an angle in radians to degrees, use \helprefn{Maths.RadiansToDegrees}{Maths.RadiansToDegrees}.

\fcol{red}{Example:}
\begin{verbatim}
float angle = Maths.ArcCos(1.0);
\end{verbatim}
calculates the arc-cosine of 1.0 and places it into variable \it{angle}.

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},


\subsection{ArcSin}\label{Maths.ArcSin}\index{Maths.ArcSin}%

\begin{verbatim}
float Maths.ArcSin(float value)
\end{verbatim}
Calculates the arc-sine, in radians, of the specified value.

To convert an angle in radians to degrees, use \helprefn{Maths.RadiansToDegrees}{Maths.RadiansToDegrees}.

\fcol{red}{Example:}
\begin{verbatim}
float angle = Maths.ArcSin(0.5);
\end{verbatim}
calculates the arc-sine of 0.5 and places it into variable \it{angle}.

\it{See Also:} \helprefn{Maths.Sin}{Maths.Sin},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},


\subsection{ArcTan}\label{Maths.ArcTan}\index{Maths.ArcTan}%

\begin{verbatim}
float Maths.ArcTan(float value)
\end{verbatim}
Calculates the arc-tan, in radians, of the specified value.

To convert an angle in radians to degrees, use \helprefn{Maths.RadiansToDegrees}{Maths.RadiansToDegrees}.

\fcol{red}{Example:}
\begin{verbatim}
float angle = Maths.ArcTan(0.5);
\end{verbatim}
calculates the arc-tan of 0.5 and places it into variable \it{angle}.

\it{See Also:} \helprefn{Maths.ArcTan2}{Maths.ArcTan2},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Tan}{Maths.Tan}


\subsection{ArcTan2}\label{Maths.ArcTan2}\index{Maths.ArcTan2}%

\begin{verbatim}
float Maths.ArcTan2(float y, float x)
\end{verbatim}
Calculates the arctangent of y/x. This is well defined for every point other than the origin,
even if x equals 0 and y does not equal 0. The result is returned in radians.

To convert an angle in radians to degrees, use \helprefn{Maths.RadiansToDegrees}{Maths.RadiansToDegrees}.

\fcol{red}{Example:}
\begin{verbatim}
float angle = Maths.ArcTan2(-862.42, 78.5149);
\end{verbatim}
calculates the arc-tan of -862.42 / 78.5149 and places it into variable \it{angle}.

\it{See Also:} \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.ArcTan}{Maths.ArcTan}


\subsection{Cos}\label{Maths.Cos}\index{Maths.Cos}%

\begin{verbatim}
float Maths.Cos(float radians)
\end{verbatim}
Calculates the cosine of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float cosine = Maths.Cos(Maths.DegreesToRadians(360.0));
\end{verbatim}
calculates the cosine of 360 degrees (which is 1.0) and places it into variable \it{cosine}.

\it{See Also:} \helprefn{Maths.ArcCos}{Maths.ArcCos},
\helprefn{Maths.Cosh}{Maths.Cosh}, \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Sin}{Maths.Sin}, \helprefn{Maths.Tan}{Maths.Tan}


\subsection{Cosh}\label{Maths.Cosh}\index{Maths.Cosh}%

\begin{verbatim}
float Maths.Cosh(float radians)
\end{verbatim}
Calculates the hyperbolic cosine of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float hcos = Maths.Cosh(Maths.DegreesToRadians(360.0));
\end{verbatim}
calculates the hyperbolic cosine of 360 degrees and places it into variable \it{hcos}.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Sinh}{Maths.Sinh}, \helprefn{Maths.Tanh}{Maths.Tanh}


\subsection{DegreesToRadians}\label{Maths.DegreesToRadians}\index{Maths.DegreesToRadians}%

\begin{verbatim}
float Maths.DegreesToRadians(float degrees)
\end{verbatim}
Converts the supplied angle in degrees, to the equivalent angle in radians.

Since the trigonometric functions such as Sin, Cos and Tan work in radians, this
function is handy if you know the angle you want in degrees.

\fcol{red}{Example:}
\begin{verbatim}
float cosine = Maths.Cos(Maths.DegreesToRadians(360.0));
\end{verbatim}
calculates the cosine of 360 degrees (which is 1.0) and places it into variable \it{cosine}.

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos},
\helprefn{Maths.RadiansToDegrees}{Maths.RadiansToDegrees},
\helprefn{Maths.Sin}{Maths.Sin}, \helprefn{Maths.Tan}{Maths.Tan}


\subsection{Exp}\label{Maths.Exp}\index{Maths.Exp}%

\begin{verbatim}
float Maths.Exp(float x)
\end{verbatim}
Returns the exponential value of the floating-point parameter, x

The result is e to the power x, where e is the base of the natural logarithm.
On overflow, the function returns infinite and on underflow, returns 0. 

\fcol{red}{Example:}
\begin{verbatim}
float expValue = Maths.Exp(2.302585093);
\end{verbatim}
calculates Exp of 2.302585093 (which should be 10) and places it into the variable.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.Log}{Maths.Log}, \helprefn{Maths.Log10}{Maths.Log10}


\subsection{Log}\label{Maths.Log}\index{Maths.Log}%

\begin{verbatim}
float Maths.Log(float x)
\end{verbatim}
Returns the natural logarithm (base e) of x.

x must be a positive non-zero number.

\fcol{red}{Example:}
\begin{verbatim}
float logVal = Maths.Log(9000.0);
\end{verbatim}
calculates Log of 9000 (which should be 9.104980) and places it into the variable.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.Exp}{Maths.Exp}, \helprefn{Maths.Log10}{Maths.Log10}


\subsection{Log10}\label{Maths.Log10}\index{Maths.Log10}%

\begin{verbatim}
float Maths.Log10(float x)
\end{verbatim}
Returns the base-10 logarithm of x.

x must be a positive non-zero number.

\fcol{red}{Example:}
\begin{verbatim}
float logVal = Maths.Log(9000.0);
\end{verbatim}
calculates Log10 of 9000 (which should be 3.954243) and places it into the variable.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.Exp}{Maths.Exp}, \helprefn{Maths.Log}{Maths.Log}


\subsection{RadiansToDegrees}\label{Maths.RadiansToDegrees}\index{Maths.RadiansToDegrees}%

\begin{verbatim}
float Maths.RadiansToDegrees(float radians)
\end{verbatim}
Converts the supplied angle in radians, to the equivalent angle in degrees.

Since the trigonometic functions such as Sin, Cos and Tan work in radians, this
function is handy to convert the results of one of those functions back to degrees.

\fcol{red}{Example:}
\begin{verbatim}
float halfCircle = Maths.RadiansToDegrees(Maths.Pi);
\end{verbatim}
converts \it{PI} radians into degrees (which is 180).

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Sin}{Maths.Sin}, \helprefn{Maths.Tan}{Maths.Tan}


\subsection{RaiseToPower}\label{Maths.RaiseToPower}\index{Maths.RaiseToPower}%

\begin{verbatim}
float Maths.RaiseToPower(float base, float exponent)
\end{verbatim}
Calculates the value of \it{base} raised to the power \it{exponent}.

This means that \it{base} is multiplied by itself \it{exponent} times.

\fcol{red}{Example:}
\begin{verbatim}
float value = Maths.RaiseToPower(4.0, 3.0);
\end{verbatim}
calculates 4 to the power 3 (which is 64).

\it{See Also:} \helprefn{Maths.Sqrt}{Maths.Sqrt}


\subsection{Sin}\label{Maths.Sin}\index{Maths.Sin}%

\begin{verbatim}
float Maths.Sin(float radians)
\end{verbatim}
Calculates the sine of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float sine = Maths.Sin(Maths.DegreesToRadians(360.0));
\end{verbatim}
calculates the sine of 360 degrees (which is 0) and places it into variable \it{sine}.

\it{See Also:} \helprefn{Maths.ArcSin}{Maths.ArcSin},
\helprefn{Maths.Sinh}{Maths.Sinh},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Cos}{Maths.Cos}, \helprefn{Maths.Tan}{Maths.Tan}


\subsection{Sinh}\label{Maths.Sinh}\index{Maths.Sinh}%

\begin{verbatim}
float Maths.Sinh(float radians)
\end{verbatim}
Calculates the hyperbolic sine of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float hsine = Maths.Sinh(Maths.DegreesToRadians(360.0));
\end{verbatim}
calculates the hyperbolic sine of 360 degrees and places it into variable \it{hsine}.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.ArcSin}{Maths.ArcSin},
\helprefn{Maths.Sin}{Maths.Sin},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Cosh}{Maths.Cosh}, \helprefn{Maths.Tanh}{Maths.Tanh}


\subsection{Sqrt}\label{Maths.Sqrt}\index{Maths.Sqrt}%

\begin{verbatim}
float Maths.Sqrt(float value)
\end{verbatim}
Calculates the square root of the supplied value.

The square root is the number which, when multiplied by itself, equals \it{value}.

\fcol{red}{Example:}
\begin{verbatim}
Display("The square root of 4 is %d!", FloatToInt(Maths.Sqrt(4.0)));
\end{verbatim}
displays the square root of 4 (rounded down to the nearest integer).

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos},
\helprefn{Maths.RaiseToPower}{Maths.RaiseToPower},
\helprefn{Maths.Sin}{Maths.Sin}, \helprefn{Maths.Tan}{Maths.Tan}


\subsection{Tan}\label{Maths.Tan}\index{Maths.Tan}%

\begin{verbatim}
float Maths.Tan(float radians)
\end{verbatim}
Calculates the tangent of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float tan = Maths.Tan(Maths.DegreesToRadians(45.0));
\end{verbatim}
calculates the tan of 45 degrees (which is 1.0) and places it into variable \it{tan}.

\it{See Also:} \helprefn{Maths.ArcTan}{Maths.ArcTan},
\helprefn{Maths.Tanh}{Maths.Tanh},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Cos}{Maths.Cos}, \helprefn{Maths.Sin}{Maths.Sin}


\subsection{Tanh}\label{Maths.Tanh}\index{Maths.Tanh}%

\begin{verbatim}
float Maths.Tanh(float radians)
\end{verbatim}
Calculates the hyperbolic tangent of the specified angle (in radians).

To convert an angle in degrees to radians, use \helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians}.

\fcol{red}{Example:}
\begin{verbatim}
float htan = Maths.Tanh(Maths.DegreesToRadians(45.0));
\end{verbatim}
calculates the hyperbolic tan of 45 degrees and places it into variable \it{htan}.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Maths.ArcTan}{Maths.ArcTan},
\helprefn{Maths.Tan}{Maths.Tan},
\helprefn{Maths.DegreesToRadians}{Maths.DegreesToRadians},
\helprefn{Maths.Cos}{Maths.Cos}, \helprefn{Maths.Sin}{Maths.Sin}


\subsection{Pi property}\label{Maths.Pi}\index{Maths.Pi}%

\begin{verbatim}
readonly float Maths.Pi
\end{verbatim}
Gets the value of Pi (defined as 3.14159265358979323846).

\fcol{red}{Example:}
\begin{verbatim}
Display("Pi is %f!", Maths.Pi);
\end{verbatim}
displays the value of Pi.

\it{See Also:} \helprefn{Maths.Cos}{Maths.Cos}, \helprefn{Maths.Sin}{Maths.Sin},
\helprefn{Maths.Tan}{Maths.Tan}



\section{Mouse functions and properties}%


\subsection{ChangeModeGraphic}\label{Mouse.ChangeModeGraphic}\index{Mouse.ChangeModeGraphic}\index{ChangeCursorGraphic}%

\it{(Formerly known as ChangeCursorGraphic, which is now obsolete)}

\begin{verbatim}
Mouse.ChangeModeGraphic(CursorMode, int slot)
\end{verbatim}
Changes the specified mouse cursor mode's cursor graphic to SLOT.
This allows you to dynamically change what a mouse cursor looks like.

\bf{NOTE:} To change what the Use Inventory cursor looks like, you should change
the active inventory item's \helprefn{CursorGraphic}{InventoryItem.CursorGraphic} property
instead of using this function.

\fcol{red}{Example:}
\begin{verbatim}
mouse.ChangeModeGraphic(eModeLookat, 120);
\end{verbatim}
will change the cursor's graphic for look mode to the image that's imported in the sprite's manager slot 120.

\it{See Also:} \helprefn{Mouse.ChangeModeHotspot}{Mouse.ChangeModeHotspot},
\helprefn{Mouse.ChangeModeView}{Mouse.ChangeModeView},
\helprefn{Mouse.GetModeGraphic}{Mouse.GetModeGraphic},
\helprefn{Mouse.Mode}{Mouse.Mode}


\subsection{ChangeModeHotspot}\label{Mouse.ChangeModeHotspot}\index{Mouse.ChangeModeHotspot}\index{ChangeCursorHotspot}%

\it{(Formerly known as ChangeCursorHotspot, which is now obsolete)}

\begin{verbatim}
Mouse.ChangeModeHotspot(CursorMode, int x, int y)
\end{verbatim}
Permanently changes the specified mouse cursor mode's hotspot on the cursor graphic
to (X,Y). This is the offset into the graphic where the click takes effect.
(0,0) is the upper left corner of the cursor graphic.

\fcol{red}{Example:}
\begin{verbatim}
mouse.ChangeModeHotspot(eModeWalkto, 10, 10);
\end{verbatim}
will change the cursor's hotspot for walk mode to coordinates 10,10.

\it{See Also:} \helprefn{Mouse.ChangeModeGraphic}{Mouse.ChangeModeGraphic},
\helprefn{Mouse.ChangeModeView}{Mouse.ChangeModeView}


\subsection{ChangeModeView}\label{Mouse.ChangeModeView}\index{Mouse.ChangeModeView}%

\begin{verbatim}
Mouse.ChangeModeView(CursorMode, int view)
\end{verbatim}
Changes the specified mouse cursor mode's animation view to VIEW.

You can pass \it{view} as -1 to stop the cursor from animating.

This allows you to dynamically change the view used for the cursor's animation
while the game is running.

\fcol{red}{Example:}
\begin{verbatim}
mouse.ChangeModeView(eModeLookat, ROLLEYES);
\end{verbatim}
will change the Look cursor's view to ROLLEYES.

\it{See Also:} \helprefn{Mouse.ChangeModeGraphic}{Mouse.ChangeModeGraphic},
\helprefn{Mouse.ChangeModeHotspot}{Mouse.ChangeModeHotspot}


\subsection{DisableMode}\label{Mouse.DisableMode}\index{Mouse.DisableMode}\index{DisableCursorMode}%

\it{(Formerly known as DisableCursorMode, which is now obsolete)}

\begin{verbatim}
Mouse.DisableMode(int mode)
\end{verbatim}
Disables the mouse cursor MODE. Any attempts to set the cursor to this mode
while it is disabled (such as using UseModeGraphic) will fail. This function
also greys out and disables any interface buttons whose left-click command
is set as "Set mode X", where X is equal to MODE.

If the current cursor mode is MODE, then the engine will change it to the
next enabled standard cursor.

\fcol{red}{Example:}
\begin{verbatim}
mouse.DisableMode(eModeWalkto);
\end{verbatim}
will make the walk mode unavailable until it's enabled again.

\it{See Also:} \helprefn{Mouse.EnableMode}{Mouse.EnableMode}


\subsection{EnableMode}\label{Mouse.EnableMode}\index{Mouse.EnableMode}\index{EnableCursorMode}%

\it{(Formerly known as EnableCursorMode, which is now obsolete)}

\begin{verbatim}
Mouse.EnableMode(int mode)
\end{verbatim}
Re-enables the mouse cursor mode MODE. This function also enables any
interface buttons which were disabled by the DisableMode command.

\fcol{red}{Example:}
\begin{verbatim}
mouse.EnableMode(eModeWalkto);
\end{verbatim}
will enable cursor mode walk which was disabled before.

\it{See Also:} \helprefn{Mouse.DisableMode}{Mouse.DisableMode}


\subsection{GetModeGraphic}\label{Mouse.GetModeGraphic}\index{Mouse.GetModeGraphic}%

\begin{verbatim}
static int Mouse.GetModeGraphic(CursorMode)
\end{verbatim}
Returns the sprite slot number of the specified mouse cursor mode.

This could be useful if you want to change it manually with ChangeModeGraphic but be able
to remember what it was before.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current mouse cursor sprite is %d.", mouse.GetModeGraphic(mouse.Mode));
\end{verbatim}
will display the sprite slot number of the current mouse cursor.

\it{See Also:} \helprefn{Mouse.ChangeModeGraphic}{Mouse.ChangeModeGraphic}


\subsection{IsButtonDown}\label{Mouse.IsButtonDown}\index{Mouse.IsButtonDown}%

\it{(Formerly known as global function IsButtonDown, which is now obsolete)}

\begin{verbatim}
Mouse.IsButtonDown(MouseButton)
\end{verbatim}
Tests whether the user has the specified mouse button down. BUTTON must either
be eMouseLeft, eMouseRight or eMouseMiddle.

Returns \it{true} if the button is currently pressed, \it{false} if not. This could be used to
test the length of a mouse click and similar effects.

\fcol{red}{Example:}
\begin{verbatim}
int timer=0;  // (at top of script file)
if (mouse.IsButtonDown(eMouseRight)) {
  if (timer == 40) {
    Display("You pressed the right button for 1 sec");
    timer = 0;
  }
  else {
    timer++;
  }
}
\end{verbatim}
will display the message if the player presses the right button for 1 sec.

\it{Compatibility:} \it{eMouseMiddle} supported by \bf{AGS 3.2.0} and later versions. ILBRK
\it{eMouseLeft} and \it{eMouseRight} supported by all versions.

\it{See Also:} \helprefn{IsKeyPressed}{IsKeyPressed}


\subsection{SaveCursorUntilItLeaves}\label{Mouse.SaveCursorUntilItLeaves}\index{Mouse.SaveCursorUntilItLeaves}\index{SaveCursorForLocationChange}%

\it{(Formerly known as SaveCursorForLocationChange, which is now obsolete)}

\begin{verbatim}
Mouse.SaveCursorUntilItLeaves()
\end{verbatim}
Saves the current mouse cursor, and restores it when the mouse leaves the current hotspot,
object or character.

This allows you to temporarily change the mouse cursor when the mouse moves over a hotspot,
and have it automatically change back to the old cursor when the player moves the mouse away.

\bf{NOTE:} You must call this \bf{BEFORE} you change to your new temporary cursor, or the
new cursor will be saved by this command.

\fcol{red}{Example:}
\begin{verbatim}
mouse.SaveCursorUntilItLeaves();
mouse.Mode = eModeTalk;
\end{verbatim}
will change the cursor mode to Talk for as long as the mouse is over the current object

\it{See Also:} \helprefn{Mouse.Mode}{Mouse.Mode}


\subsection{SelectNextMode}\label{Mouse.SelectNextMode}\index{Mouse.SelectNextMode}\index{SetNextCursorMode}%

\it{(Formerly known as SetNextCursorMode, which is now obsolete)}

\begin{verbatim}
Mouse.SelectNextMode()
\end{verbatim}
Selects the next enabled mouse cursor mode. This is useful for Sierra-style right-click
cycling through modes. This function will choose the next mode marked as a Standard Mode, and
will also use the Use Inventory mode if the player has an active inventory item.

\it{See Also:} \helprefn{Mouse.Mode}{Mouse.Mode}


\subsection{SetBounds}\label{Mouse.SetBounds}\index{Mouse.SetBounds}\index{SetMouseBounds}%

\it{(Formerly known as SetMouseBounds, which is now obsolete)}

\begin{verbatim}
Mouse.SetBounds(int left, int top, int right, int bottom)
\end{verbatim}

Restricts the area where the mouse can move on screen. The four parameters are
the relevant pixel co-ordinates of that edge of the bounding rectangle. They are
in the usual range (0,0) - (320,200).

You can pass (0,0,0,0) to disable the bounding rectangle and allow the mouse to move
everywhere, as usual.

\it{NOTE:} The effect of this function only lasts until the player leaves the screen,
at which point the cursor bounds will be reset.

\fcol{red}{Example:}
\begin{verbatim}
mouse.SetBounds(160, 100, 320, 200);
\end{verbatim}
will restrict the mouse cursor to the bottom-right quarter of the screen.

\it{See Also:} \helprefn{Mouse.SetPosition}{Mouse.SetPosition}


\subsection{SetPosition (mouse)}\label{Mouse.SetPosition}\index{Mouse.SetPosition}\index{SetMousePosition}%

\it{(Formerly known as SetMousePosition, which is now obsolete)}

\begin{verbatim}
Mouse.SetPosition(int x, int y)
\end{verbatim}

Moves the mouse pointer to screen co-ordinates (X,Y). They are
in the usual range (0,0) - (320,200/240). The mouse.x and mouse.y variables will be
updated to reflect the new position.

\bf{NOTE:} Only use this command when absolutely necessary. Moving the mouse cursor
for the player is a sure way to irritate them if you do it too often during the game.

\fcol{red}{Example:}
\begin{verbatim}
mouse.SetPosition(160, 100);
\end{verbatim}
will place the mouse cursor in the centre of the screen.

\it{See Also:} \helprefn{Mouse.SetBounds}{Mouse.SetBounds}


\subsection{Update}\label{Mouse.Update}\index{Mouse.Update}\index{RefreshMouse}%

\it{(Formerly known as RefreshMouse, which is now obsolete)}

\begin{verbatim}
Mouse.Update();
\end{verbatim}
Updates the global variables "mouse.x" and "mouse.y" with the current
position of the mouse. Normally, these variables are set just before each
script function is executed. However, if you have a very long script where
the mouse may have moved since the start of the function, and you need the
exact current location, then this command will update the variables.

\fcol{red}{Example:}
\begin{verbatim}
Display("The mouse was at: %d, %d.", mouse.x, mouse.y);
mouse.Update();
Display("The mouse is now at: %d, %d.", mouse.x, mouse.y);
\end{verbatim}
will display the mouse position just before each dialog box is displayed


\subsection{UseDefaultGraphic}\label{Mouse.UseDefaultGraphic}\index{Mouse.UseDefaultGraphic}\index{SetDefaultCursor}%

\it{(Formerly known as SetDefaultCursor, which is now obsolete)}

\begin{verbatim}
Mouse.UseDefaultGraphic()
\end{verbatim}
Changes the appearance of the mouse cursor to the default for the current
cursor mode. Use this to restore the cursor picture after you changed it
with the UseModeGraphic function.

\it{See Also:} \helprefn{Mouse.UseModeGraphic}{Mouse.UseModeGraphic}


\subsection{UseModeGraphic}\label{Mouse.UseModeGraphic}\index{Mouse.UseModeGraphic}\index{SetMouseCursor}%

\it{(Formerly known as SetMouseCursor, which is now obsolete)}

\begin{verbatim}
Mouse.UseModeGraphic(CursorMode)
\end{verbatim}
Changes the appearance of the mouse cursor to use the specified cursor. Unlike
the Mouse.Mode property, this does not change the mode used if the user
clicks on a hotspot. This is useful for displaying a "wait" cursor temporarily.

\fcol{red}{Example:}
\begin{verbatim}
mouse.UseModeGraphic(eModeWait);
\end{verbatim}
will change the mouse cursor to the cursor 'Wait' specified in the Cursors tab.

\it{See Also:} \helprefn{Mouse.ChangeModeGraphic}{Mouse.ChangeModeGraphic},
\helprefn{Mouse.Mode}{Mouse.Mode}, \helprefn{Mouse.UseDefaultGraphic}{Mouse.UseDefaultGraphic}


\subsection{Mode property (mouse)}\label{Mouse.Mode}\index{Mouse.Mode}\index{GetCursorMode}\index{SetCursorMode}%

\it{(Formerly known as GetCursorMode, which is now obsolete)}ILBRK
\it{(Formerly known as SetCursorMode, which is now obsolete)}

\begin{verbatim}
int Mouse.Mode;
\end{verbatim}
Gets/sets the current mode of the mouse cursor. This is one of the cursor modes
from your Cursors tab (but with eMode prepended). For example, a cursor mode called "Walk to"
on your cursors tab would be  eModeWalkto.

Setting this changes both the appearance of the cursor and the Cursor Mode
used if the player clicks on a hotspot.

\fcol{red}{Example:}
\begin{verbatim}
if (mouse.Mode == eModeWalkto)
{
   // code here
}
\end{verbatim}
will execute the code only if the current cursor mode is MODE 0 (WALK).

\it{See Also:} \helprefn{Mouse.SaveCursorUntilItLeaves}{Mouse.SaveCursorUntilItLeaves},
\helprefn{Mouse.UseModeGraphic}{Mouse.UseModeGraphic}, \helprefn{Mouse.SelectNextMode}{Mouse.SelectNextMode}


\subsection{Visible property (mouse)}\label{Mouse.Visible}\index{Mouse.Visible}\index{HideMouseCursor}\index{ShowMouseCursor}%

\it{(Formerly known as HideMouseCursor, which is now obsolete)}ILBRK
\it{(Formerly known as ShowMouseCursor, which is now obsolete)}

\begin{verbatim}
bool Mouse.Visible;
\end{verbatim}
Gets/sets whether the mouse cursor is visible. This is initially true by default,
but setting this to false is useful for briefly hiding the cursor on occasions
when you don't want it around.

If you want the Lucasarts-style where the mouse cursor is never visible during cutscenes
then a much easier solution is simply to import a transparent graphic over the default
wait cursor, so that the Wait cursor becomes invisible.

\fcol{red}{Example:}
\begin{verbatim}
mouse.Visible = false;
Wait(40);
mouse.Visible = true;
\end{verbatim}
hides the mouse, waits for a second, then turns it back on again

\it{See Also:} \helprefn{Mouse.UseModeGraphic}{Mouse.UseModeGraphic}


\section{Multimedia functions}%

\subsection{CDAudio}\label{CDAudio}%

\begin{verbatim}
CDAudio (eCDAudioFunction, int param)
\end{verbatim}
This function allows you to play and control an audio CD in your game.
Different tasks are performed, depending on the value of the AudioFunction
parameter. If there is no CD-ROM drive on the system, the function does
nothing.

The PARAM parameter is used by some of the functions for various reasons; if
it is not needed for the particular function you are calling, pass zero
instead.

The tasks performed are as follows depending on the COMMAND parameter:
\begin{verbatim}
eCDIsDriverPresent - checks if there is a CD-ROM driver available on
   the system. Returns 1 if there is, and 0 if there is not.
eCDGetPlayingStatus - checks whether the CD drive is currently playing
   an audio track. Returns 1 if it is, and 0 if it is not.
eCDPlayTrack - starts playback from track PARAM on the CD. If the track
   does not exist, or if it is a data track, nothing happens.
eCDPausePlayback - pauses the currently playing audio track.
eCDResumePlayback - continues from where the track was paused.
eCDGetNumTracks - returns the number of tracks on the CD
   currently in the drive. If the drive is empty, returns 0.
eCDEject - ejects the drive tray if the drive has the ability. This is
   a feature you'll play with to start off because it's neat, and then
   realize that it has no real use in your game.
   Your script does not continue until the drive is fully ejected.
eCDCloseTray - the reverse of Eject. This will pull the drive tray back
   in again. Your script does not continue until the drive has been
   fully closed.
eCDGetCDDriveCount - returns the number of CD drives in the
   system, normally 1.
eCDSelectActiveCDDrive - changes the current CD drive to PARAM,
   where PARAM ranges from 1 to (number of CD drives). All the other
   CD Audio functions operate on the current CD drive.
\end{verbatim}
NOTE: These CD Audio functions are slow compared to all the other script
functions. This will not be noticeable if you call them from most scripts,
but using CDAudio in a repeatedly_execute script will noticeably slow down
the game.

\bf{Cross-Platform Support}

Windows: \bf{ Yes, but supports 1 CD-ROM drive only }ILBRK
MS-DOS: \bf{ Yes, if CD-ROM device driver loaded }ILBRK
Linux: \bf{ Yes, but supports 1 CD-ROM drive only }ILBRK
MacOS: \bf{ No }

\fcol{red}{Example:}
\begin{verbatim}
CDAudio(eCDPlayTrack, 3);
\end{verbatim}
will play track 3 of the CD that's in the CD ROM drive.


\subsection{IsAudioPlaying}\label{Game.IsAudioPlaying}\index{Game.IsAudioPlaying}\index{IsMusicPlaying}\index{IsSoundPlaying}%

\it{(Formerly known as IsMusicPlaying, which is now obsolete)} ILBRK
\it{(Formerly known as IsSoundPlaying, which is now obsolete)}

\begin{verbatim}
static bool Game.IsAudioPlaying(optional AudioType)
\end{verbatim}
Returns \it{true} if there is currently audio playing of the specified type. If you don't
supply an audio type, then \it{true} will be returned if there is any audio at all playing
in the game.

If no audio of the specified type is playing, returns \it{false}. You can use this to wait
for some music to finish playing, for example.

\fcol{red}{Example:}
\begin{verbatim}
while (Game.IsAudioPlaying(eAudioTypeMusic))
{
  Wait(1);
}
\end{verbatim}
waits for any currently playing music to finish.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.StopAudio}{Game.StopAudio}


\subsection{IsSpeechVoxAvailable}\label{IsSpeechVoxAvailable}\index{IsVoxAvailable}%

\begin{verbatim}
IsSpeechVoxAvailable()
\end{verbatim}
Returns whether the SPEECH.VOX file is being used by the game.
This could be useful if you have an optional speech download pack, and
you want to know whether the player has it or not.

Returns 1 if the speech files are available, 0 if not.

\fcol{red}{Example:}
\begin{verbatim}
if (IsSpeechVoxAvailable()==0)
    Display ("You don't have the voice pack"); 
\end{verbatim}
will display a message if the voice pack is not available.

\bf{NOTE:} This function used to be called IsVoxAvailable, but has now been renamed to avoid confusion.

\it{See Also:} \helprefn{AudioClip.IsAvailable}{AudioClip.IsAvailable}


\subsection{PlayFlic}\label{PlayFlic}%

\begin{verbatim}
PlayFlic (int flic_number, int options)
\end{verbatim}
Plays a FLI or FLC animation. The game checks for FLICx.FLC and FLICx.FLI
(where X is FLIC_NUMBER) and if it finds one, plays it.

OPTIONS has these meanings:
\begin{verbatim}
0  player can't skip animation
1  player can press ESC to skip animation
2  player can press any key or click mouse to skip animation
+10 (ie.10,11,12) do not stretch to full-screen, just play at flc size
+100 do not clear the screen before starting playback
\end{verbatim}
The game is paused while the animation plays.

\fcol{red}{Example:}
\begin{verbatim}
PlayFlic(2, 1);
\end{verbatim}
will play flic2 and the player will be able to skip the flic by pressing the ESC key.

\it{See Also:} \helprefn{PlayVideo}{PlayVideo}


\subsection{PlaySilentMIDI}\label{PlaySilentMIDI}%

\begin{verbatim}
PlaySilentMIDI (int music_number)
\end{verbatim}
This command is obsolete.

Use the AudioClip.Play command and set its Volume property to 0 to simulate this effect.

\it{See Also:} \helprefn{AudioClip.Play}{AudioClip.Play}, \helprefn{AudioChannel.Volume}{AudioChannel.Volume}


\subsection{PlayVideo}\label{PlayVideo}\index{Videos, playing}\index{Movies, playing}%

\begin{verbatim}
PlayVideo (string filename, VideoSkipStyle, int flags)
\end{verbatim}
Plays an AVI, MPG or OGG Theora file, or any other file type supported by Media Player.
The game is paused while the video plays.

\it{VideoSkipStyle} defines how the player can skip the video:
\begin{verbatim}
eVideoSkipNotAllowed     player can't skip video
eVideoSkipEscKey         player can press ESC to skip video
eVideoSkipAnyKey         player can press any key to skip video
eVideoSkipAnyKeyOrMouse  player can press any key or click mouse to skip
\end{verbatim}

FLAGS can be one of the following:
\begin{verbatim}
0: the video will be played at original size, with AVI audio
1: the video will be stretched to full screen, with appropriate
   black borders to maintain its aspect ratio and AVI audio.
10: original size, with game audio continuing (AVI audio muted)
11: stretched to full screen, with game audio continuing (AVI audio muted)
\end{verbatim}

There are two distinct type of videos that the PlayVideo function can play.

The first is OGG Theora, which is a recently introduced video file format. AGS
has built-in support for playing these videos, so everyone who plays your game
will be able to see the video. OGG Theora videos are also built into the game EXE
file when you compile the game (just make sure the file has a .OGV extension and
is placed in your main game folder).

The second type of files that AGS can play is anything supported by Windows Media
Player. This includes AVI, MPG and more. However, in order for these to work on
the player's system, they will need to have the correct codecs installed. For example,
if you create your video with the XVid codec, the player will need to have XVid installed
to be able to view it. These types of video cannot be included into the game EXE, 
so you will have to place them separately in the Compiled folder for them to work.

\bf{NOTE:} In 256-colour games, PlayVideo is not supported. Please use a FLC/FLI video
with the \helprefn{PlayFlic}{PlayFlic} command instead.

\bf{Cross-Platform Support}

Windows: \bf{ Yes }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ No }ILBRK
MacOS: \bf{ Yes }

\fcol{red}{Example:}
\begin{verbatim}
PlayVideo("intro.mpg", eVideoSkipEscKey, 1);
\end{verbatim}
will play the video Intro.mpg, allowing the player to skip with ESC if they've seen it
before.

\it{Compatibility:} OGG Theora supported by \bf{AGS 3.1.1} and later versions.

\it{See Also:} \helprefn{PlayFlic}{PlayFlic}


\subsection{SetAudioTypeSpeechVolumeDrop}\label{Game.SetAudioTypeSpeechVolumeDrop}\index{Game.SetAudioTypeSpeechVolumeDrop}%

\it{(Formerly known as game.speech_music_drop, which is now obsolete)}

\begin{verbatim}
static Game.SetAudioTypeSpeechVolumeDrop(AudioType, int volumeReduction)
\end{verbatim}
Changes the VolumeReductionWhileSpeechPlaying of the specified \it{AudioType}. This changes
the setting, initially set in the Audio Types part of the editor. It specifies how much
the volume of clips of this type will be reduced by while speech is playing.

Specify 0 for no volume adjustment, up to 100 which will completely silence these audio
clips while speech is playing.

\fcol{red}{Example:}
\begin{verbatim}
Game.SetAudioTypeSpeechVolumeDrop(eAudioTypeMusic, 25);
\end{verbatim}
will reduce the volume of Music audio clips by 25 percentage points while speech is playing.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.SetAudioTypeVolume}{Game.SetAudioTypeVolume}


\subsection{SetAudioTypeVolume}\label{Game.SetAudioTypeVolume}\index{Game.SetAudioTypeVolume}\index{SetSoundVolume}%

\it{(Formerly known as SetSoundVolume, which is now obsolete)}

\begin{verbatim}
static Game.SetAudioTypeVolume(AudioType, int volume, ChangeVolumeType)
\end{verbatim}
Changes the default volume of the specified \it{AudioType}. This allows you to
change the volume of all audio clips of a particular type, so that you can
easily control sound and music volume separately, for example.

Possible values for \it{ChangeVolumeType} are:
\begin{verbatim}
eVolChangeExisting      change the volume of currently playing audio clips
eVolSetFutureDefault    change the default volume for clips of this type
eVolExistingAndFuture   change both currently playing and future audio
\end{verbatim}

If you use the \it{eVolSetFutureDefault} or \it{eVolExistingAndFuture}, then
the DefaultVolume property for all audio clips of this type will be overridden.
This means that any DefaultVolume set up in the editor will be lost.

\fcol{red}{Example:}
\begin{verbatim}
Game.SetAudioTypeVolume(eAudioTypeMusic, 20, eVolExistingAndFuture);
\end{verbatim}
will change the volume of all currently playing and future music to \verb$20%$.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{SetSpeechVolume}{SetSpeechVolume}, \helprefn{AudioClip.Play}{AudioClip.Play}, 
\helprefn{System.Volume}{System.Volume}


\subsection{SetSpeechVolume}\label{SetSpeechVolume}%

\begin{verbatim}
SetSpeechVolume (int volume)
\end{verbatim}
Sets the volume for in-game speech. VOLUME ranges from 0-255, where 255 is
the loudest. The default speech volume is 255 so this function can only
be used to reduce the volume.

\fcol{red}{Example:}
\begin{verbatim}
SetSpeechVolume(200);
\end{verbatim}
will set the speech volume to 200.

\it{See Also:} \helprefn{Game.SetAudioTypeVolume}{Game.SetAudioTypeVolume}


\subsection{SetVoiceMode}\label{SetVoiceMode}%

\begin{verbatim}
SetVoiceMode (VoiceMode)
\end{verbatim}
Determines whether voice speech and/or text captions are used in the game.

Valid values for VoiceMode are:
\begin{verbatim}
eSpeechTextOnly      no voice, text only
eSpeechVoiceAndText  both voice and text
eSpeechVoiceOnly     voice only, no text
\end{verbatim}
The default is \it{eSpeechVoiceAndText} if in-game speech is enabled, and \it{eSpeechTextOnly} if it
is not. Changing this setting changes the behaviour of all \helprefn{Say}{Character.Say} and
\helprefn{Display}{Display} commands which have a speech file assigned to them.

\bf{WARNING:} you should only ever use \it{eSpeechVoiceOnly} at the player's request to
do so, because there is no guarantee that they even have a sound card and so may
not understand what is going on.

\fcol{red}{Example:}
\begin{verbatim}
if (IsSpeechVoxAvailable()==1)
    SetVoiceMode(eSpeechVoiceAndText); 
\end{verbatim} 
will set the voice mode to voice and text if the voice pack is available.


\subsection{StopAudio}\label{Game.StopAudio}\index{Game.StopAudio}\index{Game.StopSound}\index{StopMusic}%

\it{(Formerly known as Game.StopSound, which is now obsolete)} ILBRK
\it{(Formerly known as StopMusic, which is now obsolete)}

\begin{verbatim}
static Game.StopAudio(optional AudioType)
\end{verbatim}
Stops all currently playing audio. If you pass no parameters, then all audio will be stopped.
Alternatively, you can pass one of the AudioTypes which will only stop audio clips of that
type.

If there are any audio clips queued up with PlayQueued, they will also be cancelled.

\fcol{red}{Example:}
\begin{verbatim}
Game.StopAudio();
\end{verbatim}
will stop all currently playing audio.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.IsAudioPlaying}{Game.IsAudioPlaying}, \helprefn{AudioClip.Play}{AudioClip.Play}, 
\helprefn{AudioChannel.Stop}{AudioChannel.Stop}


\section{Object functions and properties}%


\subsection{Animate (object)}\label{Object.Animate}\index{Object.Animate}\index{AnimateObject}\index{AnimateObjectEx}%

\it{(Formerly known as AnimateObject, which is now obsolete)} ILBRK
\it{(Formerly known as AnimateObjectEx, which is now obsolete)}

\begin{verbatim}
Object.Animate(int loop, int delay, optional RepeatStyle,
               optional BlockingStyle, optional Direction)
\end{verbatim}
Starts the object animating, using loop number LOOP of its current view.
The overall speed of the animation is set with DELAY, where 0 is the
fastest, and increasing numbers mean slower. The delay for each frame
is worked out as DELAY + FRAME SPD, so the individual frame speeds are
relative to this overall speed.

The \it{RepeatStyle} parameter sets whether the animation will continuously repeat
the cycling through the frames. This can be \it{eOnce} (or zero), in which case the animation
will start from the first frame of LOOP, and go through each frame in turn until the
last frame, where it will stop. If RepeatStyle is \it{eRepeat} (or 1), then when the last frame
is reached, it will go back to the first frame and start over again with the animation.
If RepeatStyle is 2 then it will do the animation once, but then return
the graphic to the first frame and stop (whereas repeat=0 will leave the
graphic on the last frame).

For \it{blocking} you can pass either eBlock (in which case the function will wait
for the animation to finish before returning), or eNoBlock (in which case the animation
will start to play, but your script will continue). The default is eBlock.

\it{direction} specifies which way the animation plays. You can either pass eForwards (the
default) or eBackwards.

You need to use SetView at some stage before this command, in order to set up the object's
current view.

\fcol{red}{Example:}
\begin{verbatim}
object[0].Animate(2, 5);
object[1].Animate(1, 3, eOnce, eBlock, eBackwards);
\end{verbatim}
will animate object 0 using loop 2 of its current view, at speed 5, and play the
animation once only. This happens in the background.
Then, object 1 will animate backwards using loop 1 of its current view, at speed 3. The
function won't return until the animation is finished.

\it{See Also:} \helprefn{Character.Animate}{Character.Animate},
\helprefn{Object.Animating}{Object.Animating}, \helprefn{Object.SetView}{Object.SetView},
\helprefn{Object.StopAnimating}{Object.StopAnimating}


\subsection{GetAtScreenXY (object)}\label{Object.GetAtScreenXY}\index{Object.GetAtScreenXY}\index{GetObjectAt}%

\it{(Formerly known as global function GetObjectAt, which is now obsolete)}

\begin{verbatim}
static Object* Object.GetAtScreenXY(int x, int y)
\end{verbatim}
Checks if there is a room object at SCREEN co-ordinates (X,Y).
Returns the object if there is, or \it{null} if there is not.

See the description of GetLocationName for more on screen co-ordinates.

\fcol{red}{Example:}
\begin{verbatim}
if (Object.GetAtScreenXY(211,145) == oRock) {
  // code here
}
\end{verbatim}
will execute the code only if object oRock is on the screen coordinates 211,145.

\it{See Also:} \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY},
\helprefn{Game.GetLocationName}{Game.GetLocationName}


\subsection{GetProperty (object)}\label{Object.GetProperty}\index{Object.GetProperty}\index{GetObjectProperty}%

\it{(Formerly known as GetObjectProperty, which is now obsolete)}

\begin{verbatim}
Object.GetProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the specified object.

This command works with Number properties (it returns the number), and with Boolean
properties (returns 1 if the box was checked, 0 if not).

Use the equivalent GetTextProperty function to get a text property.

\fcol{red}{Example:}
\begin{verbatim}
if (object[0].GetProperty("Value") > 200)
  Display("Object 0's value is over 200!");
\end{verbatim}
will print the message if object 0 has its "Value" property set to more than 200.

\it{See Also:} \helprefn{Object.GetTextProperty}{Object.GetTextProperty}


\subsection{GetTextProperty (object)}\label{Object.GetTextProperty}\index{Object.GetTextProperty}\index{Object.GetPropertyText}\index{GetObjectPropertyText}%

\it{(Formerly known as GetObjectPropertyText, which is now obsolete)} ILBRK
\it{(Formerly known as Object.GetPropertyText, which is now obsolete)}

\begin{verbatim}
String Object.GetTextProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the specified object.

This command works with Text properties only. The property's text will be
returned from this function.

Use the equivalent GetProperty function to get a non-text property.

\fcol{red}{Example:}
\begin{verbatim}
String description = object[0].GetTextProperty("Description");
Display("Object 0's description: %s", description);
\end{verbatim}
will retrieve Object 0's "description" property then display it.

\it{See Also:} \helprefn{Object.GetProperty}{Object.GetProperty}


\subsection{IsCollidingWithObject (object)}\label{Object.IsCollidingWithObject}\index{Object.IsCollidingWithObject}\index{AreObjectsColliding}%

\it{(Formerly known as AreObjectsColliding, which is now obsolete)}

\begin{verbatim}
bool Object.IsCollidingWithObject(Object* obj2)
\end{verbatim}
Checks if the specified object and OBJ2 are touching each other. Returns \it{true} if they
are, and \it{false} if they are not.

\bf{NOTE:} This function only performs a rectangular check, even when pixel-perfect
click detection is turned on.

\fcol{red}{Example:}
\begin{verbatim}
if (object[2].IsCollidingWithObject(object[3])) 
{
  Display("object 2 and 3 are colliding!");
}
\end{verbatim}
will display the message if the objects 2 and 3 are colliding.

\it{See Also:} \helprefn{AreThingsOverlapping}{AreThingsOverlapping}


\subsection{MergeIntoBackground}\label{Object.MergeIntoBackground}\index{Object.MergeIntoBackground}\index{MergeObject}%

\it{(Formerly known as MergeObject, which is now obsolete)}

\begin{verbatim}
Object.MergeIntoBackground()
\end{verbatim}
Merges the object into the background scene for this room.
By doing this, the object becomes part of the background and so does not
slow the game down. This is a 1-way operation - once the object has
been merged, it cannot be changed back and the state of the room is
permanently altered. Therefore you should only use this function if a game
event has occurred that means the room is permanently changed.

\bf{NOTE:} after calling this function, you cannot use the object any more and
it is permanently removed from the game.

\bf{NOTE:} objects can only be merged if the object graphic was imported at
the same colour depth as the background graphic.

\fcol{red}{Example:}
\begin{verbatim}
object[3].MergeIntoBackground();
\end{verbatim}
will merge the object's image into the room's background image and make the object unusable.


\subsection{Move (object)}\label{Object.Move}\index{Object.Move}\index{MoveObject}\index{MoveObjectDirect}%

\it{(Formerly known as MoveObject, which is now obsolete)} ILBRK
\it{(Formerly known as MoveObjectDirect, which is now obsolete)}

\begin{verbatim}
Object.Move(int x, int y, int speed, optional BlockingStyle,
            optional WalkWhere);
\end{verbatim}
Starts the object moving from its current location to (X,Y). It will
move at speed SPEED, which uses the same scale as the character Walk Speed
values in the AGS Editor.

If \it{BlockingStyle} is eNoBlock (the default), then control returns to the script
immediately, and the object will move in the background.

If \it{BlockingStyle} is eBlock then this command will wait for the object
to finish moving before your script resumes.

If \it{WalkWhere} is eWalkableAreas (the default), then the object will attempt to
get as close a possible to (X,Y) by using the room's walkable areas.

If \it{WalkWhere} is eAnywhere, then the object will simply walk directly from its
current location to (X,Y), ignoring the room walkable areas.

\fcol{red}{Example:}
\begin{verbatim}
object[2].Move(125, 40, 4, eBlock);
\end{verbatim}
will move object 2 to 125,40 and return control to the player when the object gets there.

\it{See Also:} \helprefn{Object.Moving}{Object.Moving}, \helprefn{Character.Walk}{Character.Walk},
\helprefn{Object.StopMoving}{Object.StopMoving}


	
\subsection{RemoveTint (object)}\label{Object.RemoveTint}\index{Object.RemoveTint}\index{RemoveObjectTint}%

\it{(Formerly known as RemoveObjectTint, which is now obsolete)}

\begin{verbatim}
Object.RemoveTint()
\end{verbatim}

Undoes the effects of calling Tint, and returns the object to using the room's ambient tint.

\fcol{red}{Example:}
\begin{verbatim}
object[1].Tint(0, 250, 0, 30, 100);
Wait(40);
object[1].RemoveTint();
\end{verbatim}
will tint object 1 green for a second, then turn it back to normal.

\it{See Also:} \helprefn{Object.Tint}{Object.Tint}


\subsection{RunInteraction (object)}\label{Object.RunInteraction}\index{Object.RunInteraction}\index{RunObjectInteraction}%

\it{(Formerly known as RunObjectInteraction, which is now obsolete)}

\begin{verbatim}
Object.RunInteraction(CursorMode)
\end{verbatim}
Runs the event handler as if the player had clicked the mouse
on the object in the current room, using the specified cursor mode.

\fcol{red}{Example:}
\begin{verbatim}
object[3].RunInteraction(eModeInteract);
\end{verbatim}
will execute the code defined in object 3's "Interact with object" event handler.

\it{See Also:} \helprefn{ProcessClick}{ProcessClick},
\helprefn{Character.RunInteraction}{Character.RunInteraction},
\helprefn{Hotspot.RunInteraction}{Hotspot.RunInteraction}


\subsection{SetPosition (object)}\label{Object.SetPosition}\index{Object.SetPosition}\index{SetObjectPosition}%

\it{(Formerly known as SetObjectPosition, which is now obsolete)}

\begin{verbatim}
Object.SetPosition(int x, int y)
\end{verbatim}
Changes the object's position to (X,Y). These co-ordinates specify the lower-left
hand corner of the object.

This command is equivalent to setting the object.X and object.Y separately, but provides a
more convenient way of doing so.

\bf{NOTE:} This command cannot be used while the object is moving.

\fcol{red}{Example:}
\begin{verbatim}
object[2].SetPosition(50, 100);
\end{verbatim}
will change object's 2 position to 50,100.

\it{See Also:} \helprefn{Object.X}{Object.X}, \helprefn{Object.Y}{Object.Y}


\subsection{SetView}\label{Object.SetView}\index{Object.SetView}\index{SetObjectView}\index{SetObjectFrame}%

\it{(Formerly known as SetObjectFrame, which is now obsolete)} ILBRK
\it{(Formerly known as SetObjectView, which is now obsolete)}

\begin{verbatim}
Object.SetView(int view, optional int loop, optional int frame)
\end{verbatim}
Sets the object's view to VIEW, and changes the object's graphic to FRAME of LOOP in VIEW.
If you do not supply the loop or frame, they will be left unchanged.

You must use this command before calling Animate, so that AGS knows which view to animate
the object with.

\fcol{red}{Example:}
\begin{verbatim}
object[3].SetView(14);
object[1].SetView(5, 2, 0);
\end{verbatim}
will change object 3's view to view number 14, and change object 1 to view 5, loop 2, frame 0.

\it{See Also:} \helprefn{Object.Animate}{Object.Animate}


\subsection{StopAnimating (object)}\label{Object.StopAnimating}\index{Object.StopAnimating}%

\begin{verbatim}
Object.StopAnimating()
\end{verbatim}
Stops the object from animating. It will remain on its current frame until you change it
or start a new animation.

\fcol{red}{Example:}
\begin{verbatim}
if (object[2].Animating) {
  object[2].StopAnimating();
}
\end{verbatim}
will stop object 2 animating if it currently is doing so.

\it{See Also:} \helprefn{Object.Animate}{Object.Animate},
\helprefn{Object.Animating}{Object.Animating}


\subsection{StopMoving (object)}\label{Object.StopMoving}\index{Object.StopMoving}\index{StopObjectMoving}%

\it{(Formerly known as StopObjectMoving, which is now obsolete)}

\begin{verbatim}
Object.StopMoving()
\end{verbatim}
Stops the object from moving. It will remain in its current position
until any further commands are issued.

\fcol{red}{Example:}
\begin{verbatim}
if (object[2].Moving) {
  object[2].StopMoving();
}
\end{verbatim}
will stop object 2 moving if it currently is doing so.

\it{See Also:} \helprefn{Object.Moving}{Object.Moving}, \helprefn{Object.Move}{Object.Move},
\helprefn{Character.StopMoving}{Character.StopMoving}


\subsection{Tint (object)}\label{Object.Tint}\index{Object.Tint}\index{SetObjectTint}%

\it{(Formerly known as SetObjectTint, which is now obsolete)}

\begin{verbatim}
Object.Tint(int red, int green, int blue,
            int saturation, int luminance)
\end{verbatim}

Tints the object on the screen to (RED, GREEN, BLUE) with SATURATION percent
saturation.

This function applies a tint to a specific object. For the meaning of all the parameters,
see \helprefn{SetAmbientTint}{SetAmbientTint}.

The tint set by this function overrides any ambient tint set for the room. For this
reason, passing the SATURATION as 0 to this function does not turn it off - rather, it
ensures that no tint is applied to the object (even if an ambient tint is set).

To remove the tint set by this function and return to using the ambient tint for this
object, call \helprefn{RemoveTint}{Object.RemoveTint}.

\bf{NOTE:} This function only works in hi-colour games and with hi-colour sprites.

\fcol{red}{Example:}
\begin{verbatim}
object[1].Tint(0, 250, 0, 30, 100);
\end{verbatim}
will tint object 1 green.

\it{See Also:} \helprefn{Object.RemoveTint}{Object.RemoveTint},
\helprefn{SetAmbientTint}{SetAmbientTint}



\subsection{Animating property (object)}\label{Object.Animating}\index{Object.Animating}\index{IsObjectAnimating}%

\it{(Formerly known as IsObjectAnimating, which is now obsolete)}

\begin{verbatim}
readonly bool Object.Animating
\end{verbatim}
Returns 1 if the specified object is currently animating. ILBRK
Returns 0 if the object has finished its animation.

This property is read-only. To change object animation, use the
\helprefn{Animate}{Object.Animate} command.

\fcol{red}{Example:}
\begin{verbatim}
object[2].Animate(5, 0);
while (object[2].Animating) Wait(1);
\end{verbatim}
will animate object 2 and wait until the animation finishes.

In reality, you would simply use the Blocking parameter of Animate so you wouldn't need
to do this.

\it{See Also:} \helprefn{Object.Animate}{Object.Animate},
\helprefn{Object.Moving}{Object.Moving},
\helprefn{Object.StopAnimating}{Object.StopAnimating},
\helprefn{Object.X}{Object.X}, \helprefn{Object.Y}{Object.Y}


\subsection{Baseline property (object)}\label{Object.Baseline}\index{Object.Baseline}\index{SetObjectBaseline}\index{GetObjectBaseline}%

\it{(Formerly known as GetObjectBaseline, which is now obsolete)} ILBRK
\it{(Formerly known as SetObjectBaseline, which is now obsolete)}

\begin{verbatim}
int Object.Baseline
\end{verbatim}
Gets/sets the object's baseline. This allows you to modify the line you can
set in the editor. You can disable the baseline (and revert to using the
base of the object's image on the screen) by setting it to 0.

Otherwise, set it to the Y screen co-ordinate you want to use,
normally from 1 to 200 unless you have a taller than usual room.

If you want to get the baseline and it returns 0, then the baseline is the
object's Y co-ordinate.

\fcol{red}{Example:}
\begin{verbatim}
object[4].Baseline = 100;
\end{verbatim}
will change object's 4 baseline to a line positioned at y coordinate 100.

\it{See Also:} \helprefn{Character.Baseline}{Character.Baseline},
\helprefn{Object.Y}{Object.Y},
\helprefn{SetWalkBehindBase}{SetWalkBehindBase}


\subsection{BlockingHeight property (object)}\label{Object.BlockingHeight}\index{Object.BlockingHeight}%

\begin{verbatim}
int Object.BlockingHeight
\end{verbatim}
Gets/sets the object's blocking height.

The blocking height determines how large of a blocking rectangle the object exerts to
stop characters walking through it. If this is set to 0 (the default), then the
blocking rectangle is automatically calculated to be the object's width, and 5 pixels
high.

You can manually change the setting by entering a blocking height in pixels, which is the
size of walkable area that the object effectively removes by being there.

\bf{NOTE:} This property has no effect unless the \helprefn{Solid}{Object.Solid} property
is set to \it{true}.

\fcol{red}{Example:}
\begin{verbatim}
oRock.BlockingHeight = 20;
\end{verbatim}
will make the Rock object block 20 pixels high (10 above and 10 below its baseline)

\it{See Also:} \helprefn{Object.BlockingWidth}{Object.BlockingWidth},
\helprefn{Object.Solid}{Object.Solid}


\subsection{BlockingWidth property (object)}\label{Object.BlockingWidth}\index{Object.BlockingWidth}%

\begin{verbatim}
int Character.BlockingWidth
\end{verbatim}
Gets/sets the object's blocking width.

The blocking width determines how large of a blocking rectangle the object exerts to
stop characters walking through it. If this is set to 0 (the default), then the
blocking rectangle is automatically calculated to be the object's width, and 5 pixels
high.

You can manually change the setting by entering a blocking width in pixels, which is the
size of walkable area that the object effectively removes by being there.

\bf{NOTE:} This property has no effect unless the \helprefn{Solid}{Object.Solid} property
is set to \it{true}.

\fcol{red}{Example:}
\begin{verbatim}
oRock.BlockingWidth = 50;
\end{verbatim}
will make the Rock object block 50 pixels wide (25 pixels to the left of his centre, and 25 to the right)

\it{See Also:} \helprefn{Object.BlockingHeight}{Object.BlockingHeight},
\helprefn{Object.Solid}{Object.Solid}


\subsection{Clickable property (object)}\label{Object.Clickable}\index{Object.Clickable}\index{SetObjectClickable}%

\it{(Formerly known as SetObjectClickable, which is now obsolete)}

\begin{verbatim}
bool Object.Clickable
\end{verbatim}
Gets/sets whether the object is recognised as something which the player can
interact with.

If this is set to 1, then the player can look at, speak to, and so on the
object. If it is set to 0, then the object will not respond to clicks and
the mouse will activate whatever is behind the object.
This is useful if you are using the object for visual effects and don't
want it to be clicked on by the player.

\fcol{red}{Example:}
\begin{verbatim}
object[2].Clickable = 0;
\end{verbatim}
will make object 2 ignore clicks from the player.

\it{See Also:} \helprefn{Character.Clickable}{Character.Clickable},
\helprefn{Object.IgnoreWalkbehinds}{Object.IgnoreWalkbehinds}


\subsection{Frame property (object)}\label{Object.Frame}\index{Object.Frame}%

\begin{verbatim}
readonly int Object.Frame
\end{verbatim}
Gets the frame number that the object is currently set to. If the object is not currently
assigned a view, this will be 0 (in which case the Graphic property will
hold its sprite number).

This property is read-only. To change the frame, use the animation functions.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object oDoor's frame is currently %d.", oDoor.Frame);
\end{verbatim}
will display the oDoor object's current frame number

\it{SeeAlso:} \helprefn{Object.Graphic}{Object.Graphic},
\helprefn{Object.Loop}{Object.Loop},
\helprefn{Object.View}{Object.View}


\subsection{Graphic property (object)}\label{Object.Graphic}\index{Object.Graphic}\index{SetObjectGraphic}\index{GetObjectGraphic}%

\it{(Formerly known as GetObjectGraphic, which is now obsolete)} ILBRK
\it{(Formerly known as SetObjectGraphic, which is now obsolete)}

\begin{verbatim}
int Object.Graphic
\end{verbatim}
Gets/sets the sprite slot number that the object is currently displayed as.
You can get the slot number from the Sprite Manager. If the object is
currently animating (from an Animate command) and you change the Graphic, then the
animation will be stopped.

\fcol{red}{Example:}
\begin{verbatim}
object[2].Graphic = 100;
\end{verbatim}
will change the object 2's image to the image stored in the sprite manager's slot 100.

\it{See Also:} \helprefn{Object.SetView}{Object.SetView}


\subsection{ID property (object)}\label{Object.ID}\index{Object.ID}%

\begin{verbatim}
readonly int Object.ID
\end{verbatim}
Gets the object's ID number. This is the object's number from the editor, and is
useful if you need to interoperate with legacy code that uses the object's number
rather than name.

\fcol{red}{Example:}
\begin{verbatim}
MoveObject(oRock.ID, 100, 50, 5);
\end{verbatim}
uses the obsolete MoveObject function to move the Rock object to (100, 50) at speed 5.


\subsection{IgnoreScaling property (object)}\label{Object.IgnoreScaling}\index{Object.IgnoreScaling}%

\begin{verbatim}
bool Object.IgnoreScaling
\end{verbatim}
Gets/sets whether the object is affected by walkable area scaling. This is equivalent,
\bf{though opposite}, to the "Use walkable area scaling" checkbox in the Objects pane of the editor.

If this is set to true, the object will always be the same size. If it is set to false, then
the object will be stretched or shrunk as appropriate on walkable areas.

\fcol{red}{Example:}
\begin{verbatim}
oDoor.IgnoreScaling = true;
\end{verbatim}
will tell the Door object not to be scaled on walkable areas.

\it{See Also:} \helprefn{Object.IgnoreWalkbehinds}{Object.IgnoreWalkbehinds}


\subsection{IgnoreWalkbehinds property (object)}\label{Object.IgnoreWalkbehinds}\index{Object.IgnoreWalkbehinds}\index{SetObjectIgnoreWalkbehinds}%

\it{(Formerly known as SetObjectIgnoreWalkbehinds, which is now obsolete)}

\begin{verbatim}
bool Object.IgnoreWalkbehinds
\end{verbatim}
Sets whether the object is affected by walkbehind areas. Setting this to \it{false} 
(the default setting) means that the object will be placed behind walk-behind
areas according to the relevant baselines.

If this is set to \it{true}, then the object will never be placed behind a walk-behind
area. This is useful if for example you want an object to be a picture on
a wall, and the wall can be walked behind - but you also want it to act
correctly in relation to characters, so changing its baseline wouldn't work.

\bf{NOTE:} enabling this property does not currently work properly when using
the Direct3D driver.

\fcol{red}{Example:}
\begin{verbatim}
object[1].IgnoreWalkbehinds = true;
\end{verbatim}
will make object 1 ignore walk behinds.


\it{See Also:} \helprefn{Object.Baseline}{Object.Baseline},
\helprefn{Object.Clickable}{Object.Clickable}, \helprefn{Object.IgnoreScaling}{Object.IgnoreScaling}


\subsection{Loop property (object)}\label{Object.Loop}\index{Object.Loop}%

\begin{verbatim}
readonly int Object.Loop
\end{verbatim}
Gets the loop that the object is currently set to. If the object is not currently
assigned a view, this will be 0 (in which case the Graphic property will
hold its sprite number).

This property is read-only. To change the loop, use the animation functions.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object oDoor's loop is currently %d.", oDoor.Loop);
\end{verbatim}
will display the oDoor object's current loop number

\it{SeeAlso:} \helprefn{Object.Frame}{Object.Frame},
\helprefn{Object.Graphic}{Object.Graphic},
\helprefn{Object.View}{Object.View}


\subsection{Moving property (object)}\label{Object.Moving}\index{Object.Moving}\index{IsObjectMoving}%

\it{(Formerly known as IsObjectMoving, which is now obsolete)}

\begin{verbatim}
readonly bool Object.Moving
\end{verbatim}
Returns 1 if the object is currently moving, or 0 if not.

This property is read-only; to change the object's movement, use the \helprefn{Move}{Object.Move}
and \helprefn{StopMoving}{Object.StopMoving} commands.

\fcol{red}{Example:}
\begin{verbatim}
object[2].Move(125,40,3);
while (object[2].Moving) Wait(1);
\end{verbatim}
will move object 2 to 125,40 and return control to the player when the object gets there.

\it{See Also:} \helprefn{Object.Animating}{Object.Animating},
\helprefn{Object.StopMoving}{Object.StopMoving}


\subsection{Name property (object)}\label{Object.Name}\index{Object.Name}\index{Object.GetName}\index{GetObjectName}%

\it{(Formerly known as GetObjectName, which is now obsolete)} ILBRK
\it{(Formerly known as Object.GetName, which is now obsolete)}

\begin{verbatim}
readonly String Object.Name;
\end{verbatim}
Gets the name of the object.

\bf{NOTE}: This property is read-only. It is not currently possible to change the name
of an object at run-time.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object 0's name is %s.", object[0].Name);
\end{verbatim}
will retrieve and then display object 0's name.

\it{See Also:} \helprefn{Game.GetLocationName}{Game.GetLocationName}


\subsection{Solid property (object)}\label{Object.Solid}\index{Object.Solid}%

\begin{verbatim}
bool Object.Solid
\end{verbatim}
Gets/sets whether the object can be walked through by characters.

If this is set to true, then the object is solid and will block the path of solid
characters. If this is set to false, then the object can be walked through by
characters.

\bf{NOTE:} solid objects only block characters, they don't block other objects from
moving through them.

\fcol{red}{Example:}
\begin{verbatim}
oSmallrock.Solid = true;
\end{verbatim}
will mean that the Smallrock object blocks the path of characters.

\it{See Also:} \helprefn{Object.BlockingHeight}{Object.BlockingHeight},
\helprefn{Object.BlockingWidth}{Object.BlockingWidth}


\subsection{Transparency property (object)}\label{Object.Transparency}\index{Object.Transparency}\index{SetObjectTransparency}%

\it{(Formerly known as SetObjectTransparency, which is now obsolete)}

\begin{verbatim}
int Object.Transparency
\end{verbatim}
Gets/sets the object's transparency level.

If this is set to 100, it means that the object is totally invisible, and lower values
represent varying levels of transparency. Set this to 0 to stop the object being transparent.

\bf{NOTE:} Transparency only works in 16-bit and 32-bit colour games.

\bf{NOTE:} When using the DirectX 5 driver, a large transparent object can significantly slow
down AGS.

Some rounding is done internally when the transparency is stored -- therefore, if you get
the transparency after setting it, the value you get back might be one out. Therefore, using
a loop with \verb$object[0].Transparency++;$ is not recommended as it will probably
end too quickly.

In order to fade an object in/out, the best approach is shown in the example below:

\fcol{red}{Example:}
\begin{verbatim}
int trans = object[0].Transparency;
while (trans < 100) {
  trans++;
  object[0].Transparency = trans;
  Wait(1);
}
\end{verbatim}
will gradually fade out the object from its current transparency level to being fully
invisible.

\it{See Also:} \helprefn{Character.Transparency}{Character.Transparency},
\helprefn{GUI.Transparency}{GUI.Transparency}


\subsection{View property (object)}\label{Object.View}\index{Object.View}%

\begin{verbatim}
readonly int Object.View
\end{verbatim}
Gets the view that the object is currently set to. This is either the view number, or 0
if the object is not currently assigned a view (in which case the Graphic property will
hold its sprite number instead).

This property is read-only. To change the view, use the SetView function. To remove
the view, set the Graphic property to a sprite slot.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object oDoor's view is currently view %d.", oDoor.View);
\end{verbatim}
will display the oDoor object's current view number

\it{SeeAlso:} \helprefn{Object.SetView}{Object.SetView},
\helprefn{Object.Graphic}{Object.Graphic}, \helprefn{Object.Loop}{Object.Loop},
\helprefn{Object.Frame}{Object.Frame}


\subsection{Visible property (object)}\label{Object.Visible}\index{ObjectOff}\index{ObjectOn}\index{IsObjectOn}%

\it{(Formerly known as IsObjectOn, which is now obsolete)} ILBRK
\it{(Formerly known as ObjectOff, which is now obsolete)} ILBRK
\it{(Formerly known as ObjectOn, which is now obsolete)}

\begin{verbatim}
bool Object.Visible
\end{verbatim}
Gets/sets the visible state of the object. If this is 1 (true), the object is switched on
and visible in the room. If you set this to 0 (false), the object disappears and no longer
appears in the room.

\fcol{red}{Example:}
\begin{verbatim}
object[5].Visible = false;
\end{verbatim}
will make object number 5 in the current room disappear.


\subsection{X property (object)}\label{Object.X}\index{Object.X}\index{GetObjectX}%

\it{(Formerly known as GetObjectX, which is now obsolete)}

\begin{verbatim}
int Object.X
\end{verbatim}
Gets/sets the X co-ordinate of the object.

\bf{NOTE:} This property cannot be changed while the object is moving.

\fcol{red}{Example:}
\begin{verbatim}
Display("Object 1's X co-ordinate is %d.", object[1].X);
\end{verbatim}
will display the X co-ordinate of object 1.

\it{See Also:} \helprefn{Object.Y}{Object.Y}, \helprefn{Object.Animating}{Object.Animating},
\helprefn{Object.Visible}{Object.Visible}, \helprefn{Object.SetPosition}{Object.SetPosition}


\subsection{Y property (object)}\label{Object.Y}\index{Object.Y}\index{GetObjectY}%

\it{(Formerly known as GetObjectY, which is now obsolete)}

\begin{verbatim}
int Object.Y
\end{verbatim}
Gets/sets the Y co-ordinate of the object, which is the bottom of the object's image.

\bf{NOTE:} This property cannot be changed while the object is moving.

\bf{NOTE:} If you try to use this co-ordinate with Object.GetAtScreenXY, you will find that
the object does not get picked up. The object's sprite is drawn from the Y co-ordinate
at (Object.Y - Height) to (Object.Y - 1).

\fcol{red}{Example:}
\begin{verbatim}
Display("Object 1's Y co-ordinate is %d.", object[1].Y);
\end{verbatim}
will display the Y co-ordinate of object 1.

\it{See Also:} \helprefn{Object.Animating}{Object.Animating},
\helprefn{Object.Baseline}{Object.Baseline}, \helprefn{Object.X}{Object.X}, 
\helprefn{Object.SetPosition}{Object.SetPosition}




\section{Overlay functions and properties}%


\subsection{CreateGraphical}\label{Overlay.CreateGraphical}\index{Overlay.CreateGraphical}\index{CreateGraphicOverlay}%

\it{(Formerly known as CreateGraphicOverlay, which is now obsolete)}

\begin{verbatim}
static Overlay* Overlay.CreateGraphical(int x, int y, int slot, bool transparent)
\end{verbatim}
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 \it{transparent} is true then the overlay will be drawn in the
same way as characters/objects, if it is false
then a black rectangle will be painted behind the sprite.

See the description of \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual} for more on overlays.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* myOverlay = Overlay.CreateGraphical(100, 100, 300, true);
Wait(40);
myOverlay.Remove();
\end{verbatim}
will create an overlay of the image stored in sprite manager's slot 300, at the
coordinates 100,100. It will display for 1 second, then remove it.

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.Remove}{Overlay.Remove}


\subsection{CreateTextual}\label{Overlay.CreateTextual}\index{Overlay.CreateTextual}\index{CreateTextOverlay}%

\it{(Formerly known as CreateTextOverlay, which is now obsolete)}

\begin{verbatim}
static Overlay* Overlay.CreateTextual(int x, int y, int width,
                                      FontType font, int color, string text)
\end{verbatim}
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 the Remove command, 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 the editor 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, which you use later to reposition
and remove the overlay.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\bf{NOTE:} large overlays, in the same way as objects, can impact performance
while displayed.

\bf{NOTE:} there is currently a maximum of 10 overlays displayed at any one time. Some other
commands such as Say and SayBackground create overlays internally,
so don't rely on being able to create 10 with CreateTextual.

\bf{NOTE:} if the Overlay object goes out of scope, the overlay will be removed. Hence,
if you want the overlay to last on-screen outside of the script function where it
was created, the \verb$Overlay*$ variable declaration needs to be at the top of 
the script and outside any script functions.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* myOverlay = Overlay.CreateTextual(50,80,120, Game.SpeechFont, 15,"This is a text overlay");
Wait(40);
myOverlay.Remove();
\end{verbatim}
will display a 120 pixels text area with its upper left corner at coordinates 50,80
containing the string "This is a text overlay" using the speech font and white color.
It will be displayed for 1 second, then removed.

\it{See Also:} \helprefn{Overlay.CreateGraphical}{Overlay.CreateGraphical}, \helprefn{Overlay.X}{Overlay.X},
\helprefn{Overlay.Y}{Overlay.Y}, \helprefn{Overlay.Remove}{Overlay.Remove}


\subsection{Remove (overlay)}\label{Overlay.Remove}\index{Overlay.Remove}\index{RemoveOverlay}%

\it{(Formerly known as RemoveOverlay, which is now obsolete)}

\begin{verbatim}
Overlay.Remove()
\end{verbatim}
Removes the specified overlay from the screen. Use this when you are
done using the overlay.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* myOverlay = Overlay.CreateTextual(50,80,120,2,15,"This is a text overlay");
Wait(200);
myOverlay.Remove();
\end{verbatim}
will create a text overlay , wait for 200 game cycles (about 5 seconds) and then
remove the overlay from the screen.

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual}


\subsection{SetText (overlay)}\label{Overlay.SetText}\index{Overlay.SetText}\index{SetTextOverlay}%

\it{(Formerly known as SetTextOverlay, which is now obsolete)}

\begin{verbatim}
Overlay.SetText(int width, FontType font, int color, string text, ...)
\end{verbatim}
Replaces the specified overlay with a new one, at the same co-ordinates but with
the new specified text, width, font and colour.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* myOverlay = Overlay.CreateTextual(50,80,120,Game.SpeechFont,15,"This is a text overlay");
Wait(200);
myOverlay.SetText(120,Game.SpeechFont,15,"This is another text overlay");
\end{verbatim}
will create a text overlay , wait for 200 game cycles (about 5 seconds) and then
replace the overlay with another one.

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.Remove}{Overlay.Remove}


\subsection{Valid property (overlay)}\label{Overlay.Valid}\index{Overlay.Valid}\index{IsOverlayValid}%

\it{(Formerly known as IsOverlayValid, which is now obsolete)}

\begin{verbatim}
readonly bool Overlay.Valid;
\end{verbatim}
Checks whether the overlay is a current overlay or not.
Returns 1 if it is, 0 if it isn't.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* myOverlay = Overlay.CreateTextual(50,80,120,2,15,"This is a text overlay");
Display("Overlay valid before: %d", myOverlay.Valid);
myOverlay.Remove();
Display("Overlay valid after: %d", myOverlay.Valid);
\end{verbatim}
creates an overlay, and prints out the Valid property (which will be 1). Then, removes
the overlay and prints Valid again (which will now be 0).

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.Remove}{Overlay.Remove}



\subsection{X property (overlay)}\label{Overlay.X}\index{Overlay.X}\index{MoveOverlay}%

\it{(Formerly known as MoveOverlay, which is now obsolete)}

\begin{verbatim}
int Overlay.X;
\end{verbatim}
Gets/sets the X co-ordinate of the overlay (ie. the left hand side of the overlay).

This allows you to dynamically move overlays around the screen.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* testOverlay = Overlay.CreateTextual(50,80,120,2,15,"This is a text overlay");
while (testOverlay.X < 100) {
  testOverlay.X++;
  Wait(1);
}
testOverlay.Remove();
\end{verbatim}
creates a text overlay, then gradually slides it across the screen.

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.Y}{Overlay.Y}, \helprefn{Overlay.Remove}{Overlay.Remove}


\subsection{Y property (overlay)}\label{Overlay.Y}\index{Overlay.Y}\index{MoveOverlay}%

\it{(Formerly known as MoveOverlay, which is now obsolete)}

\begin{verbatim}
int Overlay.Y;
\end{verbatim}
Gets/sets the Y co-ordinate of the overlay (ie. the top edge of the overlay).

This allows you to dynamically move overlays around the screen.

\fcol{red}{Example:}
\begin{verbatim}
Overlay* testOverlay = Overlay.CreateTextual(50,50,120,2,15,"This is a text overlay");
while (testOverlay.Y < 100) {
  testOverlay.Y++;
  Wait(1);
}
testOverlay.Remove();
\end{verbatim}
creates a text overlay, then gradually slides it down the screen.

\it{See Also:} \helprefn{Overlay.CreateTextual}{Overlay.CreateTextual},
\helprefn{Overlay.X}{Overlay.X}, \helprefn{Overlay.Remove}{Overlay.Remove}


\section{Palette functions}%

\subsection{CyclePalette}\label{CyclePalette}%

\begin{verbatim}
CyclePalette (int start, int end)
\end{verbatim}
This is used for special effects, like the flowing colours on the Space
Quest 4 title screen, and the Sierra logo of the later Sierra games.
The palette indexes from START to END are cycled around one slot. Using
this call in a repeatedly_execute function gives the effect of animation.

By default, the colours rotate leftwards through the palette. If you pass
the arguments the other way round (ie. START being larger than END) then
the colours will rotate in the opposite direction.

\bf{NOTE:} This command only works in 256-colour games.

\fcol{red}{Example:}
\begin{verbatim}
CyclePalette(10,200);
\end{verbatim}
will cause the palette indexes from 10 to 200 cycle around one slot and give a color effect.

\it{See Also:} \helprefn{FadeIn}{FadeIn}, \helprefn{FadeOut}{FadeOut}, \helprefn{SetPalRGB}{SetPalRGB}


\subsection{SetPalRGB}\label{SetPalRGB}%

\begin{verbatim}
SetPalRGB (int slot, int red, int green, int blue)
\end{verbatim}
Changes the RGB components of one of the palette slots. The palette is
initially set up in the Palette Editor, but you can override it during the game using
this function for special effects. The RED, GREEN and BLUE parameters each
range from 0 to 63 (as used in the Palette Editor).

If SLOT is a background slot, then this function's effect will last until
the player changes screen, when the palette is changed to the new room's
palette. If SLOT is not a background slot, the effect of this function is
permanent.

NOTE: This function will allow you to change the colours which are "locked"
in the AGS Editor. However, you should not normally do this as it can
cause strange colours in the game.

\fcol{red}{Example:}
\begin{verbatim}
SetPalRGB(10,63,63,21);
\end{verbatim}
will change palette slot number 10 from light green to yellow

\it{See Also:} \helprefn{CyclePalette}{CyclePalette}, \helprefn{FadeIn}{FadeIn}, \helprefn{FadeOut}{FadeOut}, \helprefn{UpdatePalette}{UpdatePalette}

\subsection{UpdatePalette}\label{UpdatePalette}%

\begin{verbatim}
UpdatePalette()
\end{verbatim}
Commits the changes you made to the game palette.
The script global variable  palette[]  stores the state of all the
colours of the palette. You can access the red, green and blue components
with .r, .g and .b. The values range from 0 to 63.

\fcol{red}{Example:}
\begin{verbatim}
palette[16].r = 60;
UpdatePalette();
\end{verbatim}
will make the black colour turn bright red. When you actually change the variable, nothing happens. Call this function to update the screen.

\it{See Also:} \helprefn{SetPalRGB}{SetPalRGB}


\section{Parser functions}%


\subsection{FindWordID}\label{Parser.FindWordID}\index{Parser.FindWordID}%

\begin{verbatim}
static int Parser.FindWordID(string wordToFind)
\end{verbatim}
Looks up \it{wordToFind} in the text parser dictionary, and returns the ID number.

If the word is not found, returns -1. ILBRK
Otherwise, the Word Group number is returned, as seen in the Text Parser tab in the editor.

You can determine if two words are synonyms by looking them both up and seeing if the 
returned IDs are the same.

Ignore words are returned as ID 0.

This function is useful if you want to use the AGS Text Parser dictionary, but implement
some custom parsing functionality instead of using the standard ParseText function.

\fcol{red}{Example:}
\begin{verbatim}
 if (Parser.FindWordID("machine") > 0)
 {
   Display("machine is in the game dictionary");
 }
\end{verbatim}
will display a message if the game dictionary includes "machine"

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{Parser.ParseText}{Parser.ParseText}


\subsection{ParseText}\label{Parser.ParseText}\index{Parser.ParseText}%

\begin{verbatim}
static Parser.ParseText(string text)
\end{verbatim}
Stores the supplied user text string for later use by Said.
You need to call this command first with the user's input before using
the Said command. You would usually call this inside the text box's
OnActivate event handler.

\fcol{red}{Example:}
\begin{verbatim}
 String command = txtParser.Text;
 Parser.ParseText(command);
\end{verbatim}
will get the players input and store it in string "command" for use with the said command.

\it{See Also:} \helprefn{Parser.FindWordID}{Parser.FindWordID},
\helprefn{Parser.Said}{Parser.Said}


\subsection{Said}\label{Parser.Said}\index{Parser.Said}%

\begin{verbatim}
static bool Parser.Said(string text)
\end{verbatim}
Checks whether the player typed in TEXT in their input passed to ParseText.
Returns \it{true} if it matches, \it{false} otherwise.

See \helpref{the text parser documentation}{TextParser} for a more detailed description.


\fcol{red}{Example:}
\begin{verbatim}
String input = txtParserInput.Text;
Parser.ParseText(input);
if (Parser.Said("load")) {
  txtParserInput.Text = "";
  RestoreGameDialog();
}
\end{verbatim}
will bring up the restore game dialogue if the player types "load" in the text parser.

\it{See Also:} \helprefn{Parser.ParseText}{Parser.ParseText}, \helprefn{Parser.SaidUnknownWord}{Parser.SaidUnknownWord}


\subsection{SaidUnknownWord}\label{Parser.SaidUnknownWord}\index{Parser.SaidUnknownWord}%

\begin{verbatim}
static String Parser.SaidUnknownWord()
\end{verbatim}
If a word not in the game dictionary was submitted to the last ParseText
call, then the word is returned by this command. This allows you to display a
message like "Sorry, this game doesn't recognise 'XXXX'."

If all the words were recognised, this returns null.

\fcol{red}{Example:}
\begin{verbatim}
String badWord = Parser.SaidUnknownWord();
if (badWord != null)
   Display("You can't use '%s' in this game.", badWord);
\end{verbatim}
will display the message if the player types a word that's not in the vocabulary.

\it{See Also:} \helprefn{Parser.ParseText}{Parser.ParseText}, \helprefn{Parser.Said}{Parser.Said}


\section{Region functions and properties}%


\subsection{GetAtRoomXY (region)}\label{Region.GetAtRoomXY}\index{Region.GetAtRoomXY}\index{GetRegionAt}%

\it{(Formerly known as global function GetRegionAt, which is now obsolete)}

\begin{verbatim}
static Region* Region.GetAtRoomXY(int x, int y)
\end{verbatim}
Returns the region at ROOM co-ordinates (X,Y).
If there is no region there, or if invalid co-ordinates are specified,
the Region* representing region 0 will be returned.

\bf{NOTE:} Unlike GetHotspotAtLocation, the co-ordinates specified are ROOM co-ordinates. This
means that if you want to use the mouse cursor location, you have to add the
screen offset to make it work in scrolling rooms.

\fcol{red}{Example:}
\begin{verbatim}
if (Region.GetAtRoomXY(player.x, player.y) == region[0])
  Display("The player is not currently standing on a region.");
\end{verbatim}

\it{See Also:} \helprefn{GetWalkableAreaAt}{GetWalkableAreaAt}


\subsection{RunInteraction (region)}\label{Region.RunInteraction}\index{Region.RunInteraction}\index{RunRegionInteraction}%

\it{(Formerly known as RunRegionInteraction, which is now obsolete)} 

\begin{verbatim}
Region.RunInteraction(int event)
\end{verbatim}
Runs the event handler as if the EVENT for the region had been activated.

\bf{NOTE:} Unlike the other RunInteraction commands, this one does not take a cursor mode.
Instead, it uses an event type as follows:

0  While player stands on region ILBRK
1  Player walks onto region ILBRK
2  Player walks off region

\fcol{red}{Example:}
\begin{verbatim}
region[4].RunInteraction(1);
\end{verbatim}
will run the actions defined in the event handler script for "Player walks onto region"
for region 4.

\it{See Also:} \helprefn{Character.RunInteraction}{Character.RunInteraction},
\helprefn{Hotspot.RunInteraction}{Hotspot.RunInteraction}


\subsection{Tint (region)}\label{Region.Tint}\index{Region.Tint}\index{SetRegionTint}%

\it{(Formerly known as SetRegionTint, which is now obsolete)} 

\begin{verbatim}
Region.Tint(int red, int green, int blue, int amount)
\end{verbatim}
Changes the region to have RGB tint (RED, GREEN, BLUE).

The red, green and blue values are between 0 and 255, and you supply the same
values that you would use in the editor.

AMOUNT determines the extent of the tinting, and is from 1 to 100, reflecting a percentage
figure. 100\verb$%$ will completely colourize characters in that area to the specified colour.

\bf{NOTE}: The tint will be reset when the player leaves the room,
so you need to use it in Player Enters Room if you want a permanent
change.

\bf{NOTE:} This function only works in hi-colour games.

\bf{NOTE}: To remove the region tint, set the LightLevel property to 0.

\fcol{red}{Example:}
\begin{verbatim}
region[2].Tint(180, 20, 20, 50); 
\end{verbatim}
will set region 2's RGB tint to (180, 20, 20) with 50\verb$%$ opacity.

\it{See Also:} \helprefn{Region.LightLevel}{Region.LightLevel}



\subsection{Enabled property (region)}\label{Region.Enabled}\index{Region.Enabled}\index{DisableRegion}\index{EnableRegion}%

\it{(Formerly known as DisableRegion, which is now obsolete)} ILBRK
\it{(Formerly known as EnableRegion, which is now obsolete)} 

\begin{verbatim}
bool Region.Enabled
\end{verbatim}
Enables/disables the specified region. If you set this to false, then all areas of the screen
that were previously part of the region now act as type 0 (no region). You can turn the region
back on later by setting this to true.

While a region is disabled, it will not be returned by Region.GetAtRoomXY, and if
the character walks onto the region then its events will not get run.

\fcol{red}{Example:}
\begin{verbatim}
region[3].Enabled = false;
\end{verbatim}
will disable region number 3.

\it{See Also:} \helprefn{Hotspot.Enabled}{Hotspot.Enabled},
\helprefn{RemoveWalkableArea}{RemoveWalkableArea},
\helprefn{RestoreWalkableArea}{RestoreWalkableArea}


\subsection{ID property (region)}\label{Region.ID}\index{Region.ID}%

\begin{verbatim}
readonly int Region.ID
\end{verbatim}
Gets the region number of this region. This allows you to interoperate with old
script using the number-based region functions.

\fcol{red}{Example:}
\begin{verbatim}
Display("Region 3 is number %d.", region[3].ID);
\end{verbatim}
displays region 3's number (which will be 3).

\it{See Also:} \helprefn{Region.GetAtRoomXY}{Region.GetAtRoomXY}


\subsection{LightLevel property}\label{Region.LightLevel}\index{Region.LightLevel}\index{SetAreaLightLevel}%

\it{(Formerly known as SetAreaLightLevel, which is now obsolete)} 

\begin{verbatim}
int Region.LightLevel
\end{verbatim}
Gets/sets the region's light level. This does the same thing as the Light Level
textbox in the editor, but allows you to change it at run-time.

The light level is from \bf{-100 to 100}. This is different from the editor, which
takes values from 0 to 200.
Subtract 100 from the value you would use in the editor when calling this function.
The reason for this discrepancy is legacy reasons from the DOS editor days.

To disable region lighting and tinting effects, set LightLevel to 0.

\bf{NOTE}: The light level will be reset to the editor settings when the player leaves the
room, so you need to use it in Player Enters Room if you want a permanent
change.

\bf{NOTE}: Setting a light level will disable any RGB tint set for the region.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGlobalInt(10)==1)
    region[2].LightLevel = 100;
\end{verbatim}
will set region 2's level light to 100 if the Global Integer 10 is 1.

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}


\subsection{TintEnabled property}\label{Region.TintEnabled}\index{Region.TintEnabled}%

\begin{verbatim}
readonly bool Region.TintEnabled
\end{verbatim}
Gets whether the region currently has an RGB tint enabled for it.

Returns \it{true} if it does, and \it{false} if it does not. If it does not, then
the LightLevel property reflects the region lighting.

If this property is \it{false}, then the TintRed, TintGreen, TintBlue and TintSaturation
properties are invalid.

\fcol{red}{Example:}
\begin{verbatim}
if (region[4].TintEnabled) {
  Display("Region 4 is tinted!!");
}
\end{verbatim}
will display a message if region 4 is tinted

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}


\subsection{TintBlue property}\label{Region.TintBlue}\index{Region.TintBlue}%

\begin{verbatim}
readonly int Region.TintBlue
\end{verbatim}
Gets the \it{Blue} setting for the region's current tint.

This property is read-only; to change it, use the \helprefn{Region.Tint}{Region.Tint} command.

\bf{NOTE:} If the \helprefn{Region.TintEnabled}{Region.TintEnabled} property is false, then
this value is meaningless.

\fcol{red}{Example:}
\begin{verbatim}
if (region[4].TintEnabled) {
  Display("Region 4 is tinted RGB (%d,%d,%d) Saturation %d.",
          region[4].TintRed, region[4].TintGreen,
          region[4].TintBlue, region[4].TintSaturation);
}
\end{verbatim}
will display a message with the region's tints.

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}, \helprefn{Region.TintEnabled}{Region.TintEnabled},
\helprefn{Region.TintGreen}{Region.TintGreen}, \helprefn{Region.TintRed}{Region.TintRed}


\subsection{TintGreen property}\label{Region.TintGreen}\index{Region.TintGreen}%

\begin{verbatim}
readonly int Region.TintGreen
\end{verbatim}
Gets the \it{Green} setting for the region's current tint.

This property is read-only; to change it, use the \helprefn{Region.Tint}{Region.Tint} command.

\bf{NOTE:} If the \helprefn{Region.TintEnabled}{Region.TintEnabled} property is false, then
this value is meaningless.

\fcol{red}{Example:}
\begin{verbatim}
if (region[4].TintEnabled) {
  Display("Region 4 is tinted RGB (%d,%d,%d) Saturation %d.",
          region[4].TintRed, region[4].TintGreen,
          region[4].TintBlue, region[4].TintSaturation);
}
\end{verbatim}
will display a message with the region's tints.

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}, \helprefn{Region.TintEnabled}{Region.TintEnabled},
\helprefn{Region.TintBlue}{Region.TintBlue}, \helprefn{Region.TintRed}{Region.TintRed}


\subsection{TintRed property}\label{Region.TintRed}\index{Region.TintRed}%

\begin{verbatim}
readonly int Region.TintRed
\end{verbatim}
Gets the \it{Red} setting for the region's current tint.

This property is read-only; to change it, use the \helprefn{Region.Tint}{Region.Tint} command.

\bf{NOTE:} If the \helprefn{Region.TintEnabled}{Region.TintEnabled} property is false, then
this value is meaningless.

\fcol{red}{Example:}
\begin{verbatim}
if (region[4].TintEnabled) {
  Display("Region 4 is tinted RGB (%d,%d,%d) Saturation %d.",
          region[4].TintRed, region[4].TintGreen,
          region[4].TintBlue, region[4].TintSaturation);
}
\end{verbatim}
will display a message with the region's tints.

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}, \helprefn{Region.TintEnabled}{Region.TintEnabled},
\helprefn{Region.TintBlue}{Region.TintBlue}, \helprefn{Region.TintGreen}{Region.TintGreen}


\subsection{TintSaturation property}\label{Region.TintSaturation}\index{Region.TintSaturation}%

\begin{verbatim}
readonly int Region.TintSaturation
\end{verbatim}
Gets the \it{saturation} setting for the region's current tint.

This property is read-only; to change it, use the \helprefn{Region.Tint}{Region.Tint} command.

\bf{NOTE:} If the \helprefn{Region.TintEnabled}{Region.TintEnabled} property is false, then
this value is meaningless.

\fcol{red}{Example:}
\begin{verbatim}
if (region[4].TintEnabled) {
  Display("Region 4 is tinted RGB (%d,%d,%d) Saturation %d.",
          region[4].TintRed, region[4].TintGreen,
          region[4].TintBlue, region[4].TintSaturation);
}
\end{verbatim}
will display a message with the region's tints.

\it{See Also:} \helprefn{Region.Tint}{Region.Tint}, \helprefn{Region.TintEnabled}{Region.TintEnabled},
\helprefn{Region.TintBlue}{Region.TintBlue}, \helprefn{Region.TintGreen}{Region.TintGreen}
, \helprefn{Region.TintRed}{Region.TintRed}



\section{Room functions}%


\subsection{AreThingsOverlapping}\label{AreThingsOverlapping}%

\begin{verbatim}
AreThingsOverlapping(int thing1, int thing2)
\end{verbatim}
Checks whether two characters or objects are overlapping each other on screen. This simply
carries out a quick rectangular check on the two things to decide - so if they have large
transparent regions around the edges, it may seem to be overlapping too soon.

THING1 and THING2 can either be a CHARID, or can be an object number PLUS 1000.
So for example, passing EGO as THING1, and 1004 as THING2, will compare the character EGO
with Object 4 in the current room.

Returns 0 if they are not overlapping, or the overlapping amount if they are. This amount
is an arbitrary scale, but 1 means they are just about touching, all the way up to higher numbers
for more overlappingness.

Calling this function with both the parameters as objects is the same as calling Object.IsCollidingWithObject.

\fcol{red}{Example:}
\begin{verbatim}
if (AreThingsOverlapping(1002, EGO)) {
  // code here
}
\end{verbatim}
will run the code if object 2 is overlapping EGO. This could be useful if object 2 was a bullet,
for instance.

\it{See Also:} \helprefn{Character.IsCollidingWithChar}{Character.IsCollidingWithChar},
\helprefn{Object.IsCollidingWithObject}{Object.IsCollidingWithObject}



\subsection{DisableGroundLevelAreas}\label{DisableGroundLevelAreas}%

\begin{verbatim}
DisableGroundLevelAreas(int disableTints)
\end{verbatim}
Disables all ground-level events. This means that all Region events, the Player Stands
On Hotspot event, and the room edges become disabled.

This command is useful in conjunction with the character[].z variable, if you want the player
to be able to temporarily fly or levitate, for example. It allows you to stop the character
from triggering Player Stands On events while they are in the air.

This command is also useful during some cutscenes, if you don't want the player to trigger
events as they walk around the room while in the cutscene.

The DISABLETINTS parameter specifies whether the visual effects of the regions (ie. light
levels and tints) are also disabled. If you pass this as 0, then just the events will
be turned off.

\fcol{red}{Example:}
\begin{verbatim}
DisableGroundLevelAreas(0);
\end{verbatim}
will disable all ground-level events, but leave light levels working

\it{See Also:} \helprefn{Hotspot.Enabled}{Hotspot.Enabled}, \helprefn{Region.Enabled}{Region.Enabled},
\helprefn{EnableGroundLevelAreas}{EnableGroundLevelAreas}


\subsection{EnableGroundLevelAreas}\label{EnableGroundLevelAreas}%

\begin{verbatim}
EnableGroundLevelAreas()
\end{verbatim}
Re-enables all ground-level events. This is used to reverse the effects of
using the DisableGroundLevelAreas command, and will return things to normal.

\fcol{red}{Example:}
\begin{verbatim}
EnableGroundLevelAreas();
\end{verbatim}
will re-enable all ground-level events.

\it{See Also:} \helprefn{Hotspot.Enabled}{Hotspot.Enabled}, \helprefn{Region.Enabled}{Region.Enabled},
\helprefn{DisableGroundLevelAreas}{DisableGroundLevelAreas}


\subsection{GetBackgroundFrame}\label{GetBackgroundFrame}%

\begin{verbatim}
GetBackgroundFrame()
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (GetBackgroundFrame()==4)
  object[2].Visible = true;
\end{verbatim}
will turn on object 2 if the background frame of the room is frame 4.

\it{See Also:} \helprefn{SetBackgroundFrame}{SetBackgroundFrame}


\subsection{GetDrawingSurfaceForBackground}\label{Room.GetDrawingSurfaceForBackground}\index{Room.GetDrawingSurfaceForBackground}%

\begin{verbatim}
static DrawingSurface* Room.GetDrawingSurfaceForBackground(optional int backgroundNumber)
\end{verbatim}
Gets a drawing surface for a room background, which allows you to directly draw
onto the room's background image. You can provide a background frame number if you
want to modify a specific frame; otherwise, the current background's surface will be returned.

After calling this method, use the various \helprefn{DrawingSurface functions}{DrawingSurfaceFunctions} to modify the
background, then call Release on the surface when you are finished.

Any changes you make will only last until the player leaves the room, at 
which point they will be lost. If you need to make long-lasting changes, you
can either use this method in the Player Enters Room event, or consider using
an alternate background frame for the changed image.

\bf{NOTE:} Drawing onto the room background can be slow, especially when using the Direct3D
driver. Do not use this command in repeatedly_execute; make sure you only use this command
when absolutely necessary.

\fcol{red}{Example:}
\begin{verbatim}
DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
surface.DrawingColor = 14;
surface.DrawLine(0, 0, 50, 50);
surface.Release();
\end{verbatim}
draws a yellow diagonal line across the top-left of the current room background,
then releases the image.

\it{See Also:} \helprefn{DrawingSurface.DrawLine}{DrawingSurface.DrawLine}, 
\helprefn{DrawingSurface.Release}{DrawingSurface.Release}


\subsection{GetPlayerCharacter}\label{GetPlayerCharacter}%

\begin{verbatim}
GetPlayerCharacter ()
\end{verbatim}
\bf{THIS COMMAND IS NOW OBSOLETE.} ILBRK
The recommended replacement is to use the player character's ID property, as follows:

\fcol{red}{Example:}
\begin{verbatim}
Display("The player character number is %d", player.ID);
\end{verbatim}

\it{See Also:} \helprefn{Character.ID}{Character.ID}


\subsection{GetRoomProperty}\label{GetRoomProperty}%

\begin{verbatim}
GetRoomProperty (string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the current room.

This command works with Number properties (it returns the number), and with Boolean
properties (returns 1 if the box was checked, 0 if not).

Use the equivalent Room.GetTextProperty function to get a text property.

Note that you cannot retrieve room properties of other rooms - only the current room
can be checked.

\fcol{red}{Example:}
\begin{verbatim}
if (GetRoomProperty("CanBeAttackedHere"))
  Display("An evil monster lunges at you!");
\end{verbatim}
will print the message if the current room has its "CanBeAttackedHere" box ticked.

\it{See Also:} \helprefn{Room.GetTextProperty}{Room.GetTextProperty}


\subsection{GetTextProperty (room)}\label{Room.GetTextProperty}\index{Room.GetTextProperty}\index{GetRoomPropertyText}%

\it{(Formerly known as global function GetRoomPropertyText, which is now obsolete)}

\begin{verbatim}
static String Room.GetTextProperty(string property)
\end{verbatim}
Returns the custom property setting of the PROPERTY for the current room.

This command works with Text properties only. The property's text will be
returned from this function.

Use the equivalent GetRoomProperty function to get a non-text property.

Note that you cannot retrieve room properties of other rooms - only the current room
can be checked.

\fcol{red}{Example:}
\begin{verbatim}
String description = Room.GetTextProperty("Description");
Display("The room's description: %s", description);
\end{verbatim}
will retrieve the room's "description" property then display it.

\it{See Also:} \helprefn{GetRoomProperty}{GetRoomProperty}


\subsection{GetScalingAt}\label{GetScalingAt}%

\begin{verbatim}
GetScalingAt (int x, int y)
\end{verbatim}
Returns the room area scaling at room co-ordinates (X,Y).

The value returned is from 1 to 200, with 100 being the normal un-scaled setting.

\fcol{red}{Example:}
\begin{verbatim}
if (GetScalingAt(player.x, player.y) == 100)
    Display ("The player is currently at normal size.");
\end{verbatim}

\it{See Also:} \helprefn{GetWalkableAreaAt}{GetWalkableAreaAt}, \helprefn{SetAreaScaling}{SetAreaScaling}



\subsection{GetViewportX}\label{GetViewportX}%

\begin{verbatim}
GetViewportX ()
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (GetViewportX()>100)
    object[2].Visible = true;
\end{verbatim}
will turn object 2 on if the player has scrolled the room by 100 pixels to the right.

\it{See Also:} \helprefn{GetViewportY}{GetViewportY}, \helprefn{SetViewport}{SetViewport}

\subsection{GetViewportY}\label{GetViewportY}%

\begin{verbatim}
GetViewportY ()
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
if (GetViewportY()>20)
    object[2].Visible = true;
\end{verbatim}
will turn object 2 on if the player has scrolled the room by 20 pixels to the bottom.

\it{See Also:} \helprefn{GetViewportX}{GetViewportX}, \helprefn{SetViewport}{SetViewport}


\subsection{GetWalkableAreaAt}\label{GetWalkableAreaAt}%

\begin{verbatim}
GetWalkableAreaAt (int x, int y)
\end{verbatim}
Returns the number of the walkable area at SCREEN co-ordinates (X,Y).
If there is no walkable area there, or if invalid co-ordinates are specified,
returns 0.

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.

\fcol{red}{Example:}
\begin{verbatim}
if (GetWalkableAreaAt(mouse.x,mouse.y) == 0)
    Display ("You can't walk there.");
\end{verbatim}

\it{See Also:} \helprefn{Hotspot.GetAtScreenXY}{Hotspot.GetAtScreenXY},
\helprefn{Region.GetAtRoomXY}{Region.GetAtRoomXY},
\helprefn{GetScalingAt}{GetScalingAt}


\subsection{HasPlayerBeenInRoom}\label{HasPlayerBeenInRoom}%

\begin{verbatim}
HasPlayerBeenInRoom(int room_number)
\end{verbatim}
Checks whether the player has ever been in ROOM_NUMBER (ie. has the 'First Time Player
Enters Room' event there ever been run). Returns 1 if they have, and 0 if they haven't.

You can use this function to determine whether the player has been to a particular location
previously. If you reset the room with ResetRoom, then this command will return 0 until
they enter the room again.

This command will always return 1 if you ask it about the current room; and it will always
return 0 if you ask it about a non-state saving room (ie. rooms numbered > 300).

\fcol{red}{Example:}
\begin{verbatim}
if (HasPlayerBeenInRoom(14)) {
  Display("The player has been to room 14 before.");
}
\end{verbatim}
will display a message if the player has been to room 14.

\it{See Also:} \helprefn{ResetRoom}{ResetRoom}


\subsection{ReleaseViewport}\label{ReleaseViewport}%

\begin{verbatim}
ReleaseViewport ()
\end{verbatim}
Releases the lock on the screen viewport, allowing it to automatically
scroll around following the player character as normal.

\fcol{red}{Example:}
\begin{verbatim}
int x;
while (x<100) {
   SetViewport(x,0);
   x++; 
   Wait(1);
}
ReleaseViewPort();
\end{verbatim}
will scroll the room 100 pixels to the right and then return the screen to its original position and unlock the screen viewport.

\it{See Also:} \helprefn{SetViewport}{SetViewport}


\subsection{RemoveWalkableArea}\label{RemoveWalkableArea}%

\begin{verbatim}
RemoveWalkableArea (int areanum)
\end{verbatim}
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 room" event when they return.

\fcol{red}{Example:}
\begin{verbatim}
RemoveWalkableArea(5); 
\end{verbatim}
will make the walking area 5 unwalkable.

\it{See Also:} \helprefn{RestoreWalkableArea}{RestoreWalkableArea}


\subsection{ResetRoom}\label{ResetRoom}%

\begin{verbatim}
ResetRoom (int room_number)
\end{verbatim}
Discards all the data that the engine has in memory about when the player
last visited ROOM_NUMBER, and resets it as if they'd never been there. The
next time the player goes to that room, all the objects and scripts will
be in their initial state (as set up in the editor), and not how they were
when the player left the room. The "First time enters room" event will be
run when they enter this room again.

This function is useful if you want to have a "View intro" option to allow
the player to watch an intro again - this function can reset all the
objects in the intro rooms to their starting positions.

NOTE: You cannot reset the current room (ie. the room that the player is in).

\fcol{red}{Example:}
\begin{verbatim}
ResetRoom(0); 
\end{verbatim}
will reset the intro room so it can be played again if the player wants to.

\it{See Also:} \helprefn{HasPlayerBeenInRoom}{HasPlayerBeenInRoom}


\subsection{RestoreWalkableArea}\label{RestoreWalkableArea}%

\begin{verbatim}
RestoreWalkableArea (int areanum)
\end{verbatim}
Makes the area AREANUM walkable again.

\fcol{red}{Example:}
\begin{verbatim}
RestoreWalkableArea(4); 
\end{verbatim}
will make the walking area 4 walkable again.

\it{See Also:} \helprefn{RemoveWalkableArea}{RemoveWalkableArea}


\subsection{SetAreaScaling}\label{SetAreaScaling}%

\begin{verbatim}
SetAreaScaling(int area, int min, int max)
\end{verbatim}
Changes walkable area number AREA's scaling. 

There are two ways to use this command: ILBRK
1. Pass the same value for MIN and MAX. This will give the walkable area fixed
scaling (same as setting it in the editor with "Use continuous scaling" un-ticked). ILBRK
2. Pass different values for MIN and MAX. In this case, continuous scaling is
enabled for the walkable area, and will go from MIN at the top to MAX at the bottom.

MIN and MAX have ranges from 5 to 200, the same as in the editor. Pass 100 for both values
to revert to the normal zoom level (100\verb$%$) for that area.

\fcol{red}{Example:}
\begin{verbatim}
SetAreaScaling(5, 120, 170);
\end{verbatim}
will set walkable area 5 to use continuous scaling from 120 to 170 percent.

\it{See Also:} \helprefn{GetScalingAt}{GetScalingAt}, \helprefn{GetWalkableAreaAt}{GetWalkableAreaAt}


\subsection{SetBackgroundFrame}\label{SetBackgroundFrame}%

\begin{verbatim}
SetBackgroundFrame (int frame)
\end{verbatim}
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 Room event to set the background before the screen fades in.

Pass the \it{frame} as -1 to return to the default behaviour of automatically
cycling through all the background frames.

The frame lock is released when the game changes rooms.

\fcol{red}{Example:}
\begin{verbatim}
if (GetGlobalInt(20)==1)
    SetBackgroundFrame(4); 
\end{verbatim}
will change the current room's background frame to 4 if the global integer 20 is 1.

\it{See Also:} \helprefn{GetBackgroundFrame}{GetBackgroundFrame}


\subsection{SetViewport}\label{SetViewport}%

\begin{verbatim}
SetViewport (int x, int y)
\end{verbatim}
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.

\bf{NOTE:} The co-ordinates supplied are 320x200-scale co-ordinates, and will
be automatically multiplied up by the engine.

\bf{NOTE:} This function has no effect if the current room isn't a scrolling room.

\fcol{red}{Example:}
\begin{verbatim}
int ypos = 0;
while (ypos < 60) {
  SetViewport(0, ypos);
  Wait(1);
  ypos++;
}
ReleaseViewport();
\end{verbatim}
will scroll the screen down from the top 60 pixels, then release it back
to follow the player around.

\it{See Also:} \helprefn{GetViewportX}{GetViewportX}, \helprefn{GetViewportY}{GetViewportY}, \helprefn{ReleaseViewport}{ReleaseViewport}


\subsection{SetWalkBehindBase}\label{SetWalkBehindBase}%

\begin{verbatim}
SetWalkBehindBase (int area, int baseline)
\end{verbatim}
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 the editor.

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.

\fcol{red}{Example:}
\begin{verbatim}
SetWalkBehindBase (3,0); 
\end{verbatim}
will disable the walkbehind area number 3.

\it{See Also:} \helprefn{Object.Baseline}{Object.Baseline}


\subsection{BottomEdge property}\label{Room.BottomEdge}\index{Room.BottomEdge}%

\begin{verbatim}
readonly static int Room.BottomEdge
\end{verbatim}
Returns the Y co-ordinate of the bottom edge of the room, as set in the Room Settings
pane of the editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room's bottom edge is at %d.", Room.BottomEdge);
\end{verbatim}

\it{See Also:} \helprefn{Room.LeftEdge}{Room.LeftEdge}, \helprefn{Room.RightEdge}{Room.RightEdge},
\helprefn{Room.TopEdge}{Room.TopEdge}


\subsection{ColorDepth property (room)}\label{Room.ColorDepth}\index{Room.ColorDepth}%

\begin{verbatim}
readonly static int Room.ColorDepth
\end{verbatim}
Returns the colour depth of the room's background scene. This is important if
you want to use DrawImage, since any sprites that you draw must be the same
colour depth as the room itself.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room background is %d-bit colour.", Room.ColorDepth);
\end{verbatim}

\it{See Also:} \helprefn{DrawingSurface.DrawImage}{DrawingSurface.DrawImage}


\subsection{Height property (room)}\label{Room.Height}\index{Room.Height}%

\it{(Formerly known as game.room_height, which is now obsolete)}

\begin{verbatim}
readonly static int Room.Height
\end{verbatim}
Returns the height of the room, in 320x200-style co-ordinates. This is
the same height as is displayed as the "Relative size" in the Editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room size is %d x %d.", Room.Width, Room.Height);
\end{verbatim}

\it{See Also:} \helprefn{Room.Width}{Room.Width}


\subsection{LeftEdge property}\label{Room.LeftEdge}\index{Room.LeftEdge}%

\begin{verbatim}
readonly static int Room.LeftEdge
\end{verbatim}
Returns the X co-ordinate of the left edge of the room, as set in the Room Settings
pane of the editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room's left edge is at %d.", Room.LeftEdge);
\end{verbatim}

\it{See Also:} \helprefn{Room.BottomEdge}{Room.BottomEdge}, \helprefn{Room.RightEdge}{Room.RightEdge},
\helprefn{Room.TopEdge}{Room.TopEdge}


\subsection{Messages property}\label{Room.Messages}\index{Room.Messages}\index{GetMessageText}%

\it{(Formerly known as global function GetMessageText, which is now obsolete)}

\begin{verbatim}
readonly static String Room.Messages[int message]
\end{verbatim}
Gets the text of the specified room message. This is useful if you want to store,
for example, a room description in Message 1 in each room -- this property allows
you to retrieve the text for that message from the current room.

If an invalid message number is supplied, \it{null} will be returned. Otherwise, the
message contents will be returned.

\fcol{red}{Example:}
\begin{verbatim}
String message1 = Room.Messages[1];
Display("Message 1 says: %s", message1);
\end{verbatim}
will print the contents of room message 1.


\subsection{MusicOnLoad property}\label{Room.MusicOnLoad}\index{Room.MusicOnLoad}%

\begin{verbatim}
readonly static int Room.MusicOnLoad
\end{verbatim}
\bf{This property is now obsolete.} It is still accessible for backwards compatibility
with old games.

Returns the music number that is set to play when the player enters this room, as
set in the "Room Settings" pane in the editor. If no music is set for this room,
returns 0.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room plays music %d when the player enters.", Room.MusicOnLoad);
\end{verbatim}


\subsection{ObjectCount property}\label{Room.ObjectCount}\index{Room.ObjectCount}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly static int Room.ObjectCount
\end{verbatim}
Returns the number of objects in the room.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room contains %d objects.", Room.ObjectCount);
\end{verbatim}


\subsection{RightEdge property}\label{Room.RightEdge}\index{Room.RightEdge}%

\begin{verbatim}
readonly static int Room.RightEdge
\end{verbatim}
Returns the X co-ordinate of the right edge of the room, as set in the Room Settings
pane of the editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room's right edge is at %d.", Room.RightEdge);
\end{verbatim}

\it{See Also:} \helprefn{Room.BottomEdge}{Room.BottomEdge}, \helprefn{Room.LeftEdge}{Room.LeftEdge},
\helprefn{Room.TopEdge}{Room.TopEdge}


\subsection{TopEdge property}\label{Room.TopEdge}\index{Room.TopEdge}%

\begin{verbatim}
readonly static int Room.TopEdge
\end{verbatim}
Returns the Y co-ordinate of the top edge of the room, as set in the Room Settings
pane of the editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room's top edge is at %d.", Room.TopEdge);
\end{verbatim}

\it{See Also:} \helprefn{Room.BottomEdge}{Room.BottomEdge}, \helprefn{Room.LeftEdge}{Room.LeftEdge},
\helprefn{Room.RightEdge}{Room.RightEdge}


\subsection{Width property (room)}\label{Room.Width}\index{Room.Width}%

\it{(Formerly known as game.room_width, which is now obsolete)}

\begin{verbatim}
readonly static int Room.Width
\end{verbatim}
Returns the width of the room, in 320x200-style co-ordinates. This is
the same width as is displayed as the "Relative size" in the Editor.

\fcol{red}{Example:}
\begin{verbatim}
Display("The current room size is %d x %d.", Room.Width, Room.Height);
\end{verbatim}

\it{See Also:} \helprefn{Room.Height}{Room.Height}



\section{Screen functions}%


\subsection{FadeIn}\label{FadeIn}%

\begin{verbatim}
FadeIn (int speed)
\end{verbatim}
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).

\it{NOTE: This is a blocking function.}

\fcol{red}{Example:}
\begin{verbatim}
FadeOut(30);
Wait(40);
FadeIn(10); 
\end{verbatim}
will fade the screen to black, wait 1 sec (40 game cycles) and then fade in again.

\it{See Also:} \helprefn{CyclePalette}{CyclePalette}, \helprefn{FadeOut}{FadeOut},
\helprefn{SetFadeColor}{SetFadeColor}


\subsection{FadeOut}\label{FadeOut}%

\begin{verbatim}
FadeOut (int speed)
\end{verbatim}
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.

\it{NOTE: This is a blocking function.}

\fcol{red}{Example:}
\begin{verbatim}
FadeOut(30);
Wait(40);
FadeIn(10); 
\end{verbatim}
will fade the screen to black, wait 1 sec (40 game cycles) and then fade in again.

\it{See Also:} \helprefn{CyclePalette}{CyclePalette}, \helprefn{FadeIn}{FadeIn},
\helprefn{SetFadeColor}{SetFadeColor}


\subsection{FlipScreen}\label{FlipScreen}%

\begin{verbatim}
FlipScreen (int way)
\end{verbatim}
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:
\begin{verbatim}
0  normal
1  horizontal-flip (upside-down)
2  vertical-flip  (left-to-right)
3  both (upside-down and backwards)
\end{verbatim}
\bf{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.

\fcol{red}{Example:}
\begin{verbatim}
FlipScreen(1); 
\end{verbatim}
will flip the screen upside down.


\subsection{SetFadeColor}\label{SetFadeColor}%

\begin{verbatim}
SetFadeColor(int red, int green, int blue)
\end{verbatim}

Changes the colour which the screen fades out to, to have the specified RGB value. Each of the
parameters can range from 0-255. The default is black, ie. (0, 0, 0)

The colour that you set here will be used in all future calls to FadeIn/FadeOut, and also
for the screen transition if it is set to Fade In/Out.

\fcol{red}{Example:}
\begin{verbatim}
SetFadeColor(200, 0, 0);
\end{verbatim}
will mean that next time the screen fades out, it fades to red instead of black.

SeeAlso: \helprefn{FadeIn}{FadeIn}, \helprefn{FadeOut}{FadeOut},
\helprefn{SetScreenTransition}{SetScreenTransition}


\subsection{SetNextScreenTransition}\label{SetNextScreenTransition}%

\begin{verbatim}
SetNextScreenTransition(TransitionStyle)
\end{verbatim}

Sets the room transition type to \it{TransitionStyle}, but ONLY for the next room change. After
that, it will revert back to the normal transition type specified in the editor or with
SetScreenTransition.

For the possible values for TransitionStyle, see \helprefn{SetScreenTransition}{SetScreenTransition}.

\fcol{red}{Example:}
\begin{verbatim}
SetNextScreenTransition(eTransitionBoxout);
cEgo.ChangeRoom(10);
\end{verbatim}
will go to room 10 with a box-out effect, but then return to the normal transition
type from then on.

SeeAlso: \helprefn{SetScreenTransition}{SetScreenTransition}


\subsection{SetScreenTransition}\label{SetScreenTransition}%

\begin{verbatim}
SetScreenTransition(TransitionStyle)
\end{verbatim}
Changes the default screen transition. TransitionStyle can be one of the following:
\begin{verbatim}
eTransitionFade
eTransitionInstant
eTransitionDissolve
eTransitionBoxout
eTransitionCrossfade
\end{verbatim}
All future transitions will be done as specified until you call this
function again.

\fcol{red}{Example:}
\begin{verbatim}
SetScreenTransition(eTransitionFade); 
\end{verbatim}
will change the room transitions to Fade.

SeeAlso: \helprefn{SetNextScreenTransition}{SetNextScreenTransition}


\subsection{ShakeScreen}\label{ShakeScreen}%

\begin{verbatim}
ShakeScreen (int amount)
\end{verbatim}
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.

\fcol{red}{Example:}
\begin{verbatim}
ShakeScreen(5); 
\end{verbatim}
will shake the screen a little.

\it{See Also:} \helprefn{ShakeScreenBackground}{ShakeScreenBackground}


\subsection{ShakeScreenBackground}\label{ShakeScreenBackground}%

\begin{verbatim}
ShakeScreenBackground (int delay, int amount, int length)
\end{verbatim}
Shakes the screen to simulate, for example, an earthquake. The game is not paused
while the screen shakes - it will continue in the background.

DELAY specifies the 'shakiness' of the shake - 2 is the lowest you can pass for this,
and will create the most shaky screen.

AMOUNT specifies the ferociousness of the shake - ie. how much the screen moves by when it
does shake. Here, 1 is a very tiny shake, up to about 30 for a ferocious shake.

LENGTH specifies how long the shake lasts for, in game loops. For example, 80 would be
equivalent to 2 seconds at the default game speed.

You can abort any current background shake that is in progress by calling this command
with the LENGTH parameter as zero.

\fcol{red}{Example:}
\begin{verbatim}
ShakeScreenBackground (4, 10, 80); 
\end{verbatim}
will shake the screen a little for 2 seconds.

\it{See Also:} \helprefn{ShakeScreen}{ShakeScreen}


\subsection{TintScreen}\label{TintScreen}%

\begin{verbatim}
TintScreen (int red, int green, int blue)
\end{verbatim}
Tints the screen with the specified RGB values. RED, GREEN and BLUE range
from 1 to 100. 

Pass (0, 0, 0) to turn off the tinting and go back to how the screen
normally looks.

For historical reasons, the tint works by applying a 50\verb$%$-transparent layer
of the specified colour to the screen after everything else has been drawn.
Therefore, it may not lead to the sort of results you might expect.

\bf{NOTE:} This command is currently experimental, since it causes a massive
slowdown in the engine, especially at high resolutions. If you use it, you
should provide an option for the player to turn it off.

\bf{NOTE:} This feature does not work in 256-colour games.

\fcol{red}{Example:}
\begin{verbatim}
TintScreen (100, 50, 50); 
\end{verbatim}
will tint a heavy dose of red. 



\section{String functions}%


\subsection{Append}\label{String.Append}\index{String.Append}\index{StrCat}%

\it{(Formerly known as global function StrCat, which is now obsolete)}

\begin{verbatim}
String.Append(string str2)
\end{verbatim}
Appends the string STR2 to the end of the specified string, and returns the result.

\bf{IMPORTANT:} The result of joining the strings together is returned as a new
string from this command. The original string will \bf{NOT} be changed. For
example, the following script will not do anything: ILBRK
\verb$mytext.Append("World");$ ILBRK
what you probably want instead is: ILBRK
\verb$mytext = mytext.Append("World");$ 

\fcol{red}{Example:}
\begin{verbatim}
String mytext = "Hello";
mytext = mytext.Append("World");
Display(mytext);
\end{verbatim}
will display "HelloWorld".

\it{See Also:} \helprefn{String.AppendChar}{String.AppendChar},
\helprefn{String.Substring}{String.Substring}, \helprefn{String.Truncate}{String.Truncate}


\subsection{AppendChar}\label{String.AppendChar}\index{String.AppendChar}%

\begin{verbatim}
String.AppendChar(char extraChar)
\end{verbatim}
Appends a single character to the end of the specified string, and returns the result.

\bf{IMPORTANT:} The newly extended text is returned as a new string from this command.
The original string will \bf{NOT} be changed. For
example, the following script will not do anything: ILBRK
\verb$mytext.AppendChar('o');$ ILBRK
what you probably want instead is: ILBRK
\verb$mytext = mytext.AppendChar('o');$ 

\fcol{red}{Example:}
\begin{verbatim}
String mytext = "Hell";
mytext = mytext.AppendChar('o');
Display(mytext);
\end{verbatim}
will display "Hello".

\it{See Also:} \helprefn{String.Append}{String.Append}


\subsection{CompareTo}\label{String.CompareTo}\index{String.CompareTo}\index{StrComp}\index{StrCaseComp}%

\it{(Formerly known as global function StrCaseComp, which is now obsolete)} ILBRK
\it{(Formerly known as global function StrComp, which is now obsolete)}

\begin{verbatim}
String.CompareTo(string str2, optional bool caseSensitive)
\end{verbatim}
Compares the specified string to STR2. \it{caseSensitive} determines whether "Dog" and "dog"
are equivalent; case sensitivity is off by default.

Returns 0 if the strings match, a number less than 0 if this string is earlier in the alphabet than STR2,
and a number greater than 0 if this string is later in the alphabet than STR2.

\bf{TIP:} To do a case-sensitive comparison of two strings, it's easier to just use the == operator.

\fcol{red}{Example:}
\begin{verbatim}
String mytext = "Hello";
if (mytext.CompareTo("hello") == 0) {
  Display("Strings match with case sensitivity off!");
}
else {
  Display("Strings don't match with case sensitivity off!");
}

if (mytext == "hello") {
  Display("Strings match with case sensitivity on!");
}
else {
  Display("Strings don't match with case sensitivity on!");
}
\end{verbatim}
will display "Strings match with case sensitivity off!", and then "Strings don't match with case sensitivity on!".


\subsection{Copy}\label{String.Copy}\index{String.Copy}\index{StrCopy}%

\it{(Formerly known as global function StrCopy, which is now obsolete)}

\begin{verbatim}
String.Copy()
\end{verbatim}
Returns a new copy of the specified string. You should not normally need to use this,
since strings can be assigned using the = operator.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "This is a test string.";
String newstring = mystring.Copy();
Display(newstring);
\end{verbatim}
will display "This is a test string".


\subsection{EndsWith}\label{String.EndsWith}\index{String.EndsWith}%

\begin{verbatim}
bool String.EndsWith(string lookForText, optional bool caseSensitive)
\end{verbatim}
Returns \it{true} if this string ends with \it{lookForText}, or \it{false} if not.

\it{caseSensitive} is \it{false} by default, but you can set it to true so that the
function will only return \it{true} for an exact-case match.

\fcol{red}{Example:}
\begin{verbatim}
String myString = "Hello from the script!";
if (myString.EndsWith("script!"))
{
  Display("Ends with script!");
}
\end{verbatim}
will display the "Ends with script!" message.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{String.IndexOf}{String.IndexOf},
\helprefn{String.StartsWith}{String.StartsWith}


\subsection{Format}\label{String.Format}\index{String.Format}\index{StrFormat}%

\it{(Formerly known as global function StrFormat, which is now obsolete)}

\begin{verbatim}
static String.Format(string fmt, ...)
\end{verbatim}
Processes the string FMT in the same way as the Display function does but
instead of displaying it on the screen, returns the result as a new string.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\bf{NOTE:} This function is static, which means you do not call it on
an existing string variable, but use \verb$String.Format()$ instead.

\fcol{red}{Example:}
\begin{verbatim}
int health=10;
String text = String.Format("%d", health);
\end{verbatim}
will create a text string containing "10".

\it{See Also:} \helprefn{Display}{Display}


\subsection{IndexOf}\label{String.IndexOf}\index{String.IndexOf}\index{String.Contains}\index{StrContains}%

\it{(Formerly known as global function StrContains, which is now obsolete)} ILBRK
\it{(Formerly known as String.Contains, which is now obsolete)}

\begin{verbatim}
String.IndexOf(string needle)
\end{verbatim}
Checks to see if NEEDLE is contained within the specified string. Returns the character position
of the match if it is, or -1 if it is not.

This function is not case sensitive; ie. testing "test string" for "sTRiN" would match.

\fcol{red}{Example:}
\begin{verbatim}
String haystack = "The haystack had a needle in it somewhere.";
int result = haystack.IndexOf("a needle");

if (result == -1) {
  Display("The string didn't contain the needle.");
}
else {
  Display("a needle was found starting at character %d in the string.", result);
}
\end{verbatim}

\it{See Also:} \helprefn{String.EndsWith}{String.EndsWith},
\helprefn{String.StartsWith}{String.StartsWith}


\subsection{IsNullOrEmpty}\label{String.IsNullOrEmpty}\index{String.IsNullOrEmpty}%

\begin{verbatim}
static bool String.IsNullOrEmpty(String stringToCheck)
\end{verbatim}
Returns whether the supplied string is null or empty. This is simply shorthand for the following:
\begin{verbatim}
if ((stringToCheck == null) || (stringToCheck == ""))
\end{verbatim}
in other words, you can easily use this to check whether a string has any text in it or not.

\bf{NOTE:} This function is static, which means you do not call it on an existing
string variable, but use \verb$String.IsNullOrEmpty()$ instead. See the example.

\fcol{red}{Example:}
\begin{verbatim}
String myString;
if (String.IsNullOrEmpty(myString))
{
  myString = "Some text";
}
\end{verbatim}
will set the myString variable to "Some text" if it is null or empty (which it is).

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.


\subsection{LowerCase}\label{String.LowerCase}\index{String.LowerCase}\index{StrToLowerCase}%

\it{(Formerly known as global function StrToLowerCase, which is now obsolete)}

\begin{verbatim}
String.LowerCase()
\end{verbatim}
Returns a lower case version of the specified string.

\bf{NOTE:} The new string is returned from this function; it
does \bf{NOT} modify the original string.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "THIS is a test string";
String lowercased = mystring.LowerCase();
Display("Old: %s, new: %s", mystring, lowercased);
\end{verbatim}
will display "Old: THIS is a test string, new: this is a test string".

\it{See Also:} \helprefn{String.UpperCase}{String.UpperCase}


\subsection{Replace}\label{String.Replace}\index{String.Replace}%

\begin{verbatim}
String.Replace(string lookForText, string replaceWithText,
               optional bool caseSensitive)
\end{verbatim}
Creates a copy of this string, with all instances of \it{lookForText} replaced
with the \it{replaceWithText}.

\it{caseSensitive} is \it{false} by default, but you can set it to true so that only
case-sensitive matches of the \it{lookForText} will be replaced.

\bf{NOTE:} The new string is returned from this function; it
does \bf{NOT} modify the original string.

\fcol{red}{Example:}
\begin{verbatim}
String original = "Hello from the script!";
String changed = original.Replace("hello", "goodbye");
Display("Old: %s, new: %s", original, changed);
\end{verbatim}
will display "Old: Hello from the script!, new: goodbye from the script!".

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{String.ReplaceCharAt}{String.ReplaceCharAt}


\subsection{ReplaceCharAt}\label{String.ReplaceCharAt}\index{String.ReplaceCharAt}\index{StrSetCharAt}%

\it{(Formerly known as global function StrSetCharAt, which is now obsolete)}

\begin{verbatim}
String.ReplaceCharAt(int index, char newChar)
\end{verbatim}
Changes the character at INDEX in the string to NEWCHAR.

INDEX is the character index into the string (where 0 is the first character,
and the last allowable value is the string's Length minus 1).

\bf{NOTE:} The new string is returned from this function; it
does \bf{NOT} modify the original string.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "Hello";
String changed = mystring.ReplaceCharAt(2, 'm');
Display("Old: %s, new: %s", newstring, changed);
\end{verbatim}
will display "Old: Hello, new: Hemlo".

\it{See Also:} \helprefn{String.Chars}{String.Chars}, 
\helprefn{String.Replace}{String.Replace}


\subsection{StartsWith}\label{String.StartsWith}\index{String.StartsWith}%

\begin{verbatim}
bool String.StartsWith(string lookForText, optional bool caseSensitive)
\end{verbatim}
Returns \it{true} if this string starts with \it{lookForText}, or \it{false} if not.

\it{caseSensitive} is \it{false} by default, but you can set it to true so that the
function will only return \it{true} for an exact-case match.

\fcol{red}{Example:}
\begin{verbatim}
String myString = "Hello from the script!";
if (myString.StartsWith("hello"))
{
  Display("Starts with hello!");
}
\end{verbatim}
will display the "Starts with hello!" message.

\it{Compatibility:} Supported by \bf{AGS 3.1.0} and later versions.

\it{See Also:} \helprefn{String.EndsWith}{String.EndsWith}, 
\helprefn{String.IndexOf}{String.IndexOf}


\subsection{Substring}\label{String.Substring}\index{String.Substring}%

\begin{verbatim}
String.Substring(int index, int length)
\end{verbatim}
Returns part of the string, starting from character \it{index} and \it{length}
characters long.

\it{index} is the initial character index, where 0 is the first character and
(Length - 1) is the last. \it{length} specifies how many characters to retrieve.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "Hello World!";
String substring = mystring.Substring(3, 5);
Display("Original: %s, Substring: %s", mystring, substring);
\end{verbatim}
will display "Original: Hello World!, Substring: lo Wo".

\it{See Also:} \helprefn{String.Append}{String.Append}, \helprefn{String.Chars}{String.Chars}


\subsection{Truncate}\label{String.Truncate}\index{String.Truncate}%

\begin{verbatim}
String.Truncate(int length)
\end{verbatim}
Returns a version of the string that has been truncated down to \it{length}
characters.

\bf{NOTE:} The new string is returned from this function; it
does \bf{NOT} modify the original string.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "Hello World!";
String truncated = mystring.Truncate(4);
Display("Original: %s, Truncated: %s", mystring, truncated);
\end{verbatim}
will display "Original: Hello World!, Truncated: Hell".

\it{See Also:} \helprefn{String.Append}{String.Append}, \helprefn{String.Substring}{String.Substring}


\subsection{UpperCase}\label{String.UpperCase}\index{String.UpperCase}\index{StrToUpperCase}%

\it{(Formerly known as global function StrToUpperCase, which is now obsolete)}

\begin{verbatim}
String.UpperCase()
\end{verbatim}
Returns an upper case version of the specified string.

\bf{NOTE:} The new string is returned from this function; it
does \bf{NOT} modify the original string.

\fcol{red}{Example:}
\begin{verbatim}
String mystring = "THIS is a test string";
String uppercased = mystring.UpperCase();
Display("Old: %s, new: %s", mystring, uppercased);
\end{verbatim}
will display "Old: THIS is a test string, new: THIS IS A TEST STRING".

\it{See Also:} \helprefn{String.LowerCase}{String.LowerCase}


\subsection{AsFloat property}\label{String.AsFloat}\index{String.AsFloat}%

\begin{verbatim}
readonly float String.AsFloat;
\end{verbatim}
Converts the string into a float, and returns that value. Returns
0.0 if the string does not contain a number.

\fcol{red}{Example:}
\begin{verbatim}
String text1, text2;
float number1,number2;
text1 = "57.362";
text2 = "Hello";
number1 = text1.AsFloat;
number2 = text2.AsFloat;
\end{verbatim}
will set number1 value to 57.362 and number2 value to 0.0
This function is useful for processing strings input from the user.

\bf{NOTE:} To convert a float to a string, you can use the \helprefn{String.Format}{String.Format}
command.

\it{See Also:} \helprefn{Game.InputBox}{Game.InputBox},
\helprefn{String.AsInt}{String.AsInt},
\helprefn{String.Format}{String.Format}


\subsection{AsInt property}\label{String.AsInt}\index{String.AsInt}\index{StringToInt}%

\it{(Formerly known as global function StringToInt, which is now obsolete)}

\begin{verbatim}
readonly int String.AsInt;
\end{verbatim}
Converts the string into an integer, and returns that value. Returns
zero if the string does not contain a number.

\fcol{red}{Example:}
\begin{verbatim}
String text1, text2;
int number1,number2;
text1 = "53";
text2 = "Hello";
number1 = text1.AsInt;
number2 = text2.AsInt;
\end{verbatim}
will set number1 value to 53 and number2 value to 0.
This function is useful for processing strings input from the user.

\bf{NOTE:} To convert an integer to a string, you can use the \helprefn{String.Format}{String.Format}
command.

\it{See Also:} \helprefn{Game.InputBox}{Game.InputBox}, \helprefn{String.AsFloat}{String.AsFloat},
\helprefn{String.Format}{String.Format}


\subsection{Chars property}\label{String.Chars}\index{String.Chars}\index{StrGetCharAt}%

\it{(Formerly known as global function StrGetCharAt, which is now obsolete)}

\begin{verbatim}
readonly char String.Chars[position];
\end{verbatim}
Returns the character at POSITION within the string.

POSITION is the character index (where 0 is the first character, and the last
allowable value is the Length minus 1).

If POSITION is outside the string, this function returns 0.

\bf{NOTE:} The \it{Chars} array is read-only. If you want to change one of the characters
in the string, use \helprefn{String.ReplaceCharAt}{String.ReplaceCharAt}.

\fcol{red}{Example:}
\begin{verbatim}
String text = "This is my string.";
Display("The 4th character is: %c", text.Chars[3]);
\end{verbatim}
will display "The 4th character is: s".

\it{See Also:} \helprefn{String.Length}{String.Length},
\helprefn{String.ReplaceCharAt}{String.ReplaceCharAt}


\subsection{Length property}\label{String.Length}\index{String.Length}\index{StrLen}%

\it{(Formerly known as global function StrLen, which is now obsolete)}

\begin{verbatim}
readonly int String.Length;
\end{verbatim}
Returns the length of the string, in characters.

\fcol{red}{Example:}
\begin{verbatim}
String text = "This is my string.";
Display("Length: %d", text.Length);
\end{verbatim}
will display "Length: 18".



\section{System functions and properties}%


\subsection{AudioChannelCount property}\label{System.AudioChannelCount}\index{System.AudioChannelCount}%

\begin{verbatim}
readonly static int System.AudioChannelCount;
\end{verbatim}
Gets the number of Audio Channels available to the game (in the current version of AGS this is 8).

This is useful if you want to loop through all the audio channels and check what is playing on them.

\fcol{red}{Example:}
\begin{verbatim}
Display("There are %d audio channels.", System.AudioChannelCount);
\end{verbatim}
will display a message with the number of audio channels.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{System.AudioChannels}{System.AudioChannels}


\subsection{AudioChannels property}\label{System.AudioChannels}\index{System.AudioChannels}%

\begin{verbatim}
readonly static AudioChannel* System.AudioChannels[];
\end{verbatim}
Gets the AudioChannel instance for the specified channel number. This allows you
to query the audio channel and find out what is playing on it.

\fcol{red}{Example:}
\begin{verbatim}
AudioChannel *channel = System.AudioChannels[2];
Display("Channel 2's current volume is %d.", channel.Volume);
\end{verbatim}
will display a message with Audio Channel 2's current volume.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Audio Channel commands}{AudioChannelCommands},
\helprefn{System.AudioChannelCount}{System.AudioChannelCount}


\subsection{CapsLock property}\label{System.CapsLock}\index{System.CapsLock}%

\begin{verbatim}
readonly static bool System.CapsLock;
\end{verbatim}
Gets whether Caps Lock is active on the player's system.

You might want to use this to warn the player to switch it off before typing
a password in, for example.

\fcol{red}{Example:}
\begin{verbatim}
if (System.CapsLock)
{
  Display("The CAPS LOCK light is on.");
}
\end{verbatim}
will display a message if Caps Lock is on.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{System.NumLock}{System.NumLock},
\helprefn{System.ScrollLock}{System.ScrollLock}


\subsection{ColorDepth property (system)}\label{System.ColorDepth}\index{System.ColorDepth}%

\it{(Formerly known as system.color_depth, which is now obsolete)}

\begin{verbatim}
readonly static int System.ColorDepth;
\end{verbatim}
Returns the colour depth at which the game is running. This is the overall game colour depth setting,
and it is possible for individual sprites or backgrounds to be different.

\fcol{red}{Example:}
\begin{verbatim}
Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);
\end{verbatim}
will display the current resolution and colour depth

\it{See Also:} \helprefn{System.ScreenHeight}{System.ScreenHeight},
\helprefn{System.ScreenWidth}{System.ScreenWidth}


\subsection{Gamma property}\label{System.Gamma}\index{System.Gamma}%

\begin{verbatim}
static int System.Gamma;
\end{verbatim}
Gets/sets the current screen Gamma level. This is 100 by default, and you can set it anywhere from 0 (pitch black)
to 200 (double normal brightness).

\helprefn{System.SupportsGammaControl}{System.SupportsGammaControl} must return \it{true}
in order for this property to have any effect.

Because every player's monitor will be different, you should normally use this property linked to a GUI Slider
in order to allow the player to adjust it to suit their system.

\fcol{red}{Example:}
\begin{verbatim}
if (System.SupportsGammaControl) {
  System.Gamma = 150;
}
\end{verbatim}
will turn the screen brightness up to \verb$50%$ higher than normal

\it{See Also:} \helprefn{System.SupportsGammaControl}{System.SupportsGammaControl}


\subsection{HardwareAcceleration property}\label{System.HardwareAcceleration}\index{System.HardwareAcceleration}%

\begin{verbatim}
readonly static bool System.HardwareAcceleration;
\end{verbatim}
Returns whether the game is running with hardware acceleration (eg. Direct3D). If this is
the case then RawDrawing is likely to be slower, but alpha blending and large sprites are
likely to be faster, than when the non-accelerated driver is used.

\bf{Cross-Platform Support}

Windows: \bf{ Direct3D driver }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ No }ILBRK
MacOS: \bf{ No }

\fcol{red}{Example:}
\begin{verbatim}
if (System.HardwareAcceleration) {
  Display("Yay, we can draw loads of alpha blended sprites fast!");
}
\end{verbatim}
will display a message if the game is being run with hardware acceleration

See Also: \helprefn{AGS Graphics Drivers}{GraphicsDriver}


\subsection{NumLock property}\label{System.NumLock}\index{System.NumLock}%

\begin{verbatim}
readonly static bool System.NumLock;
\end{verbatim}
Gets whether Num Lock is active on the player's system.

You might want to use this to warn the player to switch it off before using
the numeric keypad arrow keys, for example.

\fcol{red}{Example:}
\begin{verbatim}
if (System.NumLock)
{
  Display("The NUM LOCK light is on.");
}
\end{verbatim}
will display a message if Num Lock is on.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{System.CapsLock}{System.CapsLock},
\helprefn{System.ScrollLock}{System.ScrollLock}


\subsection{OperatingSystem property}\label{System.OperatingSystem}\index{System.OperatingSystem}%

\it{(Formerly known as system.os, which is now obsolete)}

\begin{verbatim}
readonly static eOperatingSystem System.OperatingSystem;
\end{verbatim}
Returns which operating system the game is currently running under. It can be one of
the following values:
\begin{verbatim}
eOSDOS
eOSWindows
eOSLinux
eOSMacOS
\end{verbatim}

\fcol{red}{Example:}
\begin{verbatim}
if (System.OperatingSystem == eOSWindows) {
  Display("Running on Windows!");
}
else {
  Display("Not running on Windows!");
}
\end{verbatim}


\subsection{ScreenHeight property}\label{System.ScreenHeight}\index{System.ScreenHeight}%

\it{(Formerly known as system.screen_height, which is now obsolete)}

\begin{verbatim}
readonly static int System.ScreenHeight;
\end{verbatim}
Returns the actual screen height that the game is running at.  If a graphic filter is in
use, the resolution returned will be that before any stretching by the filter has been
applied. If letterbox borders are enabled, the screen size reported will include the size
of these borders.

\bf{NOTE:} Do \bf{NOT} use this to calculate the centre of the screen when working
with co-ordinates. Co-ordinates are relative to the viewport, so you should
use \helprefn{System.ViewportHeight}{System.ViewportHeight} instead. Use the ScreenHeight
property only for reporting purposes.

\fcol{red}{Example:}
\begin{verbatim}
Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);
\end{verbatim}
will display the current resolution and colour depth

\it{See Also:} \helprefn{System.ColorDepth}{System.ColorDepth},
\helprefn{System.ScreenWidth}{System.ScreenWidth},
\helprefn{System.ViewportHeight}{System.ViewportHeight}


\subsection{ScreenWidth property}\label{System.ScreenWidth}\index{System.ScreenWidth}%

\it{(Formerly known as system.screen_width, which is now obsolete)}

\begin{verbatim}
readonly static int System.ScreenWidth;
\end{verbatim}
Returns the actual screen width that the game is running at.  If a graphic filter is in
use, the resolution returned will be that before any stretching by the filter has been
applied. If widescreen side borders are enabled, the screen width reported will include
the size of these borders.

\bf{NOTE:} Do \bf{NOT} use this to calculate the centre of the screen when working
with co-ordinates. Co-ordinates are relative to the viewport, so you should
use \helprefn{System.ViewportWidth}{System.ViewportWidth} instead. Use the ScreenWidth
property only for reporting purposes.

\fcol{red}{Example:}
\begin{verbatim}
Display("Game is running at: %d x %d, %d-bit colour", System.ScreenWidth,
                                  System.ScreenHeight, System.ColorDepth);
\end{verbatim}
will display the current resolution and colour depth

\it{See Also:} \helprefn{System.ColorDepth}{System.ColorDepth},
\helprefn{System.ScreenHeight}{System.ScreenHeight}
\helprefn{System.ViewportWidth}{System.ViewportWidth}


\subsection{ScrollLock property}\label{System.ScrollLock}\index{System.ScrollLock}%

\begin{verbatim}
readonly static bool System.ScrollLock;
\end{verbatim}
Gets whether Scroll Lock is active on the player's system.

Note that when running your game under the debugger, the Scroll Lock key will break
out of the game into the debugger, so it is not advised that you use it for any
other purpose in your game.

\fcol{red}{Example:}
\begin{verbatim}
if (System.ScrollLock)
{
  Display("The SCROLL LOCK light is on.");
}
\end{verbatim}
will display a message if Scroll Lock is on.

\it{Compatibility:} Supported by \bf{AGS 3.0.1} and later versions.

\it{See Also:} \helprefn{System.CapsLock}{System.CapsLock},
\helprefn{System.NumLock}{System.NumLock}


\subsection{SupportsGammaControl property}\label{System.SupportsGammaControl}\index{System.SupportsGammaControl}%

\begin{verbatim}
readonly static bool System.SupportsGammaControl;
\end{verbatim}
Gets whether the player's PC supports changing the screen's gamma control settings.

This must return \it{true} before you try and change the \helprefn{System.Gamma}{System.Gamma} property.
The situations in which this will be supported are listed below.

\bf{Cross-Platform Support}

Windows: \bf{ Full-screen only }ILBRK
MS-DOS: \bf{ No }ILBRK
Linux: \bf{ No }ILBRK
MacOS: \bf{ No }

\fcol{red}{Example:}
\begin{verbatim}
if (System.SupportsGammaControl) {
  Display("We can change the system gamma level!");
}
\end{verbatim}
will display a message if the system supports changing the gamma

\it{See Also:} \helprefn{System.Gamma}{System.Gamma}


\subsection{Version property}\label{System.Version}\index{System.Version}%

\it{(Formerly known as system.version, which is now obsolete)}

\begin{verbatim}
readonly static String System.Version;
\end{verbatim}
Returns the AGS engine version number. This could be useful from within script modules
in order to use features available on a particular engine version, or work around
any known bugs.

The string returned is the full version number, for example "2.71.833".

\fcol{red}{Example:}
\begin{verbatim}
Display("AGS version: %s", System.Version);
\end{verbatim}
will display the AGS version number


\subsection{ViewportHeight property}\label{System.ViewportHeight}\index{System.ViewportHeight}%

\it{(Formerly known as system.viewport_height, which is now obsolete)}

\begin{verbatim}
readonly static int System.ViewportHeight;
\end{verbatim}
Returns the height of the current viewport. This is reported in the same co-ordinate system
that the game is using, so you can use this to find out what the maximum possible Y co-ordinate
is within the screen.

\fcol{red}{Example:}
\begin{verbatim}
Display("Game viewport: %d x %d", System.ViewportWidth, System.ViewportHeight);
\end{verbatim}
will display the current viewport size

\it{See Also:} \helprefn{System.ScreenHeight}{System.ScreenHeight},
\helprefn{System.ViewportWidth}{System.ViewportWidth}


\subsection{ViewportWidth property}\label{System.ViewportWidth}\index{System.ViewportWidth}%

\it{(Formerly known as system.viewport_width, which is now obsolete)}

\begin{verbatim}
readonly static int System.ViewportWidth;
\end{verbatim}
Returns the width of the current viewport. This is reported in the same co-ordinate system
that the game is using, so you can use this to find out what the maximum possible X co-ordinate
is within the screen.

\fcol{red}{Example:}
\begin{verbatim}
Display("Game viewport: %d x %d", System.ViewportWidth, System.ViewportHeight);
\end{verbatim}
will display the current viewport size

\it{See Also:} \helprefn{System.ScreenWidth}{System.ScreenWidth},
\helprefn{System.ViewportHeight}{System.ViewportHeight}


\subsection{Volume property (system)}\label{System.Volume}\index{System.Volume}\index{SetDigitalMasterVolume}\index{SetMusicMasterVolume}%

\it{(Formerly known as SetDigitalMasterVolume, which is now obsolete)} ILBRK
\it{(Formerly known as SetMusicMasterVolume, which is now obsolete)}

\begin{verbatim}
static int System.Volume;
\end{verbatim}
Gets/sets the overall system volume, from 0 to 100. This is the master volume control, that
affects all audio in the game. You would usually attach this to a GUI Slider to enable the
player to control the volume from some sort of Control Panel GUI.

\fcol{red}{Example:}
\begin{verbatim}
System.Volume = 80;
\end{verbatim}
will set the overall output volume to 80.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{AudioChannel.Volume}{AudioChannel.Volume}, 
\helprefn{Game.SetAudioTypeVolume}{Game.SetAudioTypeVolume}


\subsection{VSync property}\label{System.VSync}\index{System.VSync}%

\it{(Formerly known as system.vsync, which is now obsolete)}

\begin{verbatim}
static bool System.VSync;
\end{verbatim}
Gets/sets whether AGS waits for the vertical retrace before rendering each frame.
This is off by default.

If you switch this on, it can help to reduce the "tearing" effect that you can
get when the screen scrolls. However, doing so will lock the game frame rate to
the monitor's refresh rate, which will mean you cannot reliably set a game speed higher
than 60 fps.

\bf{NOTE:} This property has no effect with the Direct3D driver.

\fcol{red}{Example:}
\begin{verbatim}
if (System.VSync) {
  Display("Vertical retrace sync is enabled!");
}
\end{verbatim}
will display a message if vsync is on


\subsection{Windowed property}\label{System.Windowed}\index{System.Windowed}%

\it{(Formerly known as system.windowed, which is now obsolete)}

\begin{verbatim}
readonly static bool System.Windowed;
\end{verbatim}
Returns whether the game is currently running in a window (\it{true}) or
full-screen (\it{false}).

\fcol{red}{Example:}
\begin{verbatim}
if (System.Windowed) {
  Display("Game is running in a window!");
}
\end{verbatim}
will display a message if the game is running in a window




\section{Text display / Speech functions}\index{Speech functions}%

\subsection{Display}\label{Display}%

\begin{verbatim}
Display (string message, ...)
\end{verbatim}
Displays a message to the screen. It will be displayed in the standard
message box, and centred in the middle of the screen.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

\fcol{red}{Example:}
\begin{verbatim}
int my_counter;
Display ("The counter is currently set to %d.", my_counter);
\end{verbatim}
will replace the '\verb$%d$' with the value of the variable "my_counter".

NOTE: Display is a blocking function - that is, control will not return
to the script until the player has removed the text window (by pressing a
key or clicking the mouse). While the window is displayed, all other
processing, like animations and interface display, are disabled. This is
usually used for responses to the player LOOKing at things.

\it{See Also:} \helprefn{DisplayAt}{DisplayAt}, \helprefn{DisplayMessage}{DisplayMessage},
\helprefn{Character.Say}{Character.Say}, \helprefn{DisplayTopBar}{DisplayTopBar},
\helprefn{String.Format}{String.Format}


\subsection{DisplayAt}\label{DisplayAt}%

\begin{verbatim}
DisplayAt(int x, int y, int width, string message, ...)

\end{verbatim}
Identical to the "Display" function, only this allows you to define the
position and size of the window where the text is displayed. The X and Y
variables define the co-ordinates of the upper-left corner of the window.

The WIDTH variable defines the maximum width of the window. The height is then
automatically calculated so that the message fits into the window.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

Note: This is a blocking call. See the "Display" help for more information.

\fcol{red}{Example:}
\begin{verbatim}
DisplayAt (50,50,100, "This is a message");
\end{verbatim}
will display the message at coordinates 50,50 in a box 100 pixels wide.

\it{See Also:} \helprefn{Display}{Display}, \helprefn{DisplayAtY}{DisplayAtY}

\subsection{DisplayAtY}\label{DisplayAtY}%

\begin{verbatim}
DisplayAtY (int y, string message)
\end{verbatim}
Similar to the Display function, except that this will display the message
box at the specified Y location on the screen. The Y defines the co-ordinate
of the top of the message box. The horizontal positioning will be
automatically calculated as usual.

\fcol{red}{Example:}
\begin{verbatim}
DisplayAt (50, "This is a message");
\end{verbatim}
will display the message at y coordinate 50.

\it{See Also:} \helprefn{Display}{Display}, \helprefn{DisplayAt}{DisplayAt}

\subsection{DisplayMessage}\label{DisplayMessage}%

\begin{verbatim}
DisplayMessage (int message_number)
\end{verbatim}
Identical to the Display function, but this uses a message text defined in
the AGS Editor rather than in the script. It will either use a message
from the current room, or a global message (if message_number >= 500).

\fcol{red}{Example:}
\begin{verbatim}
DisplayMessage(220);
\end{verbatim}
will display the message 220 of the Room message editor.

\it{See Also:} \helprefn{Display}{Display}, \helprefn{DisplayMessageAtY}{DisplayMessageAtY}


\subsection{DisplayMessageAtY}\label{DisplayMessageAtY}%

\begin{verbatim}
DisplayMessageAtY (int message_number, int yposition)
\end{verbatim}
Identical to the DisplayMessage function, except that the text box
is positioned with its top at YPOSITION, the same way as DisplayAtY
works.

This is useful if you have an important graphic in the middle of the screen that
the text box would normally cover up - with this function you can place the message
above or below it.

\fcol{red}{Example:}
\begin{verbatim}
DisplayMessageAtY(527, 200);
\end{verbatim}
will display global message 527, in the lower half of the screen.

\it{See Also:} \helprefn{DisplayAtY}{DisplayAtY}, \helprefn{DisplayMessage}{DisplayMessage}



\subsection{DisplayTopBar}\label{DisplayTopBar}%

\begin{verbatim}
DisplayTopBar(int y, int text_color, int back_color, string titleText, string message, ...)
\end{verbatim}
Displays a message in a text window, with a caption bar on top of it.

This displays MESSAGE in a similar way to the normal Display command, but above the
text window a caption bar will be displayed with TITLETEXT in it. This method was
used in some early Sierra games to indicate who was talking by having their name in
the caption, and can be handy if you don't want to draw a talking view for a character.

You can insert the value of variables into the message. For more information,
see the \helprefn{string formatting}{StringFormats} section.

The Y parameter specifies the Y location on the screen where the message box will appear.
The default is 25.

The TEXT_COLOR parameter specifies the text colour of the top bar, and the BACK_COLOR specifies
the background colour of the top bar.

You can pass 0 for Y, TEXT_COLOR or BACK_COLOR - if you do, it will use the setting you used
last time.

There are a couple of game variables available which can further customize the look of
the bar. You can change these before calling DisplayTopBar.

\bf{game.top_bar_bordercolor} sets the colour used for the bar's border (set to the same
colour as the backcolor if you don't want a border) ILBRK
\bf{game.top_bar_borderwidth} sets the width of the bar's border, in pixels (default 1) ILBRK
\bf{game.top_bar_font} sets the font to use for the top bar. The default is -1, which means
that the current Normal font is used. Set it to a specific number to use that font instead.

\fcol{red}{Example:}
\begin{verbatim}
DisplayTopBar(25, 8, 7, "Evil wizard", "Get out of my house and never return!");
\end{verbatim}
will display "Get out of my house and never return!" in the message box, with the
caption bar reading "Evil wizard". The message box will have dark grey text on a light
gray background.

\it{See Also:} \helprefn{Display}{Display}, \helprefn{DisplayAt}{DisplayAt}


\subsection{SetSkipSpeech}\label{SetSkipSpeech}%

\begin{verbatim}
SetSkipSpeech (int new_mode)
\end{verbatim}
Changes whether the player can skip speech text by clicking the mouse.
This option is initially set in a checkbox in the Main tab of the editor, but
this function allows you to change it at run-time.
The value of NEW_MODE means the following:
\begin{verbatim}
0  player can skip text by clicking mouse or pressing key
1  player can skip text by pressing key only, not by clicking mouse
2  player cannot skip text with mouse or keyboard
3  text does not time-out; player must click mouse or press key each time
4  player can skip text by clicking mouse only, not by pressing key
\end{verbatim}

\fcol{red}{Example:}
\begin{verbatim}
SetSkipSpeech(2);
\end{verbatim}
will make the player unable to skip the text by pressing a mouse button or a key.

\it{See Also:} \helprefn{Game.IgnoreUserInputAfterTextTimeoutMs}{Game.IgnoreUserInputAfterTextTimeoutMs},
\helprefn{Game.TextReadingSpeed}{Game.TextReadingSpeed}


\subsection{SetSpeechStyle}\label{SetSpeechStyle}%

\begin{verbatim}
SetSpeechStyle(SpeechStyle)
\end{verbatim}
Changes the way in which speech text is displayed. This modifies the setting
originally set in the editor. SpeechStyle can be:
\begin{verbatim}
eSpeechLucasarts
  speech text over character's head
eSpeechSierra
  close-up portrait of character
eSpeechSierraWithBackground
  close-up portrait + background window for text
eSpeechFullScreen
  QFG4-style full screen dialog pictures
\end{verbatim}

\fcol{red}{Example:}
\begin{verbatim}
SetSpeechStyle(eSpeechSierra);
\end{verbatim}
will change the speech style to a close up portrait of the character.


\section{ViewFrame functions and properties}


\subsection{Flipped property}\label{ViewFrame.Flipped}\index{ViewFrame.Flipped}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly bool ViewFrame.Flipped
\end{verbatim}
Gets whether the frame was set to Flipped in the editor.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
if (frame.Flipped) {
  Display("This frame is flipped");
}
else {
  Display("This frame is not flipped");
}
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame},
\helprefn{ViewFrame.Graphic}{ViewFrame.Graphic}


\subsection{Frame property (view frame)}\label{ViewFrame.Frame}\index{ViewFrame.Frame}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly int ViewFrame.Frame
\end{verbatim}
Returns the frame number represented by this ViewFrame.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
Display("This ViewFrame is view %d, loop %d, frame %d",
  frame.View, frame.Loop, frame.Frame);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame},
\helprefn{ViewFrame.Loop}{ViewFrame.Loop},
\helprefn{ViewFrame.View}{ViewFrame.View}


\subsection{Graphic property (view frame)}\label{ViewFrame.Graphic}\index{ViewFrame.Graphic}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
int ViewFrame.Graphic
\end{verbatim}
Gets/sets the sprite slot number that this view frame displays.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
Display("This frame uses sprite %d", frame.Graphic);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{LinkedAudio property (view frame)}\label{ViewFrame.LinkedAudio}\index{ViewFrame.LinkedAudio}\index{ViewFrame.Sound}\index{SetFrameSound}%

\it{(Formerly known as ViewFrame.Sound, which is now obsolete)} ILBRK
\it{(Formerly known as SetFrameSound, which is now obsolete)} ILBRK
\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
AudioClip* ViewFrame.LinkedAudio
\end{verbatim}
Gets/sets the audio clip that plays when this frame comes around in animations.

If there is no linked sound, this should be \it{null}.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
if (frame.LinkedAudio == null)
{
  Display("This frame has no frame-linked audio.");
}
else
{
  frame.LinkedAudio.Play();
}
\end{verbatim}
checks view WALKING to see if frame 4 in loop 2 has a linked audio clip; if so, plays it.

\it{Compatibility:} Supported by \bf{AGS 3.2.0} and later versions.

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{Loop property (view frame)}\label{ViewFrame.Loop}\index{ViewFrame.Loop}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly int ViewFrame.Loop
\end{verbatim}
Returns the loop number represented by this ViewFrame.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
Display("This ViewFrame is view %d, loop %d, frame %d",
  frame.View, frame.Loop, frame.Frame);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame},
\helprefn{ViewFrame.Frame}{ViewFrame.Frame},
\helprefn{ViewFrame.View}{ViewFrame.View}


\subsection{Speed property (view frame)}\label{ViewFrame.Speed}\index{ViewFrame.Speed}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly int ViewFrame.Speed
\end{verbatim}
Gets the speed setting of the view frame. This is 0 by default but may have been changed
in the AGS Editor.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
Display("This frame has speed %d.", frame.Speed);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame}


\subsection{View property (view frame)}\label{ViewFrame.View}\index{ViewFrame.View}%

\it{(Formerly part of GetGameParameter, which is now obsolete)}

\begin{verbatim}
readonly int ViewFrame.View
\end{verbatim}
Returns the view number represented by this ViewFrame.

\fcol{red}{Example:}
\begin{verbatim}
ViewFrame *frame = Game.GetViewFrame(WALKING, 2, 4);
Display("This ViewFrame is view %d, loop %d, frame %d",
  frame.View, frame.Loop, frame.Frame);
\end{verbatim}

\it{See Also:} \helprefn{Game.GetViewFrame}{Game.GetViewFrame},
\helprefn{ViewFrame.Loop}{ViewFrame.Loop},
\helprefn{ViewFrame.Frame}{ViewFrame.Frame}



\section{SCUMM_VERBCOIN_GUI functions}

SCUMM_VERBCOIN_GUI is a script module that is included with the Verb Coin template.
The functions in this section are only available if you have created your game
using that template.




\subsection{SCUMM_VERBCOIN_GUI Deselect}\label{SCUMM_VERBCOIN_GUI.Deselect}\index{SCUMM_VERBCOIN_GUI.Deselect}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Deselect()
\end{verbatim}
Deselect an item if it is active or quit the inventory. Used for keyboard support.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.RunInteraction}{SCUMM_VERBCOIN_GUI.RunInteraction},
\helprefn{SCUMM_VERBCOIN_GUI.Select}{SCUMM_VERBCOIN_GUI.Select}


\subsection{SCUMM_VERBCOIN_GUI DisableVerbCoinGUI}\label{SCUMM_VERBCOIN_GUI.DisableVerbCoinGUI}\index{SCUMM_VERBCOIN_GUI.DisableVerbCoinGUI}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.DisableVerbCoinGUI(bool disabled)
\end{verbatim}
Activates/deactivates the SCUMM Verbcoin GUI system. This can be used to turn the SCUMM
VerbCoin system on and off at runtime.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.DisableVerbCoinGUI(true);
\end{verbatim}

will disable all verbcoin processing code.


\subsection{SCUMM_VERBCOIN_GUI DoubleClickSpeed}\label{SCUMM_VERBCOIN_GUI.DoubleClickSpeed}\index{SCUMM_VERBCOIN_GUI.DoubleClickSpeed}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.DoubleClickSpeed(int speed)
\end{verbatim}
Sets the time frame in which a double-click can be registered. Increase this value
for slower double-clicks, decrease this value for quicker double-clicks.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.DoubleClickSpeed(GetGameSpeed()/4);
\end{verbatim}

will set the double-click speed to 1/4 of a second. (This is a good default)

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.doubleclick}{SCUMM_VERBCOIN_GUI.doubleclick}


\subsection{SCUMM_VERBCOIN_GUI GoInventory}\label{SCUMM_VERBCOIN_GUI.GoInventory}\index{SCUMM_VERBCOIN_GUI.GoInventory}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.GoInventory()
\end{verbatim}
This function opens and closes your inventory.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.


\subsection{SCUMM_VERBCOIN_GUI Item_Count}\label{SCUMM_VERBCOIN_GUI.Item_Count}\index{SCUMM_VERBCOIN_GUI.Item_Count}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Item_Count(int count)
\end{verbatim}
Sets the number of items that inventory scrolling will use to position to the next x amount of items.

This value should equal the amount of items that fit in your inventory window.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.Item_Count(10);
\end{verbatim}

will make sure that on the next inventory scroll you will start with item 11, 21, 31, ...

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.InvScroll_Left}{SCUMM_VERBCOIN_GUI.InvScroll_Left},
\helprefn{SCUMM_VERBCOIN_GUI.InvScroll_Right}{SCUMM_VERBCOIN_GUI.InvScroll_Right}


\subsection{SCUMM_VERBCOIN_GUI InvScroll_Left}\label{SCUMM_VERBCOIN_GUI.InvScroll_Left}\index{SCUMM_VERBCOIN_GUI.InvScroll_Left}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.InvScroll_Left()
\end{verbatim}
Scrolls the inventory to the left, by the number of items set with Item_Count.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.


\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Item_Count}{SCUMM_VERBCOIN_GUI.Item_Count},
\helprefn{SCUMM_VERBCOIN_GUI.InvScroll_Right}{SCUMM_VERBCOIN_GUI.InvScroll_Right}


\subsection{SCUMM_VERBCOIN_GUI InvScroll_Right}\label{SCUMM_VERBCOIN_GUI.InvScroll_Right}\index{SCUMM_VERBCOIN_GUI.InvScroll_Right}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.InvScroll_Right()
\end{verbatim}
Scrolls the inventory to the right, by the number of items set with Item_Count.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.


\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Item_Count}{SCUMM_VERBCOIN_GUI.Item_Count},
\helprefn{SCUMM_VERBCOIN_GUI.InvScroll_Left}{SCUMM_VERBCOIN_GUI.InvScroll_Left}


\subsection{SCUMM_VERBCOIN_GUI Inv_Border_active}\label{SCUMM_VERBCOIN_GUI.Inv_Border_active}\index{SCUMM_VERBCOIN_GUI.Inv_Border_active}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Inv_Border_active(bool x_borders, bool y_borders)
\end{verbatim}
Sets which inventory exit borders are active.

Inventory exit borders determine where the inventory will exit when moving over a line.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.Inv_Border_active(false, true);
\end{verbatim}

will make the game exit the inventory when moving the mouse over either the top or the bottom of the screen.

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Inv_Border_SetPos}{SCUMM_VERBCOIN_GUI.Inv_Border_SetPos}


\subsection{SCUMM_VERBCOIN_GUI Inv_Border_SetPos}\label{SCUMM_VERBCOIN_GUI.Inv_Border_SetPos}\index{SCUMM_VERBCOIN_GUI.Inv_Border_SetPos}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Inv_Border_SetPos(int top, int bottom, 
                                            int left, int right)
\end{verbatim}
Sets the inventory exit border positions.

Inventory exit borders determine where the inventory will exit when moving over a line.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.Inv_Border_SetPos(20, 220, 20, 295);
\end{verbatim}

will set the top exit border to y-coordinate 20, the bottom border to y-coordinate 220, 
the left border to x-coordinate 20 and the right border to x-coordinate 295

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Inv_Border_active}{SCUMM_VERBCOIN_GUI.Inv_Border_active}


\subsection{SCUMM_VERBCOIN_GUI Inventory_GUI}\label{SCUMM_VERBCOIN_GUI.Inventory_GUI}\index{SCUMM_VERBCOIN_GUI.Inventory_GUI}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Inventory_GUI(int gInventory_ID,int gInvUnderlay_ID)
\end{verbatim}
Sets the inventory gui ID's, so the module will know which GUI is your
inventory and which GUI is the inventory underlay.

This allows you to change your inventory GUI's on the fly, which is particularly
interesting if you have a game with multiple playable characters. You could have
a different inventory for each character!

If the game is 32-bit with alpha-blended (transparent) GUI buttons on the
inventory, you need to use an Underlay gui which contains the actual inventory
background, and the regular gui which is empty except for the inventory window
and the gui buttons.

If your game does not use alpha-blended GUI buttons, leave the underlay inventory
empty. (use sprite 0 for its background)

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.Inventory_GUI(2, 3);
\end{verbatim}

will tell the module your inventory gui is GUI nr.2 and that the underlay gui is GUI nr.3


\subsection{SCUMM_VERBCOIN_GUI RunInteraction}\label{SCUMM_VERBCOIN_GUI.RunInteraction}\index{SCUMM_VERBCOIN_GUI.RunInteraction}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.RunInteraction(CursorMode)
\end{verbatim}
Runs the event of choice. Used for keyboard support.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.RunInteraction(eModeTalkto);
\end{verbatim}

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Deselect}{SCUMM_VERBCOIN_GUI.Deselect},
\helprefn{SCUMM_VERBCOIN_GUI.Select}{SCUMM_VERBCOIN_GUI.Select}


\subsection{SCUMM_VERBCOIN_GUI Select}\label{SCUMM_VERBCOIN_GUI.Select}\index{SCUMM_VERBCOIN_GUI.Select}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Select()
\end{verbatim}
Selects an item, or if an item is active tries to use it. Used for keyboard support.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.Deselect}{SCUMM_VERBCOIN_GUI.Deselect},
\helprefn{SCUMM_VERBCOIN_GUI.RunInteraction}{SCUMM_VERBCOIN_GUI.RunInteraction}


\subsection{SCUMM_VERBCOIN_GUI Verbcoin_GUI}\label{SCUMM_VERBCOIN_GUI.Verbcoin_GUI}\index{SCUMM_VERBCOIN_GUI.Verbcoin_GUI}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.Verbcoin_GUI(int gVerbcoin_ID)
\end{verbatim}
Sets the verbcoin gui ID, so the module will know which GUI is your verbcoin GUI.

This is particularly useful if you have a game with multiple playable characters,
where you could have a different verbcoin for each character.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.Verbcoin_GUI(1);
\end{verbatim}

will tell the module your verbcoin gui is GUI nr.1


\subsection{SCUMM_VERBCOIN_GUI verbgraphic}\label{SCUMM_VERBCOIN_GUI.verbgraphic}\index{SCUMM_VERBCOIN_GUI.verbgraphic}%

\begin{verbatim}
static SCUMM_VERBCOIN_GUI.verbgraphic(ButtonChoice, int sprite_number)
\end{verbatim}
Attaches a verbcoin sprite to a button. This sprite will be displayed when
moving over the button.

The only exception is the 'bIdle' button, which is not a button but the default
verbcoin graphic with no buttons active.

\bf{NOTE:} This function is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
SCUMM_VERBCOIN_GUI.verbgraphic(bTalk, 2);
\end{verbatim}

will set the sprite for moving over the talk button to sprite 2


\subsection{SCUMM_VERBCOIN_GUI doubleclick variable}\label{SCUMM_VERBCOIN_GUI.doubleclick}\index{SCUMM_VERBCOIN_GUI.doubleclick}%

\begin{verbatim}
global bool doubleclick
\end{verbatim}
Used to determine when a double-click has occured.

\bf{NOTE:} This variable is part of the Verb Coin template and is only available if
you used this template to create your game.

\fcol{red}{Example:}
\begin{verbatim}
  if (doubleclick == false){
    Display("You made a single-click");
  }
  else{
    Display("You just made a double-click!");
  }
\end{verbatim}

will display "You made a single-click" when you made a single-click on the object/hotspot/character/...

\it{See Also:} \helprefn{SCUMM_VERBCOIN_GUI.DoubleClickSpeed}{SCUMM_VERBCOIN_GUI.DoubleClickSpeed}




\chapter{Reference}%

This section contains a reference for various parts of the system except the scripting
language, which has its own separate Scripting section.

\section{Event Types}%

The following events are available in the "Events" section of the Properties Window
(when clicking the lightning bolt icon).

\subsection{Hotspot events}%

\begin{description}
\item [Player stands on hotspot] occurs repeatedly while the player character
is standing on the hotspot.
\item [Look at hotspot] occurs when the player clicks on the hotspot while in
the "Look" mode (cursor mode 1).
\item [Interact with hotspot] occurs when the player clicks on the hotspot while
in the "Interact" mode (cursor mode 2).
\item [Use inventory on hotspot] occurs when the player clicks on the hotspot
while in the "Use inventory" mode (cursor mode 4). You can use the 
\helprefn{player.ActiveInventory}{Character.ActiveInventory} property to distinguish
which item they used. ILBRK
\item [Speak to hotspot] occurs when the player clicks on the hotspot while in
the "Talk" mode (cursor mode 3).
\item [Any click on hotspot] occurs when the player clicks on the hotspot in
any cursor mode (except Walk). This allows you to add extra modes like
smell, taste, push, pull, and so on. This event also occurs as well as
the other event for the Look, Interact and Talk modes.
\item [Mouse moves over hotspot] occurs repeatedly while the mouse cursor is
over the hotspot. You can use this to highlight the cursor, and for other
various effects.
\end{description}

\subsection{Object events}%

\begin{description}
\item [Look at object] occurs when the player clicks on the object while in
the "Look" mode (cursor mode 1).
\item [Interact with object] occurs when the player clicks on the object in
the "Interact" mode (cursor mode 2).
\item [Speak to object] occurs when the player clicks on the object in the
"Talk" mode (cursor mode 3).
\item [Use inventory on object] works like "Use inventory on hotspot" - see
that description (above) for more information.
\end{description}

\subsection{Room events}%

\begin{description}
\item [Walk off left] occurs when the player character walks off the left edge
of the screen.
\item [Walk off right] occurs when the player walks off the right edge of the
screen.
\item [Walk off bottom] occurs when the player character walks off the bottom
edge of the screen.
\item [Walk off top] occurs when the player character walks off the top edge
of the screen.
\item [First time enters room] occurs the first time the player enters the
room. This event occurs AFTER the screen has faded in, so it allows you to
display a message describing the scene.
\item [Player enters room (before fadein)] occurs just after the room is loaded into memory.
This event occurs every time the player enters the screen, and it happens
BEFORE the screen has faded in, which allows you to change object graphics
and do other things to the screen which the player won't notice.

\it{NOTE: This event is ONLY meant for adjusting things such as object and
character placement. Do NOT use this event for any sort of automated intro
to the room - use the "Enters Room After Fade In" event for that instead.}
\item [Repeatedly execute] occurs repeatedly on every interpreter cycle. The
normal game speed is 40 cycles per second, so this event occurs about
every 25 milliseconds.
\item [Player enters room (after fadein)] occurs every time the player enters the
room, AFTER the screen has faded-in. Suitable for displaying text
descriptions and so on, that you want the player to see.
\item [Player leaves room] occurs when the player leaves the screen, just
before the screen fades out.
\end{description}

\subsection{Inventory item events}%

\begin{description}
\item [Look at inventory] occurs when the player clicks on the inventory item
while in the "look" mode.
\item [Interact with inventory] currently, because the Interact mode selects the
inventory item, this event can only be triggered by manually calling
the InventoryItem.RunInteraction script function (ie. you have to use the Handle
Inv Clicks in Script option).
\item [Speak to inventory] only applies to the Lucasarts-style inventory,
occurs when the player clicks the Talk icon on the inventory item.
\item [Use inventory on inv] occurs when the player uses another inventory
object on this one. You can use the \helprefn{player.ActiveInventory}{Character.ActiveInventory}
property to distinguish which item they used. ILBRK
This event allows the player to combine items, and so on. For example, if they had
picked up a laptop computer and a battery separately, then you could use this to
allow them to insert the battery into the computer.
\item [Other click on inventory] only applies to the Lucasarts-style inventory,
occurs when the player clicks any other cursor mode (apart from look, talk
and use_inv) on the item.
\end{description}

\subsection{Character events}%

\begin{description}
\item [Look at character] occurs when the player clicks on a character while in the "look" mode.
\item [Interact with character] occurs when the player clicks on a character while in the "interact" mode.
\item [Speak to character] occurs when the player clicks on a character while in the "talk" mode.
\item [Use inventory on character] occurs when the player uses an inventory
object on a character.  This event could be used to allow the player to give items to characters.
\item [Any click on character] occurs when the player clicks any other cursor mode (apart from look, talk and use_inv) on the character.
\end{description}

\subsection{Region events}%

\begin{description}
\item [While player stands on region] occurs repeatedly while the player character stands on this region
\item [Player walks onto region] occurs when the player moves from another region onto this one. Will
  also activate on whichever region they start on when they enter the screen.
\item [Player walks off region] occurs when the player leaves the current region. Does not occur
  if they go to a different room.
\end{description}



\section{System limits}%

This section tells you the maximums for various parts of the system. If you
have been wondering "How many rooms can I have?" or something similar,
chances are this section will answer it.

There are maximum...
\begin{verbatim}
      40  objects per room
     299  state-saving rooms per game
     300  inventory items
   30000  imported sprites
      30  controls on each GUI
     500  dialog topics
      30  options per dialog topic
      20  screen overlays at a time
       5  background frames per room
      20  mouse cursors
       8  audio channels
     100  local messages per room (excluding script)
unlimited words in the text parser dictionary
unlimited characters
unlimited views
unlimited GUIs
unlimited loops per view
unlimited frames per loop
\end{verbatim}

If you think any of these limits is a serious problem, contact me and I can
probably increase it.

\section{Keyboard Shortcuts}\label{KeyboardShortcuts}%

The AGS Editor provides various keyboard shortcuts to help you get your work done quickly.
These are summarized below:

\begin{verbatim}
F1       Help
F2       Game Statistics
F3       Find Next
Ctrl+F4  Close tab
F5       Run with Debugger
Ctrl+F5  Run without Debugger
F7       Build EXE
F9       Toggle Breakpoint
F11      Step Into

Ctrl+A   Select All
Ctrl+B   Match Brace 
Ctrl+C   Copy
Ctrl+D   Duplicate line to next
Ctrl+E   Replace
Ctrl+F   Find
Ctrl+G   Open GlobalScript.asc
Ctrl+H   Open GlobalScript.ash
Ctrl+L   Open Game
Ctrl+Q   Quit
Ctrl+R   Save Room
Ctrl+S   Save Game
Ctrl+V   Paste
Ctrl+W   Close Tab
Ctrl+X   Cut
Ctrl+Y   Redo
Ctrl+Z   Undo

Ctrl+Space      Show Autocomplete
Ctrl+Tab        Next tab
Ctrl+Shift+Tab  Previous tab

Tab         Indent selected lines
Shift+Tab   Un-indent selected lines
\end{verbatim}

\section{ASCII code table}\label{ASCIIcodes}%

This section lists the key codes which can be passed to  on_key_press  and
which keys they represent:
\begin{verbatim}
AGS KeyCode       Key         ASCII code
eKeyCtrlA         Ctrl+A        1
eKeyCtrlB         Ctrl+B        2
eKeyCtrlC         Ctrl+C        3
eKeyCtrlD         Ctrl+D        4
eKeyCtrlE         Ctrl+E        5      
eKeyCtrlF         Ctrl+F        6
eKeyCtrlG         Ctrl+G        7
eKeyCtrlH         Ctrl+H        8
eKeyCtrlI         Ctrl+I        9
eKeyCtrlJ         Ctrl+J       10
eKeyCtrlK         Ctrl+K       11
eKeyCtrlL         Ctrl+L       12
eKeyCtrlM         Ctrl+M       13
eKeyCtrlN         Ctrl+N       14
eKeyCtrlO         Ctrl+O       15
eKeyCtrlP         Ctrl+P       16
eKeyCtrlQ         Ctrl+Q       17
eKeyCtrlR         Ctrl+R       18
eKeyCtrlS         Ctrl+S       19
eKeyCtrlT         Ctrl+T       20
eKeyCtrlU         Ctrl+U       21
eKeyCtrlV         Ctrl+V       22
eKeyCtrlW         Ctrl+W       23
eKeyCtrlX         Ctrl+X       24
eKeyCtrlY         Ctrl+Y       25
eKeyCtrlZ         Ctrl+Z       26
eKey0             0            48
eKey1             1            49
eKey2             2            50
eKey3             3            51
eKey4             4            52
eKey5             5            53
eKey6             6            54
eKey7             7            55
eKey8             8            56
eKey9             9            57
eKeyA             A            65
eKeyB             B            66
eKeyC             C            67
eKeyD             D            68
eKeyE             E            69
eKeyF             F            70
eKeyG             G            71
eKeyH             H            72
eKeyI             I            73
eKeyJ             J            74
eKeyK             K            75
eKeyL             L            76
eKeyM             M            77
eKeyN             N            78
eKeyO             O            79
eKeyP             P            80
eKeyQ             Q            81
eKeyR             R            82
eKeyS             S            83
eKeyT             T            84
eKeyU             U            85
eKeyV             V            86
eKeyW             W            87
eKeyX             X            88
eKeyY             Y            89
eKeyZ             Z            90
eKeyAmpersand         &            38
eKeyAsterisk          *            42
eKeyAt                @            64
eKeyBackSlash         \            92
eKeyBackspace         Backspace     8
eKeyCloseBracket      ]            93
eKeyCloseParenthesis  )            41
eKeyColon             :            58
eKeyComma             ,            44
eKeyDelete            Delete      383
eKeyDollar            $            36
eKeyDoubleQuote       "            34
eKeyEquals            =            61
eKeyEscape            ESC          27
eKeyExclamationMark   !            33
eKeyForwardSlash      /            47
eKeyGreaterThan       >            62
eKeyHash              #            35
eKeyHyphen            -            45
eKeyInsert            Insert      382
eKeyLessThan          <            60
eKeyOpenBracket       [            91
eKeyOpenParenthesis   (            40
eKeyPercent           %            37
eKeyPeriod            .            46
eKeyPlus              +            43
eKeyQuestionMark      ?            63
eKeyReturn            RETURN       13
eKeySemiColon         ;            59
eKeySingleQuote       '            39
eKeySpace             SPACE        32
eKeyTab               TAB           9
eKeyUnderscore        _            95
eKeyF1                F1          359
eKeyF2                F2          360
eKeyF3                F3          361
eKeyF4                F4          362
eKeyF5                F5          363
eKeyF6                F6          364
eKeyF7                F7          365
eKeyF8                F8          366
eKeyF9                F9          367
eKeyF10               F10         368
eKeyF11               F11         433
eKeyF12               F12         434
eKeyHome              Home        371
eKeyUpArrow           UpArrow     372
eKeyPageUp            PageUp      373
eKeyLeftArrow         LeftArrow   375
eKeyNumPad5           NumPad 5    376
eKeyRightArrow        RightArrow  377
eKeyEnd               End         379
eKeyDownArrow         DownArrow   380
eKeyPageDown          PageDown    381
\end{verbatim}

Use these key codes in your on_key_press function to process player input. For example:
\begin{verbatim}
if (keycode == eKeyA) Display("You pressed A");
if (keycode == eKeyPlus) Display("You pressed the Plus key");
\end{verbatim}

The following extra codes can only be used with IsKeyPressed
(ie. on_key_press is never called with these codes):
\begin{verbatim}
 403       Left shift
 404       Right shift
 405       Left ctrl
 406       Right ctrl
 407       Alt
\end{verbatim}



\chapter{Frequently Asked Questions}\index{FAQs}%

This section of the manual is very rarely updated. Please consult
the AGS Forums on the website -- in particular, the Beginners Technical
Forum has an excellent Beginners FAQ (the "BFAQ") which is much more
extensive and is updated regularly with all sorts of Q&A's.

\bf{Q. What's the deal with the license? What does it mean in plain English?}

A. Adventure Game Studio is pretty much freeware. That means you may use
   it freely for non-commerical games, and you don't have to send me anything
   in return.
   There is one requirement - if you want to SELL a game you make, for profit,
   then you must contact me beforehand as there are some licensing issues
   which you may need to be aware of.
   When you finish your game, please do post it on the Announcements
   Forum and the Games Database so that everyone can give it a go.

\bf{Q. Why the swapware license? Why aren't you charging for it?}

A. Because I don't want to. There's no need to be suspicious, the fact that it's
   free doesn't necessarily mean that it's rubbish.

\bf{Q. On my screen, I can't move the main character. Wherever I click to move him,
   he just stands there.}

A. If the main character isn't on a walkable area, he will not be able to move.
   Load the room in the editor, and check that the location where the
   character starts is on a walkable area.

\bf{Q. When I enter a certain room, I just get a black screen.}

A. Make sure that you haven't used a Display Message command in the "Enters
   room before fade-in" event for that room. Remember that this event happens BEFORE
   the screen fades in.

   To make sure, when you get the black screen, try pressing enter, or clicking
   the left mouse button. If nothing happens then something more serious may
   have happened. If this is the case, press Alt+X, which should exit the
   program and allow you to trace which line of script it has stopped on.

\bf{Q. The character isn't drawn behind my walk-behind areas!}

A. You need to define the base line for the area, or he will always be drawn
   in front. See the tutorial for more information.

\bf{Q. My game EXE file seems to have disappeared.}

A. Because this file is your entire game, including the room files, when you
   save a room in the Room Editor it will delete the exe file (because the
   room contained in the exe is out of date). To get it back, simply build the
   game again by using the "Build EXE" command on the Build menu.



\chapter{Upgrading to AGS 3.0}\label{UpgradeTo30}%

If you've used AGS before, you'll probably be a bit confused and perhaps even
taken aback by this new editor. But don't worry, once you've got used to it
I'm sure you'll agree that it's a massive improvement over the old one.

The best place to start is probably to flick through \helprefn{the tutorial}{StartingOff},
which has been updated for AGS 3 and by following it through you should
get a good feeling for how the editor works.

The main changes are explained below:

\bf{Interaction Editor}

The Interaction Editor has been removed from AGS 3.0. When you import your game, AGS
will attempt to convert all your interactions into scripts. These should mostly
just work, however there are a couple of things you should be aware of:

1. Concurrency issues -- that is, while a blocking script was running in 2.72
it was still possible for interactions to run at the same time if they didn't
include any scripting. Now, that is no longer the case. ILBRK
2. Blocking interactions -- in 2.72, a "Run Dialog" interaction, for example,
waits until the dialog has finished before moving onto the next action. If you
had a Run Dialog followed by a Change Room, then the dialog would finish before
the room change happened. ILBRK
With scripting, you need to be careful because the dialog[x].Start() command
does not block; instead, it waits until the event script has finished running
before the dialog runs. This would mean that the room change would not
necessarily happen after the dialog. ILBRK
To mitigate these types of problems, you can use an alternate solution such
as a \it{run-script} command at the end of the dialog to run the room change.

\bf{Global Messages}

Global Messages are no longer supported and should be considered obsolete --
there's really no need for them now that the interaction editor has gone.
Any global messages that you had will be retained and will still work,
however the AGS 3 editor provides no way to edit them. If you need to change
one, just replace the \verb$DisplayMessage$ command with a normal \verb$Display()$
command.

As of 3.0.2, there is now a Global Variables editor in which you can create global
string variables, which provide all the functionality of Global Messages and more.

\bf{Saving and testing your game}

AGS 3.0 works slightly differently to previous versions in the way that saving
and testing games works. The Save option (Ctrl+S) is the equivalent of the old
"Quick Save" option -- it will save your changes, but not compile the EXE file.

The "Test game" option has become "Run" on the Build menu. This runs your game
with the new \helprefn{Script Debugger}{Debuggingfeatures}, which allows you to pause
and step through the script in order to track down problems.

The debugger always runs your game in a window, so if you want to test it out
full-screen there's the "Run without debugger" option (Ctrl+F5) to do so.

Use the "Build EXE" command (F7) when you want to create all the compiled files
to distribute your game.

\bf{NOTE:} When you use the Run command, your game EXE file does \bf{NOT} get built.
AGS 3's Run command is much faster than the old Test Game command because
it directly loads the files from the game folder instead. If you want to
build your game EXE, you need to use the "Build EXE" command to do so.

\bf{RawDraw scripting changes}

The RawDraw family of functions have finally been object-ised, and the old versions
are now obsolete. Support has been added to allow you to RawDraw onto dynamic sprites
as well as room backgrounds. As a result, at first the new commands will seem more
complicated than the old ones, since you can no longer just do "RawDrawImage" to
draw something onto the room background.

Instead, there is a new \helprefn{DrawingSurface}{DrawingSurfaceFunctions} object which
you do the drawing onto. You get one of these by calling
\helprefn{DynamicSprite.GetDrawingSurface}{DynamicSprite.GetDrawingSurface} or
\helprefn{Room.GetDrawingSurfaceForBackground}{Room.GetDrawingSurfaceForBackground},
depending on what you want to draw onto; and you can then use the various drawing surface
methods to do your drawing.

You must call \helprefn{Release}{DrawingSurface.Release} on the surface once you have
finished drawing onto it, which tells AGS to update the data in memory.

For examples, see the \helprefn{DrawingSurface}{DrawingSurfaceFunctions} function
help pages.

\bf{Other script changes}

Scripting hasn't really changed in AGS 3. Two new features (extender functions
and dynamic arrays) have been added, but you shouldn't need to change any
existing code.

The only breaking changes are as follows: ILBRK
1. \verb$new$ is now a reserved word. This means that if you had any variables
called "new" then your script will fail to compile. Just rename the variable
to something else. ILBRK
2. Because of the removal of some system limits, some of the AGS_MAX_ constants
have been removed (since there is no sensible value for them now that the limits
have gone). This will probably only affect module authors and is unlikely to
affect your game. Specifically, the following have been removed: AGS_MAX_GUIS,
AGS_MAX_CHARACTERS, AGS_MAX_VIEWS, AGS_MAX_LOOPS_PER_VIEW, AGS_MAX_FRAMES_PER_LOOP.


\chapter{Upgrading to AGS 3.1}\label{UpgradeTo31}%

AGS 3.1 contains some major changes over previous versions. The main change
is support for native hi-res co-ordinates.

\bf{What are native hi-res co-ordinates?}

In previous versions of AGS, everything in the game was addressed in co-ordinates
ranging from 0-319 for X values, and 0-199 (or 239) for Y values.

This made sense if your game was 320x200 or 320x240, but if your game was running
at 640x480 or 800x600 this was a pain because you couldn't think in the co-ordinate
system that your game was written for.

\bf{Why was it like this?}

When AGS was originally written it only supported 320x200, and extra resolutions
were then "bolted-on" on top later. But the fundamental co-ordinate system underneath
was never changed. This had the advantage that Setup could provide the option to
run a 320x200 game at 640x400 or vice versa, since it didn't make any difference
to the way the game would run internally.

\bf{Why change it?}

One of the main problems with the 320x200 co-ordinate system was that if you were
making a 640x480 game, you could only ever place objects and characters on even
co-ordinates. Aligning the objects with the background properly could be a pain
and involved adding an extra column of transparent pixels to the sprite to get it
to line up properly.

Originally this was judged to be a minor annoyance, but over time as more and more
people have started making hi-res games it has become a major limitation of AGS.

\bf{What has changed?}

If your game is 320x200 or 320x240, you will not notice any difference. Everything
should continue working the same way as before.

However, if your game is 640x400 or higher then the first thing you will notice
when importing your game into AGS 3.1 is that all the co-ordinates in the editor
will double. From now on, the editor will \bf{always} display native hi-res
co-ordinates.

In your scripts though, you've probably got loads of commands like \it{player.Walk} where
you pass in specific low-res co-ordinates. By default, AGS will import your game
in backwards-compatible mode, where your scripts continue to work as before. This
means that all script commands and properties will continue to accept and return
low-res co-ordinates. It also means that the limitations of placing objects on even
pixels remains.

If you want to enable the new native hi-res co-ordinate support, there is an option
in the Scripting section of the General Settings pane called "Use low-res co-ordinates
in script". If you turn this off, AGS will expect native resolution co-ordinates to
be used in your script.

Obviously converting all your scripts to use hi-res co-ordinates would be a mammoth
task, so you may well decide to continue using low-res co-ordinates for your current
game, and then start your next game with native hi-res co-ordinates. It's up to you.

\bf{Setup has changed, I can't select the resolution any more!}

Yes, as part of the support for native co-ordinates, you are no longer able to run
a 320x200 game at 640x400, or vice versa.

If you are developing a 320x200 game and were using the 640x400 setting to enlarge the
window, you can enable the 2x or 3x graphics filter in Setup instead, which provides a
similar result.


\chapter{Upgrading to AGS 3.2}\label{UpgradeTo32}%

AGS 3.2 contains some major changes, the main one being a completely new way of
scripting the game audio.

\bf{Why a new audio system?}

In previous versions of AGS, sound and music was a pain to use. Although it was
very simple to script using commands like PlayMusic(5) and PlaySound(10), the
fact that it was so basic became a limitation.

What is music 5? Which sound effect is Sound 10? How are you supposed to remember?
It was all a bit chaotic and old-fashioned. Furthermore, controlling the volume
involved several different commands, making it something of a black art.

\bf{So what's changed?}

The old commands like PlayMusic and PlaySound have been obsoleted now, and replaced
with a new object-based audio system. This means that audio files are now represented
by script instances in the game.

For example, in AGS 3.1.2, you might have done this:

\verb$PlaySound(10); // this is an explosion$

Now, with AGS 3.2 you would do it like this instead:

\verb$aExplosion.Play();$

\bf{So how do I name my audio files?}

There is a new "Audio" item in the project tree, which you now use to manage your audio.
By default, when you import your game from a previous version of AGS, it will create
audio clips with names like "aMusic5" and "aSound30", corresponding to their old names.

If you want the old-style commands like PlayMusic and PlaySound to continue working,
then \bf{you must not rename these audio clips}. AGS maintains a backwards compatibility
layer by mapping the PlayMusic(X) command to play an audio clip called "aMusicX", and
the PlaySound(X) command to play a clip called "aSoundX".

Otherwise, if you want to convert your scripts to the new audio system, you can simply
right-click and rename these audio clips as you see fit.

\bf{There is now an AudioCache folder, do I still need the Sound and Music folders?}

When you import an audio file into AGS, it makes a copy of it in the AudioCache folder,
but it also remembers where the file came from originally. If the original file changes,
AGS will automatically copy the updated file into the AudioCache folder.

When you upgrade an old game, the original file location for where AGS thinks your audio
files came from is set to the "Sound" and "Music" folders. Therefore, keeping these folders
is advisable initially as it allows you to continue to update the existing files in the same way
you always have done, and AGS will automatically pick up the changes.

But going forward, as you import new audio files, there's no need to have them in the Sound
or Music folders; import them from wherever you like.

\bf{What about controlling the volume?}

Glad you asked! Instead of all those old commands like SetMusicVolume, SetDigitalMasterVolume,
etc, there is now simply one overall system volume (\helprefn{System.Volume}{System.Volume}), and
then each sound that is playing has its own volume control as well. This is controlled by the
\helprefn{Volume property}{AudioChannel.Volume} on the audio channel (see the \helprefn{Audio page}{MusAndSound}
for details on this).

Finally, you can update the volume of one particular type of audio (eg. sound, music) by using
the \helprefn{Game.SetAudioTypeVolume}{Game.SetAudioTypeVolume} command.

\bf{Wait, what's an audio channel?}

AGS uses two new concepts -- Audio Clips (which represent a particular sound file), and Audio Channels
(which represent a currently playing piece of audio). The reason for this distinction is that you might
have the same sound effect playing two or more times simultaneously, and having Audio Channels allows you to
control each one individually. The \helprefn{Audio page}{MusAndSound} describes this further.

\bf{PlayAmbientSound is obsolete! How do I do ambient sounds?}

Ambient Sounds were a bit of an oddity in AGS, caused by the fact that you couldn't tell a PlaySound
command to loop the sound. With the new audio system, the \helprefn{Play command}{AudioClip.Play} has
an optional Repeat parameter, allowing you to specify whether it loops or not.

The X/Y directional aspect of PlayAmbientSound is supported by the \helprefn{SetRoomLocation}{AudioChannel.SetRoomLocation}
command on the audio channel.

\bf{Is there any new cool stuff that I can do?}

You can now adjust the left-right panning of audio, using the \helprefn{AudioChannel.Panning}{AudioChannel.Panning}
property. You also have finer control over syncing up different pieces of audio, through the ability
to get and seek offsets more accurately.

\bf{Has voice speech changed?}

No, speech is still handled the same way as in previous versions of AGS. You still need 
the Speech folder within your game folder, and name the files within it using the same
naming convention as you always have done.

\bf{Where should I look for more info?}

See the \helprefn{Audio help}{MusAndSound} for more information.


\chapter{Anonymous usage information}\label{AnonymousUsageInfo}%

AGS contains an option to send anonymous usage information to the AGS website.
But what is it all about and why would you want to do so?

\bf{What information does it send?}

The following is the information that AGS currently sends to the server.

\begin{itemize}\itemsep=0pt
\item AGS version
\item Windows version (eg. XP, Vista)
\item .NET Framework version
\item Screen resolution
\end{itemize}

That's it. Nothing else is sent, no personal details or scripts from your games
or anything like that.

\bf{Why should I enable this?}

By having a clearer picture of what types of system people are running, it
allows us to make better decisions about future versions of AGS. Here are some
examples of where it will be useful:

\begin{itemize}
\item A serious bug is found that affects an older version of AGS. By knowing how
many people are still using that version, we can decide whether to fix it or not.
\item We want to add a feature to the AGS Editor that would only work on Vista. By
knowing how many people are running Vista, it gives us a clear idea of how many
people would stand to benefit and therefore whether it's worth doing.
\item The AGS Editor GUIs can be designed to work with the screen resolutions
that most people are using. By knowing what the minimum resolution is that people
still use, that guides how the editor is designed.
\end{itemize}

If you object to this very basic information being submitted to AGS, you can
turn it off in the Preferences window. However, by doing so you may lose out in
the long run if AGS features are developed that will not work on your system.

\bf{When does it send this information?}

The editor contacts the AGS website once a month and sends it these details.

\bf{Will games that I make contact the AGS website?}

No, only the editor does this.



\chapter{Contacting the author}%

If you have any comments or suggestions, the first place to go is the AGS
Forums. Linked off the main AGS website, it's where the AGS community
meets and you will find answers to many questions there.

If you think you've found a bug, if you need help or can't get it to work,
please check the following:\begin{itemize}
\item That your question is not already answered in this manual. AGS has been
painstakingly documented, so PLEASE read this manual through before asking
me a question.
\item If it is not covered in the manual, check the CHANGES.TXT file. If a new
feature has been added then it will be described there, if it has not yet
been added to this manual.
\item That you are using the most recent version of AGS. Use the "Check For
Updates" option on the Help menu to make sure you're up to date.
\item If you are receiving an error message, please write down the EXACT message
and any other information which you think is appropriate. PLEASE WRITE THE
EXACT ERROR MESSAGE TEXT, don't just say "I get a message about it not being
able to find a file".
\item If you are getting lock-ups or techno-garbage printouts, please try to
give a situation which causes the problem. For instance, if you notice that
it only happens on certain screens, or only if there is an object, etc then
please state that - it makes replying a lot easier and faster.
\end{itemize}
Whatever the problem, if you can't solve it then post to the Technical Forums
for help and include all the details of the problem -- there are lots of
people there who will try to help you out.

Please don't send me e-mail or private messages about problems using AGS.
Post them to the forums, where others can help you and your question will
then be searchable so that people in future can find out the answer without
having to ask again!

\bf{IMPORTANT: Please DO NOT e-mail me your game.} When you have a demo or
full game to show off, please post it in the appropriate forum.

\it{NOTE:} If you want to mail me an attachment to demonstrate a problem you are
having, PLEASE COMPRESS IT using WinZip, PKZIP, etc and send it to me as a
zip file. Also, please get permission in advance before sending me any
attachments, or your message may get automatically deleted.

\bf{REMEMBER:} When you post a question to the forums, give it at least 24
hours before posting again asking "WHY IS NOBODY HELPING ME?!?!?". We don't
all read the forums 24/7, good things come to those who wait.

The AGS website: http://www.adventuregamestudio.co.uk

The AGS forum:   http://www.adventuregamestudio.co.uk/forum/


\chapter{Credits}\label{Credits}%

\begin{itemize}
\item Adventure Game Studio was programmed by Chris Jones, with contributions from Tzach Shabtay, Steven Poulton, Nefasto and ProgZmax.
\item Linux port by Shawn Walker (drevil@warpcore.org).
\item Mac port by Steve McCrea.
\item Demo Quest III updated by RickJ.
\item The default icon bar graphics were done by Teemu Eramaa (teemue@nic.fi)
\item Windows editor icons by Klaus.
\item Blank Game template created by AGA.
\item Default Game template enhanced by Rui "Trovatore" Pires
\item LEC 9-verb template by abstauber
\item Verb Coin template by Electroshokker, graphics by Misj
\item Hq2x and Hq3x scalers by Maxim Stepin.
\item Hi-colour fade out/in routines by Matthew Leverton.
\item Sprite anti-aliasing code by Michael Bukin.
\item Editor uses irrKlang .NET audio player (http://www.ambiera.com/irrklang)
\item The DOS engine uses DJGPP, a free 32-bit C/C++ compiler by DJ Delorie,
  which you can get from http://www.delorie.com/djgpp/
\item Graphics and sound are courtesy of the Allegro graphics library by Shawn
  Hargreaves and many others. You can get it at
  http://alleg.sourceforge.net/
\item Script editor component is scintilla by Neil Hodgson. You can get it from http://www.scintilla.org
\item Animated GIF loader by Kevin Weiner.
\item TrueType font display uses ALFont by Javier Gonzalez and the Freetype project.
\item Windows engine uses libcda CD player by Peter Wang.
\item MP3 player is almp3 by Javier Gonzalez and the FreeAmp team. It uses the mpg123 MP3 decoder.
\item OGG player is alogg by Javier Gonzalez, using the Ogg Vorbis decoder, which is available
from http://www.xiph.org/
\item OGG Theora player is APEG by Chris Robinson, using the Ogg Theora decoder, which is available
from http://www.xiph.org/
\item Windows MOD/XM/S3M/IT player is DUMB, (C) 2001-2003 Ben Davis, Robert J Ohannessian and Julien Cugniere. You
can get it from http://dumb.sf.net/
\item DOS/Linux engine use JGMOD mod player by Guan Foo Wah. You can find it at
  http://surf.to/jgmod
\item Executables compressed with UPX v1.22w (c) 1996-2002 by Laszlo Molnar & Markus F.X.J. Oberhumer
\end{itemize}

\bf{AGS Demo Game II Credits:}

\begin{itemize}
\item Written by Relight, cornjob, Chrille, Spyros and Dark Stalkey.
\item Additional material by Kairus.
\item Intro music by Mods.
\item Original backgrounds and main character were drawn by D281@aol.com.
\end{itemize}

Thanks to all the AGS beta testers for all their suggestions and bug reports -
Cornjob, AGC2, AGA, Relight, c_leksutin, Spyros and the rest of the team.

\end{document}