BlueGui User Manual

v2.0

1 Introduction (what is BlueGui?) 

1.3 System Requirements

2 Using the Mouse 

2.4 Using the Cursor Keys

3 Using the Status Bar 

4 Using the Icon Bar 

4.11 Keyboard Functions

5 Skip Introduction Dialog 

6 Select Inventory Dialog 

7 Save Game Dialog 

8 Restore Game Dialog 

9 Quit Game Dialog 

10 Game Settings Dialog 

11 Debug Functions 

11.3 Keyboard Functions

12 Browser Interface 

12.3 Transparent Browser

13 Licensing 

13.2 BlueGui License Agreement
14 Summary 

GLOSSARY 33

INDEX 34 

The BlueGui is a graphical user interface and a template for the creation of 2D adventure games. It is an open source project which means that it’s source code is freely available on the internet. The BlueGui offers many potential benefits to users of Adventure Game Studio. The purpose of this manual is to document the features of the BlueGui and describe how it is used.

Two dimensional adventure games, a very popular form of computer games, were introduced in the mid 1980's and retain a loyal following to this day. These games consist of multiple scenes created from two-dimensional drawings or photographs. The user perspective remains constant as the animated player character moves through scenes and interacts with the game world, as directed by the user. The objective is to progress through a storyline by collecting and using items to solve puzzles until the story reaches it’s ultimate conclusion.

Adventure Game Studio (AGS) is a popular adventure game development system, authored by Chris Jones, and is freely available from the internet. With AGS, it is easy to create two dimensional adventure games. Currently, there is a vigorous community of amateur AGS game developers who share ideas, art, source code, and other forms of advice.

The BlueGui User’s Manual will attempt to duplicate the look and follow the format of the AGS User’s Manual as much as possible. Since the intended audience is already familiar with the AGS User’s Manual, adoption of the same format will provide them with an instant comfort level. The scope of the BlueGui User’s Manual will be limited to usage, of the BlueGui, during game play. Although additional material may be presented to establish context, this manual will not attempt to cover AGS or it’s programing language, nor will it attempt to duplicate documentation already available. It is assumed that the audience is already familiar with these materials. 

Adventure Game Studio, the BlueGui, and AGS require an IBM compatible personal computer with a DOS or MS Windows operating system. A computer system meeting or exceeding the following criteria will be required.

Hardware Requirements

Pentium Class CPU

200Mhz Clock

32 MB RAM

2 MB Hard Disk Free Space

PC Sound Board

SVGA Monitor and Video Card

Modem, DSL, or other internet connection

Software Requirements

DOS or WIN operating system

Netscape or Iexplorer

Winzip or other Unzip program

Graphic Design - MS Paint, Photoshop, etc

Adventure Game Studio and documentation

BlueGui Source Code and documentation

The operating system is normally packaged with the hardware. Upgrades, as well as full versions, are available at computer retail outlets. A graphic design program is also necessary to be able to produce original graphics. There is a broad range of such programs also available at computer retail outlets. One should be selected according to personal preference and budget. AGS and BlueGui may be obtained online free of charge for their official websites listed below.

AGS Official Website www.adventuregamestudio.co.uk

BlueGui Official Website www.bluegui.netfirms.com

Matt Gnoble Website www.mattgoble.com/ags/

Greek AGS Website www.gac.gamespage.com./

There is a comprehensive manual describing AGS’s features and programing language upon which the BlueGui is based. A BlueGui Programmer’s Manual is planned in the near future. It will document how the BlueGui is used in developing a new adventure game. In addition, there are numerous supplementary documents and tutorials written by various AGS users. These documents may be obtained from the websites above. Many other sites are also available; it is not practical to list all of them here.

1.4 Installation Procedure

The BlueGui tutorial and source code can be downloaded from the BlueGui website and easily installed by following the installation procedure below. AGS is not required to run the tutorial. It is only required for game development activities.

Run the file bluegui.exe

Adventure Game Studio code can be downloaded from the official AGS website and easily installed by following the installation procedure below. AGS is copyrighted but is free of charge. There is a vibrant and enthusiastic support community that collaborate and offer help online.

