AGI Template Game ----------------- Version 1.11 By Peter Kelly 15 February 1998 The template game is an AGI version 2 game which you can use to build other games from. It contains one room, and all the basic functionality you would expect in an AGI game such as menus, key assignments, loading/saving and a debug mode. Using this template as a starting point for other games will be easier than modifying an existing game because it does not contain lots of game-specific code. Before attempting to program an AGI game, I suggest you have a look at the AGI Specs documentation (http://www.ozemail.com.au/~ptrkelly/agi/specs). This will tell you a lot about how LOGIC programming is done, and contains an excellent command reference which you will find very handy. Also, a good way to learn the language is by looking at the logics of existing games (including this one!). Compiling ========= You will need a compiler to compile the logics in this game. There are three compilers available at the time of writing: MATS, AGIC and AGI Studio. The syntax used by this version of the template game is now the "official" syntax that all logic decoders and compilers support, so this game should compile with any compiler. (Note: At the time of writing, MATS and AGIC do not fully support the new syntax. They should eventually support it though.) Running the game ================ This package is released without an interpreter. The reason for this is because the interpreter is written by Sierra-online and it could possibly be a violation of copyright laws distributing their interpreter with the game. Because of this, you will need to use an interpreter from another game. The only DOS versions of the interpreter that should be used is 2.915, 2.917 or 2.936. Others will most likely not work. If you do not have one of the interpreters mentioned above, you can obtain one from one of the demo packages that are available (there are some on my website). Make sure you get the right interpreter version. To use the game with an existing interpreter, just copy the files distributed with the game into the same directory as the interpreter and run the loader program (usually called SIERRA.COM). Alternatively, you can copy all the *.OVL files, the AGI file and the loader into the directory containing the data files. Eventually, other interpreters will probably be written capable of running this and other AGI games. Distributing the game ===================== This template game is freely distributable. You can modify it as much as you want (that's what it's for!) and distribute any games you make from it as you like. However, if you are distributing it as a template (it's current form) rather than a game, I request you leave all the files intact, including this readme. Also, if you are distributing games made from this I suggest that you do not distribute Sierra's interpreter with it. As mentioned above, it may be a violation of copyright laws. I am not sure about the status of the interpreter, but it's probably safer not to distribute it as part of your game. It is available in the demo package anyway, which is freely distributable. As far as I can see, there is nothing wrong with creating your own data files which work with the interpreter, as with the many other game editors that are available. A note about game IDs ===================== The DOS versions of the interpreter include a "Game ID", which is a short string identifying the game they are supposed to run. Somewhere in the logics the game is supposed to set the game ID. When it does this, the interpreter compares this with it's own game ID. If they are different, the interpreter quits instantly. This was probably to stop people from running games with the wrong version interpreter, which could mean the game wouldn't run properly. However, I have discovered that there is a very easy way around this, and that is to simply not set the game ID at all. The game will run fine, and the saved games will be called "sg.1", "sg.2" instead of having the game ID in front of the name, e.g. "sqsg.1", "sqsg.2". This template game does not set the game ID, and you should also not do this, so that your game will run with any interpreter (provided it is the right version). Operation of this game ====================== Looking at all the code that is required for just this small template game can be a bit daunting at first, so it helps to understand what it is all doing. I will attempt to explain this a bit. Read the following section with the logic 0 alongside so you can understand what each piece of code is doing. You should already know a bit about variables, flags, logics etc. When the interpreter first starts, it loads logic 0 into memory and executes it. The interpreter operates in cycles, and on each cycle it runs logic 0 and updates any screen objects that are visible. Logic 0 calls other logics during it's execution, most importantly the logic of the current room, whos number is stored in var 0. First off, we check the value of error_code. If this is greater than 0, an error has occured and the error handling logic (98) is called, which displays an error message and quits the game. Next we check the value of v0 (the current room number). If this is 0, the game has just started so logic 91 is called to do some initialization. If game_restarted is set, then we are ready to go straight into the game. If so, we go to the first room which is 2. Otherwise, we set up the menus and go to the intro/opening screen (room 1). Then we check to see if the flag new_room is set. If so, this is the first cycle in a new room and there are some things that need to be set up. Since all resources other than logic 0 are unloaded when the current room changes, we need to load the resources that we need again. First we load logic 90, which contains various bits of game-specific code. Then we turn off debug, and set up ego. Then we check the value of death_type. If this is greater than 0, then the player is dead so we disable some menu items and then call logic 94 (the death handler). Logic 94 looks after anything that happens after the player is dead. Also, if the player is dead, we skip to the end of the logic as we don't want them doing any other stuff like picking up things or talking to other characters. Next we check for menu events. If the player has pressed Esc, then we activate the menu with the menu.input() command. We check for and respond to any menu commands like saving or restoring games or changing speed. We also check for commands like save, restore etc. These are only checked for if the flag disable_game_functions is not set (so if you want to stop the player from doing these things, for example during intros/cutscenes, you can set this flag). After that we have to check the animation of ego. If ego has stopped, then we must unanimate him/her. To determine this we compare ego's old position with their current position. There are also two flags, always_animate_ego and never_animate_ego which can force the animation on or off. If the player wants to turn the clock on or off, we check for this and act accordingly. If the clock is on, we update it. If they have restored a game, we must now clear the bottom lines of the screen, turn debug mode off and disable the file separator menu item again. The next thing that is done is one of the most important things that logic 0 does. The logic for the current room number is called. Because logic 0 is executed on every cycle, and the logic for the current room number is called from logic 0 every time, the current room's logic also loops around like logic 0. Then, if debug mode is active, we then call the debug logic (99). Also called is logic 90 which performs any game-specific functions. After that we check to see if the player has typed in an unknown word. If so, we tell them we don't understand the word they've typed. You might like to put some funny responses in here. Then, if the player's input has not yet been parsed, we tell them that we don't understand what they've typed and perhaps suggest that they try rephrasing it. This is the end of logic 0. The other logics are fairly self explanatory, and are fairly easy to understand once you know how logic 0 works. Resources used by this game =========================== Picture 1 - intro text background (black) Picture 2 - first room background (white) View 0 - ego View 1 - dead ego View 220 - test object Logic 0 - main logic Logic 1 - intro screen Logic 2 - first room Logic 90 - game specific functions Logic 91 - initialization Logic 92 - help Logic 93 - debug mode help Logic 94 - player death handler Logic 95 - trace info (this script contains a list of commands used in tracing) Logic 98 - error handler Logic 99 - debug script Variables, flags and controllers used by this game ================================================== Variables: 30 - new_ego_x 31 - new_ego_y 32 - old_ego_x 33 - old_ego_y 34 - old_ego_dir 35 - death_type 36 - thankyou_timer (used by death handler) 37 - old_clock_seconds Flags: 30 - never_animate_ego 31 - always_animate_ego 32 - debug_active 33 - disable_game_functions 34 - clock_active 35 - coords_shown Controllers: 1 menu item - quit game 2 menu item - help 3 menu item - save game 4 see object (key) 5 menu item - restore game 7 menu item - restart game 9 echo line 10 menu item - inventory 12 menu item - clock on/off 14 enter debug mode 15 menu item - configure joystick 16 menu item - sound on/off 17 clear input line 18 menu item - pause game 19 activate menu 20 menu item - separator on file menu 21 menu item - about 22 menu item - see object 23 menu item - fast speed 24 menu item - normal speed 25 menu item - slow speed 26 decrease volume 27 increase volume 28 menu item - fastest speed Changes since v1.1 ================== This is just a minor bug fix. I found out that when the player restarts the game, the separator on the file menu is enabled so that the player can select it. This was fixed by adding the line "disable.item(menu_fileseparator);" near the top of logic 0 (you'll see it there after "if (game_restarted) {"). Changes since v1.0 ================== There have been number of changes since the last version, mainly due to the new syntax and the ability to use the #include command (all variable names are now defined in defines.txt). There are a few other things, however: I have removed all computer-specific code from the game - things such as different key assignments for different machines, etc. I figure all new games will either be run under Sierra's DOS interpreter or a new interpreter written for unix, mac, windows etc. which will act like the DOS interpreter and map the appropriate keys across. However, I have left support in for sound volume control as this may be supported by new interpreters. Also removed from the game is any reference to "Template game" or "by Peter Kelly". This is because it is supposed to be just that - a template game, and you want to be able to start off afresh without having to remove anything that's already there. However, I do suggest you remove the part when the player dies when they type "die" (this can be found in logic 90). This code is in there to demonstrate how to kill the player, and is not meant to be part of an actual game. Also, at some point early in the development of your game you will want to change the game_version_message and the game_about_message to something suited to your game. These can be found at the bottom of defines.txt (you will need to recompile logic 0 after changing these). The flags debug_active, clock_active, never_animate_ego, always_animate_ego and disable_game_functions have been changed from f22, f24, f20, f21, f33 to f32, f34, f30, f31, f33 respectively. This was to avoid possible conflicts with "reserved" flags (the highest one of these known so far is 15, but they may go higher). Logic 0 (main logic): -Added clock on/off to special menu and removed "change graphics mode" -Fixed errors where || was missing -Changed if (v25 = 1) to if (v25 == 1) in place where test object is shown -added clear.lines(24,24,0); after reset(debug_active); to clear the line which shows ego's coordinates when in debug mode. Logic 90 (game specific code): -Added a test at the start to see if unknown_word_no (v9) was equal to 0. When this test was missing and the player typed in "look ", where was not in the words.tok file, they would get two error messages ("What? Where?" and "I don't understand "). This was also the case with "get " and "use " and any other generic responses that had been added. Logic 91 (initialization): -Added key assignment for clock on/off (F6) -Fixed assignment for + and - keys (for increasing/decreasing volume) which were the wrong way round (not that it matters for Sierra's DOS interpreter, but it might for new interpreters with sound card support). -sound_volume (v23) is now set to 15 (the highest allowable value) on startup. Previously this was set to 0. Logic 92 (help screen): -Modified help screen a bit Logic 93 (debug help screen): -Condensed a couple of the descriptions in the debug help screen and added command to toggle display of ego's coordinates Logic 94 (death handler): -Added test for player saying "inventory" as well as testing for the menu controller -Label1 removed and goto replaced with else Logic 99 (debug mode): -Added code to show ego's coordinates on screen when in debug mode I apologize about all these changes to those who have already started writing games based on version 1.0 of the template game. I suggest these people take what code they have written so far and move it over to v1.1 of the template game, as this contains proper names for all main variables used and therefore is a bit easier to program with (and also because it is in the new syntax). I do not expect the template game to change again (except perhaps a small bug fix or two which does not require much modification). More information ================ For more information on AGI, visit my website: http://www.ozemail.com.au/~ptrkelly/agi AGI Specs, a collection of documentation on all aspects of the interpreter, is available at http://www.ozemail.com.au/~ptrkelly/agi/specs You can contact me at ptrkelly@ozemail.com.au