G T A C Graphic Text Adventure Creator ©1995 Andrea Gallo This program is provided "as is" without warranty of any kind, either expressed or implied. The entire risk as to the quality and performance of this program is with you. If you have any advises, complaints or bug reports, write phone or fax to: Mr Andrea Gallo 237, Viale Cortina d'Ampezzo 00135 Roma Italy Tel/fax: +39 6 35506014 ----------------------------------------------------------------------------- Contents. 1. Introduction. 2. Set up. 3. Tutorial: a working adventure in few minutes... | Section 3 is not 3.1. Creating a new project. | included in this 3.2. Rooms, actions and conditions. | file. 3.3. Add a new room. | 3.4. Flags and Items. | You will find it 3.5. Save to disc. | in the printed 3.6. Playtest. | manual which goes 3.7. Pictures. | with the registered 3.8. Sound.--------------------------------| version. 4. Syntax. 4.1. Variables and flags. 4.2. System constants. 4.3. Values. 4.4. Actions. 4.5. Conditions. 5. GTAC Windows. 5.1. Text Window. 5.2. Action Window. 5.3. Control Window. 5.4. Action Control Window. 5.5. Variables Window. 5.6. Status Window. 5.7. Items Window. 5.8. Inventory Window. 5.9. Find Text Window. 6. GTAC Menus. 6.1. Project. 6.2. Playtest. ----------------------------------------------------------------------------- 1. Introduction. Adventure games have been played on computers for many years and are one of the most popular of all types of computer games. Usually the player is presented a text description of the place where he is staying at the moment, often complemented by a picture. Then the user has to decide what to do and has to type it in on the computer keyboard. The biggest limit of these parser-based adventures (parser is the program inside the adventure that interprets and tries to understand what has been typed) is that the user must hope to have used the right verb or noun, and not the wrong synonym: if he does not second-guess the game-writer (or whoever wrote the adventure), he will never solve the adventure. GTAC adventures are different. Every action the user can perform is there on the screen, ready to be selected with just a mouse click! Of course some actions will not be always available, perhaps the user will need to be carrying some objects with him. For example a locked door cannot be opened if the user does not have the right key. Thus the "Unlock door" action will be displayed only when the user can really unlock it. Moreover, GTAC adventures multi-task in the RISC OS Desktop. 2. Set up. Make a backup copy of your GTAC disc and store the original one in a safe place. GTAC can be installed on hard disc: in your drive root directory create a new directory name "GTAC" - or whatever you like - open it by double-clicking on it with the mouse and then drag the !GTAC filer icon and every other file and directory inside it from your GTAC original disc. GTAC is not copy protected, so please copy for your back-up purposes only. Do not distribute copies to your friends: this is illegal. Next section is a tutorial and will help you build a small adventure in few minutes. Following sections will then describe the GTAC programming language (section 4) and its main windows (section 5) and menus (section 6). 3. Tutorial: a working adventure in few minutes... Section 3 is not included in this file. You will find it in the printed User manual which goes with the registered version. Please read the !Help file for details on registering. To start a new project read section 6. To reload and edit a project, drag its filer icon on the GTAC icon bar icon (so you must have started GTAC). 4. Syntax. In this section the GTAC sublanguage will be studied in details. Full syntax will be provided in some theoretical manner in order to allow for a later reference. 4.1. Variables and flags. Variables and flags can be used in GTAC in order to record events during the game. A variable is of type integer and can assume any positive or negative value in the 32 bit range (i.e. -7fffffff ÷ 7fffffff). Every variable is initialised to 0 at the beginning of every game and after every restart. The first 10 variables (i.e. var 0 ÷ var 9) can be linked to a string, describing its use. These are displayed in the Status Window (see section 5). The number of gold pieces or remaining provisions can be stored in a variable, for example. A flag can be either True or False. Every flag is initialised to False at the beginning of every game and after every restart. For example, a door can be locked (True) or unlocked (False). A key is being either carried (True) or not carried (False). Every flag can be linked to a description string, thus constituting an item. This string can be displayed in the Inventory Window if its flag is True. The status of a door (locked or unlocked) will not be displayed with other carried items, while a key or a sword will be. Every aspect concerning flags can be edited in the Items Window (see section 5). 4.2. System constants. Listed below are the limits to the maximum number of system resources allowed. max_room 999 (locations - 1, i.e. 0 ÷ 999) max_flag 999 (flags - 1, i.e. 0 ÷ 999) max_var 999 (variables - 1, i.e. 0 ÷ 999) max_pic 999 (pictures - 1, i.e. 0 ÷ 999) max_invent 20 (items in Inventory Window) max_status 9 (variables in Status Window - 1, i.e. 0 ÷ 9) max_sample 76 (samples - 1, i.e. 0 ÷ 76) max_name 10 (enemy's name length) rand_max 7fffffffH (random number) 4.3. Values. Unsigned integer: One or more digit, without any sign preceding them. E.g.: 0 123 4003 Integer: A sign '+', '-' or nothing, followed by an unsigned integer. E.g.: +5 5 -5 Value: Integer or v, with i = 0 ÷ max_var (returns the value of variable ) r, with i = 1 ÷ rand_max (returns a random value between 0 and rand_max) E.g.: 6 -7 v3 r12 String: One or more characters in the range 'A' to 'Z' or 'a' to 'z'. No punctuation mark, spaces or other symbols are allowed. E.g.: Goblin 4.4. Actions. Actions should be typed without leading spaces, in lower case. The Test Luck and Fight commands, examined below, assume that you have declared three Status Variables as: var. 0: Skill var. 1: Stamina var. 2: Luck Your Skill score reflects your swordsmanship and general fighting expertise; the higher the better. Your Stamina score reflects your general constitution, your will to survive, your determination and overall fitness; the higher the longer you will be able to survive. Your Luck score indicates how naturally lucky a person you are. Luck and magic are facts of life in the fantasy kingdom you are about to describe/explore. GO TO room: r go to room , with i = 0 ÷ max_room E.g.: r5 RESET flag: - set flag to 0, with i = 0 ÷ max_flag E.g.: -2 SET flag: + set flag to 1, with i = 0 ÷ max_flag E.g.: +2 TOGGLE flag: ! toggle status of flag , i.e.: 0 -> 1 and 1 -> 0, with i = 0 ÷ max_flag E.g.: !2 SET variable: v, set variable to value , with i = 0 ÷ max_var E.g.: v4,v2 or v4,-2 or v4,r5 ADD variable: a, add variable and value and store result in variable , with i = 0 ÷ max_var E.g.: a4,v2 or a4,-2 or a4,r5 SUBTRACT variable: s, subtract variable and value and store result in variable , with i = 0 ÷ max_var E.g.: s4,v2 or s4,-2 or s4,r5 INITIALISE variable: i, initialise variable to + random integer between 0 and , with i1 = 0 ÷ max_var, i2 = 0 ÷ rand_max i.e.: = 6 means roll one die and add 6 = 12 means roll two dice and add 12 If lies in the 0÷max_status-1 range, the initialised value will be automatically stored into variable max_status+ too, in order to allow for a later "restore to initial value". Thus, variables max_status ÷ 2*max_status-1 are used as back-up for variables 0÷max_status-1. Variables in the 2*max_status÷max_var-1 range are completely free to be used as you prefer. This command is equivalent to: v,ra,v,v E.g.: i4,6 will initialise variable 4 with a number between 7 and 12 and will copy this number in variable 14, as well, with max_status being 10. i22,6 will perform just as i2,6 but will not copy any value in variable 32. TEST luck: t, test your luck and continue from room or , depending on whether you have been lucky or not. Two dice are rolled and their total score is compared against your luck, stored in variable 2. If your luck value is higher then or equal to this number, you have been lucky. At every luck test your luck value is decreased by 1 point. FIGHT enemy: f,,, , fight against enemy called , whose skill is and whose stamina is . If you win, go to room , else restart game. Your skill is assumed to be stored in variable 0 and your stamina in variable 1. The enemy's skill score is turned in an attack strength, with a random number added to it. The same is done for your attack strength. If yours is higher than that of your enemy, you have wounded it. If its value is higher than yours, you have been wounded. The one who has been wounded gets its stamina score subtracted by 2 points. If both attack strengths are the same, you have avoided each other's blows. At the end of every round you will be offered the chance to test your luck and to use it to reduce your damage by restoring 1 stamina point or inflict a severe wound to your enemy by subtracting extra 2 stamina points. If you are unlucky, however, your damage will be more serious, subtracting extra 1 stamina point, or your enemy's wound will be a mere graze, restoring 1 stamina point. Another round with the same rules is played until yours or your enemy's stamina has been reduced to zero (death). If you die, the game restarts from room . If is 0 the "You have been defeated by ..., your adventure ends here" message will be automatically displayed. If you win, the game continues from room . E.g.: fRat,10,4,10,5 BEEP: b is the standard RISC OS bell-like sound. PLAY SAMPLE: p plays sample with sample = 0 ÷ max_sample. Sample must have been loaded and fine tuned, otherwise no sound is generated (see section 5). E.g.: p0 4.5. Conditions. Conditions should be typed without leading spaces, in lower case. Conditions can be nested recursively. True: 1 Condition is always verified. False: 0 Condition is never verified. Although useless, it is kept for compatibility with other languages. AND: &(cond1,cond2) Condition is True if both subconditions cond1 and cond2 are True. OR: |(cond1,cond2) Condition is True if either cond1 or cond2 is True. NOT: !(cond) Condition is True if subcondition cond is False, and viceversa. FLAG status: ? Condition is True if flag is True and False if flag is False, with i = 0 ÷ max_flag. IDENTITY: =(,) Condition is True if value v1 = value v2, otherwise False. GREATER THAN: >(,) Condition is True if value v1 > value v2, otherwise False. SMALLER THAN: <(,) Condition is True if value v1 < value v2, otherwise False. Examples. !(?0) Condition is True if flag 0 is False. &(?1,!(?2)) Condition is True if flag 1 is True and flag 2 is False. |(?2,!(&(?3,?4))) Condition is True if flag 2 is True or either flag 3 or 4 is False. In fact if both flag 3 and flag 4 are True, &( ... , ... ) will be True and !(...) will give False! 5. GTAC Windows. Several windows are used to develop and debug GTAC adventures. Every one will be analysed in details. 5.1. Text Window. The Text Window contains the text description of each room. Click the Select button on the mouse to position the caret. Then use: left/right arrow keys to move to the previous/next character; Shift+left/right arrow keys to move to the previous/next word; Control+left/right arrow keys to move to the beginning/end of line; up/down arrow keys to move to the previous/next line; Control+up/down arrow keys to move to the first/last line; Return to insert a new line at cursor position, eventually splitting current line, and to move the others down; Shift+Return to join current and next lines; Control+Return to delete current line and to move the following ones up; Control+U to clear a line, Copy to delete next character, Shift+Copy to delete current word. 5.2. Action Window. The Action Window displays all the available options in a RISC OS menu manner. It is used during game play to perform actions. Its content can be edited through the Action Control Window, described later. 5.3. Control Window. Everything starts in the Control Window. You can edit almost every aspect of your adventure using the tools presented in this window. Current room. The first line displays the number of the room that you are currently editing. To select another room you can either use the two arrow icon buttons or click with the mouse the writable icon and type directly the desired room number, then press Return. Total defined rooms. The second line displays the total number of rooms that you have already defined. Graphics. The third line controls the graphical aspect of your adventure. Every room can have a picture complementing the text description. This icon is used to select which picture goes with the current room. Every picture is numbered from 0 to max_pic, so that different rooms can share the same picture. If "-1" is displayed, it means that the current room has no picture. Every picture is stored in the form of a Draw file, eventually squashed, in a directory inside the project directory, with a fixed three-digit filename: i.e. "000" is the filename for picture 0, "010" for picture 10, and so on. Pictures 0 ÷ 76 will be in directory "pic0", 77 ÷ 153 in "pic1" and so on. Draw files have been chosen because of their smaller memory occupation. Note that this choice does not prevent you from displaying sprites as well. In fact a Draw file can also contain a sprite. However you should ensure that the sprite has a palette saved with it, in order to be correctly displayed. For more details about Draw and Sprite files please refer to the Acorn Application Guide, supplied with your computer. Draw files can of course contain some text. If you are not using the System font, either provide the !Font directory with the font you are using - if you have the rights to do it - or convert it to path from the !Draw application. Please refer to your RISC OS Application Guide. Acorn Squash compression module is supported. Files in pictures directories can be stored in squashed form. These will be kept compressed in memory and decompressed on the fly, i.e. one at a time and only when needed, thus reducing memory occupation to the bare minimum. As this operation can introduce some delay, especially on ARM2 machines, files saved in plain Draw format (i.e. not squashed) will be kept in memory unsquashed and no decompression will be carried on, without slowing down the computer. In this way you can choose whether to use Squash or not by saving pictures in Squash or Draw format. For more information about using Acorn !Squash application to squash files, please refer to your Application Guide. Next to the writable field there is the Graphics icon button. If you press it you will open the Picture Control Window, which has been examined in details in section 3.7. Add/Copy room. The Add/Copy room icon button is used to define a new room. Click with either Select or Adjust on it. The former will give you a new blank room, the latter will ask you the number of a room to be used as a basis. In both cases the number of total defined rooms will increase by one and the new room will be selected as the current one. Delete room. The Delete room icon button is used to delete a room which you have previously defined. Note that room number 1 must always be present, so you are not allowed to delete it. Moreover, room 0 does not exist, but it is used as a Restart: when you go to room 0, variables and flags will be reinitialised and the game will continue from room 1. It is equivalent to select Restart from the main menu (see section 6). During the adventure if your adventurer gets killed, you should provide a "Restart" option, with action "r0" and condition "1". User will select Restart from the main menu when he is in a blind alley or has done an irreparable action. Find text from start. Clicking on the Find text from start icon button you will be asked for which text to search from room 1. The room containing the desired text will be then displayed. Find text from current/Next match. Click Select to be asked for which text to search from current room onwards. Click Adjust to find the next match of the last searched text. Actions. Clicking on the Actions icon opens the Action Control Window. Variables. Clicking Select on the Variables icon will open the Variables Window. Clicking Adjust will open the Status Window. Items. Clicking Select on the Items icon will open the Items Window. Clicking Adjust will open the Inventory Window. Update. Clicking on the Update room icon, GTAC will store every change that has been carried out to the current room. Before updating, anyway, GTAC performs a syntax check of actions and conditions. If any error is present, the caret will be positioned within the offending icon, near the error. Moreover, the standard RISC OS error dialogue box will inform about error type. Note that a room update is carried out every time you select a new room from the Control Window, both by clicking on the arrow icons and by typing a room number directly, and every time you add a room. Room update is not performed when selecting an action in the Action Window, i.e. while playtesting the game. A room update to every defined room is also carried out before saving to disc. Samples. Clicking the Samples icon button will open the Samples Window, which has been examined in details in section 3.8. Disc. Click the Disc icon button to save your adventure to disc. An adventure saved in this way can be edited again in GTAC at any time by dragging its filer icon onto the !GTAC icon bar icon. If you double-click onto your adventure filer icon, it will run and display a message saying it is not a closed adventure. In fact, an adventure can be permanently closed by selecting the Close current option from the Project submenu. Once closed, the adventure cannot be edited anymore in GTAC and cannot be examined for solution as well! 5.4. Action Control Window. This window is divided into 10 sections, each one corresponding to one option (see section 3). Each option has three writable fields: text, action and condition. The first one is the text string that will appear in the Action Window while playing the game. The second one contains the commands to be executed when its text field is selected from the user. These commands are those listed in section 4. The third field contains the condition which should be verified in order to display the relative text in the Action Window. If this condition is True, during game play, the relative option is said to be available. If it is False, no text is displayed in the Action Window and the corresponding option cannot be selected. Condition syntax has been analysed in section 4. An interactive syntax checking is always carried out as soon as you press Return. The caret will move to the following field if syntax is right. If an action or a condition has a wrong number of parameters or a separator is missing, an error will be reported in a standard RISC OS message dialogue box. If an option has an empty text field, its action and condition fields will be deleted when updating current room. Thus, if you want to delete a whole option and make the following ones move up, just delete its text field and click on the Update room icon in the Control Window. If you want to insert an option among others, position the caret in any field of the first option which should be moved down and press Insert on the keyboard. A blank option will be inserted. Use cursor keys to move up or down by one field, control+cursor keys to move to the text field of the first or the last defined option, page up or down to move to the corresponding field of the previous or next option. 5.5. Variables Window. This window has been specifically designed for playtest and debugging of your adventures. It is made of two main sections: flags and variables. The former contains fifty radio buttons, each one being associated to a flag, whose status on/off is represented by the button being pressed/depressed. Changing its value is a matter of just clicking on the relative button with the mouse. Consequent changes will be carriet out immediately, i.e. an item will be dropped or taken, a door shut or opened, etcetera. Clicking on the arrow icons will cycle through all the flags available. The latter, the variables area, contains ten writable fields, each one being associated to a variable. Its value can be read and edited in the usual way: click in the desired field to position the caret, type in a new value and press Return. The variable will be updated and consequent changes will be carriet out immediately. Clicking on the arrow icons will cycle through all the available variables. 5.6. Status Window. The first ten variables (var 0 ÷ var 9) can be displayed during game play in a special window together with a text description. For example you could want the user to know how many gold pieces he has collected so far, or which level is his stamina. If the number of gold pieces is stored in variable 3, open the Status Window and write "Gold pieces" in field number 3. Its value can be read on the right. To change this value you have to use the Variables Window. If you need to display less than ten variables, let's say 5, leave fields 5 to 9 blank. During game play, outside !GTAC, these fields will not be displayed. If on the contrary you display variables 0, 2, 3, 4 and 9, the whole window will be displayed, even though variables 1 and 5 ÷ 8 are not used. 5.7. Items Window. Every flag can be linked to a text description. This can be made appear in the Inventory Window, by setting the Appear in Inventory flag. In this case it is considered to be an item, which can be collected and carried around. On the contrary, if it is not allowed to appear in the Inventory Window, if you type a description anyway, it will be for your record only. 5.8. Inventory Window. This window will display the text description of every item being carried, i.e. whose flag is True. When this value changes to False (i.e. it is not being carried anymore), its name will be removed from the list. "Nothing" will be displayed if no item is being carried. 5.9. Find Text Window. Open this window by clicking either the Find text from start or Find text from current icon button. Type in the string to be searched for and then either press Return or click the Search icon. You will see rooms being examined for the required string. The one containing your text will be displayed or, if text cannot be found, you will be returned to the last room being edited. 6. GTAC Menus. Clicking the mouse Menu button in any !GTAC window will open a menu. This menu has four fields: Info, Project, Playtest and Quit. The Info option will give information about the current version of GTAC, its Author and Publisher. Quit will kill the application. If you are editing an adventure, you will be offered the chance to save it to disc before leaving. 6.1. Project. Sliding the mouse pointer on the right of the Project field will open a submenu with the following options: Info, New project, Save current, Close current and Export data. Sliding the mouse pointer on the right of the Info option will open the About this Project dialogue box. Here you can find information about the current project and its author: you can edit the latter by clicking with Select on the corresponding icon to position the caret. Then just type your name and press Return. The New project option is used to start writing a new adventure from scratch. Sliding the mouse pointer on the right of the New project field will open a standard RISC OS save box. Type in the name of your adventure, beginning with "!", and drag the filer icon in your favourite directory viewer. An empty adventure structure will be created and several windows will open: you are ready to start. The Save current option is used to store permanently every change you have carried out to your adventure. No save box will open as GTAC already knows where your adventure files are kept. It is exactly the same option offered by the Disc icon button in the Control Window. The Close current option is the most important one: it will permanently prevent your adventure from being loaded into !GTAC and edited anymore. No one will therefore be allowed to change it or examine it for solution. As this is an irreparable action, you will be asked for confirmation. Anyway, you would better keep an open copy of your project, just in case you discover a bug or want to change something. You have been advised! Note that a closed adventure is a stand alone application and therefore can be run by double-clicking on its filer icon. Selecting the Export data option will open the Export Data Window. Here you can choose which parts of your project you want to export as pure text. You can choose to export rooms, flags and status variable declarations and in which range. If you select Text only you will be able to import all room descriptions in a text editor and spell-check them. Once you have set everything up, just click on the Export icon button: you will be presented a standard RISC OS save box. Drag the text filer icon either in a directory viewer to save it or onto the Printers Driver application icon bar icon to print it or into an editor. 6.2. Playtest. Sliding the mouse pointer on the right side of the Playtest field will open a sub menu with the following options: Save status, Status, Inventory and Restart. This sub menu contains the same options present in the finished stand alone game. The Save status option is used during a game to save the current game situation in order to restore it later. Slide the mouse pointer on the right side of the Save status field and drag the filer icon in an appropriate directory viewer. While playing, if you want to restore the saved game, drag its Data filer icon on the icon bar icon to load it. The Status option will open the Status Window, just like clicking Adjust on the Variables icon in the Control Window. The Inventory option will open the Inventory Window, just like clicking Adjust on the Edit items icon in the Control Window. The Restart option will reinitialise all flags and variables and will restart the game from room 1. HAPPY ADVENTURING