Follow the links from the AGS website to the support forums and ask questions

The user interacts with the game by using the mouse and a "point and click" style interface. Game play consists of positioning the cursor over specific game areas or objects and clicking the mouse button. The game responds by performing one of several possible operations that were specified by the game designer. The specific operation performed is determined by the current cursor mode.

 The current cursor mode is selected by clicking on an Icon Bar button corresponding to the desired cursor mode. The Icon Bar will be described in greater detail in subsequent sections of this document. The cursor mode is indicated to the user by the cursor graphic displayed on the screen. There is a different graphic for each cursor mode. Cursor modes are game specific and may vary from game to game. Some of the more common cursor modes are described below. If debug functions are not active, the player may cycle through the following cursor modes using a right mouse click:

Walk To - In this mode the main character will walk to the point in the scene where the cursor was positioned when the mouse was clicked.

Look At - When the cursor is positioned over a character or other game element and the mouse is clicked in this mode a game event is generated. Response to such events are specified by the game designer. Usually when the user "looks at" something a text message is displayed. If no response has been specified then nothing happens.

Interact With - When the cursor is positioned over a character or other game element and the mouse is clicked in this mode a game event is generated. Response to such events are specified by the game designer. When the "interacts with" an object, actions or operations commonly associated with that type of object are performed. For example, interacting with a door may cause it to open or close. The specific actions depend upon the object and the game. If no response has been specified then nothing happens.

Talk To - When the cursor is positioned over a character or other game element and the mouse is clicked in this mode a game event is generated. Response to such events are specified by the game designer. Usually when the user "talks to" something or another character either a text message is displayed or an interactive dialog is initiated. Other actions may occur also. For example the player could say "Open sesame!" to a door to open it. If no response has been specified then nothing happens.

Use Inventory - When the cursor is positioned over a character or other game element and the mouse is clicked in this mode, a game event is generated. Response to such events are specified by the game designer. Usually when the user "uses" an inventory item on an object, actions or operations commonly associated with that type of object are performed. For example, using a key on a door object may cause it to unlock or lock. The specific actions depend upon the object, the game, and the specific inventory item. The cursor graphic displayed depends upon which inventory item is selected. If no response has been specified then nothing happens.

User Interface - When the cursor is positioned over a user interface element (i.e. button, scroll bar, dialog box, etc...) the cursor graphic is automatically changed to a pointer. When the cursor is moved away from the user interface the cursor graphic is returned to it’s previous mode and graphic automatically.

When the game starts an introductory sequence is played for the user. Normally, it includes a number of screens containing music, animation, and text. The purpose of the introduction is to display copyright information, introduce game characters, and theme. The introduction may be interrupted by clicking the mouse anywhere on the screen. This will open a dialog box, as shown, that allows the player to skip the introduction.

When the introductory sequence ends the normal user interface is enabled and game play begins. A status bar appears across the top of the screen which shows the game name and the player’s score. When the cursor is positioned near the status bar an icon bar pops up and allows the user to access the game’s features. Both of these elements will be discussed, in greater detail, in subsequent sections of this document.

The cursor keys, left, right, up and down allow the user to move the character in the corresponding direction. Pressing one of these keys causes the character to move in the corresponding direction, until it reaches the end of the screen or encounters an obstacle. A second press of the same key causes the character to stop.

The status bar displays information about the current state of the game. It is located at the top of the screen.

game title - The name of the game and it’s version number appears in this location. The

game title can be included in the background image or displayed by the AGS game engine. In the example above the title text is part of the background graphic and is therefore not changeable at runtime. The game designer may instead choose to display the title text dynamically at runtime

mouse over object - The name of the object or other game item under the cursor is displayed in this location. When the cursor is placed over an object, the player may interact with, it’s name will be displayed in the status bar. This functions something like a "tool-tip" feature found in many modern day software applications.

maximum score - The maximum possible number of points that can be scored are displayed in this location.

current score - The players current score is displayed in this location. The player earns point by solving puzzles or interacting with the game. The player’s current score is display first and is followed by the maximum possible score.

