1. Adventure Game Studio Ags
2. Adventure Game Studio Templates

Feb 15, 2021 Adventure Game Studio is described as '(AGS) - is the IDE and the engine meant for creating and running videogames of adventure (aka 'quest') genre. It has potential, although limited, support for other genres as well'. There are more than 50 games similar to Adventure Game Studio for a variety of platforms, including Windows, Linux, Mac, the. Adventure Escape has been played by tens of millions of players and has a 4.5 star average rating. Game critics like AppPicker, TechWiser, AndroidAuthority, and AppUnwrapper have picked Adventure Escape games as the best escape room game. SUPPORT AN INDIE COMPANY We're an indie game studio that loves making games and puzzles.

Editing GUIs

A game's user interface is typically split up into multiple GUIs. Each GUI is a rectangular region on the screen which is drawn on top of the background scene, typically configured with one of the following behaviors:

• always be displayed (for example the Sierra status-line)
• pop-up when the mouse moves to a certain position (e.g. Sierra icon-bar)
• pop-up on script command only

The default interface for the Sierra game templates is made up of two GUIs - the status line, and the icon bar.

Go to the 'GUIs' node in the main project tree. This is where all the GUIs in the game are listed - double-click one to edit it. To create a new one, right-click on the main 'GUIs' node and choose 'New GUI'.

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

The 'Visibility' property allows you to set whether the GUI will be initially visible or not.

The 'PopupStyle' property defines some pre-configured behaviors for managing GUI visibility:

NOTE: The user interface is automatically disabled during blocking actions but the same result is achieved by using the script function DisableInterface(). To automatically hide a GUI during these times, the General Settings option When player interface is disabled, GUIs should needs to be set as Be hidden.

NOTE: Depending on how scripts are configured, pausing the game may also disable the calls to input handling functions, such as on_mouse_click and on_key_press.

The 'Z-Order' setting allows you to set which order the GUIs are drawn in, i.e. when there are two GUIs that overlap this determines which one will be drawn in front of the other. The Z-order setting is an arbitrary number between 0 and 1000. AGS draws the GUIs in order, from the lowest value (0) at the back to the highest value (1000) at the front.

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

You'll notice that the GUIs also have names. These can be used in the script in a similar way to using character names. For example, if a GUI is called 'gIconBar', you can use reference it in a script by using this name. For example, to configure the visibility of GUI when the game starts:

GUI buttons

To provide interactivity with the interface, the most common type of GUI control to use is a button.

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

Using the Properties window, you can choose an image to use for the button instead of the text, and you can also set various other self-explanatory attributes. You set what happens when the player clicks on the button by using the 'Click Action' attribute. This can be set to 'Run Script' (the default), and also 'Set mode', which sets the cursor mode to whatever value has been specified in the 'New mode number' property.

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

Interface text

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

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

As well as typing normal text into the label, you can add some special values which will automatically be updated during the game. The following tokens will be replaced with the relevant values in the game:

Example: 'You have @SCORE@ out of @TOTALSCORE@ points.'

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

Customized 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. Right-click the 'GUIs' node, and choose 'New Text Window GUI'.

The element will be resized to about 1/4 of the screen, and you will see 8 images - one in each corner and one on each side. These are the border graphics. You can change each of these in the normal way, by setting the image number in the properties panel. You can give every corner and side a name to more easily identify it, although the current selection will be indicated by by surround the image with bright red squares.

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

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

To set the text color in the window, simply set the Foreground Color of the GUI and that will be used for any text that it displays.

Additionally, you may configure padding - the distance kept between the text window's border and text inside of it.

For example editing the GUI Borders of the [Display] Command in the [New Sierra Style Template] looks like this:

After compiling it looks like this in game (with x2 Scaling):

Custom inventory

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

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

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 corner out in the same way you would with 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.

Adventure Game Studio Ags

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

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

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

See also:Sliders Functions and Properties

Text Boxes

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

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

List Boxes

