Adventure Game Studio v2.21
Copyright 1999-2001 Chris Jones
Adventure Game Studio (or AGS for short) allows you to create your own
point-and-click adventure games, like the older Sierra games (Space Quest 4,
King's Quest 5-6, etc). It includes an easy-to-use Integrated Development
Environment, and you do not need any programming experience to make a game
using it.
For more advanced users, AGS supports scripting, where you can write a sort
of program which allows you to have great control over the game.
By default, AGS will create Sierra-style adventure games, with the pop-up icon
bar, and right-click cycles through the modes (walk, look, use, speak).
However, you can change the interface completely using the Interface Editor
to make Lucasarts-style or any other type of interface you want.
AGS handles many parts of the system for you, like load/save game, character
movement and object animations.
(You may have known this program previously as the Adventure Creator: the last version was Adventure Creator v1.14. The reasons for the name change are described in the "Upgrading from v1" section of this document).
AGS system requirements (for 256-colour games):
Hi-colour games also require the above, but in addition:
This is the HTML version of the manual. A plain text version is also available. This HTML version hasn't been properly formatted, so some of the indentation, especially in the command reference, looks ugly. Read the text version instead if you find this hard to read.
1. Contents
This document contains the following sections:
1. Contents (this is it)
2. Using the run-time engine
3. Tutorial - introduction to how to make a simple game
4. Other features - not covered in the tutorial
5. Upgrading from AC v1
6. Reference - interaction events & commands, text script commands
7. Troubleshooting
8. Contacting the Author
9. Credits
2. Using the run-time engine
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.
2.1 THE DEMO GAME
The first thing you'll probably want to do is to run the demo game. This
short game (made up of 9 screens) will show you some of what AGS can do. It
doesn't demonstrate all the features, though - you'll find about them for
yourself. To run the demo, type DEMO and press return (or double-click the
DEMO.BAT file in Windows).
2.2 WINDOWS 2000 AND WINDOWS XP ISSUES
I thought I'd better bring this up quite early on because it's important -
if you are not using Windows 2000 or XP then skip this paragraph.
The AGS engine comes in two flavours - a Windows DirectX version and a DOS
version. The DOS version is basically rock-solid and stable, and runs on
DOS (obviously), Windows 95, 98 and Me. The Windows version is still
relatively new and so has a few "quirks", but will allow your game to run
on Windows 2000 and XP.
However, the AGS Editor is currently DOS-based. This may work for you in
Windows 2000, or the screen may go blank when you try to run it - this
depends on your graphics card. If it doesn't work I'm sorry but there's
nothing I can do until the Windows editor is finished (which will be quite a
while). Currently I have a duel boot between Windows 95 and 2000 to allow
me to test all versions.
2.3 RUN-TIME ENGINE SETUP
By default, the engine will automatically detect the player's sound card, and
use the low-resolution 320x200 display mode. However, the player can override
the autodetection if it cannot detect their sound card. To run the setup
program, type SETUP and press return.
In the Setup program, the user can choose their sound effect card (used for
sound effects like WAVs, and also for MOD and XM music) and their MIDI music
card (used for MIDI music only).
They can also choose what screen resolution they would like to run the engine
using. The available choices are 320x200, 640x400 and 960x600. The higher
resolution gives a better quality picture in the game, but slows the game down.
Generally, use the 320x200 mode for computers which are Pentium-100 or slower.
The 640x400 mode is the best choice and will work with Pentium-120 or higher
computers. The 960x600 mode should only be used with very high-spec machines
(ie. Pentium-II and better machines).
Note however, that the picture quality is only as good as it was drawn, so if
all the scenes in your game are drawn at 640x400, then using the 960x600
resolution will not help - it will just slow the game down.
2.3.1 THE WAVETABLE SYNTH MIDI DRIVER
New in v2.02 is a MIDI driver called "Software wavetable synth". This uses
a MIDI patch set to play MIDI music through the digital sound driver, thus
meaning that the music will sound the same on all sound cards. This is
particularly useful for standard Sound Blaster cards, where the built-in MIDI
chips on the card sound very crappy.
This driver is never autodetected; the player must choose it specifically
by running the Setup program. Note that since it uses the digital driver to
play the sound, you must have a digital sound card installed in the system
for it to work. Also note that it will slightly slow down the game over just
using a standard MIDI driver.
To use the wavetable driver, you need to get the General MIDI patch set, which
you can download from the AGS website (it's 1.5 Mb, that's why it's only
available seperately). If the patch set is not found in the AGS directory,
then Setup will not allow you to choose the driver.
3. Tutorial
This section will introduce you to the AGS by leading you through how to
create a simple game.
3.1 CREATING YOUR FIRST ROOM
In adventure games, the character moves from one screen to another, and each
screen consists of a pre-rendered background drawing with objects and
characters on top of it to give interaction. A screen is also called a "room".
First, you need to draw a background scene for the first room. You do this in
your favourite paint program. The size must be either 320x200 or 640x400, and
you must make sure that the colour depth is set to 8-bit or 16-bit colour.
Save it as a BMP or PCX file (TIP: a PCX will give smaller file sizes since
PCXs are compressed, whereas BMPs are not).
Load the AGS editor (type ROOMEDIT and press return). It will ask you which
game you want to edit. Highlight "NEW GAME", then click OK. Here you type the
directory name for the game (up to 8 characters max), and press return. You
have now created a new game.
Choose the "ROOM" tab if it is not already displayed (The tabs are the four
buttons along the bottom of the screen). On the left hand side of the screen,
there are five other buttons, called "Setup screen" down to "Objects". By
clicking one of these, you choose which sub-mode the editor is in.
NOTE: Don't let the name "RoomEdit" fool you - it is, in fact, your integrated
environment for development of the whole game, not just the rooms.
First of all we need to import a background scene for the room. Click on
"Setup screen" and then choose the "Load scene..." button on the main panel.
You will see a file selector where you should now find the background scene
graphic which you drew. Click OK, and it will be imported.
(If you get a message asking you what resolution the picture is drawn for,
choose the appropriate button. For example, if you have drawn a 640x400-sized
scene, then click "640x400").
You will see the top half of the picture, on the screen, along with two scroll
bars which you can use to see the rest of it.
NOTE: The Editor always runs in the 320x200 graphics mode. If you have drawn
a high-resolution picture at 640x400 it will seem to have been reduced. This
is only in the editor and you will see the proper picture in the actual game.
You can check that it was imported properly by clicking the "Full screen"
button which gives you a preview at the proper resolution.
NOTE: The Room Editor has on-line context sensitive help (and now with a new
graphical help reader!) Press F1 at any time.
3.1.1 WALKABLE AREAS
Now that you have the background scene, you need to tell the game where the
player character is allowed to walk. You do this using walkable areas. Choose
the "Walkable areas" mode from the left-hand button list.
Everywhere that the character's feet are allowed to walk, you must make
walkable. Adding walkable areas works in a similar way to most paint programs:
you use three tools (line, fill and freehand) to draw them.
You will probably want to start off with the "Line" tool - click the button
in the main panel. Now, draw round the outline of the walkable areas on the
screen. To draw a line, click the left mouse button where you want to start it,
then hold down the button and drag the mouse to the finish of the line, where
you should release the button. Once you are sure that the area is completely
enclosed by blue lines, choose the "Fill" button and click inside the area -
it should be filled in. If the entire screen is filled blue, you didn't contain
the area properly. To remove the area, choose the "Wipe colour" mode and then
click on the area. Now, start over again.
3.1.2 WALK-BEHIND AREAS
The next job you need to do is to define the walk-behind areas. These areas,
also called "priorities", tell the game where the character needs to be drawn
behind the background. For example, in the three bottom screens of the demo
game, the player can walk behind the fence.
Choose the "Walk-behind" mode from the left-hand list. You add walk-behind
areas in a very similar way to the walkable areas - in fact, you have the same
three drawing tools.
Once you have finished, you need to define the base-line for the area. This
is a horizontal line which tells the game at what level the character must be
in order to be drawn behind the area. For example, when the man is standing
in front of the street lamp he must be drawn in front; when he is behind it,
he must be drawn behind. Click the "Base-line" button, then click the mouse
on the scene at the base of the walk-behind area. When the character's feet
are below this line, he will be drawn in front of the area; when his feet are
above the line, he will be drawn behind the area.
You may have noticed a window on the screen titled "Editing colour". By
default, you have been drawing blue walk-behind areas onto the screen. This
is fine for one area, but what if you have two different walk-behind areas on
the screen? They'll need different base-lines, won't they. You can change the
colour you are drawing by clicking the up and down arrows in the "Editing
colour" window. Each colour has its own base-line, which effects the areas
drawn in that colour.
3.1.3 TRYING OUT YOUR GAME
Now that you have a semi-complete first room, it would be a good time to test
it out. Go back to the "Setup screen" mode and click "Save room...". This
will save your work to disk. In the file selector, click near the top on the
line which displays the current directory, then type in the name you want to
give the room file. The game uses files called ROOMx.CRM, where x is the room
number, and the player starts in room 1, so type ROOM1 and press the OK
button.
Now, go to the "Game" tab (bottom of the screen), and click the "Save game"
button. This will create all the files necessary to run the game. Click
the "Quit" button to exit the editor. Your game is created as an EXE file
with the name you entered at the very beginning. For example, if you typed
MYGAME as the name for the new game, it will be MYGAME.EXE. Run this to test
your game.
You should see your first screen, with the man on it. Walk around the screen,
checking out any walk-behind areas you added. If the man won't move anywhere,
he probably hasn't started on a walkable area and therefore can't move.
Press Ctrl-Q to exit the engine, then load up the Room Editor again. Choose
the "Load room..." button and load in the ROOM1 you saved earlier.
(If you need to change where the man starts, choose the "Visual" tab, then
the "Characters" sub-mode, then click on the "AT 260,190" button on the right
hand side of the screen. Here you can type in the co-ordinates for where you
want the man to start. To get the co-ordinates, use the "Ask position"
function in the Rooms, Setup screen mode).
Whenever you want to test your game, ALWAYS save the room you were working on,
and then save the game before exiting the editor.
3.1.4 HOTSPOTS
Your room is now almost complete - except for one thing, interactivity. As it
is, the player can't look at anything, talk to anything, or do anything.
A hotspot is an area of the screen where the game will react if the player
clicks the mouse there. For example, a wall could be a hotspot, a fence could
be a hotspot, and so on - in fact, every part of the screen can be one hotspot
or another.
Choose the "Hotspots" sub-mode from the Rooms tab. As with the walkable areas
and walk-behind areas, you draw hotspots using the standard three drawing
modes. The different colours this time represent the different game reactions:
the player clicking on a hotspot 1 area will cause a certain response;
clicking on a hotspot 2 area will cause a different response.
Once you have drawn the hotspots on, you need to define what happens when the
player interacts with them. You do this one hotspot at a time. Use the up and
down arrow buttons to make sure that colour 1 (dark blue) is the current
hotspot. Now, click the "Interaction" button.
3.1.4.1 INTERACTIONS
The interaction window is split up into two parts: the bottom part lists all
the available events on the hotspot which you can add a reaction for. The top
part shows the reactions you have added. To start with, the top window is
empty. To respond to an event, click on the event's name in the bottom window.
For example, we want to display a message when the player LOOKs at our
hotspot 1. So, click "Look at hotspot" on the bottom list. It will be added
to the top list, along with three other columns - Score, Command and Data.
The Score column allows you to give the player points when the event occurs,
and note that this will only happen the first time they do it, so they can't
keep getting more and more points. We don't want to give our player a score
for just looking though, so we'll leave it as 0.
The Data column is used to provide additional information to certain commands;
otherwise you can just leave it as 0.
The Command column defines what happens when the event occurs (in this case,
when the player looks at our hotspot). Click on the "(Do nothing)" and a menu
appears, with all the possible responses to the event. What these all mean
is listed in section 6.2. We just want to display a message though, so
click the "Display message %d" option. The "%d" simply means that you will
have to type in a number to replace it - in this case, the message number.
On clicking, a window pops up asking you for the message number you want to
display. (We can't just type the message in there and then; we'll do it in a
second). Since this will be our first message, and since message numbering
starts at 0, type in 0 and press return.
3.1.4.2 MESSAGES
Each room has its own set of messages. These are the strings that can be
displayed during the game. Choose the "Message editor" button at the bottom
of the interaction window. The screen will switch to text-mode and you will
see displayed "No messages". To create one, press A. Now, press enter to
edit it. Type in a message appropriate to your hotspot, for example,
This is a brick wall. Nothing more exciting than that.
and press return.
Note that pressing F2 toggles "Display next message" on and off. When this
is on, the next message will be displayed after the player has clicked to
remove this one. This feature is useful for conversations and long
descriptions. We won't use it now, however, so leave it set to "No".
Now hit ESC to leave the message editor. Click OK to exit the interaction
window.
3.1.4.3 WALK-TO SPOTS
You may have noticed on the Hotspots screen, a button called "Walk-to". This
allows you to set a position for each hotspot where the character will walk to
whenever the player interacts with the hotspot. This is like the way the
Lucasarts games like Monkey Island (tm) work. If you set a walk-to point, then
whenever the player clicks interact or talk on the hotspot, the main character
will first walk to that point before the relevant event is triggered.
If you want, the man can also walk there when the LOOK mode is used - this
option is configurable in the Game tab, "Main" sub-mode.
3.1.5 SCREEN EDGES
Each room has four "edges". The edges define how near to the side of the
screen the player needs to go for him to be considered to have left the
screen. More precisely, when the man passes an edge he triggers the related
event in the room interaction screen.
Edges are the usual way that room changes take place - when the man walks off
an edge, the game responds with a "Go to screen" command to send him to a new
location.
To view the edges, go to the Room tab, "Setup screen" sub-mode, then click
the "Edges" button. The four edges will be displayed as yellow lines on top
of the background. To move an edge, click the left button on it and drag the
mouse.
To set what happens when the character walks off an edge, click the
"Interaction" button on the "Setup screen" tab. This contains four events,
called "Walk off top", "Walk off bottom", and so on, which are triggered when
the man passes the relevant edge. This interaction window also contains some
other useful room events.
3.1.6 OBJECTS
Objects, also known as "sprites", are images on the screen which, unlike the
screen background, can move, change and disappear. You use objects for things
which the player can take (so they disappear) and for things on the screen
which you want to animate.
As as example, let's say you want to have a key on the floor of your room
which the player can take. Go to the Rooms tab, "Objects" sub-mode. Now, click
the "New object" button. You now click onto the screen where you want the
object to be added. Don't worry if you don't get its position right, you can
move it later. The object will be added as a blue cup.
The first thing we want to do is change the look of the object - obviously, we
want a picture of a key. Click on the picture of the cup near the bottom-right
corner of the screen. When you do, you will be presented with a screen which
shows all the sprite graphics available. There is a picture of a key on the
top row, so click on that. (You can add your own graphics to this list; we
will describe how to do that later).
If you want to move the object, click the "Move objects" button. Then, click
and drag the left button on the object to move it.
Lastly, we need to define what happens when the player interacts with the
object. Click the "Interaction" button. This is almost identical to the way
it worked with the hotspots (see section 3.1.4.1).
You may have noticed a couple of other buttons on the Objects screen, called
"Base-line" and "Object is on". Normally, the base-line for an object is at
the base of the object (the baseline is used for front-to-back ordered drawing
of the graphics). However, in some cases you may want to override this - for
example, if a poster is lying flat on the ground, you wouldn't want the man to
walk behind it. You can override the baseline for an object by clicking the
"base-line" button and clicking on where you want the base to be (near the top
of the screen would solve our poster problem).
Normally, you want the objects to be visible on the screen to begin with.
However, in some situations you may not want the object to appear until later
on in the game. To have the object start the game "off", click the "Object is
on" button to toggle it. You can switch the object on in the game using the
"Turn on object" command.
NOTE: The game's speed is directly related to the number of objects on the
screen. Although you probably won't notice it on a Pentium, a room with 10
objects will noticeably slow down on a 486.
Now, we have a fully-working first room. Follow the procedures we did in section 3.1.3 to try it out.
3.1.7 ROOM OPTIONS
In the "Setup screen" mode, you can set a few room options by clicking the
"Options" button. This screen allows you to configure some room-specific
things. To change an option, left-click it.
3.2.1 PALETTE SETUP
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, then go to the Game tab, "Palette" mode,
and click the "Make game hi-color" button. This will convert your game to
use hi-colour from now on. 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. See section 3.2.11 below for more info on
the hi-colour option.
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.
Choose the Game tab, "Palette" sub-mode. 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 click the button
"background" (or "un-background") to swap the slot's status.
IMPORTANT NOTE: 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.
The "Export pal" button exports 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 "Import pal" button replaces the selected 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.
3.2.2 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 Game tab, "Inventory" sub-mode. Here, each item
also has a number which you use in interactions to identify the object.
The left hand side of the screen lists all the items in the game. On the
right is the graphic used for the object in the inventory window. To change
this, left-click the picture, then select the new graphic from the dialog
which appears.
To change the object's name, click the button marked "Name" in the bottom part
of the screen. If you want the player to start the game with this item in his
inventory, check the "Player starts with this item" check-box.
To create a new item, click the "New item..." button. You will be asked for
the new item's name, and then it will be assigned the next available number.
The last thing to do with the inventory items is to define their interactions:
what happens when the player manipulates them in the inventory window. Click
the "Interaction" button, which brings up a window which works identically
to the hotspot interactions (section 3.1.4.1). The available events are
described in the reference section 6.1.4.
NOTE: Several limitations apply to the commands you can use in the Inventory
interactions. This is because they must run from all rooms, and so cannot
have any room-specific commands. In particular, you cannot use the "Run
animation" or "Run graphical script" commands, and if you use a "Display
message" command, then it must display a global message (see section 3.2.4,
below).
To give the item to the player during the game, you use the "Add inventory"
or "Remove obj, add inv" commands. The inventory number required by these
commands is the item number from the list described above.
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
seperate inventory. All inventory commands always operate on the *current
player character*.
You have two choices about how the inventory is displayed to the player.
Unfortunately, due to the way the inventory works, the two options are
built-in to the engine and are not customizable.
The default option is the Sierra-style pop-up inventory window, which is
popped up by clicking on the Bag icon on the icon bar (which uses the text
script InventoryScreen function to display it).
The other option is a Lucasarts-style inventory window. To use this, you
will need to edit the interface 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.
3.2.3 USING YOUR OWN SPRITE GRAPHICS
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 Visual tab, "Sprite mgr" sub-mode. 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.
The "import" button overwrites the currently selected slot; the "import new"
button will create a new slot for the graphic.
When you click either of these buttons, the file selector appears, where you
can choose a BMP, PCX or GIF file to import. The graphic you choose 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).
The picture is displayed on-screen. The mouse cursor changes to a rectangle,
in which you should enclose the portion of the graphic which you want to
import. You can change the size of the rectangle by clicking the right mouse
button and dragging the mouse. When the rectangle is correctly positioned,
left-click. You can also import the entire picture by pressing Enter.
You may well find that the colours on your graphic look slightly strange in
the Room Editor. This is because the sprites are only allocated, by default,
the first 41 of the palette colours (see the palette section 3.2.1 above), 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 very long (and you can only have 120 sprites per folder
anyway). 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 (or DOS directories) - they can be nested inside
each other, and in every folder except the main one there is a "parent" link
which will take you back to the folder above.
Note, however, that at present you cannot move sprites between folders so
they are stuck in the folder in which you create them. (Imported sprites
are placed into the currently displayed folder). Also, you cannot delete
sprites or folders.
AGS now has the ability to import tiled sprites from a single bmp/pcx file. To do this, draw all the frames of your animation at equal spacings apart on the source bitmap. Then, when you click "Import" in roomedit and have selected the file, press "T". This displays a grid and allows you to position it correctly over your graphics. Then, click the mouse button and the grid vanishes, but now you can drag the mouse to resize the grid out to encompass the sprites you want to import. Once it's the right size, click the mouse again and they will be imported.
3.2.4 GLOBAL MESSAGES
While each room has its own set of messages ("local messages"), in some
situations you need to be able to display a message from more than one room,
or in a global game interaction which is not related to a room. For this
purpose global messages are provided.
Choose the Game tab, "Gl. messages" sub-mode. Here you are presented with
a list of the 500 available global message slots. By default, they are all
empty except messages 996-999 which contain the default messages for actions
on the player character. Global messages are numbered between 500 and 999 so
that they are not confused with local room messages.
To display a global message, simply use its number in any "Display message"
command. If you set the Data column, then the message will be displayed as
speech text from that numbered character (check in the Character editor for
the number of each character). If the Data column is zero, the message is
displayed in the normal dialog box.
You can include a couple of variables into global (and local) messages. You
do this by inserting special tokens into the message. When the message is
displayed in the game, the engine replaces the token with its value:
token replaced by
@INx@ number of inventory item x that the player has
@GIx@ the current value of GlobalInt x (used with SetGlobalInt/GetGlobalInt)
3.2.5 INTRODUCTION SEQUENCES
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. However, you can change this to any
room you want. Go to the Visual tab, "Characters" mode. Make sure that the
main character is selected in the list on the left. You will see on the right
hand side "Start in room:" followed by "Room 1". This is the starting room
for the player character, and it is this entry that decides which is the first
room loaded. If you set it to room 0, then a file named INTRO.CRM will be
used (not ROOM0.CRM as you might think). This is for backward compatibility
with AC 1, but it is also good practice and it is suggested that you use this
feature.
Set the starting room to room 0. Now, when you run the game, the intro will
be the first room loaded. In this room, you will probably want to disable
the main character (if you want a logo graphic up first). Remember, you do
this through Setup Screen -> Options -> Main character visible.
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.
As an example, let's make your logo stay for 5 seconds and then go on to the
next screen. The graphical script's timer functions would be ideal here.
(You may want to read the graphical script documentation, section 3.3.3,
before continuing here).
Choose Setup Screen -> Interaction. Now, add the "Player enters screen"
event, and set the command to "Run graphical script". Click the "..." to edit
the script, and add a single command, "Set timer to %d loops". There are
about 40 loops per second, so replace the %d with 200.
Now, press ESC to exit the graphical script editor. You are back at the
interaction screen. Add the "Repeatedly execute" event. Again, set this to
run a graphical script, and click the "..." button. For this script, we will
need the "If timer expired" command, so drag it in from the left. Remove
the "Display message" commands which it gives you, and add a "Go to screen"
command under the IF statement. Choose whatever screen number you want. You
could go to screen 1 to start the game, or to another screen to have a longer
introduction sequence. It's up to you.
3.2.6 ANIMATIONS
In most games you will use some sort of animation during the game, whether
it be a flag waving in the breeze or the man 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 Visual tab, "Views" sub-mode. This is the View Editor. Here you will
see the main character's walking view.
Click the "New view" button to create us a new, empty view. Now, click the
down arrow button until the currently displayed view shows our newly created
one.
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.
Above each frame you will see "SPD:0". This is the frame's *relative* speed,
which you can change by clicking on the word "SPD:". 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 speed to make it particularly fast, for example setting
it to -3 means that the frame will stay for hardly any time at all.
You run an animation by using the "Run animation" interaction command or the
text script animation commands. If you use the "Run animation" interaction
command, you then click the "..." button to edit the animation. The animation
editor is very similar to the graphical script editor (see section 3.3.3),
but it has different commands available.
To animate an object, you first of all need to set the object's view to the
correct view number (use the "Set object view" animation command or the
SetObjectView text script command), and then use the "Animate using loop"
animation command or the AnimateObject text script command to actually start
the animation. The Animation Editor commands are described in section 6.8.
3.2.7 CHARACTERS
Adventure Game Studio makes it easy to add your own non-player characters
into the game. 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 "Visual" tab, "Characters" mode. You will see on the left of the
screen a list of all the characters in the game, with "NEW CHARACTER" at the
end of it. To create a new character, select "NEW CHARACTER" from the list,
then click the "NAME" button in the bottom part of the screen to change its
name to whatever you want to call your character. By doing this, a new
character slot is created.
You will see that there are a lot of options which you can set for each
character. First of all, the "This is the player character" check-box 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. By checking this box for one character, it will be de-selected
for any other character which was previously set.
Secondly, the "Ignore scaling" check-box allows you to specify that this
character will not be stretched or shrunk in scaling areas of the screen. This
could be useful 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 scaling area.
The "No interaction" check-box tells AGS that you want the character to be
invisible to all the interaction parts of the game. This is like the way the
main character works 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, click the "Room 1" button on the
right hand side of the screen, and type in the new room you want him to start
in. If you set this to room 0 for the player character, he will start in the
intro screen, INTRO.CRM (see section 3.2.5 for information). You can set the
character's location within this room by clicking the "AT 160,160" box and
typing in the X,Y co-ordinates you want him to start at. These co-ordinates
should be the middle of his feet. (You can find out the co-ordinates of a
screen point using the "Ask position" option in the Rooms, Setup Screen tab).
The "Default view" is where you set what the character looks like. You must
create a view in the View Editor (described in section 3.2.6, above), 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:
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
Once you set this option, you should see a preview of the character walking
around in the top part of the screen.
To change the rate at which the character animates, click the "Anim spd"
option. Here, a smaller number means faster animation. Note that this does NOT
effect the speed at which the character actually moves when walking.
The "Move spd" option allows you to control how fast the character moves when
walking. Here, a larger number means he walks faster.
The "Talk clr" option on the right of the screen specifies which colour is
used for the text when this character is talking. It effects both messages
displayed with "Display message" commands which are set to that character,
and also conversations. You can find out the colour for each number by going
to the Game tab, "Palette" mode.
The "Idle view" button 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, click "No idle view" and type in
the view number. If the player stands still for 20 seconds (you can change
the timeout with the SetCharacterIdle text script function), then a random
loop from the view will be played.
In the very bottom-right of the screen is a button called "Script Name". This
sets the name which the character will be referred to by in text scripts and
in conversation scripting. The difference from the main Name of the character
is that the script name may only contain letters A-Z.
To set what happens when the player interacts with the character, click the
"Interaction" button. You will be presented with the (by now familiar)
interaction window. NOTE that, as with Inventory interactions, you may NOT
use the "Run animation" or "Run graphical script" commands, or display a local
message. Basically, you need to display global messages or use text scripts
to handle character interactions.
You can also set a talking view for the character. To set one, click the
button beside where it says "Talking view:". 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).
New in v2.05 is support for exporting your characters. What this means is that
you can export a character 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. When you click the "Export char"
button, you will be asked what you want to call the file, so type a short
name and press ok. The entire character setup, and graphics, will be exported
to the file. This includes the character's walking and talking graphics.
Then, in RoomEdit (with any game loaded), press the "I" key. The file selector
appears, where you should find the CHA file which you exported earlier. A
new character slot will be created and all the settings imported.
NOTE: Because importing always creates a new slot, you cannot use it to
overwrite an existing character.
3.2.8 CONVERSATIONS
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 "Advanced" tab, Dialog mode.
Conversations are made up of Topics. A "topic" is a list of choices from
which the player can choose. You may have up to 14 choices in a topic.
However, not all of them need 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-explanitory - you view one topic at a time,
using the up/down arrow buttons to choose the current topic. Then, you see
the list of options for the topic in the top part of the screen. Each option
has a "Yes" or "No" on the right hand side, which specifies whether that
option is available to the player at the start of the game.
There is also a column headed "Say" - this 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.
You control what happens when the player chooses an option by clicking the
"Edit script" button. This is NOT the same script language as the main text
scripts use - it is a much simplified and easier to understand language
specific to dialogs.
Each topic has its own script file. When you click "Edit script" for the
first time on a topic, all you will see 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
ego: "I am very happy today because it's my birthday."
The character name is used by the system to choose the correct colour for
the text. You can have as many lines of speech like this as you want within
the script. You can also use the special character name "narrator", which
displays the text in the pop-up message box instead of as speech text.
To signal the end of the script for this option, place a "return" command on
the last line of it. For example,
@1
ego: "Hello. How are you?"
narrator: The man looks you in the eye.
otherman: "I'm fine."
return
This tells the program to go back and display the choices again to the player.
If you use "stop" instead of return, then the conversation is ended. You use
this after the player saying "Goodbye" or something similar.
The dialog commands available are:
goto-dialog X
Switches the current topic to Topic X, and displays the current list of
choices for that topic.
option-off X
Turns option X for the current topic off, meaning it won't be displayed in
the list of choices next time.
option-off-forever X
Turns option X off permanently. It will never again be displayed, not even
if an "option-on" command is used.
option-on X
Turns option X for the current topic on, including it in the list of choices
to the player next time they are displayed.
play-sound X
Plays sound effect SoundX.wav or SoundX.voc. You can use this to add speech
to your game.
return
Stops the script and returns to the list of choices.
run-script X
Runs global text script function "dialog_request", with X passed as the
single parameter. This allows you to do more advanced things in a dialog,
such as adding an inventory item and so on. The "dialog_request" function
should be placed in your game's global script file, as follows:
function dialog_request (int xvalue) {
// your code here
}
stop
Stops the conversation and returns the player to the game.
For an example of a dialog script, load the demo game into RoomEdit and
look at the script for its topic 0.
3.2.9 GAME OPTIONS
On the Game, Misc tab you may have noticed some check-boxes in the top half
of the screen. These set gamewide options, and mean the following things.
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:
3.2.11 HI-COLOUR NOTES
AGS now supports 16-bit hi-colour graphics. In order to use this feature,
go to the Game tab, "Palette" mode and click the "Make game hi-color" button.
Acknowledge the warning and your game is converted. You won't see any change
at first - in fact, the only difference made is that it now allows you to
import 16-bit backgrounds and sprites, and that the engine will select a
16-bit colour display mode. This means that to play your game the player MUST
have a Super-VGA card - standard VGA cannot display hi-colour. They will
also need to make sure they have all their VESA drivers correctly installed.
RoomEdit now switches to 320x200 16-bit colour, so all your backgrounds and
sprites should look as they will in the game.
Because hi-colour support is new to AGS, you may notice bugs with it in
various places in roomedit - for example, sprites showing up funny in various
modes. Don't worry though - it'll all look right when you run the game.
If you select the 640x400 video mode, and run a hi-colour game, you'll notice
that the engine is using letterboxing even if you didn't want to. This is
because there is no 640x400x16 video mode, so the engine has to use 640x480
and put black borders on the top and bottom. Sorry, no way round this.
3.3 OTHER ROOM FEATURES
This section describes slightly more advanced things you can do with the
rooms.
3.3.1 CHARACTER 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 100%, ie. full size. However, you can adjust it using the "Walkable
Areas" mode to anywhere from 10% (one-tenth size) to 200% (double size).
The scaling settings effect all CHARACTERS in the game, but not objects. You
can disable the scaling for an individual character by checking the "ignore
scaling" box in that character's properties.
3.3.2 SCROLLING
If you've been wondering, I'll tell you now: Yes, you can create scrolling
rooms, like the ones used in Lucasarts games like Monkey Island (tm) and Day
of the Tentacle.
To create a scrolling room, just import a scene that is larger than 320x200.
For example, 500x200 is a good size for Lucasarts-type rooms.
When you import the scene, a message box will appear asking you what
resolution the picture is drawn for - this is because the picture could
either be a scrolling room at 320x200, or a single non-scrolling screen at
640x400. So, with a 500x200 room you would click the "320x200" button.
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 follow the main character
around.
TIP: You can also have scrolling hi-res rooms. Just import a scene which is
larger than 640x400.
3.3.3 GRAPHICAL SCRIPTS
While AGS provides a comprehensive text scripting system, there are some
occasions when it is easier and neater to use a graphical script. Also, if
you are new to scripting, the graphical script is the best way to learn.
A graphical script is the easiest way to add several responses to an event.
Normally, when an event occurs, you can only set one reaction using the
Interaction window, which limits your possibilities. But, by using a graphical
script, you can do much more complex things.
At its simplest, a graphical script is just a list of commands which are
carried out from top to bottom. For example, a "Display message" command
followed by a "Remove object" command. But the graphical script's main power
is in conditional statements - that is, commands which may or may not be
executed, depending on other factors.
To support conditional statements, the graphical script uses flags. Each flag
is either "Set" or "Clear". All the flags start off clear, and you can set
a flag to the "Set" state to signal that some sort of event has occured.
There are two types of flags - Local flags and Global flags. Local flags are
specific to each room, and you can give the flag a name when you create it.
Global flags are available to every room in the game. They are named GLOBAL1
to GLOBAL50, and changing one of these flags from one room's graphical script
will also change it for all other rooms.
The graphical script editor displays the current script on the left hand
side of the screen, and the list of available commands on the right. When you
start a new script, you will have a single "Display message" command on the
script to the left. To add a new command, drag it from the list on the right
to below the "display message" on the left. You will be asked to type in the
number to replace the %d if the command requires it; this is the same way as
it works in the Interaction windows. To delete a command, drag it over to the
right. You can modify a command's properties by right-clicking it.
When you add conditional ("if") statements, an indented "display message"
command will be added below it. The indented commands will only be carried out
if the condition is true. For example, consider this script:
Display Message 1 <-- "You turn around to face the key"
If flag GOTKEY is set
Display Message 2 <-- "But it's gone. You've already taken it"
Stop Script
Set flag GOTKEY
Display Message 3 <-- "You pick up the key"
Add Inventory 2
Give Score 5
You can create this yourself by dragging the commands over from the right.
The first time the script is run, GOTKEY will be Clear (remember, all flags
start "Clear"), the player will get the key and 5 points, and GOTKEY will
be "Set". The next time the script is run, instead of getting another key,
the player will be told they already have it, and the script is aborted.
(The "Stop Script" command tells the game not to carry out the rest of the
script).
Commands like "Give score" WILL be carried out every time they are encountered
(in the Interaction windows, the score is only given once), so you must make
sure to use conditional statements so that the player can't keep repeating
the action if you don't want them to.
Descriptions of the special graphical script commands are available in
section 6.7, below.
3.3.4 IMPORTING A FILE AS THE WALKABLE AREA MASK
AGS now has the ability to import an external BMP or PCX 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 RoomEdit itsself, 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 FILE" button in the relevant mode of
the Room Editor. There are some restrictions to how this file must be drawn:
it must be the exact same size as the background scene (but in the 320x200-
resolution), 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. For example, if you have
a 640x400 hi-res background scene, the mask bitmaps must be 320x200 size.
NOTE: Do NOT use any colour numbers above 15 on the mask bitmap. Use only
palette indexes 0 to 15.
3.3.5 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:
(a) There is a limit of 10 objects per screen, so you may not be able to
animate everything that you want to.
(b) Objects slow down the game - the more objects on the screen, the slower
the game runs.
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 RoomEdit, then
go to the Room tab, Setup Screen mode, and click the "Anim bkgrnd" button. A
screen appears, which lists the current backgrounds for the room. To import
a new background, click where it says "None". To delete a background, click
the "Del" button on the relevant row. That's all there is to it. To leave the
background editor, press any key.
You can adjust the speed of the animation by clicking the "SPD" button, which
is just under the "Anim bkgrnd" button. Smaller number means faster animation,
and the default is 5.
NOTE: All the background scenes must be the same size.
NOTE: All scenes are mapped to the palette of the first scene - this should
not be a problem, but if you use very different colours in the different
frames, you may need to fine-tune the graphics.
3.3.6 LIGHTING EFFECTS
New in v2.14 is the ability to use lighting effects on your characters. The
walkable areas tab has a new option in the bottom-right called "Light level".
By default this reads "Normal", but by clicking the arrows you can change it
to from -100 to +100. This number is the light level in the current walkable
area: a negative number makes the character darker (-5 is slightly tinted,
down to -100 is very dark), a positive number makes the character lighter (+5
is slightly lighter, +100 is very bright, probably ending up white).
This 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.
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).
NOTE: In a 256-colour game, only darkening areas (light level < 0) will work.
Also, depending on the room palette the quality of the darkening will vary
in 256-colour games.
NOTE: Light levels affect characters only - they do not affect objects,
overlays or the background scene.
3.3.7 EXACT PALETTE IMPORT
If you have drawn a 256-colour background scene which you want to do palette
effects with (for example using the CyclePalette text script function), you
may find that Roomedit remaps the colours to different slots making it
difficult to do these effects.
To counteract this, RoomEdit now has an "Exact pal import" feature, which
will simply take the palette slots as they are from the source image and
replace the corresponding background slots with them in the room. This means
that your colours will be in the exact slots that you put them in, but you
must make sure that the scene only uses the palette slots that you have
allocated to the background in the Palette editor.
To enable/disable Exact Pal Import mode, press "P" on on the Setup Screen mode
of the editor.
4. Other features
4.1 MUSIC AND SOUND
All good games use sound to involve and immerse the player in the game. AGS
allows you to play a background music track, and also to play sound effects
at appropriate times.
The DOS version of AGS supports Adlib, Sound Blaster and General MIDI for
background music, and it supports the Sound Blaster and ESS Audiodrive for
sound effects.
The Windows version of AGS supports all DirectX-compatible sound cards.
For background music, AGS can use MIDI, MOD, XM, S3M and MP3 music files. For
sound effects, you can use WAV and VOC files.
When AGS needs to play music number X, it will search for the files in the
following order. The first file it finds, it plays: MUSICx.MP3, MUSICx.MID,
MUSICx.MOD, MUSICx.XM, MUSICx.S3M.
NOTE: The AGS currently does not support MP3 files with ID3V2 tags.
WARNING: A warning about MP3 - because mp3s are compressed it places a massive
load on your computer's processor playing them back, since it has to decode
all the data as well as playing it. For that reason, it is not recommended to
use MP3s at all with AGS, even though they are supported.
For example, my Pentium-233 system can quite happily manage 50 fps in SVGA
hi-res mode normally, but in a room with an MP3 background music the frame
rate drops in half to about 20 fps. If the engine detects a 386 or 486
processor it will automatically disable MP3 music. If you want to have a
digital soundtrack, use XM or MOD instead, as these cause hardly any overhead
for the CPU.
When the game loads, music 0 will be played if it exists in the game directory.
You can change the music later by setting "Play music on room load" in a room
(see section 3.1.7 for information), by using the PlayMusic text script
command, or by using the "Play sound" interaction command. If you use the
interaction command, you must add 1000 to the music number so that AGS
recognises it as music and not a sound effect. For example, to play music 23,
use "Play sound 1023".
To play a sound effect during the game, you can use the PlaySound text script
command, or the "Play sound" interaction command. The game will search for
SOUNDx.WAV and SOUNDx.VOC, where X is the sound number.
Note: The Adlib sound card only supports MIDI music. It cannot play sound
effects, or MOD, XM or MP3 music.
NOTE: Currently, any MP3 music you have will NOT be included in the file
built when you distribute your game. You will have to distribute MP3 files
seperately along with the main game file. Section 4.3 describes game
distribution.
4.1.1 VOICE 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:
ego: "Hi! How are you?"
david: "I'm fine."
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 FIRST FOUR
LETTERS of the character's SCRIPT NAME, then an ID number. For example,
ego: &10 "Hi! How are you?"
david: &7 "I'm fine."
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.
NOTE: Currently, only WAV-format files can be used for speech.
If you add or update any voice files, you need to click the "REBUILD SPEECH"
button in the Main, Game tab of roomedit which will combine them into the
speech file used in the game. This file is called SPEECH.VOX and is seperate
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.
SeeAlso: SetVoiceMode text script function.
4.2 EDITING THE INTERFACE
AGS now supports customizable interfaces. By default, the game interface is
set up to act like Sierra's point-and-click interface of its 1990-93 games.
AGS v2.07 has a completely re-written interface system, now called the GUI
system. (The name change is to help distinguish the new system from the old
system). A description of what's changed from the last version is in
section 4.2.6, below.
To change the interface (recommended for advanced users only), go to the Game
tab, "GUI" mode.
The game interface is split up into GUI "elements". Each element is a
rectangular region on the screen which is drawn on top of the background
scene. Each element can be set to either:
* be always displayed (for example the Sierra status-line)
* pop-up when the mouse moves to a certain position (eg. Sierra icon-bar)
* pop-up on script command only
The default interface is made up of two elements - the status line, and the
icon bar.
In the GUI Editor, you will see several buttons. The "Export GUI" button
exports the entire interface (ie. all the GUIs, plus button graphics) to a
file, which you can then import later into a different game using "Import GUI".
This allows you to design your interface and then use it in all your games.
The "New GUI" button creates a new element. You can change which element you
are editing by clicking the up and down arrow buttons.
In the top part of the screen the current GUI element is displayed. You can
change the size of the rectangle by dragging the lower-right hand corner of
it with the mouse.
You will also notice a window titled "Properties". This allows you to edit
the various properties of the GUI, and it works something like Visual Basic
(tm)'s Properties window. In the Properties window, you can change the
background colour of the GUI, set a background picture, and manually set the
location and width/height amongst other things.
The "Visible" property allows you to set when the GUI is displayed. The
default is "Always", which is like the Sierra status-line: always present
on the screen. The "Script only" option means that the GUI will be initially
off and must be turned on by a text script command. 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.
The "Clickable" check box at the bottom of the screen 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 used to display information.
4.2.1 GUI BUTTONS
To provide interactivity with the interface, you use buttons. There is no
limit to the number of buttons per GUI, but the game can only contain a total
of 80 GUI buttons.
To add a button, click the "Add button" button, 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 "Left
clk" attribute. This can be set to "Do nothing" (the default), and also "Set
mode", which changes the cursor mode to the mode specified in the "Clk data"
property. The other option, "Run script", runs the "interface_click" text
script function, passing the GUI number and button number of the clicked
button.
To delete a GUI button, select it then press the Delete key on the keyboard.
4.2.2 INTERFACE TEXT
You can also display text on interfaces. For example, the Sierra-style
interface displays the score in the status bar.
To add text to a GUI, you add a label. Click the "Add label" button, 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:
@GAMENAME@ The game's name, specified on the Game, Misc tab
@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. This string will be in the user's chosen language.
@TOTALSCORE@ The maximum possible score, specified on Game, Misc tab
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.
4.2.3 TEXT WINDOWS
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. Create a new GUI element, and check the "text window" box for it.
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
Game tab, "Misc" mode, and check the "Text windows use GUI" box in the top
part of the screen. When prompted, enter the number of the interface element
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.
4.2.4 LUCASARTS-STYLE INVENTORY
The final option you may have noticed in the GUI editor is the "Add Inventry"
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 text script code to those buttons to use the avaialble
variables such as game.top_inv_item, described in section 6.4.
4.2.5 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, interface_click is called with the GUI
and object numbers of the slider. This means that if they continually drag
the handle up and down, interface_click will get called repeatedly.
Your script can find out the value of the slider using the GetSliderValue
text script command.
4.2.6 UPGRADING INTERFACES TO GUIs
When you load a v2.06 or earlier game into RoomEdit, it will display a message
telling you that the interfaces have been upgraded. Most of the process is
automatic - however, you should check the new GUIs to make sure they converted
properly. Also, any interface text which you were using is not converted - you
will need to re-create it using labels.
A couple of major things to note with the new GUIs:
First, you can no longer access interface properties, like vtext, from the
text script using the "iface" variable. Code using this will still compile
and run, but will not have any affect on the game.
You can now change the text instead by using the SetLabelText function -
described in the text script reference, section 6.3.
Also, the "$c", "$r" and "$l" alignment tags for the status bar text are
no longer supported - they have been replaced by the "Align" attribute of
labels.
Finally, it is currently not possible to delete buttons or GUIs.
4.3 DISTRIBUTING YOUR GAME
When you choose the "Save game..." button in the Room Editor, as well as
creating data files which it needs for itsself, the program will create an
executable file with the name of your game, in the directory above where all
the other files are stored. This single file contains all of the program
code and data for your game, and is the file you should distribute. You may
remember that AC v1.14 included the ability to make a data file so that you
only needed to distribute it and the exe file - well this goes one step
further! Copy the USERGAME.EXE file to another directory or drive, or even
another computer, and there you have your game, contained in a single file!
Note, though, that you should also include the SETUP.BAT file to allow the
user to run the Setup program.
NOTE: It is not possible to load the exe file back into the Room 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, AC2GAME.DTA, etc) as they are what the Editor
needs to be able to load your game for editing.
NOTE: Read the LICENSE.TXT file included for information on what you may, and
may not, distribute with your game.
NOTE: MP3 music files are not included in the exe. You must include them
seperately in your game's distribution.
4.3.1 CUSTOM 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 Roomedit, make sure it says "Target: Win" and click
the "Save Game" button.
Your icon must be standard 32x32 pixels in 16-colour. If it is any other size
or colour depth, RoomEdit will give an error.
4.3.2 SPLITTING RESOURCE FILES
Some people found that once their game became large, the single EXE file
was slow at changing rooms. AGS now includes an option to split up the
resource files into smaller chunks to avoid this happening. On the Game,
Main tab you'll notice a checkbox "Split resource files up into X Mb". 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.
4.4 TEXT SCRIPTING
Version 2 of AGS includes a radically overhauled text scripting system which
is now much more powerful and allows you much greater control of the game
through the scripts, if that is what you want to do.
The script language is based on the 'C' programming language, and anyone
familiar with C should be able to pick it up very quickly. If not, I will
introduce it now:
Basically, the script consists of FUNCTIONS. Each function (think of it as
an event handler) is run when a particular event occurs. For example, the
"on_key_press" function is run whenever the user presses a key on the keyboard.
The code within the function is executed in procedural fashion - ie. from the
top downwards, one statement at a time. The function outlines look as follows:
function name_of_function() {
// your code here
}
The keyword FUNCTION identifies this as the start of the function. Next is
the function's name. This can consist of any letters A-Z, plus underscores.
Note that spaces and numerical digits are NOT allowed in the name. After the
name are the brackets (). These define what parameters will be passed to the
function. In this case, there are none. Next comes the { symbol. This
signifies the start of the code block. Execution of the function starts after
this symbol and finishes at the } symbol, which signifies the end of the
function.
To store information, you use variables. A VARIABLE is a block of memory which
holds a number or string of text. You define a variable as follows:
int my_counter ;
The "int" is the type of variable you want to create. Available types are
"char", which stores a 1-byte character, "int" which stores a 32-bit integer,
and also "string" which stores up to a 200-byte text string.
The "my_counter" is the name of the variable. You then use this name in the
script to refer to the variable. The semicolon marks the end of the statement.
The scripting language requires every statement to end with a semicolon. If
you get a "Parse error" when your script is compiled, this is the first thing
to check.
You declare variables at the top of the script, BEFORE any functions.
To assign a value to a variable, use the = operator. For example,
my_counter = 1;
will set the "my_counter" variable to 1. Notice again the semicolon - they are
required after every statement. You can also add variables together, and do
simple maths with the assignments. For example,
my_counter = other_counter - 5;
will set "my_counter" to the value of "other_counter" minus 5.
I think it's time for an example script function. So:
function on_key_press(int key_code) {
my_counter = my_counter + 1;
}
The above script will increment the "my_counter" variable every time a key is
pressed.
NOTE: If you are simply adding a value to a variable, shortcuts are available.
These are the += and -= operators. For example, "my_counter += 1;" is
equivalent to "my_counter = my_counter + 1;".
To compare variables, you use the IF keyword with the following operators:
== is equal to
> is greater than
< is less than
!= is not equal to
For example,
if ( my_counter < 5 ) {
my_counter = my_counter + 1;
}
will increment "my_counter" if it is less than 5. Note the use of the curly
brackets again - these define what code will be executed depending on the
result of the comparison.
NOTE: You will notice that the "is-equal-to" operator == is different from
the assignment operator = . Do not get these mixed up, because using a single
equals in an "if" statement can cause major bugs in your script.
IMPORTANT NOTE: Do NOT use the = or == operators with string variables, or
you will get strange results. You must use the provided functions (whose
names begin with "Str") to compare and assign strings. This is VERY IMPORTANT.
IMPORTANT NOTE: The script system is case-sensitive. That means, that the
variable names "my_counter", "My_Counter" and "MY_COUNTER" are all different.
To call a function (listed in the section 6.3, below), you use the function
name, followed by its parameters in parenthesis, then a semicolon. For
example, to add inventory item 2 to the player's inventory, do this:
AddInventory (2);
The space between the function name and parenthesis is optional.
If the function returns a value, you can capture it using the standard '='
operator. So, for example:
int currentchar;
currentchar = GetPlayerCharacter();
will store the current player character number in the currentchar variable.
You can also use the function directly in a statement much as you would
use a variable, for example:
if (IsGamePaused() == 1) {
// your code here
}
would execute the code if the IsGamePaused function returned 1.
Section 6.3 further down lists all the text script commands that are avilable.
Each command is described with the parameters it takes, and the description
will mention if it returns a value. For example, this entry from section 6.3:
GetSaveSlotDescription (int slot, string description)
Returns 1 if successful, 0 otherwise.
This entry means that the function accepts two parameters, the first is an
integer (ie. a number), and the second is a string. Where a string is required
you can either pass a string variable or just type the string in directly
using speech marks. So you could call that function as follows:
if (GetSaveSlotDescription (10, buffer) == 1) {
Display("Successful");
}
else {
Display("Failed.");
}
NOTE: If you are an experienced programmer, please NOTE THE FOLLOWING: The compiler will allow you to use 'C'-type pointers in your code, for example using int*, char* and so on. However, DO NOT DO THIS as the data will be corrupted when the user does a Save/Load game position.
Adventure Game Studio has two types of script files - "global" scripts and
"local" scripts. There is one global script in a game, and it is always
loaded in memory. This is the script which contains instructions for game-wide
events, like the key_press event.
Each room file also has its own local script. Both types of script use the
same syntax and have the same functions available to them. The local script
for a room is only in memory while that room is loaded, in order to save
memory. So although you could put all your code into the global script, using
the local scripts for functions which you only need in that particular room
will save memory and help speed up the game.
To edit a room's local script, load the room into the Room Editor, and then
choose the "Edit scripts" button from the ROOM, Setup Screen tab.
To edit the game's global script, click the "Edit script" button on the GAME,
Misc tab.
If you want to share information between room scripts and the global script,
there are 100 global variable slots which you can store numbers in.
Use the function SetGlobalInt (index, value); to set variable INDEX to
VALUE, and then GetGlobalInt (index); to get the value back again.
You can access the graphical script's global flags by using the gs_globals[]
array, but the numbers are shifted down one. So, gs_globals[3] is GLOBAL4
from the graphical script. A value of 1 means flag set and 0 means clear.
Currently it is not possible to call functions in other scripts - that is, you can't write a function in the global script, and call it from a room script. I hope to add support for this in a later version.
All co-ordinates used with functions in the script system are from 0 to 319
for X and from 0 to 199 for Y, where (0,0) is the top-left corner of the
screen, and (319, 199) is the bottom-right corner. This is independant of the
screen resolution the user is using - all co-ordinates are converted to the
320x200 scheme for scripting.
NOTE: In a scrolling room, the maximum co-ordinates are larger than this. To
find out, go to the Rooms, Setup Screen tab, and load in your scrolling room.
Under the "Options" button is a line which says: "Size: 320 x 200" (or
whatever the size of your room is). The co-ordinates you can use range from
0 to the width/height minus 1. Remember that you can use the "Ask Position"
button to find out the co-ordinates of a point on the room.
A complete list of all the functions and variables available in the text script system is in section 6.3, below.
4.4.1 TEXT SCRIPT EVENTS
In your main global script file, there are some functions which are
automatically added when you create the game. These are "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:
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.
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
interfaces on and off.
gscript_request (int parameter)
Called when one of two things happens:
(a) The CallGlobalScript function is used in a room script.
(b) The graphical script "Run text script" command is used.
The value of PARAMETER is the parameter passed to CallGlobalScript, or
the "%d" replacement in the graphical script.
interface_click (int interface, int button)
Called when the player clicks on a button on an interface 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.
on_key_press (int 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 section 6.6, below.
on_mouse_click (int button)
Called when the player clicks a mouse button. BUTTON is either LEFT or
RIGHT, depending on which button was clicked. The "mouse.x" and "mouse.y"
global variables contain the mouse's position.
repeatedly_execute ()
Called every game cycle (normally 40 times per second).
unhandled_event (int what, int type)
Called when an interaction is run, but no events are listed in the
interaction window. 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. The possible values are listed below:
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
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
3 0 Look at character
3 1 Interact with character
3 2 Speak to character
3 3 Use inventory 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
Note that the "Character stands on hotspot", and all "Any click" events
do not trigger this function.
4.4.2 OTHER SCRIPT NOTES
Only one text script can be executing at any one time. A script is considered
to be "executing" if there is still code left in a script function that needs
to be executed.
What this means is that if you call a function like MoveCharacterToObject,
which is BLOCKING - that is, it waits until the character finishes moving
before continuing the script - then while the character is moving no other
scripts will be run (for example, repeatedly_execute scripts).
5. Upgrading from AC v1
If you have used AC version 1.xx, and you want to continue with a game you
were making using this new version, this section describes the major changes
and what to do about them.
Of course, first of all you will need to get to know the new Room Editor. I'd
recommend reading through the tutorial in this file, as it will introduce you.
Instead of the old Condition List, the conditions are now split up into the
individual events. Where there are conditions now, an "Interaction" button is
available on those tabs. Clicking this gives a window where you can set the
responses you want to implement for those events.
5.1 CHANGES FROM v1
MAJOR CHANGES
From v2.2 onwards, AGS can no longer import v1.xx games.
(It's been 2 years now since v2.00 was released, so I find it unlikely that
anyone still has any).
If you need to import a v1 game, download an older version of AGS such as v2.07, use that to import your v1.xx game, then import that game into the current version.
6. Command reference
This section contains a complete reference for the room "interaction" events
and commands, and a comprehensive description of all the text script functions
available.
6.1 INTERACTION EVENTS
The following events are available in Interaction windows:
6.1.1 HOTSPOT INTERACTIONS
6.4 TEXT SCRIPT GLOBAL VARIABLES
The following variables are available to your script. Those marked with
an asterisk * are read-only and should NOT be modified by your script.
(For the characters, CHARID is the script ID name as set in the Room Editor).
*character[CHARID].x X co-ordinate of the character (see Note1 below)
*character[CHARID].y Y co-ordinate of the character
character[CHARID].name The character's full name
character[CHARID].prevroom The room it was in before this one
character[CHARID].room Which room the character is in
character[CHARID].activeinv The currently selected inventory item (or -1)
character[CHARID].inv[x] Whether the character is carrying inventory X
*character[CHARID].walking Whether the character is currently moving
*character[CHARID].animating Set to 1 while an AnimateCharacter animation runs
character[CHARID].talkview The character's talking view number (-1 for none)
game.debug_mode Whether we are in debug mode or not.
*game.items_per_line Number of inventory items displayed per line (useful
for working out how much to scroll the window down)
*game.num_inv_displayed Number of inventory items which can be seen in the
inventory window.
*game.num_inv_items Number of different inventory items which the current
player is carrying.
*game.score The player's score. (see Note2 below)
game.sierra_inv_color The background color of the sierra-style inventory.
game.talkanim_speed The animation speed for talking views (default 5).
game.text_speed How long speech text stays on the screen. Default 15,
lower number means shorter time.
game.top_inv_item Index of the first inventory item in the window
game.used_mode Cursor mode used with last click (use with "any click"
events to find out which mode was used)
gs_globals[50] The graphical script global flags (0=clear, 1=set)
*mouse.x Mouse X co-ordinate when the script was started (0-319)
*mouse.y Mouse Y co-ordinate when the script was started (0-199)
palette[SLOT].r The red component (0-63) of palette slot SLOT
palette[SLOT].g The green component (0-63) of palette slot SLOT
palette[SLOT].b The blue component (0-63) of palette slot SLOT
player.[x,y,name,...] Alias to character[EGO]. Note: only set at game start,
does not update if you change the player character.
*system.screen_height The vertical screen resolution (200 or 400) see Note3
*system.screen_width The horizontal screen resolution (320 or 640)
*system.color_depth The color depth (8 or 16).
*system.os Interpreter version (1=AGS-DOS, 2=AGS-WIN).
Notes:
(1) The character X & Y co-ordinates may be modified as long as the character
is stationary; changing these while the character is moving will cause it
to start moving off in the wrong direction.
(2) To modify the score, use the GiveScore function.
(3) The system information is provided in order for your game to behave
differently if it needs to; however, do NOT use this information to force
the player to use a specific resolution. The AC engine is designed to allow
players with varying speeds of computer to enjoy the game at a playable
speed; people with a 486 would rather see blocky graphics at 320x200 than
be forced to run very slowly at 640x400.
6.5 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...
10 objects per room
100 messages per room
500 global messages
10 commands per animation
10 commands per 'if' block of graphical script
299 rooms per game
98 inventory items
5000 imported sprites
240 sprites per folder
200 views
8 loops per view
10 frames in each loop
50 characters
20 GUI elements
30 controls on each GUI
80 total GUI controls of each type
200 dialog topics
2000 dialog-script messages
14 options per topic
8 screen overlays at a time
If you think any of these limits is a serious problem, contact me and I can probably increase it.
6.6 ASCII CODE TABLE
This section lists the key codes which can be passed to on_key_press and
which keys they represent:
1..26 Ctrl-A .. Ctrl-Z
13 Enter (Ctrl-M is also Enter)
27 Escape
32 Space
48..57 '0' key .. '9' key
65..90 'A' .. 'Z' (letters are always passed as uppercase)
316..325 Alt-Q/W/E/R/T/Y/U/I/O/P
330..338 Alt-A/S/D/F/G/H/J/K/L
344..350 Alt-Z/X/C/V/B/N/M
359..368 F1 .. F10
371 Home (numeric pad)
372 Up arrow
373 PgUp (numeric pad)
375 Left arrow
376 '5' (numeric pad)
377 Right arrow
379 End (numeric pad)
380 Down arrow
381 PgDn (numeric pad)
433..434 F11 .. F12
6.7 GRAPHICAL SCRIPT COMMAND REFERENCE
While many of the graphical script commands mirror the behavior of the
standard Interaction commands with the same name, there are some extra
commands special to the graphical script:
þ Set object view to %d
Changes the view assigned to the object. The '%d' is the number of the
view, from the status bar in the View Editor. This command also resets
the object's graphic to the first frame of loop 0 in the chosen view.
You can use a special view number 0, which is the main character's default
view. This is useful to put back the main character if you changed his
graphics during the game.
þ Animate using loop %d
Starts the object animating using loop number '%d' of its current view.
The object will cycle through all the frames in the loop and then stop.
If the Wait column is set, the next command will not be executed until
the animation has finished.
If you set the "second value" number to 1 then the animation will repeat
continuosly. If it is 0 (default) the animation will run once then stop.
NOTE: Don't set the Wait column AND set "second value" to 1, or you will
be waiting a LONG time!
þ Move to %d,%d
Starts the object moving to the specified co-ordinates. You can find out
the co-ordinates of a point by using the Misc | Ask Position feature
in RoomMake. If the Wait column is set, the next command will not be
executed until the object has reached its destination.
NOTE: If you specify a target point which cannot be reached, there will
be a short delay and then the next command will be executed immediately.
þ Move to %d,%d no walls
Identical to "Move to %d,%d", except that the object will move in a direct
path straight to the destination, ignoring all the walls on the screen.
This is useful if you want to have the man, for instance, walking into a
door once it's open (which would mean crossing the base of the door,
presumably a wall to the player). It can also be used to simulate flying
objects.
þ Place at %d,%d
Moves the object's position to the location immediately. Note that this
will only work if the object is turned OFF. Useful with the "player enters
screen" event to move objects around or to place the main character
somewhere which isn't on a screen edge.
Note that the position specified is the BOTTOM LEFT of the object graphic.
7. FAQ & Troubleshooting
This section is split up into three parts:
Q. Can I play an AVI file?
A. No, not directly. However, you can convert an AVI file for use with the
program. You've probably noticed that AGS supports WAV files for sound
effects and FLI/FLC for animations. By using a "Play sound" command straight
before a "Play FLC" command the sound should be in sync with the animation.
To split an AVI file into WAV and FLC components, I recommend the excellent
Smacker tools (www.smacker.com) which are free to download and also do
a VERY good job of reducing true-color AVIs down to 256-colours.
Q. Why is AGS so slow compared to the original Sierra/Lucasarts games? I
could run Space Quest 3 on my 286, but AGS needs 16 Mb RAM????
A. There are several reasons why AGS is not as fast, and more resource
hungry than the original games. First of all, AGS is not optimised for
speed, I admit that. Luckily however, most people these days have at
least a Pentium-class system so that's no big problem.
Second, consider that AGS supports up to 640x400 hi-colour resolution,
whereas the original Sierra/LEC games only did 320x200x256.
Thirdly, the Sierra/LEC systems were entirely script-based - that is, the
programmers created the game without any features like interaction lists,
GUI editors and Dialog editors. These features, while making AGS a lot
easier to use, also have their toll on memory and processor usage. If I
was to convert AGS to a script-only system, it would probably only need
a fraction of the system resources. But would you use it then?
Finally, yes I could spend a month or so optimising the engine to be as
fast as possible. However, you the users have made it clear that you
prefer new features and bug fixes to speed improvements, so that's what
I'm trying to give you.
At time of writing this (December 2000), a mid-range new PC is 750 MHz,
with most people currently using around a 450 MHz system. Therefore, I am
not going to spend a lot of time doing speed improvements just so it'll run
on your 486. Sorry, but that's the way it is.
Q. Are you going to do a Windows port of the editor?
A. Probably some day, yes. However, it's something that I'll start from
scratch if I do it, so it'll take a long time to finish.
Q. It's a bit cheap, the way you use MS-DOS EDIT to edit the text scripts.
Why not have an integrated editor?
A. An integrated text editor will probably come soon, but in order to release
the program as quickly as possible, I felt it best to leave a well-tested,
reliable editor there instead of delaying the release while I write my own
text editor. Also, this way you can use your favorite text editor instead by
copying it to EDIT.EXE in the RoomEdit directory.
Q. What's the deal with the license? What does it mean in plain English?
A. Adventure Game Studio is swap-ware. That means, that if you use and like
the program, you should send me something in return. This could be a game
you have made using it, some new graphics, a new translation for the system
messages, or even money! You don't HAVE to do this though, if you're really
mean, and I won't hold it against you :-)
There is one requirement - if you want to SELL a game you make, for profit,
then you must EITHER (a) send me a copy, or (b) tell me about it, giving me
a location where I can download the full game.
Even if you're not selling it, I'd appreciate you telling me about the game
when you finish it, so that I can add it to the main AGS website Links page.
In exceptional circumstances, I may even agree to host your game on the AC
site, but you should really get a web page of your own. It's not hard :-)
Q. Why the swapware license? Why aren't you charging for it?
A. Because I want to. Mainly because if you see a program claiming to create
adventure games, but charging you a registration of $100 if you want to
distribute a game, you're not likely even to try it. A few people are doing
this, for example Twilight Software with their system, but at $40 for a
single user registration, just to make freeware games with it, that's a sure
way to make it unpopular. Remember "Klik'n'play"? Hmmm.....
7.2 RUN-TIME ENGINE PROBLEMS
Q. The engine quits with "Aborting due to signal SIGxxxx, Shutting down
allegro" and a load of numbers. What's going on?
A. You may have found a bug in the engine. First of all, check that you
haven't done anything silly, like assigning a view number to an object
where the view doesn't exist.
Otherwise, try and work out when the problem happens - does it always
happen at the same time (like whenever you turn an object on).
Write down the list of numbers (each begins with "0x") and mail me with
the problem. Even better, take a screen shot of the complete error display
and send me that.
Q. When I choose the 960x600 mode in Setup, the game appears in a box in the
middle of the screen surrounded by black borders. What's wrong?
A. Nothing, that's just how it is. The reason: a monitor can only use certain
specific resolutions, like 320x200, 640x400, 640x480, 1024x768, and so on.
So, to get the 960x600 mode, AGS tells the monitor to use its 1024x768 mode,
and place the game window in the centre.
Q. Then why doesn't AGS support a 1024x768 mode?
A. For compatibility. The lowest resolution supported is 320x200, and all
other supported resolutions are multiples of this. This gives 640x400 and
960x600. Without this, AGS would be stuck in 1024x768 and would not allow
different video modes. Whether you think that would be a good thing or
not isn't the issue :-)
Q. I don't get sound from my SB Live! soundcard.
A. That's not a question.
Q. Ok, how do I get sound from my SB Live! soundcard?
A. To get any sound at all, you need to have the SB16 emulation enabled. (The
SB Live install program should have done this for you).
First of all, run AGS Setup and change the MIDI music card to the "General
MIDI" option. This gives much better sounding MIDI music than the Sound
Blaster midi driver which is autodetected.
Secondly, digital sound. This appears to be an incompatibility between
the SB16 emulator which comes with the SB Live, and AGS's sound driver. As
far as I've tried it, you can get digital sound if you run AC from a Windows
DOS-prompt, but not if you restart in MS-DOS mode. If you have more luck
in MS-DOS mode, I'd like to hear about it. You can try setting the digital
sound driver to "Sound Blaster Pro" in Setup, as this is more compatible
than the SB16 driver. Also, the IRQ which the SB Live emulation program
uses can cause problems. Try setting the SB16 emulation to use various IRQ
lines (5, 7, 9 for example) until you find one which works.
Want to sort this problem out? Well, mail Creative Labs and tell them to
release some specs for the SB Live soundcard. The reason there is no proper
driver and you have to use SB16-emulation is because Creative are keeping
how the card works secret. That's not my fault.
Q. Where can I get a "DOS mouse driver"?
A. If you have Windows installed, it comes with a DOS mouse driver, so just
try typing MOUSE and press return. If not, try typing C:\WINDOWS\MOUSE and
press return (change the directory if Windows is installed elsewhere).
If you don't have one, you can download the Microsoft DOS mouse driver
from Microsoft's web site.
Q. I don't get sound under Windows 2000!
A. This is due to the way that Windows 2000 works, and cannot be fixed for
the DOS engine. You need to run the Windows version of the engine instead,
which will give you sound using DirectX.
7.3 GAME CREATION PROBLEMS
Q. How do I import this character I downloaded in CHA format?
A. In Roomedit, go to the Visual, Characters tab and press 'I' on the keyboard.
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 screen into the Room Editor, and check that the location where the
man is has a walkable area there.
If you are upgrading from AC v1, you need to upgrade the room - see
section 5 for information.
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 "Player
enters screen" 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 Ctrl-Break, which should exit the
program and give you a list of numbers which you can send to me to
investigate.
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 section 3.1.2 for information.
Q. My USERGAME.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 save the
game again by going to the Game, Main tab and choosing the "Save game"
button.
Q. I get a message "Exiting due to signal SIGxxxx, Shutting down Allegro"
and it says it "exited without requesting it".
A. If you see a list of numbers, each starting with "0x", please write them
down and contact me. Check that you haven't done anything silly, like used
a sprite or view number which doesn't exist.
7.4 KNOWN BUGS
8. Contacting the author
If you have any comments/suggestions, the first place to go is the AGS
messageboard. 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:
9. Credits
The Adventure Game Studio v2 was programmed by Chris Jones.
The DOS version uses DJGPP, a free 32-bit C/C++ compiler by DJ Delorie,
which you can get from http://www.delorie.com/djgpp/
Graphics and sound are courtesy of the Allegro graphics library by Shawn
Hargreaves and many others. You can get it at
http://www.talula.demon.co.uk/allegro/
Thanks to Javier Gonzalez and the amp11 team for the Windows MP3 player.
Uses JGMOD mod player by Guan Foo Wah. You can find it at
http://surf.to/jgmod
DOS engine uses libamp MP3 player by Tomislav Uzelac and Ove Kaaven.
The demo game backgrounds and main character were drawn by D281@aol.com.
The icon bar graphics and Finnish translation were done by Teemu Eramaa
(teemue@nic.fi)
The Dutch translation and the website logo were done by Erix Designs
(erixdesigns@hotmail.com).
The German translation was done by Wolfram Guenther.
The Portugese translation was done by Nuno Costa (ncosta@mail.telepac.pt).
The Norwegian translation was done by Martin Seterstoen (martin-s@online.no).
The Spanish translation was done by Javi G.G.
The French translation was done by Pierre-Marc Jobin
(djobin1@globetrotter.qc.ca).
The Lithuanian translation was done by Tomas J. (thebandit@takas.lt)
The Slovenian translation was done by Janez Kranjc (janez.kranjc@amis.net)
The Bulgarian translation was done by Alexander Alexandrov.
The Czech translation was done by Lukas Rachunek.
The Polish translation was done by Jakub Offierski.
The Swedish translation was done by Arn.
The Italian translation was done by Mario from Naples.
Includes CWSDPMI DPMI host (c) 1994-1997 by Charles W. Sandmann
Executables compressed with DJP v1.07 (c) 1996-1998 by Laszlo Molnar
LEGAL STUFF
Pentium is a trademark of Intel corporation.
Windows is a trademark or registered trademark of Microsoft corp.
THIS SOFTWARE IS PROVIDED WITH ABSOLUTELY NO WARRANTY, NOT EVEN THE IMPLIED
WARRANTIES OF MERCHANTIBILITY OR FITNESS FOR A PARTICULAR PURPOSE.
USE THIS SOFTWARE AT YOUR OWN RISK. CHRIS JONES IS NOT RESPONSIBLE IF YOUR
COMPUTER STARTS BURPING, CATCHES FIRE, GETS A SENSE OF HUMOUR OR ANYTHING
ELSE WHICH HAPPENS DUE TO THE USE OF THIS SOFTWARE.
SEE THE ACCOMPANYING LICENSE.TXT FILE FOR INFORMATION ON GAME DISTRIBUTION.