When the cursor is placed over the status bar, the icon bar appears in place of the status bar. The icon bar consist of ten buttons that give the user access to game control functions. Cursor mode button icons were inspired by the penguin character shown at the right. His eyes, beak, wings, and feet are the basis for the "look at", "talk to", "interact with", and "walk to" icons. When the cursor is positioned over an icon bar button the button is highlighted. Clicking the mouse button causes the operation associated with the button to be initiated.

When the "Walk To" button at the right is pressed, the cursor mode is changed to the "Walk To" mode. After the button is pressed the cursor is automatically repositioned below the icon bar and the icon bar is closed. AGS is inconsistent in selecting the new cursor position. This behavior is caused by AGS and not BlueGui.

When the cursor is in the "Walk To" mode it’s graphic is changed to the "man walking" icon as previously discussed. When the mouse is clicked in the game area, the main character will walk to the cursor location. This is used to move the player character around the game world.

When the"Look At" button at the right is pressed, the cursor mode is changed to the "Look At" mode. After the button is pressed the cursor is automatically repositioned below the icon bar and the icon bar is closed. When the cursor is in the "Look At" mode it’s graphic is changed to the "eye" icon. The player can gain clues and knowledge required to solve puzzles and to complete the game, by looking at different objects.

When the "Interact With" button at the right is pressed, the cursor mode is changed to the "Interact With" mode. After the button is pressed the cursor is automatically repositioned bellow the icon bar and the icon bar is closed. When the cursor is in the "Interact With" mode it’s graphic is changed to the "hand" icon. The player can interact with objects and other characters. The kind of interaction is determined by the type of object and it’s state. For example, interacting with a door may cause it to open. If it was already open, then it would close.

When the "Talk To" button at the right is pressed, the cursor mode is changed to the "Talk To" mode. After the button is pressed the cursor is automatically repositioned bellow the icon bar and the icon bar is closed. When the cursor is in the "Talk To" mode it’s graphic is changed to the "man speaking" icon. The player talk to other characters or even objects. Normally, a conversation is initiated when the player character talks to another character. In such a conversation the player selects his response from a menu. By conversing with characters the player can earn points, gain valuable information, or obtain objects required in other parts of the game. In addition, the player character may speak to objects.

When the "Use Inventory" button at the right is pressed, the cursor mode is changed to the "Use Inventory" mode. The selected item’s icon is displayed inside the button. If an item is not selected then a blank button is displayed. After the button is pressed the cursor is automatically repositioned below the icon bar and the icon bar is closed. When the cursor is in the "Use Inventory" mode it’s graphic is changed to an iconic representation of the selected inventory item. Positioning the cursor over an object or character and clicking has the effect of using the inventory item on the object or character. Using a "key" on a door object would likely unlock or lock it. Using a hammer on a nail would produce the obvious result.

When the "Select Inventory" button at the right is pressed, the inventory selection dialog box is opened and the icon bar is closed. Game operation is suspended while the dialog box is open. The player can view or select inventory items in the player character’s possession. Further discussion of the use of the inventory selection dialog box is given in subsequent sections of this document.

When the"Save Game" button at the right is pressed, the save game dialog box is opened and the icon bar is closed. Game operation is suspended while the dialog box is open. The save game dialog box is used to save the players progress and the current game state on the computers hard disk so that play may resume at a later time. Use of the save game dialog box is discussed in subsequent sections of this document.

When the "Restore Game" button at the right is pressed, the restore game dialog box is opened and the icon bar is closed. Game operation is suspended while the dialog box is open. The restore game dialog box is used to restore a previously saved game so that the player may resume game play from his previous state. Use of the restore game dialog box is discussed in subsequent sections of this document.

When the "Quit Game" button at the right is pressed, the quit game dialog box is opened and the icon bar is closed. Game operation is suspended while the dialog box is open. The quit game dialog box is used to terminate game play. Use of the restore game dialog box is discussed in subsequent sections of this document.

When the "Game Setting" button at the right is pressed, the game settings dialog box is opened and the icon bar is closed. Game operation is suspended while the dialog box is open. The game settings dialog box allows a game parameters such as game speed and music volume to be adjusted. Use of the game settings dialog box is discussed in subsequent sections of this document.