List box controls allow you to add a list of items to your GUI. These can be useful for allowing the player to make a selection from a list of options, but a common use is in the implementation of a custom save/load dialog box.

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

The ListBox.Translated property defines whether a game's translation to another language will also be applied to list items or not. It is recommended to disable translation for lists containing saved games.

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

Music and sound

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

File formats

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

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

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

Audio in the Editor

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

Speech

At the moment, voice speech files are not set up within the editor. See the Speech help page to find out more about adding speech to your game.

Audio Types

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

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

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

Importing audio files

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

Select this option, and you'll be given a dialog box to find the audio files that you want to import. Once imported, they'll be assigned script names automatically. If you already name the soundfiles you create and want to use in a short and descriptive way you don't have to rename them in the game project and save a lot of time and keep both your game project and the assets organized.

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

Using folders to organize sounds

Rightclick on the main music node, on one of the subordinate type folders or any user-created subfolder to these to create a subfolder to that node. It is good practice to add some new subfolders when you start a new project or you will have to drag and drop a lot of files later (as you can not drag and drop them in droves but only one at a time). You could split your music into Chapter 1 music, Chapter 2 music, etc or split it to 'music calm' and 'music battle' or whatever you need.
The same applies to the folder for sounds and sound effects, add subfolders to it to split your sound library into 'Menu sounds' for button presses and 'game sounds' for in-game sounds. Sort them by chapter or by room, this will make finding, navigating and addressing the sounds so much easier.

Playing audio in the game

The script to play an audio clip in the game is very simple. For example:

plays the audio clip called aExplosion.

Priorities and channels

AGS currently has an 8-channel audio system, which means that up to 8 sounds can be playing at the same time. One channel is always reserved for the speech voice-over and you cannot change that, so you have 7 at your disposal. By default Audio Types reserve one channel for music and one for ambient sounds; thus leaving 5 available for other types, but you can change that to your needs.

NOTE: Because total number of channels is a constant, AGS does not guarantee to reserve exactly as many channels as you set. Channels are reserved in the order of types in the project, so if you set 'MaxChannels' to 5 for music and 5 for sounds, then at runtime the game will reserve 5 for music and only 2 remaining for sounds.

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

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

Sometimes you might not want the priority of the sound to be fixed in the editor -- you might want to decide it at run-time in the script. For this reason the Play command has an optional parameter which allows you to explicitly specify the priority when you play it, for example:

NOTE: having only one channel reserved for an audio type and all clips having same priority by default will make any new played sound of that type replace the previous one automatically. This may be useful, for example, to ensure that only one music clip is playing at the same time in your game.

See also:AGS Audio Channel Troubleshooting

Seeking and changing volume

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

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

Adventure Game Studio Templates

This will start the aExplosion audio clip playing, and then change its volume to 20%.

Using Audio Channels

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

longWindedSound = aExplosion.Play();

later on, elsewhere in the script, you can change the volume by doing:

Note the check for null here -- this makes sure that your game won't crash if the sound isn't playing (it might have finished, or not have been started yet).

Overall system volume

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

Conclusion

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

AudioClip reference, AudioChannel reference

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:

Normally this would display the words in the speech text above the characters heads. However, you can add the special character '&' to symbolize that a voice file should also be played.

The file name has format XXXXY.EXT, where XXXX is made of up to first four letters of the character's script name (except the leading 'c'), the Y is the speech file number (with no leading or trailing zeroes or padding of any kind), and EXT is the file extension.

For example, if you have dialog script:

or common script using Say script function:

Both of those examples would play EGO10.WAV with the first line, and MICH7.WAV with the second. When a line of text has a voice linked to it, the text on the screen will not be removed until the voice file has finished playing. If the player interrupts it by clicking the mouse or pressing a key, the text and voice will be stopped. Voice files must be placed in the 'Speech' sub-directory of the game folder.

NOTE: WAV, OGG and MP3 format files can be used for speech.

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

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

SeeAlso:Speech.VoiceMode

The AudioCache folder

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

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

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

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

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