In addition to the icon bar, there are several functions that can be accessed through the keyboard. Some of these are the same functions accessed through the icon bar buttons. It is not appropriate to activate some functions from the icon bar. For example, if the "screen shot" function were activated from the Icon Bar, the Icon Bar would appear in the screen shot. A list of functions available from the keyboard follow:

Ctrl-Q quit game - Pressing this key will open the quit game dialog box allowing the user to terminate game play.

Ctrl-S screen shot - Pressing this key will create a BMP file containing an image of the current game screen.

F5 save game - Pressing this key will open the save game dialog box allowing the player to save the current game.

F7 screen shot - Pressing this key will open the restore game dialog box allowing the player to restore a previously saved game.

F9 restart - Pressing this key will cause the game to resume at the restart point. The restart point is set each time a game save operation is performed.

F12 screen shot - Pressing this key will create a BMP file containing an image of the current game screen.

TAB inventory - Pressing this key will open the select inventory dialog box allowing the player to select an item from the player character’s inventory.

The dialog box showing below, allows the player to skip the introductory sequence which explains the game’s theme and objectives. In this way the game designer can provide a lengthy and thorough introduction for the benefit of beginners without annoying novice and expert players. During the introductory sequence the normal user interface is not active. This is apparent because the status bar is not displayed during the introduction. Any mouse click will open the skip introduction dialog box.

play game button - Clicking this button will skip the introduction and begin game play at the beginning of the game. The normal user interface will be enabled and the status bar displayed.

restore game button - Clicking this button will skip the introduction and begin game play from a previous save game. The normal user interface will be enabled and the status bar displayed.

continue introduction - Clicking this button will close the dialog box and continue playing the introductory sequence.

The inventory selection dialog box allows the player to select an inventory item from the collection of item’s currently in the player character’s possession. Items come into the player character’s possession through interaction with the game world during the normal course of the game. An icon view of each item is shown below in the inventory list window.

title - The title contains descriptive text identifying the dialog box and it’s functionality.

top - Clicking this button causes the beginning of the inventory list to be displayed in the window.

previous - Clicking this button allows the player to scroll the inventory list to the previous line.

next - Clicking this button allows the player to scroll the inventory list to the next line.

bottom - Clicking this button causes the end of the inventory list to be displayed in the window.

inventory items - Each inventory item is represented in the inventory list by an icon. Inventory items are objects that can be possessed by characters and used to interact with game elements. For example, a wrench may be used to repair a vehicle necessary for the player character to be transported to another part of the game world.

inventory list - The invent list is displayed in a window in the dialog box. It contains the inventory items that are in the player character’s possession. Items are added to the list when they are acquired by the player character. Items are removed from the lists when they are consumed or expended by the player character.

select - Clicking this button allows the player to select an inventory item from the list. After clicking the select button the player can then click on an inventory item to select it. The selected item is then displayed in side the used button and can be used to interact with the game.

examine - Clicking this button allows the player to examined an inventory item in the list. Normally a message, describing the item and its purpose, is displayed.  

The save game dialog allows the current state of the game to be saved to anamed save slot. This same game can then be restored at a later time and game play resumed as if no interruption had occurred.

title -The title contains descriptive text identifying the dialog box and it’s functionality.

save slot name - This is a text entry field that allows the player to enter a descriptive name for the selected save slot.

save slot list - Clicking on this list selects a save slot where the current game state may be saved. Clicking on the "<new>" element causes a new save slot to be selected; clicking on any other element causes a previously used save slot to be selected.

scroll up - Clicking this button causes the save slot list to scroll up by one line.

scroll down - Clicking this button causes the save slot list to scroll down by one line.

save - Clicking this button will causes the current game state to be saved in the selected slot.

cancel - Clicking this button will cause the dialog box to be closed without performing any operations.

The restore game dialog allows a previously saved game to be restored and game play to resume as if no interruption had occurred. To restore a game the player selects the game to restore from the save slot list and then clicks the restore button. The dialog box closes and game play resumes from the point where the game was previously saved. A definition of each control appearing on the dialog box follows:

title -The title contains descriptive text identifying the dialog box and it’s functionality.

save slot list - Clicking on this list selects a save slot containing the game to be restored.

scroll up - Clicking this button causes the save slot list to scroll up by one line.

scroll down - Clicking this button causes the save slot list to scroll down by one line.

restore - Clicking this button will causes the game saved in the selected save slot to be restored.

cancel - Clicking this button will cause the dialog box to be closed without performing any operations.

The quit game dialog allows the user to terminate game play. When the yes button is clicked the game is terminated. The BlueGui provides the game designer with the option of specifying an end of game scene and message.

A game using the BlueGui can either terminate immediately or display an end of game scene and message before terminating. A definition of each control appearing on the dialog box follows:

title -The title contains descriptive text identifying the dialog box and it’s functionality.

yes button - Clicking the yes button closes the dialog box and terminates game play. If an end scene is specified it will be displayed until a time delay expires or until the player presses any keyboard key.

no button - Clicking the no button closes the dialog box and resumes game play.

The game settings dialog allows the player to adjust various game parameters such as speed and volume. Adjustments are made by using the mouse to drag the sliders to a desired level. Game settings are saved and restored via the game save and restore operations. A definition of each control appearing on the dialog box follows:

title -The title contains descriptive text identifying the dialog box and it’s functionality.

ok button - Clicking on the ok button closes the dialog box and resumes game play.

text speed - The text speed controls how long character speech text is displayed before the conversation continues.

walk speed - The walk speed controls how fast the player character moves from place to place using the "Walk To" functions.

game speed - The AGS game engine normally animates characters and objects at approximately 40 frames per second. This can be modified to be anywhere from 10 to 100 frames per second. The upper limit of 100 frames per second is not achievable on older computers.

speech volume - When a character speaks, in addition to displaying text, an audio clip, containing the speech, can be played. The volume of the audio clip can be adjusted using this slider.

 sound volume - When interacting with the game world, sounds, corresponding to the action occurring on the screen, may be played. This slider adjusts the volume of such sounds.

music volume - Background music can be played when the player character enters a scene. This slider adjusts the volume of the background music.

difficulty - This slider adjusts the difficulty level of the game. Implementation of game difficulty level is left up to the game designer and consequently it’s behavior is game specific.

special - This slider adjusts a game specific or special parameter. The specific use of this parameter is determined by the game designer and should be explained in the game documentation.  

AGS games have an internal debug flag whose state is set by the game designer. This flag disables or enables debugging functions during game play. Normally debugging functions are disabled when game development is complete and are therefore not accessible. When debugging functions are enabled the player may switch them on or off by pressing the Ctrl-T key.

cursor position - Normally the player character’s x-y position is displayed in this location. If the left mouse button is held down then the cursor graphic changes to a pointer and the cursor’s x-y position is displayed instead of the character’s position.

room number - The numeric ID of the current room, or scene, is displayed in this location. A new ID can be entered in this location to change to a new room. The change occurs when the new ID is entered and the enter key is pressed.

inventory number - The numeric ID of the currently selected inventory item is display in this location. Inventory items are selected using the normal user interface.

inventory name - The descriptive name of the currently selected inventory item is display in this location.

global integer index - AGS provides a mechanism for sharing data between rooms, known as global integers. There can be up to 300 global integers, each of which can store an integer or whole number. A numeric ID or index is used to access the value of a global integer.

The debug interface allows a the value of a selected global integer to viewed and modified. A global integer is selected by clicking this location and entering the index of the desired global integer in the text entry box that pops up.

global integer value - The value of the selected global integer is displayed in this location. The value may be modified by clicking on it and entering the new value in the text entry box that pops up.

animation engine - The animation engine is an optional BlueGui module that provides a convenient means of implementing background animations and other operations. The animation engine’s current instruction is displayed in this location. There are also controls that allow the animation engine to be stopped, started, or set to execute a specific instruction. A thorough discussion of the animation engine’s features and uses are beyond the scope of this manual and so not presented here.

debug text - The game designer may display debug text at strategic points in the game program. This helps identify which part of the game program is running when incorrect behavior is observed. Debug text messages are displayed in this location.

The property inspector displays detail information about characters, objects, and other interactive game elements. This includes numeric IDs, descriptive names, and other information that may be available. The properties display, show at right, is activated by right clicking on any interactive game element while debug functions are switched on.

title - The descriptive name of the game element being inspected is displayed in this location.

property list - Various information about the game element being inspected is displayed here. Different information is available for different types of game elements so the format of the property list is dependent upon the type of thing being inspected.

scroll up - Clicking this button will cause the property list to scroll up by one line.

scroll down - Clicking this button will cause the property list to scroll down by one line.

click outside - Any mouse click outside of the property inspector box will cause it to close and normal game play to resume. 

There are a number of debug functions that may be accessed from the keyboard and are described below. If the game has not been compiled with the debug option enabled then these functions will not be available.

Ctrl-A show walkable areas - Pressing this key causes the areas where the player character can walk to be displayed.

Ctrl-D show game information - Pressing this key causes game information to be displayed.

Ctrl-F show fps - Pressing this key causes the actual game speed to be displayed in frames per second.

Ctrl-I give all Inventory - Pressing this key gives all inventory items to the player character. This makes it unnecessary to perform other game interactions to acquire inventory items.

Ctrl-T debug mode - Pressing this key causes the debug interface to be switched off

and on.

Ctrl-V show version - Pressing this key causes the AGS version to be displayed.

Ctrl-X goto new room - Pressing this key allows the player to teleport to a new room.

 The browser interface provides a means of viewing plain files ASCII files from within a game. This makes it convenient to provide help text to the end user or to implement text intensive game elements such as books or computer screens. The browser can take one of three forms as described below. The ASCII file size is limited to about 100 lines of text.

 The text browser displays the contents of one or more plain ASCII files as specified by the game designer. When the text browser is first activated it displays the contents of the first file in the specification. Controls (first, previous, next, and last) allow the player to view other files in the specification.

title - The first line of text in the file is displayed as the title text at the top of the interface window.

text from file - Subsequent lines of text in the file are displaced in this location. If the file contains more lines of text than can be displayed on the screen the scroll buttons can be used to view these additional lines.

scroll up - Pressing this button causes the text to be scrolled up by one line.

scroll down - Pressing this button causes the text to be scrolled down by one line.

first file - Clicking on this button causes the contents of the first file in the game designer’s file specification to be displayed.

previous file - Clicking on this button causes the contents of the previousfile in the game designer’s file specification to be displayed.

next file - Clicking on this button causes the contents of the next file in the game designer’s file specification to be displayed.

last file - Clicking on this button causes the contents of the last file in the game designer’s file specification to be displayed.

close browser - Clicking on this button causes the browser window to be closed and normal game play resumed.

The file browser displays the contents of one or more plain ASCII files as specified by the game designer. When the file browser is first activated it displays the contents of the first file in the specification, as shown below. It also displays a list of files contained in the specification. Clicking on a file in the list causes that file to be displayed.

title - The first line of text in the file is displayed as the title text at the top of the interface window.

text from file - Subsequent lines of text in the file are displaced in this location. If the file contains more lines of text than can be displayed on the screen the scroll buttons can be used to view these additional lines.

scroll up - Pressing this button causes the text to be scrolled up by one line.

scroll down - Pressing this button causes the text to be scrolled down by one line.

file list - The file list contains a list of all files, in the game directory, matching the game designer’s specification. Clicking on a file name in this list causes the contents of that file to be displayed.

close browser - Clicking on this button causes the browser window to be closed and normal game play resumed.

The transparent file browser displays the contents of a plain ASCII files as specified by the game designer. When the file browser is activated, it displays the contents of the specified file on the screen. The Transparent File Browser’s background is transparent so that the text appears on top of the room graphic. If the file contains more lines of text than can be displayed on the screen then the additional text is ignored. The are no user controls for this browser; it can only be controlled by the game program.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

animation 8, 10, 23, 26, 31

list 23

Contents within this site are copyrighted by both the author of essays and/or Jan Strever.
The contents within these pages are solely those of the author and S.C.C.
should not be held responsible.  ©1999-2009
Last revised: November 19, 2009 by Jan Strever -- jstrever@scc.spokane.edu
Personal site:  http://www.js.spokane.wa.us/