1 Contents ============= 1 Contents 2 Introduction 2.1 Copyright Information 2.2 Credits 2.3 About the Manual 2.4 Release Info 2.5 Notation Conventions 3 (Finally:) The REAL Introduction 3.1 So, What Is GRAAL? 3.2 Other Tools of the Trade 3.3 The Things That Make a GRAAL 3.4 GRAAL Script Files 3.5 The graal.main Script 3.6 The .room Scripts 3.7 The .section Files 3.8 The .scene Scripts 3.9 The .ptrn Scripts 3.10 Running an Adventure 3.11 Loading, Saving and Quitting 4 Starting on an Adventure 4.1 Starting on the graal.main File 4.2 The Hero - What a Character! 4.3 Basics about Images and Bobs 4.4 The Images in the graal.main File 5 "A Room! A Room! A Kingdom for a Room!" 6 The Object Matter 7 Section Objects and BOBs 8 Camera! Action! Lights! 8.1 ACTION: statements 9 Using Exits 10 The DACT: Statements 11 Flags and String Variables 11.1 Flags 11.2 String Variables 12 Having a Chat 13 Multiple Characters and Inventories 13.1 Multiple Character Graphics 13.2 Character Objects 13.3 Switching Characters 13.4 Inventory Switching 13.5 Identifying Characters and/or Inventories 13.6 Characters Following Characters Around... 13.7 Helpful Conditions 13.8 Things to Consider 13.9 Space-saving Tip 14 Character and Graphics Design 14.1 Size 14.2 Colour 14.3 Pointer Shapes and Colours 14.4 Designing Animations 14.5 Complex animation patterns 14.6 Flipped images 14.7 All About 3D and Hotspots 14.8 Scaling the Characters 15 Cutscenes 15.1 Hop, Skip and Jump 15.2 No Breaks! 15.3 Nesting 16 Timer Events 17 Special Techniques or "How The Heck Did He Do That?" 17.1 The Load / Save Room. 17.2 Going into the Alley 17.3 Speaking In a Foreign Tongue 17.4 An Automated Room 17.5 The Art of Avoiding a Seagull 17.6 A Spitting Image 17.7 A Map Room 18 The On-line Monitor 19 Macros 19.1 Starting a Macro Recording 19.2 Saving a Macro 19.3 Playing a Macro 19.4 Restrictions to Macro Playback 20 "Productifying" Your Adventures 20.1 The Basics 20.2 The diskinfo.graal File 20.3 GREP 20.4 GPRO 20.5 GDC 21 The Editor 21.1 Introduction 21.2 System Requirements 21.3 Known Bugs & Irritating Facts 21.4 Creating a New Script 21.5 Working with the Editor 21.6 Creating a Report 21.7 The Parameter Editor 21.8 Icon Tooltypes 21.9 Editor Keyboard Shortcuts 22 Hints and Tips 22.1 Flags 22.2 Diverse 23 Questions and Answers 2 Introduction ================= 2.1 Copyright Information -------------------------- GRAAL 2 is Shareware. If you like it and use it, register and make me happy! All rights to the GRAAL system remains with Performance Software and is copyright © 1997 Per Thulin. Users of GRAAL may use the system freely to distribute their own graphic adventures, but are completely forbidden to use any of the supplied example material - puzzles, characters, animations, or scenes - in their own work. Quite simply, all material used in your own GRAAL adventures must be your own! The shareware version of GRAAL is not crippled in any way, but it is not quite adapted for "professional" use, which is explained later in this manual. See the file Registration.form for details on how to register. 2.2 Credits ------------ GRAAL is coded in Amos Professional. You know it makes sense... :) Also, let's not forget that Black Legend Craft 1 and AMCAF extensions. They made things that much better! The GRAAL Editor is coded in Blitz 2 Basic. You know it makes even more sense... ;) 2.3 About the Manual --------------------- This manual contains an awful lot of text. Don't be discouraged - that is simply because each little GRAAL statement carries an awful lot of power (and because I'm such a blabbermouth), and some sophisticated initial definitions automate most of the gameplay! Before you get totally discouraged, print out the following files from the example disk(s): graal.main 1.section 1.room If you look at these files, and disregard the abundance of comment lines starting with /*, you will quickly realise how precious little GRAAL code is actually needed for the basics of an adventure, and be able to read on with a lighter heart. Also remember that there is an editor included making your GRAAL-coding life a lot easier - you don't have to enter that many tricky parts manually, the editor can help you. The GRAAL documentation is divided into three main parts: 1. The latest .readme file - essential to all who wants to read about the news in the latest version of the system. 2. This manual. 3. An AmigaGuide on-line reference (graal.guide), the definitive authority on all GRAAL statements and commands. If you want to play the provided "Olaf" demo AND build your own Graphic Adventure, I strongly suggest you play the game first! Because "Olaf" is used as an example throughout the tutorial, some of the secrets of the demo is given away here. This is also a good way of deciding whether this kind of stuff is what you want to spend the rest of your life doing :-) 2.4 Release Info ----------------- GRAAL 2.2 brings you the following features: * A graphic adventure point'n'click interface along the lines of, among others, the Indy games and Monkey Island (Trademarks of LucasArts Ltd.). * Automation of most of the controllable characters' walking, talking, and general fiddling around. * 32- or 64-colour (EHB) lowres, automatically scrolling background screens, 320 to 640 pixels wide. * 16-colour, hires, fully configurable command area, 640 pixels wide. * Any number of player commands. * Features to handle "USE", "GIVE TO" and "GO TO" commands. * Room and section data swapped in and out of memory at runtime to minimise the growth of permanent in-memory data as the adventure grows. This gives you a virtually unlimited number of locations (rooms), objects, images, dialogues, etc. * Also automatically detects extra memory and uses this as cache memory to avoid unnecessary disk access. * Animated objects and characters. * Pixel-perfect detection of objects. * Side-view "simulated 3D" scenes with foreground, "middle", and background objects. * Dynamic depth-scaling of characters. * A rather intelligent and easy-to-use dialogue system for those totally silly discussions with sidekick characters we all have come love so much. * An equally intelligent and smart but perhaps a little more difficult-to-grasp floor and path definition system - for defining legal movement paths and automatic negotiation of obstacles. * Cut-scenes with or without indicators. Nested cut-scenes are possible. * Timer events. * Functions for in-game clocks and dates. * Built-in requesters for save/load and quit functions - or disable them and design your own save/load and quit screens. * Multiple character control. * Multiple inventories. * Soundtracker style music modules for background music. * IFF and raw samples for sound effects. * Run-time error checking (to a degree). * GRAAL automatically detects if a GRAAL adventure is run from diskette, CD-ROM, or hard disk, and adjusts disk swapping and save/load routines accordingly. * All tools included except an art/animation package and (optional) sound sampler equipment. * Diskette layout system for automatic copying and labelling of distribution master diskettes. * Dynamic on-line monitor and debugger for script testing, on- the-fly temporary corrections, and examination of the game status. * Single-step trace mode for debugging. The developer's registered version also gives you: * Optimization and encryption of distribution files. The process also locks all development functions (the on-line monitor, break keys, etc.) so that they cannot be used by the player. * Extra graphics files offering various "requester looks". It does NOT give you: * AGA (but on the other hand, a much broader customer base for your games. Let's be kind to those ECS users out there! :) 2.5 Notation Conventions ------------------------- In this text, < > denotes button gadgets and [ ] keyboard keys. Furthermore, I have tried to print names of files and sections of scripts in a special font: file.name Of course, those of you who only have the ascii manual will not benefit from this. Register and order the manual! :) 3 (Finally:) The REAL Introduction ===================================== Welcome to GRAAL. Maybe thy quest is over! ...or maybe it has just begun. Because, although GRAAL is a powerful tool, designing a graphic adventure still needs an awful lot of hard work from your side - all GRAAL does is take most of the actual coding work out of the job and lets you get on with designing the story, logic, backgrounds, objects, animated characters and dialogue! Which, in itself, should keep you busy for quite a while. GRAAL was mainly invented along with the 7-room demo of the first ever GRAAL adventure "Olaf Longhair, Part I", delaying the release of both, but ensuring that GRAAL really works on a full- scale and rather advanced graphic adventure. Although maybe not quite up to LucasArts standards, it proves that GRAAL can make at least a budget-level game any day! And since this manual was written parallel to the code that went into "Olaf" and GRAAL itself, you should find everything of importance right here. 3.1 So, What Is GRAAL? ----------------------- All GRAAL adventures consist of: * The GRAAL driver program, which is the "adventure engine". It is named GRAAL_2 in the development package. When you use it to run a specific game, it is usually renamed to whatever that adventure is called. * GRAAL script files, containing the statements that make up the adventure. There are different kinds of script files: One graal.main file, .room files, .section files, .scene files, and .ptrn files. * IFF image files, depicting background scenes and object and character "clip-art". * A file called diskinfo.graal. This file contains, among other things, the names of all the other files used in your adventure. This file is used by GRAAL to locate files and handle disk swapping in an intelligent way if your game gets so big it does not fit onto one disk. * Optionally, soundtracker music modules and sample banks. 3.2 Other Tools of the Trade ----------------------------- If you don't have AmigaGuide (or Multiview - WB 3 and above), get hold of it NOW. You'll need it to use the editor, and read the on-line command reference. You will not go far without a good paint program like Deluxe Paint, Brilliance or Personal Paint to create all backgrounds, objects and animations. An image processing program like Photopaint, Image FX or ADPro is a good complement. To take some of the work out of the backdrop scene creation, why not use a modelling and rendering package? (Believe it or not, there are some good ones that are freeware, even - POV-ray, for instance. A sound sampler and software could also come in handy, as could a scanner or digitizer. But hey, it's up to you. Or rather, your wallet. 3.3 The Things That Make a GRAAL --------------------------------- Because there are a lot of things in the GRAAL system to keep track of, and you need almost all of it to make the adventure work, the manual will try to explain most of the stuff in the tutorial form, followed by in-depth discussions on a number of the trickier subjects and concepts. There is also an on-line command reference in Amigaguide format, which is a necessary complement to this manual, and which will be vital once you get hang of things in general. Also, the Olaf 1 demo provides you with well commented script files of all types. These demonstrate almost all major GRAAL techniques. (Beware: READ THE COPYRIGHT NOTICE!) But first, let's have a quick general look at the general structure of a GRAAL game. 3.4 GRAAL Script Files ----------------------- The GRAAL code needed to make an adventure tick is contained in a number of script files. It is a compact language; if it wasn't for the heavy commenting, they would not take up too much space at all! There are different types of script files, each controlling a different portion of the game. Their relationships form a tree- shaped structure, like this: There may be any number of .section files beneath the graal.main file, and any number of .room files under each .section file. (Although placed in the middle of the structure, the importance of section files vary greatly depending on the design of your adventure. In some cases, you may want to have only the one section file, containing nothing at all! More about this further on.) In all these script files there are three basic kinds of lines: Comment lines - All comment lines must begin with the characters /* which can be followed by any text, like in /* This is a comment if ever I saw one! Use comments a lot, because the GRAAL syntax is not particularly reader-friendly, and what was clear in your mind when you typed it in may seem like pointless rubbish a couple of weeks later - if you don't have the comments there to remind you. Hint: The GRAAL_Editor uses the first line of each script file to explain its contents in file requesters, making it easier to find the file you want. Therefore, always make the first line of each script a comment, like this: /* Short description of script contents Empty lines - may be used as separators for improved readability. Statement lines - each statement line contains a statement (or keyword, if you will), followed by a colon, and one or more parameters separated by semicolons. Like this: statement: parameter1;parameter2;...;parameterN In many cases, the parameters contained in a statement line are conditions or commands, containing their own parameters. Example: ACTION: 4;IFRF 2=0;SAY I Can't do that;EXIT In this example, ACTION: is a statement that comes into play when GRAAL is checking a command input by the player. More precisely, the ACTION statement in this example will be used if a sentence using verb 4 (parameter 1) has been entered by the player. GRAAL will then execute the commands SAY and EXIT, but only if the condition IFRF 2=0 has been fulfilled first. Note: There must be a space between the ":" and the parameters, but there must be no spaces around the semicolons separating the parameters! Also, there is no semi-colon after the last parameter in a line. Each statement in a script file may be up to 255 characters long. The script files are case sensitive, so make sure all statement and command names are written in upper case. Any line in the three types of script files mentioned above that does not conform to the rules will be spotted by GRAAL at run-time, normally causing the execution of the adventure to halt with an error message. Double-check everything, and use the GRAAL editor for help with the parameter syntax and syntax checking! 3.5 The graal.main Script -------------------------- "All right, but what do these different script files actually do?" I hear you scream. Good questions! The first, and in many ways the most important, is the graal.main file. It is called that because that is what it must be called - if GRAAL doesn't find a graal.main file in the current directory, it will say so and terminate. The graal.main file sets up everything that is common to the entire adventure, such as: * All basic aspects of the main character's behaviour - he's certainly going to be around in the entire adventure! * Where the adventure starts. * The fonts to be used for the user interface. * All the objects that can be carried anywhere in the game. * All the characters involved in dialogues. * All the actions the main character can take that are common to all, or at least to most, locations. 3.6 The .room Scripts ---------------------- Once GRAAL has interpreted the graal.main file, it knows which room file to look for first. All room files have the suffix .room preceded by the room number, so the first room file used in the adventure is very often called 1.room . (If you decide on a better starting point for the adventure later on, you may of course tell GRAAL to start in, for example, room 45 instead.) Since GRAAL reserves memory for each possible room number from 1 and up to the highest room number used, it is quite wasteful to have "gaps" in the room sequence. If you have deleted some rooms in the middle of the sequence, use the vacant numbers when you add new rooms, thus minimising the gaps in the numbering sequence. The .room files do much the same for each adventure location or "room" as the graal.main file does for the adventure as a whole. They contain, among other things, the following: * The name of the IFF file to be used as the background in the Scene Area. * Information about "clip-art" to be loaded in and used as graphic elements and objects for this particular room. * The dialogues that take place in this room. * The objects that can only exist within this room. * All actions that are specific to this room. 3.7 The .section Files ----------------------- .section files are very similar to .room files. Their main purpose in life is to make GRAAL more memory efficient. The basic idea is that many graphic adventures are divided into logical sections, a section being a number of connected rooms where the same objects can be handled and a number of puzzles need to be solved before you can move on to the next section. However, once you are through with a section, there are a number of objects and images you will never use again, and therefore they can be deleted from memory the freed space can be used for the objects of the new section. Or, perhaps the rooms of the section share a lot of graphics - like a labyrinth in a system of caves probably would. How you define sections is up to you, and you do not need to use the concept at all if it is irrelevant. (In that case, just use section 1 for all the rooms, and place no commands in the 1.SECT file - just a few comment lines describing what the blazes you are up to, with a couple of totally blank lines in between.) 3.8 The .scene Scripts ----------------------- .scene files are known as cut-scene files, containing non- interactive parts of the adventure (playing much like cartoon movies). They can also be used as subroutines, saving you the work of re-coding the same set of commands in a lot of places. The cut-scene files are a little special (but simpler) than the previous script files, and will be discussed later on. 3.9 The .ptrn Scripts ---------------------- .ptrn files are not scripts as such - they contain definitions of animation patterns that would be too long to enter into the other script files directly, or you wish to re-use in a number of different places in your scripts - or all of the above. (For those of you familiar with Amos Pro, the contents of the .ptrn files follow the AMAL syntax exactly.) 3.10 Running an Adventure ------------------------- At some point or other, you feel that the script files are ripe for testing. This is simply a matter of trying to start the adventure by running the driver program GRAAL_2, which must be placed in the same directory as all the script and graphics files you refer to in the game. (You should, of course, run the syntax checker in the GRAAL_Editor on all scripts first to get rid of all typing errors and other such mistakes. This takes far less time than re-running GRAAL_2!) First, the GRAAL_2 program loads. Then, the GRAAL title screen is shown. The progress indicator (the horizontal bar) indicates that the contents of the graal.main file are being loaded and processed. When the title screen disappears and the screen goes blank for a moment, the system is working on the first .room script. Most likely, you will get some error messages before everything starts running smoothly. A GRAAL "run-time error" message will appear in yellow text surrounded by a red border on screen, stating the type of error, which room was currently loaded, and which file was last accessed. Note: This file may in some cases not be the actual culprit! For example, If GRAAL has loaded a small cutscene file, executed it and run into a problem in the calling script later on, it is still the name of the completely innocent cutscene file that is shown, so take this information for what it is. Some problems may be of a less severe nature. In those cases, GRAAL sometimes lets you decide whether to continue playing, or exit the program (in which case it tries to clean up the memory just as if you give the "Q"uit command when playing the game the normal way). Continuing after such a warning is not always safe: The error almost certainly affects some aspect of the game. However, things like flag value errors may often be corrected using the on-line monitor (see the appendices). Also note that in the error messages, the offensive statements and commands are sometimes printed in a slightly different way from how they appear in the script: This is because all RBOBn, SBOBn, ROBJn and SOBJn references, which are relative numbers, are translated directly upon loading to become absolute numbers. So if your N_xxxxBOBS statement in the graal.main file decide that ROOMBOBS start at image number 51, an erroneous statement containing RBOB4 would actually show the number as "54" in the error message. (Sorry 'bout that. Read on, and you will probably understand what the heck I am talking about later.) There will most likely always be some errors that are not trapped properly, and the system may just "die on you". In those cases, try to determine how far the loading process has actually gone, and check the structure of YOUR scripts carefully against the Olaf 1 demo and the order in which things appear there! Also, resetting your Amiga before trying again often helps - as always, there is a certain amount of memory thrashing going on if you make a lot of consecutive test runs. For an overview of the features of the GRAAL_2 player interface, read the "Olaf.guide" that contains instructions for the demo adventure. 3.11 Loading, Saving and Quitting --------------------------------- GRAAL has its own, built-in requesters and short-cut keys for the standard tasks of loading, saving, and quitting a game. However, you can easily disable those short-cut keys (with some statements in the graal.main script) and design your own routines. Olaf Longhair uses a special room where you can have a look at the score, save and load games, and optionally quit the program. In the demo, I have not disabled the short-cut keys, so you can choose which way to quit, for example - the quick one or the impressive one! On the subject of loading saved games, note that saved game files can only be used with the same GRAAL driver and adventure version with which they were saved - each time you add or delete objects, rooms and other stuff in the adventure, the saved game file format changes, and renders old saved game files unusable. To make the task of testing a little easier, have a look at the macro feature ("Macros" on page 65). 4 Starting on an Adventure ============================= I won't bother you with a lot of talk about how you must plan the contents of your adventure, have a good storyline, so on and so forth. If you don't that's not my fault, is it? I simply assume you HAVE a story to tell, and that you are well aware of how graphic adventures of this kind works - if you don't, you'd better play some first. I will then show how you can do it all using GRAAL. I won't even go into the basic idea behind my example adventure "Olaf Longhair", because surely you have played the demo by now! This tutorial concentrates on everything that makes the first four rooms in Olaf Longhair tick - because once we have that much going, almost everything follows along the same lines (or will be pointed out separately). The four rooms, in order of appearance, are: 1. The bar, where Olaf wakes up the morning after the night before, and has an informative chat with the bartender. 2. The street outside the bar, where he bumps into a strange- looking guy with an even stranger-looking animal. 3. The harbour, where he meets a foreign captain and deals with a rather irritating seagull. 4. The shopping emporium of one Ali Harrod, Esq. 4.1 Starting on the graal.main File ------------------------------------ Look at the graal.main script now. To do it "the GRAAL way", * Start the GRAAL Editor, which should be in the same directory as the example files. * Press right Amiga + "4" to automatically open a new window in the editor and load the graal.main script there. The GRAAL Editor with graal.main loaded into window no.2 The best way to start creating a new adventure is to take a graal.main file that works, and alter it to suit your own needs. Using the GRAAL editor, you can also choose to create a graal.main file template, with comments and statements showing what is mandatory and what is not. (This method can also be used for the other script types.) Here are some examples of statements that can be set almost immediately. Other ones will be dealt with once we start designing rooms, objects and characters for the adventure. If you use the GRAAL Editor, you can read more about each statement if you place the cursor in the statement name somewhere and then press the [Help] key or click the button. NAME: "Olaf Longhair Goes East" The name of my adventure is "Olaf Longhair Goes East". (The quotes are not there because they enclose a string or anything - I actually want them displayed on screen when the name of the adventure is called up by pressing the [V] key during a game!) VERSION: Demo 2.2 The adventure version number. This is especially useful to guarantee that you don't try to load old saved game files when testing a newer version of the adventure. Then follows a lot of statements dealing with the player interface layout, and numbers setting limits for how many images, objects, and other things GRAAL can handle in your adventure. Basically, the size of the comand area, the number of available commands, their positions and appearance, the layout of inventory lists, and dialogue alternative displays can all be adjusted to suit your needs. Read the comments in the graal.main file, that's the best way to learn about them. Many of these statements require graphic images to be specified and positioned - more about graphics follows below. Fonts """"" Among the statements in graal.main, one thing worth a special mention is the way GRAAL uses fonts. The statements MSGFONT: xen;8 COMFONT: garnet;9 TITLEFONT1: olaf;27 TITLEFONT2: times;14 each loads a font with a certain size and stores it in memory for later use in the game. (For more information on what font is used where, go to the on-line reference.) To keep things easy to handle on the player side, we do NOT install these fonts in the normal Workbench FONTS: drawer, but keep them in a special FONTS drawer inside the drawer where all the other game files reside. This means all fonts you wish to use in the game must be copied to this special "game fonts" drawer in your development directory. The only trouble is that GRAAL needs to have its fonts drawer "prepared" with the standard Amiga FIXFONTS command in order to be able to load the fonts. What this means is that whenever you change the fonts in the drawer, you should run the standard Workbench "fixfonts" program, with the logical assign FONTS: pointing to the game fonts drawer. You do this in a CLI shell, and the commands used should look something like this ("DH1:" below is a hard disk drive, and "MYADVENTURE" is the path to your development drawer on that disk): > assign FONTS: to DH1:MYADVENTURE/FONTS > fixfonts > assign FONTS: to SYS:FONTS The last command re-assigns FONTS: to the Workbench FONTS drawer. 4.2 The Hero - What a Character! --------------------------------- At this point, we will not get much further without bringing the big star, our main character, the man, Olaf Longhair himself, into play! One of the things GRAAL makes so easy to manage is the point and click control of the main character - in this case, Olaf. GRAAL controls what animation sequence is the correct one to use in all standard situations, in which direction Olaf is heading, where in a room he can actually place his feet, and so on. Wonderful as all this may be, it doesn't relieve you of the responsibility for the character design - in other words, before GRAAL can do all this wonderful stuff, you must design the main character and the animations used for his basic movements. Basically, what we need now are some still images and animation cels showing Olaf in various standardised poses. For "Olaf", all these are placed in the IFF picture file "Olaf_Original.iff", which you should take a look at now. What the images portray are: * Olaf walking towards, away, and sideways * Olaf's front, back, and profile when standing still * Olaf talking - the front, back, and profile views. * Olaf manipulating things - also front, back and sideways views, but for each view also in three "height" versions - for objects high up, far down, or "in mid-air". As you notice, the images of Olaf in the file are neatly and evenly spaced. This makes it easier for GRAAL to "cut out" these images and store them in its image bank later. Also note that there are no separate images for the right and left profiles - to make life a little easier, and less memory consuming, the profile images will simply be flipped by GRAAL when a reversed view is required. We will need more images of Olaf during the course of the game, but since they will only be used for special occasions, they are loaded into memory only when they are needed and erased afterwards. So "Olaf_Original.iff" contains all the "global" images of our main character and favourite hero. 4.3 Basics about Images and Bobs --------------------------------- We are going to talk a lot about stills, cels, animations and BOBs in this tutorial, all concepts dealing with how an image is used. A still is any image that is static. An animation is any image that moves, and it does so by using a number of slightly different stills replacing each other, called ANIMATION CELS. BOB is short for Blitter OBject. BOBs are well-known to Amos programmers. They are, basically, the way GRAAL displays all graphics on screen that aren't just backdrops: Objects, animated characters, texts, and so on. BOBs can be put into the display and deleted again without harming the backdrop picture. To achieve this, the system must keep track of all the little graphic bits and pieces by assigning each one used at any time with a BOB number. To make it easier to keep track of the images used by the BOBs, they are stored in a BOB image bank. Any BOB may use any image (or vice versa, depending on how you look at the world). For example, BOB number 44 may be used to display a flower, held in image bank position 56, in one scene. In another room or scene, the same BOB number 44 may be used to display a knife, which is image 78 in the bank. Confusing? Just keep this in the back of your head until we start discussing the script file statements! Since re-cycling is the word of the day, there is no difference in the image types used for different purposes - all are stored in the BOB image bank, and you may use the same image as an animation cel in one situation and as a still image in another. The BOB image bank, where we store all images, must be logically divided into three sections: 1. Global BOB images are those that are kept in memory at all times, for example all Olaf's basic movements, icons for global objects, and command area graphics. The number of slots used for these are defined with the N_GLOBALBOBS: statement. Make an educated guess how many of these you'll need. "Olaf" uses about 90. 2. Room BOB images are images that are only needed in a specific room - as soon as the game switched to a new room, all these images are erased from memory and replaced by the graphics for the new room. The number of these is defined by the N_ROOMBOBS: statement. When referred to in the scripts, their numbers are always prefixed with RBOB: RBOB5 means room BOB 5. 3. Section BOB images work the same way as room BOBs, but for a section (collection of connected rooms) rather than a single room. Their number is defined by the N_SECTIONBOBS: statement. When referred to in the scripts, their numbers are always prefixed with SBOB: SBOB10 means section BOB image 10. If you make a mistake when estimating the number of each image category here, it is not the end of the world. These numbers can be altered at any time later on. 4.4 The Images in the graal.main File -------------------------------------- Back to the graal.main file now, to practice what was just preached: N_GLOBALBOBS: 90 N_SECTIONBOBS: 30 N_ROOMBOBS: 70 This means that right now, we believe we need 50 global BOB images, 30 for use in sections, and 70 for use in rooms. If we change our minds later on, we can always change the numbers then. Let's define the main character's images. The statement CLPART: Olaf_Original.iff tells GRAAL that following statements will grab images from the picture file Olaf_Original.iff BOBS: 10;11;1;1;31;47;32;0 tells GRAAL to grab 10 BOB images and store them in image slot 11 and upwards (slots 1-10 are reserved for system use, remember?) In the GRAAL editor, try this: 1. Put the cursor on the statement name "BOBS:". 2. Click . 3. Click . 4. The Olaf_Original.iff file appears with ten frames showing which pieces of graphics will be cut out. The frames can be moved, resized, and re-spaced. If you were to change the new position with the Enter key (but don't do it now!), the parameters of the statement reflects the changes you made. See "The Editor" on page 74 for a complete description of the editor. More CLPART: and BOBS: statements follow upon this first one, until all basic images we need have been loaded into the image bank. If you want to use multiple controllable characters, automatic character scaling, or make the cingle controlled character "clickable", you have to define a CHAR: statement for it. Each CHAR: statement defines a controllable character, and because parameters in CHAR: also set height, width, and other properties, the above statements may seem a little useless and out-of-date. So they are, but bear with me - they are left in for compatibility. In my demo adventure, I do use character scaling, so let's define Olaf with a CHAR: statement: CHAR: 1;18;11;40;1;1;37;0;22;1.2 1; means Olaf is character number one. There must ALWAYS be a character number one if CHAR: statements are used at all! 18; means that Olaf is object 18. We'll come back to defining objects later - in this case, the object definition holds some important information about Olaf, like which animation channel he will be using. We will not go into details about the other parameters here - read all about it in the on-line reference. (In older versions of GRAAL, there was no CHAR: statement, or indeed a character object - instead, you had separate CHARACTER_WIDTH:, CHARACTER_HEIGHT: and similar statements to set the properties now dealt with in the CHAR: statement.) Anyway, on with it. We need to define some graphics concering some standard movements and still images for our hero: STILL_RIGHT: 14 STILL_LEFT: //14 STILL_BACK: 12 STILL_FRONT: 11 These statements tell which still images are to be shown when Olaf is facing in the respective direction, doing nothing. Wait a minute, what's that strange "//14" thing? Well, it's a convenient way of re-using graphics. Any image number prefixed with "//" will display the image flipped left/right, so you don't have to create graphics for both views. Neat, eh? Anyway, on with it. PAUSE_RIGHT: 13 PAUSE_LEFT: //13 PAUSE_BACK: 12 PAUSE_FRONT: 11 These images are used when Olaf pauses after having gone in a certain direction. If you wish, they may be set to exactly the same values as the STILL_ images. However, as you see, Olaf uses image 13, a slightly more relaxed, forward-facing and "ready-for-input" pose, for the right and left poses in these statements than in the STILL_ statements. You don't HAVE to make the left pose the flipped-over version of the right pose - if you want to draw different images for each direction, go right ahead. Also, if there is any risk of both views of the same image being shown on screen at the same time, they should be separate images! For more info, see "Character and Graphics Design" on page 48. So far, all we have done is specify still images. Now we enter into the gruesome, yet strangely attractive world of animation: WALK_RIGHT: A 0,(16,6)(15,6)(14,6)(17,6) ... WALK_LEFT: A 0,(//16,6)(//15,6)(//14,6)(//17,6) ... WALK_AWAY: A 0,(29,8)(30,8)(31,8)(30,8) WALK_TOWARD: A 0,(26,8)(27,8)(28,8)(27,8) And yes, AMOS Pro users will immediately give a cry of joy: It's AMAL! AMAL is AMOS Pro's animation language, and GRAAL uses the same syntax for animations. So let's see what we have here: "A 0," simply tells GRAAL to repeat the following animation sequence indefinitely. (Stay calm - GRAAL will handle all starting and stopping of standard character animations automatically.) "(16,6)(15,6)(14,6)" and so on are the images and display lengths of each animation cel. For WALK_RIGHT, first image 16 is displayed for 6 frames (=screen updates), then image 15 is displayed for 6 frames, and so on. When the end of the list is reached, the animation loops and starts over with image 16 again. As you see in the WALK_LEFT statements, flipped images are used in animations also - no problems. For more about animations, see "Designing Animations" on page 49. It's quite wise to use 6 frames as the smallest time space for any image during background scrolling - 3 is possible and may work well if you have a limited number of BOBs in each scene in your adventure. However, if you paint on a large canvas so to speak, the system will have problems fitting all graphic updates into a 3 frame space and so the animation may become jerky. (6 isn't safe in all situations, but it usually works and is a good compromise.) TALK_MAP: 11;A 0,(20,18)(11,12)(20,12)(11,6)(19,12) Not only walking is animated and automated in GRAAL - talking is as well. The animation to be used for speech in each situation is not connected to a certain direction, but rather to what image is displayed on screen at the time the character starts talking - The above statement tells us to use this animation if the character is facing forwards (image 11) when the speech starts. As you see in graal.main, there are six TALK_MAP:s specified - all STILL_ and PAUSE_ images are accounted for, which indeed they must be for GRAAL automation of the speech to work in all standard situations. And you can test for flipped images, too: "TALK_MAP: //14; ...", for instance, checks if the image displayed is the flipped version of image 14. HANDLE_MAP: 11;A 1,(11,12)(36,1);A 1,(11,12)(34,1);A 1,(11,12)(35,1) Standard "manipulation" or handling of objects are specified in a similar manner - the animation to be used when a certain object is handled depends on a) the previous character image on screen and b) whether the object in question is placed high up, low down or in mid-air - an animation sequence for each possible position is supplied in the same statement, separated by semicolons. Note that the last image in each sequence should be specified as shown for only ONE frame - this is because a) the character will stay in that position during the handling of the object anyway, and b) we may wish to immediately do some other graphic tricks after the HANDLE command has been given, such as placing an object in the character's out-stretched hand. Specifying too long a pause in these animation sequences would produce an unwanted pause in the flow of the script. To summarise, if the character is facing forward using image 11, and suddenly is commanded to handle an object placed in mid-air, (the cup in the "Constantinoplian" bar is a concrete example), the middle animation sequence in the above statement, which is "A 1,(11,12)(34,1)", would be executed. OK. That was a lot of hard work and tricky definitions to sink one's teeth into, but guess what? We're done! We have actually completed a large percentage of the animations needed for our hero, and can get on with designing the adventure itself! The statements we have defined above will be used and executed time and time again throughout the adventure, and in a fully automated fashion, too. But you control-freaks should not worry too much: GRAAL contains enough script commands to enable you to break away from the standard poses and animations in any given special situation - if you are willing to take on the extra work and extra coding in the scripts that is required. 5 "A Room! A Room! A Kingdom for a Room!" ============================================= As you may gather from the heading of this chapter, we now quite badly need a room or other location to move about in - having our hero confined to a lot of abstract image and animation statements in the graal.main file will not make anyone happy. Let's start with room number one. Although the demo adventure first goes through a couple of other rooms, these only make up the introductory animation, that is where the real action starts. Similar to how the main properties of the adventure is defined in graal.main, the properties of room 1 is defined in the file 1.room. Have a look. The first statement we come across here is UPDATE: 3;1 which sets the updating speed of the scene area. The higher the numbers, the slower the screen updating, and the more graphics GRAAL is capable to shift between updates. To keep animations etc. from becoming jerky, the numbers must be set high enough to cope with all graphics. Actually, this only becomes a real problem when the background is scrolling, so there are two numbers. The first is only used during such scrolls. At all other times, the update rate is determined by the second number. And in this room, the first number is completely irrelevant, because the scene fits into the display without scrolling - it is exactly 320 pixels wide. For other rooms, like the harbour, UPDATE: is set to 6. (I have designed all of Olaf's animations to work with the update range set in multiples of 2 or 3.) Next, there comes a SECTION: 1 statement, indicating that this room is part of section 1, as are all the rooms making up Constantinople in this game. Next, we need a background picture for the scene area. I prepared the interior of this rather primitive bar in the file "1BG.IFF" using the 3D modelling and rendering freeware program POV-RAY. The gorgeous 24-bit image that was the result was then reduced to 16 colours, creating an image that is crude but suitably "cartoon-like" for the purpose. The background's 16 colour registers were then moved around and combined with 16 standard colours used for Olaf and any other common BOBs and images, whereupon i remapped the colours of the 16-colour original in DPAINT. Now, all that remains is to tell GRAAL to use this picture as the backdrop. BACKDROP: 1BG.IFF takes care of that. The width of the backdrops may be from 320 up to 640, making for excellent scrolling background scenarios (as shown in the Constantinople main street and the Baghdad panorama, for instance). The height is variable, but must be the same for all rooms, and be set with the AREA_SIZES: statement in graal.main Each time we enter a new room, Olaf must have a starting position and pose. This is defined by the START_POS: 1;13;20;115;L;1 statement. This not only indicates where Olaf starts, but whether the background screen starts scrolled to the far left, far right or the middle. (In this case, it's all the same, since the scene fits within the screen width.) Any number of starting positions may be defined for the same room - great for those really awkward labyrinths! GRAAL is not truly 3D - nothing shown on a computer screen ever is - but uses a simulated 3D perspective. The bar in 1BG.IFF has a floor, extending from the very bottom of the scene area and a few lines up in the picture - if Olaf moves higher up in the picture, he is also going further back in the room. The effect is demonstrated more fully by the alley in the street outside the bar, which Olaf can actually "walk into". To enhance the effect, GRAAL can also scale the character or characters under your control automatically, so the further up they go, the smaller they become. (However, this is only done for rooms where it is needed, and only if you specifically ask for it.) Now, in order for Olaf to stay on the floor and not start climbing the walls of the bar, we need some way of restricting his movement. We do that using statements like FLOOR: 1;16;114;304;119;1-1/2-2/3-3/4-4 Each such statement defines a rectangular part of the picture where Olaf may place his feet. If there is more than one such rectangle, each is defined by a separate floor statement, and all floors must overlap with at least one other floor to enable Olaf to find his way from one floor to another. The last parameter, "1-1/2- 2/3-3/4-4", describe how Olaf navigates between the four floors in this room. See the FLOOR: statement in the on-line reference for more information about this. It wouldn't be much fun to have an adventure take place in only one room (although such a thing IS possible - how about a "closed room murder mystery"?). So the next statement, EXIT: 1;7;66;12;112;10;113;Exit to\street defines an exit from the bar. This creates a "clickable" rectangle on the screen with some additional parameters describing the properties of the exit. We will come back to the subject of switching rooms further on. So, now we have a background, an exit, and area to move about on, and much more. Time to add some special graphics to the room to spice things up a little. CLPART: 1FG.IFF is a statement telling GRAAL that we wish to grab some clipart from the 1FG.IFF file to use as images in this room. ROOMBOBS: ... statements follow the syntax of the BOBS: statement we used in the graal.main file. Every image grabbed with this statement should later be referred to by a "room BOB image number", which is a number proceeded by "RBOB". For example, RBOB3 means room BOB image 3. The images we grab as RBOBs are all used for objects and graphics that are unique to this room, and are not much use outside it (although you CAN grab clipart from the same 1FG.IFF file anywhere you like in the game, of course). Perhaps some of the clipart we just loaded is supposed to be pasted into the scene without doing anything except being pretty. The statements STATIC: and ANIM: are used for this purpose - which one depends on whether the image should be static or animated. We have two such static objects in the bar. One is the barrel behind which Olaf appears. It has no other function except hiding Olaf at the start of the game and being a general foreground object which adds a bit of depth to the scene. The other is the wooden pillar, also placed in the foreground. That is the graphics department of room 1 over and done with. 6 The Object Matter ====================== You could, theoretically, spring Olaf loose in the bar now, but there would be absolutely nothing to do - just an exit pointing to an undefined room, floors to move about on - and a barrel to hide behind! So far, there is not a single object to interact with! The OBJECT: statement lets you define things that can be manipulated in various ways. Every piece of your scene that you need to hide, show, interact with, or move around, should be defined as an object. (For graphics that follow very simple, and don't move around, you may wish to use ANIM: or STATIC: statements, or BOBON / PBOB commands.) Just as with BOB images, objects are defined in various places depending on where in the adventure they may appear - just in one room, in a section, or in the entire adventure. Sticking with the 1.room file for the moment, you see some ROOMOBJ: ... statements here. They define objects which are never removed from the bar, and never changed in any way: One of the barrels, the plate of spam that Olaf refuses to touch, and so on. Room objects are a great way of adding atmosphere, detail, and red herrings to a game without wasting computer memory - from the players' point of view, there is no way of telling whether an object is a room, section, or global object. Only you know! The policy in the tutorial is to leave details to the on-line reference in graal.guide, but understanding the properties of an object is rather vital, so we will examine one of the global objects present in the bar closely. (The room objects are no good for this purpose, since their use is severely restricted.) In the graal.main file, locate the line OBJECT: 16;piece of\paper;8;VIS;56;RBOB6;66;119;12;0;//14;with;PICK;0;8;47;LOW;WD;an;this;it In the GRAAL Editor, you get a better view of the parameters if you place the cursor on the word OBJECT: and then click to load the object into the Edit Parameters window: An object loaded into the parameter editor (more about that in the chapter about the GRAAL Editor). This statement describes a piece of paper not actually used in the demo portion of the adventure, but it serves to display the properties of a typical object: 16; means this is global object number 16. piece of\paper; is the name of the object. The backslash is replaced by a line break when the name is shown in the scene area. 8; is the room where the object first appears. VIS; means the object can be seen and handled. (NVIS means "invisible".) 56; is the BOB number (not the IMAGE number!) that will be used when displaying the object. RBOB6; is the BOB image number which is used to display the object by default. This could also be an animation sequence using the same animation syntax as the TALK_MAP: etc. statements explained previously. But wait a minute! We use an RBOB image, obviously grabbed in the 8.room file, to display a global object, which is obviously not tied to that one room? Isn't this strange? No, it actually makes sense. Room 8 is the only place where the piece of paper will actually be SHOWN in that shape - when it is used further on in the game, it will only be displayed using its inventory icon. So this is a safe use of RBOBs! 66;119; is the x and y position of the RBOBs hotspot. 12;0; is the "character offset". When Olaf wants to handle the piece of paper, he will walk to a position 14 pixels to the right and 0 pixels above the object's hotspot. Normally, we talk about the relative positions of the character's and object's hotspots here. (See "All About 3D and Hotspots" on page 52.) However, if you prefix the x value with a "W", for example W8;0; the x position refers to the edge of the character that is closest to the object instead. That technique allows for multiple characters of different widths more easily. However, if you only have one character, or they look more or less the same, don't bother. //14; is the still image used to display Olaf once he has walked up to the object. Since the object is to the left of him, he will face it using image //14. And specifying the correct still image for each object is vital: Should Olaf begin to handle the object after walking up to it, the HANDLE_MAP sequence linked to image //14 will be used. Should he start to talk, the TALK_MAP sequence linked to the image will be used. But you need not worry about this, as long as you specify the HANDLE_MAPs, TALK_MAPs and still images used for object handling correctly! with; is a preposition. If a preposition exists, it is assumed that this object can not be USEd on its own with the USE verb - it must be combined with something else, and so the sentence line will read USE PIECE OF PAPER WITH, and the system will wait for a second object to be clicked. If this parameter is left blank, the object will be used on its own. PICK; indicates that the object can be picked up (the condition IFPICK returns TRUE). NPICK is used for the opposite. Actually, you can easily override this parameter using script commands - picking up objects marked NPICK, and making the character refuse to pick up objects marked PICK. Still, this setting means objects which rely on the global ACTION: statements dealing with picking up and dropping will be handled in the right way. Also, there is no risk in making an object pickable even if it is initially invisible (NVIS). If it cannot be seen, it cannot be accessed by the player, and thus, the PICK status becomes insignificant... (ALWAYS use NPICK for room objects, unless you make sure you make the character drop the object again before he leaves the room!) 0; If the object is animated using an animation command (instead of the single RBOB17 for this example), the animation channel must be specified here. The range of possible values is 2-16, and as with BOB numbers, the same number may not be used for two things simultaneously. The piece of paper is not animated, and therefore this parameter is 0. 8; This is the object's "quick command", that is, the command issued when the player points to the object and clicks the right mouse button. Verb 8 is LOOK AT. 47; This is the object icon used to show the object in the inventory: Global BOB image 47. LOW; This is an important one for all objects which can be picked or handled! It determines which of the "handle animations" Olaf will use. Since the piece of paper is on the floor, the LOW animation will be used. (Always place objects, or Olaf, using the character offset co-ordinates so that one of the three positions can be used in a natural way!) DW; This is an "attribute string" which can be used to determine some general properties for the object. "D" stands for dead object, and "W" for "wood". (A rather pointless attribute in this case. Basically, it only tells us that it is softer than stone or steel!) Attributes are used to make basic responses to some actions seem more natural - you don't have to define separate replies to all objects, but can specify a general response for all cases of Olaf trying to use the small knife on objects made of wood, for instance. You may also find an "abstract" class very useful - when Olaf attempts to pick up the horizon, it enables you to respond with some really insulting remarks! (Look in the graal.main script for ACTION: statements containing IFTYPE tests to see how this can be used.) GRAAL is quite flexible in many ways, and there are a number of GRAAL commands to alter many of the object's properties, such as the name, visibility, location and so forth during the course of the game. See the on-line reference for a complete list of commands. Generally speaking, the statements in the script files set things up - it is the commands contained in DACT:, LACT: and ACTION: statements executed during gameplay that brings the whole thing to life! While we are at it, let us examine another, but more human, global object: The bearded man / bartender. So, what is the difference between a bearded man and some sheep bones? Well, the bartender is animated using a default animation sequence, as you see. This sequence also uses RBOB images, since the bartender never leaves 1.room. Furthermore, the bartender can not be picked up (there's a relief!) and uses animation channel number 8 for the animation. His special attributes are "MV" - meaning he's a male character and alive. 7 Section Objects and Bobs ============================= There is a third class of objects involved in the bar scene, those defined in the section file 1.section with the SECTIONOBJ: statements. These are objects that only exist the very first time a new section of the game is visited, and disappear again before the section is exited. It is not that useful, but some of the objects in Constantinople is of this kind - the magic flute, for example, which disappears into the pawn shop before you can leave town. You will probably find section BOB images (SBOBs) more useful than section objects. These are grabbed in the section file the same way RBOBs are grabbed in the room files, but with the SECTIONBOBS: statement. Needless to say, they remain in memory during the visit to the section, but disappear and are replaced by other graphics the moment you walk into another game section. You are not obliged to use the section concept at all, especially if your adventure is quite small. However, at least one section script must exist, even if it just contains a comment saying "Not Used". Then specify all your rooms as belonging to this "empty" section. Okay, we have everything in place, except one VERY important thing - the instructions telling Olaf to deal with the commands you give him! 8 Camera! Action! Lights! ============================ 8.1 ACTION: statements ----------------------- All conditions and commands used to respond to the player's actions are placed in ACTION: statements (leaving the dialogues out of it for the moment). ACTION: statements may appear in all three major types of script file: .room, .section and graal.main. The idea is that the ACTION: statements taking care of a certain action is placed closest to the place where the action takes place. If an action can only take place in one specific room, the ACTION: statements for it are placed in that .room file. If the action is only valid in a certain section, they are placed in the .section file. If it is something that needs to be taken care of regardless of where it appears, the graal.main file is the place. In fact, almost every action should have some "safety net" in the graal.main file - if no specific action is taken in the ACTION: statements of the .room and .section files, the graal.main ACTION: statements should at least make it look like Olaf understood what you were trying to do! There is nothing more unrewarding than clicking away at lots of things and have absolutely nothing happen. Okay. So we write a lot of action statements containing commands that makes Olaf walk, talk, and jump! But how does GRAAL know when to use what actions? Well, suppose we want to pick up the cup on the barrel in the bar. Let's look at how that is performed in GRAAL, keeping in mind that GRAAL always checks the .room file first, then the .section file, and finally, if nothing else helps, the graal.main file. Each file is checked from the top down to the bottom, which is very important to remember in order to get the sequence of tests and commands right. When the player has clicked PICK UP and the CUP, GRAAL starts looking for appropriate ACTION: statements, knowing the number of the verb (PICK UP = 2) and the object (the CUP is section object 3, referred to as SOBJ3). The first parameter in each ACTION: statement is always the verb number, and in 1.room, the first ACTION: 2;... statement that we come across is ACTION: 2;IFOBJ SOBJ3;ADDRF 0,20,1 IFOBJ SOBJ3 tells us to perform the rest of the actions if we pointed to room object SOBJ3, and we did. What happens next? Well, 1 is added to the value of room flag 20 for room 0. More about flags later - suffice to say they are like variables in ordinary programming languages, and this particular flag is used to hold the player score in "Olaf". So you get one point for picking up the cup... When we are done with the first ACTION: 2;... line, the next one reads ACTION: 2;IFOBJ ROBJ6;.... This is not a match, because the line is only relevant if we're trying to pick up ROBJ6. Going through the rest of the ACTION: 2;... lines in 1.room, we quickly discover that there are no more line concering the mug there. Switching to the 1.section file, let's see if we are more lucky. No, not a single PICK UP command, actually. This is not so surprising, since almost all objects start out in a certain room. Well, why then wasn't there a command to really pick up the cup in the 1.room file? Because, with the power of GRAAL, almost all PICK UPs of any "pickable" object can be handled using a few single ACTION: statements in the graal.main file - only objects handled in special ways in room 1 need to have their actions in the 1.room file. Going on to the graal.main file, we find the following: ACTION: 2;IFCARR;SAY I Already have it!;EXIT IFCARR says that if the object we refer to is already in the inventory, then let Olaf say "I already have it!". EXIT means no more tests on ACTION statements will be done for our current input: The sentence line will be cleared and Olaf is ready to try something else. However, SOBJ1 is NOT in our inventory yet, so we go on: ACTION: 2;IFPICK;MOBJ;HANDLE;W 12;PICK;HANDLE -1;EXIT Now behold the true power of the GRAAL. This is the stuff we have been tormenting ourselves for all along the tutorial up to this point! IFPICK; If the object is "pickable"... MOBJ; Olaf walks to the default offset position next to the object (as specified in the OBJECT: statement for the cup)... HANDLE; Olaf stretches out a hand according to the HANDLE_MAP: animation... W 12; and waits for about 1/4 of a second... PICK; grabs the object (it disappears from the screen and enters the inventory list)... HANDLE -1; lowers the hand again to the position it had before the HANDLE command... EXIT; ...and then we are done! Now, if our object hadn't been "pickable", the ACTION: used by us above are followed by a couple of "safety nets". (Remember, we never get to these lines if the object has indeed been picked up - the "EXIT" command sees to that.) One example of such a safety net is: ACTION: 2;IFTYPE -;SAY That was rather far-fetched, wasn't it?;EXIT IFTYPE -; This checks if the referred object was an abstract object, like the horizon in the Constantinople harbour. Since abstract objects can't very well be picked up under any circumstances, SAY That was rather far-fetched, wasn't it?;EXIT makes Olaf "speak" this sentence using the talk-map corresponding to his current position on the screen. And finally, if the object happens to be un-pickable, but of another type, ACTION: 2;SAY I can't pick that up.;EXIT gives a rather dull but to-the-point message to the player. Don't go erasing ACTIONs in the supplied example graal.main file altogether the first thing you do - a lot of these "safety net" actions should be in almost any game, although you should of course alter the wording and detailed behaviour to suit your own needs! Special ACTION: Statements """""""""""""""""""""""""" The verb numbers corresponding to normal player input goes from 1 and upwards. Instead of an ordinary verb number, the following can appear as the first parameter of an ACTION: statement: 0 (zero) - the verb number used for GO TO (that is, an exit has been clicked. See "Using Exits" on page 34). -1 Timer events. See "Timer Events" on page 57. -2 Things to do after a LOAD or RESUME command. See "The Load / Save Room." on page 58. ? means any normal verb number from 1 and upwards will match this statement. For example, you may have a room where no ordinary actions should be possible. All player input (except exit movements) could then be trapped in the room script with a single ACTION: ?;EXIT statement. Repeating Verbs and Conditions If the first parameter in an ACTION: statement reads = the verb number and initial conditions from the action statement immediately above, saving you some typing if several statements begin in the same way. Example: ACTION: 1;IFOBJ 2;IFOBJ2 21;MOBJ 21;SAY Here you go!;... ACTION: =;RESP R,4,Thank you very much!;EXIT The second line will actually be interpreted as ACTION: 1;IFOBJ2;IFOBJ2 21;RESP R,4,Thank you very much!;EXIT If only some of the initial conditions should be repeated, but a blank space in between conditions. Here's the example once more, this time repeating only the first condition: ACTION: 1;IFOBJ 2; ;IFOBJ2 21;MOBJ 21;SAY Here you go!;... ACTION: =;RESP R,4,Thank you very much!;EXIT Now the second line will actually read ACTION: 1;IFOBJ2;RESP R,4,Thank you very much!;EXIT The method can also be used to repeat the initial part of DACT: and LACT: statements. 9 Using Exits ================ Now that we are familiar with the general behaviour of ACTION statements, it is time to explain how exits work. As you may or may not remember, the EXIT: statement in the 1.room file defined a "clickable" rectangle on screen. However, we never explained what happens when the player clicks the exit. This is what happens: GRAAL interprets this as a very special input sentence, with the VERB set to 0 and OBJ1 set to the number of the exit. It then checks the ACTION statements just as if the player had input a normal command. This is a typical ACTION statement to take care of an exit command: ACTION: 0;IFOBJ 1;MEXIT;CBOB 12;GOTO 2,1 0; was the verb number indicating an "exit click". IFOBJ 1; tests if it was exit number 1 that was clicked. MEXIT; is a special command that can only be used in ACTION: 0;... statements. It makes the main character move to the exit point specified in the EXIT: statement (not to be confused with the EXIT *command*, which is something completely different). CBOB 12 Perhaps we wish the character to face the door before exiting. GOTO 2,1 is a command specifying which room and entrance to go to. Voilŕ! Of course, you are free to do whatever you like in these statements, just like in any other ACTION: statement. You may manipulate the way exits are interpreted to your heart's content! 10 The DACT: Statements ========================= In each room file, there must be at least one DACT: statement. The DACT: statements contain conditions and commands that are run through each time the room is entered. The flow of control is the same as for ACTION: statements: If a condition is not met, the rest of that DACT: statement is disregarded, and if an EXIT command is encountered, no more DACT: lines will be checked this time around. When GRAAL starts to run through the DACT: statements, all graphics and objects are already loaded into their proper places. However, the screen is still black - the light switch has not been pushed yet, so to speak. This means you can do tests and move things around using commands in the DACT: statements before you let the player see the scene, which is very, very useful. Once you are done preparing the scene, simply use a LIGHTS ON command in a DACT: statement. When an EXIT command is encountered, control is handed over to the player. 11 Flags and String Variables =============================== In order to keep track of what is going on in your adventure, you need a way to store information about the player's actions. In GRAAL, there are two forms of variables that can be used to stora information: Flags and string variables. 11.1 Flags ---------- Flags can hold integer numbers. There are 20 flags for each room and 6 for each object. In reality, you can use any flag for any purpose you like, but naturally it is most logical to keep information regarding a certain room in that room's room flags, information about an object in its own object flags, and so on. Also, this is often most conventient - if you refer to the current room's or object's flags, you don't have to specify the room or object number in most flag-handling conditions and commands. Since room 0 is never used as a location in the game, but it exists as a "flag space", you can use room 0 flags to hold information that pertains to the whole game. There are commands to set, add, and subtract from flag values, and conditions to test the contents in many different ways. Flags can also be set to store in-game dates and times. The flag values can also be printed in sentences by all text- displaying commands - see the on-line reference for information about how to do that. 11.2 String Variables --------------------- In addition to the flags, there are 12 "global" string variables that can hold text strings like the player name, or just snippets of text you have to repeat in several text-displaying commands. There are commands to set and test string variable contents, and there is also a PROMPT command that asks the player for input. The PROMPT command uses the dialogue area to display a prompt on the first line and a text cursor on the second line. The player then enters the text of his choice, and ends the input by pressing the Enter key. Simple as that. 12 Having a Chat ================== There are few things that breathe life into a graphic adventure the way good dialogues do. Of course, in order to have a dialogue, you need to have at least two people communicating. In this case, this means our hero and another character in the game. In the bar where the game starts, there is a bearded bartender who is very likely to become the first person Olaf speaks to. Let's look at how this is done. First of all, any character involved in conversations must be defined as an object using an OBJECT: statement - it can be a global, section or room object. There is nothing special with the definition: Just make sure the object is visible and placed in the room where the dialogue takes place. Also, assign an animation channel to it. We need a way to make each "speaking partner" talk to the player- controlled character, which is done by defining DLG: statements in the graal.main file (below the OBJECT statements). Each DLG: statement defines a set of rules for where and how the speech is displayed, and an animation sequence for the speaking partner talking. DLG: 1;5;11;-20;A 0,(RBOB4,12)(RBOB6,24)... 1; means this is dialogue speech definition number one. 5; means that the appearance of the speaking partner is defined by global object 5 (the bartender). 11; is the colour used for the text displayed when the bartender speaks. 20; determines how far above the bartender's head the text is displayed. A 0,(RBOB4,12)(RBOB6,24).... is the animation used when the bartender talks. Some speaking partners are probably fairly static, and then you do not need more than one animation for the speech. However, nothing prevents you from defining more than one DLG: statement for the same speaking partner. Now that we have two statements in the graal.main file, we move on to the 1.room file, where the actual dialogue contents are defined. A dialogue always starts when GRAAL encounters a DSET command in an ACTION: or DACT: statement. It then shifts into another mode, where the player's input is no longer a normal command sentence, but only the number of a dialogue alternative. GRAAL responds to the chosen alternative by going through LACT: statements that correspond to the selected alternative, and does not consider the ordinary ACTION: statements. Sooner or later, GRAAL encounters an EDLG command in one of the LACT: statements, which terminates the dialogue and switches the game back to the normal input mode. Let's begin from the beginning. When the player commands TALK TO BEARDED MAN, the following ACTION line is performed: ACTION: 5;IFOBJ 5;IFOF 1=0;MOBJ;SAY Hello;RESP R,1,Hello,yourself; DSET 1,+3,+7,+9,+11,+12;EXIT 5; the verb is TALK TO - we have a match IFOBJ 5; the object is the BEARDED MAN/BARTENDER - we still have a match IFOF 1=0; Hello, what's this? It's a test of an object flag, a concept we have not discussed earlier. Object flags are variables attached to each object. There are six flags for each object, and each can have any numerical, integer value. By assigning values to flags and testing them, you can keep track of everything that has happened to an object - it's up to you to decide what to use the flags for. In this case, I have decided to use flag 1 for the bartender to see if this is the first time ever we talk to him. All flags are initially 0, so this test - IFOF 1=0 - is true in our case. Before the dialogue is ended, the flag values will be set to 1 to indicate that next time around, we should resume the conversation in a slightly different manner. OK, on with it: MOBJ; We move up to the bartender just like we move up to any object before manipulating it. SAY Hello; Say "Hello". RESP R,1,Hello, yourself.; This is the bartender's response. "1" means GRAAL will look up the statement DLG: 1;... in the graal.main file to find out how the bartender should behave when talking. "R" means the default bartender animation will resume as soon as the talking is over. So far, all statements have been performed with the game still in the "normal" mode. Now comes the command which switches to dialogue mode: DSET 1,+3,+7,+9,+11;12 This command engages us in dialogue number one and tells GRAAL to add the four dialogue alternatives 3, 7, 9, 11 and 12 to the list of possible lines for Olaf to speak. Since this is the first DSET statement ever to be performed for dialogue one, they will be the ONLY four alternatives. EXIT exits the parsing of the TALK TO command, and leaves us to get on with the dialogue - the player now has to select a dialogue line from the dialogue area which has replaced the normal control area. Hmm. Dialogue lines 3,7,9, 11 and 12. What are they? All the lines are defined by LINE statements in the 1.room file. Let us take line 3 as an example: LINE: 1;3;What is this place?;Where did you say I was?; 1;3; means this is line 3 of dialogue 1 What is this place?; This is the line appearing in the dialogue command area (where the player can choose a line to say) when the alternative is previously unused. Where did you say I was?; is the version that will appear if the alternative is "re-used". If this second version is specified as a blank space only, the first version of the sentence will always be used. "one blank space" The last semi-colon is followed by one, very important blank space, which tells GRAAL there are no conditions attached to this dialogue line. To explain the concept of dialogue conditions, let's look at another of the initially added lines, line 7. The definition of that LINE goes: LINE: 1;7;Do you know anything about the ship in the harbour?; ;IFOF 2=1 First of all, notice there is no second version of this line. The question will always look the same, regardless of how many times Olaf puts it to the poor bartender. Here, there is an additional condition that determines whether this dialogue alternative is available to Olaf or not. Object flag 2 for the bartender must be set to 1, otherwise the line will not appear in the dialogue command area, no matter how many "DSET 1,+7" commands are issued. However, once a DSET 1,+7 command has been given, line 7 becomes a possible line: GRAAL will check object flag 2 for the bartender each time the dialogue is re-engaged or refreshed, and as soon as flag 2 becomes 1, the line will appear and become available for Olaf to speak. If you look through the lines, you will notice that only lines 3, 11 and 12 are unconditional. This means that if the first thing Olaf does is engage in conversation with the bartender, only those two alternatives will be visible. So what the player now sees in the command area is: What is this place? My head hurts. Could you help me, please... However, if he trundles off to the harbour to look at the ship, and only then returns to talk to the bartender, line 7 Do you know anything about the ship in the harbour? is also available. OK, back to our poor player, currently facing the task of choosing a sentence to speak. When the player clicks one of the alternatives, the corresponding line number is sent back to GRAAL. Let's assume the player clicks on My head hurts. This means the number "11" is returned. GRAAL now starts to search for LACT statements starting with 1;11; - there had better be one, or nothing will happen! Fortunately, there is: LACT: 1;11;RESP R,1,That's probably because...;DSET 1,N11 This is a typical example of a simple response to a dialogue line. The bartender speaks, and then another DSET command is given. Because we already are in dialogue mode, this command only "refreshes" the dialogue - that is, makes alterations to the current set of valid alternatives. In this case, the adjustment is to take away line 11 and tell GRAAL that it should never been shown again. That's what "N11" means. The alternative "Could you help me, please..." yields a similarly unusable response, so assuming Olaf hasn't been out exploring the town yet, he is now left with only one alternative - the line What is this place? The response to this one is a bit more substantial. The bartender makes a long response - so long, in fact, that is does not fit into one LACT statement with ease. Instead, there are two statements, performed in sequence. When using this technique, remember NOT to put an EXIT or DSET command at the end of the first statement, because that would interrupt the process and prohibit the second statement from being executed! In the process, the bartender - if he is still named "bearded man" - reveals his identity. Therefore, there is a NAME bartender; command, renaming object 5 "bartender" if it has not been done already. The response ends with DSET 1,+1,+2,+5. This means that three more possible alternatives will be added to the set of lines available to Olaf, all of which are unconditional. The current alternative - line 3 - also remains, but now appears in its alternative form "Where did you say I was?". This makes the conversation a bit more believable, since you usually rephrase your questions when you feel you need to repeat them. One of the added alternatives, line 1, is an "end-of-conversation" alternative. When Olaf says "Thank you very much", the bartender answers "Don't mention it.". Then, EDLG;EXIT is performed, which switches the game back to normal input mode. As you se in the LACT statement, object flag 1 for the bartender is set to 1 with a SETOF (set object flag) command to indicate that if we TALK TO the bartender again, it is a resumed conversation - the initial "hellos" will be expressed a bit differently. This concludes the basic tour of the features available in GRAAL 1.0, but stay tuned: Below are a lot of hints and tips about how to use the power and special techniques of GRAAL to their full potential. 13 Multiple Characters and Inventories ======================================== In the dialogues described in the previous chapter, the "speaking partners" were little more than ordinary objects, animated to make them look and act like human beings (or wizards, hobbits, monsters... take your pick). You can also offer the player true control over more than one character. GRAAL keeps track of each character's location. There are also multiple inventories, so that each character may have its own inventory. Up to four alternate characters and four inventories can be used. (The Olaf Longhair adventure demo does not use multiple characters. Get hold of "The GRAAL Herald, Issue 2" - GraalHerald2.lha - which contains a mini-demo showing off these and other 2.1+ features.) 13.1 Multiple Character Graphics -------------------------------- To make the multiple character feature feasible, each character uses the same animation patterns, sequences and default still images as the main (default) character. The only thing that differs between the characters are the image numbers being used. This means that we still only need one set of "default graphics" statements in graal.main. In other words, the STILL_... PAUSE_... WALK_--- HANDLE_MAP: ... TALK_MAP: ... statements are defined only for the main character, exactly the same way as in single-character games. Also, the CBOB command expects you to specify a BOB number for the main character, and then automatically uses the corresponding image for the currently controlled character instead, and the same goes for the IFCBOB condition. All images used in these statements should have numbers close together so as to form a "block" of graphics in the image bank, describing all default poses of the main character. This block should be placed as low as possible in the image number series. For example, the main character graphics may consist of 30 images, which we need to store in image numbers 11 to 40. Something like /* Clipart file containing all graphics for the main character CLPART: main_character.iff /* The BOBS: statements below grab 3*10=30 images BOBS: 10;11;... BOBS: 10;21;... BOBS: 10;31;... in graal.main should take care of that. Now, for each extra controllable character, an identical "graphics block" must be loaded in a similar way. Ideally, these blocks are placed directly above the main characters graphics, like this: CLPART: second_character.iff BOBS: 10;41;... BOBS: 10;51;... BOBS: 10;61;... would place the graphics for the second character in slots 41 to 70. Note: The image numbers used for alternate characters MUST be higher than those for the main character graphics! Now, as you have already guessed, the images contained in the two block must match each other: If image 11 shows the main character facing forward, image 41 MUST show the second character facing forward, and so on. 13.2 Character Objects ---------------------- In normal, single-character adventures, the main character is not an object in itself - that is why no name appears when you move the mouse pointer over the main character in the scene area. However, when you have multiple characters each one must be defined by a global object before we can start to put any "character-switching functions" into the game. First, define a global object for each character. It's nice if the main character is object number 1, and the second character object 2 and so on, but this is not at all necessary as we shall see later on. You MUST abide by the following rules for the character objects: * Each one must have a unique BOB number not used for anything else in the parts of the game where the character can appear. * Each one must have a unique animation channel, not used for anything else in the parts of the game where the character can appear. * They should all be VISible. * They should all be NPICK (not "pickable"). Apart from this, they are defined pretty much like any other type of object. Now, we need to tell GRAAL that there are multiple controllable characters in the game, and define some more properties for them that cannot be deduced from their respective OBJECT: definitions. This is done with CHAR: statements: CHAR: no;object;stimg;eimg;floor;colour;height;text_offset;width;speed no is the character number. The main (default) character is always number 1, and if CHAR: statements are used at all, there MUST be one for character number 1! object This is the object number of the object defining the character, as discussed earlier. startimage;endimage These parameters define the first and last image number of the "image block" containing all default character graphics. startfloor This one may seem a little odd. Each character's starting position in the game is defined by the room and x/y parameters of the OBJECT: statement, but we also need to know what floor in the room contains that point, which is a piece of information not available in the OBJECT: statement. colour;height;text_offset;width;speed When using a only one controllable character, all these things are set in separate statements. Examples: CHAR: 1;1;11;40;2;11;40;10;20;1.2 Character 1 is global object 1, occupies image slots 11-40, and starts out on floor 2 - the room and exact position are specified in the object definition. Furthermore, it uses text colour 11, is about 40 pixels high, has an extra 10 pixels above its head to the place where related text is displayed, is 20 pixels wide, and walks at a speed of 1.2. (This is one of the very few floating point numbers used in GRAAL!) CHAR: 2;20;41;70;1;4;0;30;30;1.5 Character 2 is global object 20, occupies image slots 41-70, and starts out on floor 1 - once again, the room and exact position are specified in the object definition. It uses colour 4, its height is set to 0 which makes the mouse pointer point to its feet, the text is displayed 30 pixels higher up than that, it is 30 pixels wide and uses a walking speed of 1.5. Note that if your various controllable characters are of different heights, it is probably a very wise thing to set the height to 0 as in this example, otherwise offsets from objects and the mouse cursor will look very strange indeed. Using a Character Object with a Single Character Perhaps you want to manipulate your character using commands that requires it to be clickable in the scene area. Even if you only have one character in your game, you can still specify an object for it and connect it with a CHAR: 1;... statement. Then the mouse pointer will now recognise the character and display its name in the scene area. also, if you wish to use the automatic 3D scaling feature for the character, a CHAR: 1,... statement is required. 13.3 Switching Characters ------------------------- Proper BOBS:, OBJECT:, and CHAR: statements - that is all that is needed in your graal.main file to make your game multi- character. However, we still need a way of switching between the various characters. Well, here it is. Switching between characters is r-e-a-l-l-y easy - in fact, I can't think of a single way to make it any easier. The command to use is simply SWITCH character * If the characters are visible in the current screen, you won't see the change, apart from the fact that the next time you click in the scene area, the new character moves instead of the old one. * If the characters are in different rooms, GRAAL will simply jump to the room where the new character is currently located - the first time you switch to a character, this is of course the room and position specified in that character's OBJECT: statement. * If the characters are in the same room, but the one you switch to is "off camera", the scene area will scroll the character into view. The SWITCH command must always come last in a command sequence, followed by an EXIT command. 13.4 Inventory Switching ------------------------ Now, you probably want each character to have its own inventory. Normally, this means the SWITCH command should be preceded by an inventory command: INVENTORY 2,U;SWITCH 2 would switch to inventory 2 (and update the command area to show the change), and then also immediately switch to character 2. Note: The inventory switching is handled completely separately from the character switching, and there is no law that says character 1 must use inventory 1 and so forth. This is because you may want to switch inventory lists for other purposes than switching characters! Another note: The default inventory is inventory 1. (There's a big shock for you... :) To make an object start out in an inventory rather than in a room, you use a special form of room number in the OBJECT: statement room parameter. Simply type an "I" followed by the inventory number: I2 will place the object in inventory 2. PICK, GET, and PUT commands always work with the currently selected inventory. To place things in another inventory than the currently selected, you must use the PUT command specifying the inventory in a similar way to the OBJECT: statement room number: PUT 4,U,I2 would move object 4 to inventory 2. The parameter "U" indicates that the move is made from the current inventory, since U means we wish to update the inventory display to show the change. Technically, each inventory is a room number, calculated by 1000 - inventory number = inventory room which means inventory 1 is actually room 999. This concept works as long as you don't have more than 990 rooms in your game, and I really don't think you do... 13.5 Identifying Characters and/or Inventories ---------------------------------------------- You may well wish to have some way of knowing which character is currently selected. There is a COMGR command that can paste an image anywhere in the command area (although you should take care not overlay the inventory list or any other areas used by the system, of course). Simply create a global image containing the name, symbol or portrait for each of the possible characters / inventories, then COMGR the proper one onto the command area when switching. 13.6 Characters Following Characters Around... ---------------------------------------------- If you have a game with two controllable characters it is very likely that, from time to time, you will want one of them to follow the other one around. As long as all movements by the currently controlled character is generated either by the player clicking in the scene area, or by the CMOVE command, this is quite simple to achieve. The command FOLLOW character,startx,starty,followx,followy will cause the specified character to follow the one under player control around. This continues until a SWITCH command switches the control to another character, or you give a FOLLOW OFF command. The parameters following the character specification deals with where the following character will position itself in relation to the current character. Generally speaking, it will strive to always stop "behind" the controlled character. startx,starty After a FOLLOW command has been given, any GOTO command moving the controlled character to a new room will cause the following character to go there, too. startx specifies the number of pixels between the characters. It is the Left/Right/Middle parameter of the START_POS: statement that determines whether the following character will be to the left or the right of the controlled one. Thus, it should always be a positive number; GRAAL determines the actual sign. starty should normally be a small, negative number. followx, followy These number work about the same way as startx and starty, except they determine the offset between the characters after having walked around in a room. Both numbers should always be positive: GRAAL "knows" where to place the following character in most cases. Note that when the controlled character goes next to a floor boundary, the following character probably ends up a few pixels off that floor, depending on your offset settings. There are two things to remember about this: * You may want to adjust the floor sizes in some rooms to prevent the following character from "climbing the walls". * Normally, if control is switched to the following character, it will be treated as if it had been placed on the same spot as the previously controlled character. Normally, having a character move from a spot outside the floor system results in very odd movement paths, but in this special case, the slight misplacement of the character will be taken care of automatically. However, if a SHOW or OMOVE command has been issued for the character's object between the last "follow" and the switching of control to it, GRAAL expects you to correctly specify the character's current floor using SETFLOOR instead (once control has been switched to it). 13.7 Helpful Conditions ----------------------- To help to determine what the scene looks like, a couple of conditions have been added primarily for multiple character games: IFCHAR character is TRUE if the current character under player control is the specified character. IFHERE object is TRUE if the specified object is in the room. Note that the parameter is the object number and not the character number - because this may also come in handy for other objects apart from characters. 13.8 Things to Consider ----------------------- Unfortunately, there is no collision detection between characters. From time to time, they will seem to "walk through" each other on screen. The only thing you can do about it is try to minimize the problem by carefully thinking about character placements and floor layouts. 13.9 Space-saving Tip --------------------- If you have a need for different controllable characters in different sections of the game, you can save a lot of chip memory by letting them share the same space in the image bank. Just put CLPART and BOBS commands in the appropriate section files (and also in ACTION: -2 statements to make sure the correct set is loaded after loading a saved game). 14 Character and Graphics Design ================================== Well, fellow adventurer, by now you are a proficient GRAAL user. I hope. Anyway, welcome to the first master class, where we will look at some of the central GRAAL concepts a bit more closely. This chapter deals with designing your main character and planning your graphics, something that must be done with some thought and consideration - although small adjustments are easy to make at any stage during the game development, things like the character size influence every other piece of graphics you create, so beware! 14.1 Size --------- Get a suitable character size, keeping the backgrounds in mind - they are 120 pixels high, and in lowres, so you must use lowres when designing too - otherwise your hero will look rather fat on the screen! I should think a character between 40 and 60 pixels high would be about right. Below 40 and there is not much room for detail at all, more than 60 and the scenes start to feel cramped because the character takes up too much space. Also, bigger graphics takes more processing power. In addition, the more pixels you have to animate, the more chances you have of making a bad job of it! Really, I am not kidding. Small can be beautiful sometimes. Naturally, how you want the backdrops to relate to the main character is also a factor - is he a small guy in a big, cruel world, or an ace detective always moving around in cramped Victorian tunnels and Baker Street studies? 14.2 Colour ----------- Use only some of the available colours for your character, and make it a good spread of useful colours, because these colours will have to be the same in all scenes! Colours not used for portrayal of the main character, or frequently occurring objects, can change according to the current scene - the more colours you have left to play with, the more variation you can bring to the backdrops. Note: The first three colours more or less have to be as follows: Colour 0 should always be used ONLY for transparent areas in BOB images. Colour 1 SHOULD be a rather bright white, colour 2 MUST be black!! Here's a tip: When working with a background or clip-art picture in a paint program, set colour 0 to something strange to distinguish it from "usable" colours, but always set it back to black before saving, or the borders around the adventure scenes when running the adventure may become coloured in ways that we don't want! If you don't follow this advice, you surely will make the mistake of using colour 0 as the black colour in spots of the graphics, whereas it will be transparent when used in the game - and vice versa! Note: Despite the fact that you should only use some colours for the character, always create the graphics with a palette using the same number of colours as your backdrop pictures. 14.3 Pointer Shapes and Colours ------------------------------- The shape of the two mouse pointers used in GRAAL can be changed in graal.main by using the ARROW_CURSOR: and CROSSHAIR_CURSOR: statements. The new pointer shapes are simply images stored in the image bank like any other, but they have some special properties: * They must be four colours only, and colour 0 is transparent. * Colours 1, 2, and 3 of the pointer shape will be mapped to colours 17, 18, and 19 of the backdrop palette. If you want the pointer to always have the same colours in the scene area, these colours must be the same for all backdrop pictures. If there was a way to alter these palette numbers I would, but there isn't, so I can't. So there. This means that you may want to plan ahead and decide the following colours for all scene are graphics, once and for all: 0 Black (transparent. Do NOT use this for the black parts of the backdrop itself!) 1 White 2 Black (Use THIS for the black parts of the backdrop picture!) 17 Pointer colour 1 18 Pointer colour 2 19 Pointer colour 3 14.4 Designing Animations ------------------------- The following poses must be designed for the main character: * The stills to use for front, back and "sideways facing left" still poses. * The animations for walking towards, away, and sideways right to left. * The animations for talking corresponding to the front, back and side stills. (Open and close the mouth in different ways, move the head slightly, etc.) * The animations or stills used for handling objects (picking up, handing over, etc.), also corresponding to the three "main stills" previously mentioned, but in three different heights for each still - High, Middle and Low, depending on whether the object is located on the floor, high up or on a table or something else in "mid air". The reason you don't have to make separate animations and images for right and left is that you can mirror one image to point in the other direction using a simple trick described further on. This saves memory as well as time spent in paint programs! To get the animation smooth, it should be designed to work with frame updating taking place every 6th vertical blank. This may sound like nonsense to you, but what it means is that you can switch the animation cel every six 50ths of a second, which equals six frames displayed on a PAL TV system (or 60ths of a second on an NTSC system). Actually, too many animation cels for a certain movement may not necessarily add that much to the game anyway. Olaf uses only 5 cels for a basic walking movement, each cel being shown for 6 50ths of a second. So, now you should have you basic animations designed. Good. First, test them against some different backdrops that you think will be representative for the game in your excellent paint program. Then, satisfied that your character basically looks OK, you should now design a "dummy room" in GRAAL, place some "dummy objects" in that room that will force your character to use all his newly learned physical skills. Then, give him a good work-out. 14.5 Complex animation patterns ------------------------------- Some times, we may need more complex animations for an object or character. For example, the captain in room 3 of the Olaf demo walks back and forth aboard his ship, bends down to fix things, and occasionally, also loses his hat! The AMAL animation language used by GRAAL allows us to achieve this, but the code needed is longer than will comfortably fit into a statement line in GRAAL. Therefore, ANIM:, OMOVE:, SHOW:, and OBJECT: statements all accept animation pattern specifications that look like this: ...PTRN n... which tells GRAAL to go look for the animation code in a file called n.ptrn. Here is part of the pattern file for the captain's movements as described above: /* The captain's standard movements for room 3 /* S: A 15,(RBOB6,6)(RBOB5,6)(RBOB4,6)(RBOB7,6)(RBOB8,6)(RBOB7,6)(RBOB4,6)(RBOB5,6) M 20,0,70 M 20,10,150 M 98,-6,200 A 1,(RBOB4,100) M 0,0,100 A 3,(RBOB9,72)(RBOB10,128) M 6,0,1 M 0,0,499 A 1,(RBOB4,50) M -6,0,1 M 0,0,49 A 15,(//RBOB6,6)(//RBOB5,6)(//RBOB4,6)(//RBOB7,6)(//RBOB8,6)(//RBOB7,6)(//RBOB4,6)... ... A 1,(//RBOB4,500) M 6,0,1 M 0,0,499 J S The pattern contains three things: * Labels and jumps to labels * Animation commands (A...) * Movement commands (M...) S: is simply a label allowing us to repeat the entire sequence of commands indefinitely by jumping back to the S: label from the very end of the commands sequence with the J(ump to) S command. The rest of the script is made up of "blocks" where we first specify an animation sequence, and how many times it should be repeated, and then one or more movement commands that decide how the object is to be moved during that animation. In the M(ove) commands, the first number is the number of pixels to move left or right (negative numbers = left), the second is the number of pixels to move up or down (negative numbers = up), and the third is the number of frames the movement should take. Note that only the M(ove) commands control the timing of the program. If one or move M(ove) commands before the A(nimation) command has run out of frames to display, the program still moves on to the next A(nimation) command. This means that: In most cases, the total number of frames that the A(nimation) command takes should match the number of frames the corresponding M(ove) command(s) will take. This way, the entire animation will keep in sync. To specify a "still image" in the middle of the pattern, do like this: A 1,(RBOB4,100) M 0,0,100 Here, RBOB4 is shown for a hundred frames, and during that time, the M 0,0,100 command keeps it still, because it is told to move nowhere (0,0). 14.6 Flipped images ------------------- As discussed in the section on image definitions in the graal.main file, you can easily "flip" an image left/right by prefixing the number with two slashes ( // ). However, there is a catch: You cannot safely use both the normal and the flipped image on screen at the same time - unpredictable results will occur if you do so! The rule is, if you run the risk of having the same image in both the original and the flipped version on screen at the same time, you have to make the flipped version into a proper image in the image bank, with its own image number. 14.7 All About 3D and Hotspots ------------------------------ GRAAL rooms are usually displayed in a "simulated 3D" perspective (although top-down views can be achieved). This basically means that the things slightly higher up the picture seem "further away" than the things towards the lower end of the picture. Take the harbour in "Olaf" as an example: When Olaf walks towards the water and the edge of the quay, he's actually only moving a number of pixels up the screen - there is no such thing as "away", because the screen can never really be anything but 2D. This simple fact allows us to play with foreground and background objects. Anything placed towards the bottom of the screen will, generally speaking, be "in front". I'm talking about objects as well as STATIC: and ANIM: images now, mind you - everything drawn directly onto the background picture will naturally always be part of the background! So, as a rule anything lower down goes "in front" of anything further up, but that's not necessarily the way we want people to perceive things - take the mug on top of the barrel in the bar, for instance. Looking only at the placement of the images of the mug and the barrel, the mug should logically be partly hidden by the barrel, because it is further up the picture. It's not. Instead, it looks like it is placed ON the barrel, which is what we want. Also, when Olaf walks behind the barrel, he must also walk behind the mug - if the mug is on the barrel but Olaf seems to be walking in front of the mug but behind the barrel, everything becomes hideously unrealistic. The answer to this problem? It's simply a matter of setting each image's hotspot correctly. The hotspot is the point of each image that will actually be placed at the x and y coordinate specified when displaying the image. Each image has its own hotspot, and it is normally set when the image is loaded with a ...BOBS: statement (the last parameter - look it up in the reference). The GRAAL default is to place the hotspot at the middle of the bottom edge of the image - you might say at the "foot" of the image. This is normally very appropriate, especially so for people and living objects. But you can place the hotspot anywhere you like - if you specify a value other than the default, the hotspot will be offset in the y direction that number of pixels from the top edge of the image. Both negative and positive values are allowed. Study the ROOMBOBS: statement for the mug image in room one, compare that to the mug's x and y position in the OBJECT: statement in graal.main, and you will see that the hotspot is placed well below the actual image, making it the "frontmost" object in the bar. The hotspot of an image can also be altered using the HOTSP command - this is used in some cutscenes dealing with the ship in the harbour, to switch the depth-placing of the sail. This is because the captain first walks behind the sail, but when summoned ashore, he suddenly has to go in front of it! The solution? Just alter the sail's hotspot...! 14.8 Scaling the Characters --------------------------- Starting with GRAAL 2.2, the characters under player control can be automatically scaled to match the simulated 3D perspective in your backdrop. (You should only use this in rooms where you really need it, because the scaled images never look as good as the original-sized ones.) It is demonstrated in room 2 of the demo adventure, where Olaf gets a lot smaller when walking into the alley. To begin with, the 3D scaling process relies on the information about graphics stored in the CHAR: statements in graal.main. So even if you only have one controllable character, you have to create a global object and a CHAR: statement for it, as discussed in "Multiple Characters and Inventories" on page 42. After that, the process is a simple one: At the very start of a room script, put a 3D: statement. (See the on-line reference for details). Each parameter in the 3D: statement defines a vertical line on screen, and above each line, the character will be a little smaller than below it. If the character is below the first line, it will retain its original size as drawn by you. If the character is above the last line, it is at its minimum size (25%, that is, half the height an half the width). The 3D scaling works with the SAY, MOBJ, HANDLE, CMOVE, CBOB and CPOS commands, and the IFCBOB condition. This means you shouldn't use OMOVE or SHOW to move or animate controllable characters, unless you know exactly where in the room the animations will be used and can make them according to that size. If you handle more than one controllable character in the same room, you probably need to use the SWITCH command a lot so you can animate each character with the above commands rather than relying on OMOVE and SHOW. By setting some of the "scaling lines" outside the scene area, you can force GRAAL to only use one or two of the scaled sizes. I have used this in 7.room, where Olaf is only shown in the minimum size, because all the scaling lines are put below the displayed scene area. Note 1: If you use the BOBS command to load a new set of global images that make up the graphics for one of your characters, you will have to issue the MAKE3D command afterwards to recreate the scaled versions of the images as well. Note 2: If you use the FOLLOW command (see "Characters Following Characters Around..." on page 46), take care to lay out floors and paths so that the following character always ends up the same size as the controlled character. Otherwise, it usually looks plain ugly. 15 Cutscenes ============== CUTSCENES are simply script files (suffixed with .scene) that contain nothing but commands. That's right - no conditions, and no statements! This means lines should NOT start with ACTION: or anything like that - just fire away with the command name in column one of each line! You can include several commands on the same line just like in ACTION: statements as long as you separate them with semi-colons. Depending on the command used to start the cutscene, the command area either disappears completely, has a special "cut- scene icon" overlaying part of it, or remains totally unaffected (although still unusable until the cutscene has ended). You may use this to alter the degree of "movie-feel" the cutscene invokes. Cutscenes that are so short that the player hardly notices anything special happening control-wise should NOT mess with the display of the command area. The immense usefulness of cutscenes may not be apparent at first, but you will soon find out that you use quite a lot of them - because in addition to being used for "movie scenes", they are also very handy whenever you have a sequence of GRAAL commands that you need to use in a lot of different places. In these cases, cutscenes can act the way procedures or subroutines do in ordinary programming languages. In those cases, you must make sure the entire cutscene is executed, and you probably don't want to show the cutscene indicator to the player. It's easy enough - just read on! The logic of cutscenes ought to be a fairly simple subject, since there are no conditions allowed in them. In practice, two things require you to think very carefully about designing your cutscenes: The "skip" function (pressing the [Esc] key to jump past a cutscene) and nested cutscenes. 15.1 Hop, Skip and Jump ----------------------- Normally, a cutscene consists of two parts: The main part at the top, always containing ALL the actions in the scene, and the FINAL section at the end. The FINAL section is ONLY used if the [Esc] key was pressed during execution of the main part. It must duplicate all statements necessary to set the scene exactly the same way it would have been set if the main part had been run through completely. Remember, you never know exactly where in the flow of the main part the player decides to press [Esc] and breaks out of the action! 15.2 No Breaks! --------------- In some circumstances, for example when you use cutscenes as "subroutines" as discussed above, you may not want the skip option to be in effect. In this case, start the entire cutscene with the cutscene command NOBREAK, which disables the [Esc] key for the duration of the cutscene. If a cutscene starts with NOBREAK, you don't need a FINAL section in it. 15.3 Nesting ------------ Now, to complicate things even further, cutscenes may be nested in up to three levels - that is, you can execute a cutscene within a cutscene from within a cutscene! "Why on earth would I want to do that?" you ask. Well, a good example is the harbour scene in room 3 of "Olaf". There are a number of occasions when Olaf needs to interact with the captain, calling him ashore time and time again. The captain's going ashore and aboard can not be handled as simple PTRN sequences, because he, the ship itself, and the sail need to be rearranged in various ways to make the captain go behind the sail, in front of the sail but behind the gangplank, etc. Therefore, the captain going ashore is played using one cutscene, the going aboard in another (well, actually two, depending on whether his hat is secured with the rubber band or not). These cutscenes are then used from within, or in conjunction with, a number of others specifying what is going on when the captain comes ashore to talk to Olaf. Let us call the first cutscene the "master scene" and those called from within that "sub-scenes". Now, what we have to watch out for is this: If we press [Esc] at the very beginning of the master scene, or indeed anywhere before the last sub-scene, this means some of the sub-scenes will not come into play at all. However, the contents in each sub-scene may affect how the game should be set up at the end of the master scene. To conclusion is that the FINAL section of the master scene also must include all statements that are present in the FINAL sections of the relevant sub-scenes. Let's look at Olaf and the captain again, when Olaf tries to use the dictionary on the captain and gets it all wrong. This is depicted in CUTSCENE 13 structured like this: 1. First, CUTSCENE 2 is called as a sub-scene to make the captain come ashore. Note: Sub-scenes should always be called with parameter ,F or ,NF to stop the cutscene indicator symbol flickering on the screen. The master scene should be called with parameter ,S or N because when it's finished, the whole scene is finished. 2. Then, Olaf tries to speak hindi or something like that, fails miserably, and is knocked down. 3. While Olaf is still on the ground recovering, CUTSCENE 3 is invoked to put the captain back aboard the ship. 4. Once the captain is back aboard, Olaf gets up and notes that the whole endeavour wasn't particularly successful. 5. The FINAL section of the master scene CUTSCENE 13 then needs to contain the following: The commands from the FINAL section of CUTSCENE 3, because those make sure the captain is back in place aboard the ship, and some commands to put Olaf back on his feet in the right position. We do NOT have to bother about anything in CUTSCENE 2, because the captain's coming ashore does not have anything to do with how things look after the master scene is finished. 16 Timer Events ----------------- GRAAL contains a number of functions that can make things happen at regular or irregular intervals more or less independent of the movements of your controlled character. First, you use a DOAFTER command to set one of three "timer devices" to go off after a certain period of time (and this can also be a random amount). Next, you specify a number of ACTION: -1;... statements, because each time a timer reaches zero, it goes through the list of ACTION: -1;... statements to see if it should do anything. (Each timer - there can be up to three running at the same time - uses its own "fake object number", so you can use IFOBJ conditions to see what statements belong to which timer if you have several running simultaneously.) The timer will go on repeating itself, until you issue a CANCEL command for it. If you want the time between the timer events to change continuously, you should end each ACTION: -1,... command sequence with another DOAFTER for the same timer, specifying another random interval. The timer device called "0" is a little special. It doesn't check the time elapsed since the DOAFTER command, but rather how long the player has been inactive. You can use this to trigger "stall anims" (like the one in "Simon the Sorcerer", where Simon puts on his headphones when nothing happens). Normally, the cursor will flicker during execution of the ACTION: -1;... statements, because as always the player can't do anything while a command sequence is being executed. However, if the timer events are performed very quickly, you can use a TCURS OFF command to stop the cursor from disappearing. One of the uses for a timer is the concept of in-game date and time. GRAAL contains a number of commands and layout statements to set, advance, check, and automatically display the date and time, even on an analogue clock face with hands for the hours and minutes. (These things are displayed in special, reserved sections of the command area.) There is more on each of these subjects in the command descriptions in the on-line reference. 17 Special Techniques or "How The Heck Did He Do That?" ========================================================= This is a walk-through of some of the particularly clever stuff in the Olaf script files. I hope this proves that I have tried not only to solve a limited set of specific problems when writing GRAAL, but provided a set of commands that are flexible enough to allow even the nearly impossible to be done without an endless array of "novelty gadgets". 17.1 The Load / Save Room. -------------------------- GRAAL has some dull, built-in requesters for saving, loading and quitting games, but the demo adventure shows how you can customize these features using a special room. The room is called by clicking verb 10, which is represented on screen by a diskette icon. Because the load/save room should be available everywhere, the code for jumping to it is in an ACTION: 10;... statement in graal.main, containing the following: * We set a flag to remind ourselves about the missing command area - see below. * Next, we need to issue a MARK command - this is absolutely essential. Not only do we need it to get back to the same place when backing out from the load/save room, but we actually use the MARKed data when saving the game! (We can't just SAVE directly in the load/save room, because then we would save - the load/save room position!) * The next one may seem a little odd: We issue an EDLG command. This is because from GRAAL 2.2, you can call load/ save routines from within a dialogue, and if we were in dialogue mode, we need to get out of it in order to access the buttons and stuff in the load/save room. (When you load a saved game, the correct mode is automatically switched on again.) * Because we will not need the command area in the load/save room, we hide it with a COMAREA OFF command. * After all of this, we jump to room 40, which is the load/save room. Study the code to see how IFNOTSAVEDISK is used to ensure we have a place to save the game, and how IFEXISTS is used to check for existing, saved games and to alter the appearance of the save/load buttons and game slots according to what's available at each moment. Now, if we back out from the load/save room, we'd like the command area back in place, thank you very much. Well, the "backing out" is handled by either a LOAD or a RESUME command, and both makes GRAAL look through the ACTION: -2... statements. So, all we have to do is have such a statement checking the flag we set earlier, and issue a COMAREA ON command to put the command area back where it belongs. (In Olaf, some rooms don't use the command area at all, so we also have an extra flag, set in each room, to test if we should do a COMAREA ON or not when loading a saved game.) Note: If you have designed your own save/load/quit functions, you could disable the ordinary short-cut keys for the standard requesters in the finished version of the game. You do this by putting a couple of DISABLE_... statements in the graal.main script. Or, you could define your own save/load commands, pointing to your newly designed room, and map the standard short-cut keys (S/L/Q) to these commands. You do not necessarily have to put the "clickable areas" for these commands inside the command area visible to the player - if you put the areas off the screen with some coordinates like 500;500;501;501, you force the player to use the short-cut keys to access those commands. Finally, remember that it is up to you to keep track of whether the command area is displayed or not every inch along the way - saving a game whilst the command area is not shown requires mechanisms to check out how it should be after each and every loading of a new game position. 17.2 Going into the Alley ------------------------- In room 2, there is an example of how an un-named exit can be used to cover an area and make special things happen when the player tries to direct his character to go there. In this case, the back of the alley is covered with an un-named exit. When the player clicks the alley for the first time, Olaf moves there and makes a comment about how very uninteresting it is. Then, a room flag is set, and the exit is hidden. From there on, the alley is just an ordinary part of the scene, and Olaf may walk in and out of the alley any number of times without anything special happening. The alley also demonstrates a typical use of the 3D scaling function - the way the 3D: statement is set up in 2.room, GRAAL uses 3 of the available character sizes to display Olaf, depending on how far into the alley he has gone. 17.3 Speaking In a Foreign Tongue --------------------------------- The conversation with Rajah Singh on the quay is rather special - you are forgiven for thinking a special font is being used to display the foreign language spoken by Rajah. However, this is not the case. Instead, I have combined a "blank" RESP command with BOBON and BOBOFF commands. Have a look in the 3.room file: First, the "foreign language" was "typed" in an ordinary picture (3FG.IFF) using DPAINT. Then, the "words" were grabbed as RBOBs using ROOMBOB: statements. Rajah's responses to Olaf dialogue lines are as follows: 1. First, a BOBON command is used to display the RBOB with the "foreign language". 2. Immediately upon that, a RESP command displaying nothing but blank spaces is used to make Rajah Singh "speak". The number of blank spaces determines the time it takes to execute the RESP command. 3. After that, a BOBOFF takes away the strange text again. Simple, eh? No need to construct an entire font (and no need for another GRAAL command to handle that font!). 17.4 An Automated Room ---------------------- As you may have noticed, you can never get into normal game mode in Ali Harrod's shop - As soon as you walk in, you end up in dialogue mode, and when you end the dialogue, you are immediately transported out of the boutique. This is thanks to the DACT statements, where the programmer can grab control and keep it for as long as he likes! Have a look in 4.room - there is not a single run- through of DACT statements not ending with a DSET... EXIT combination, forcing the player into dialogue mode. Therefore, there are no ACTION: statements either. This technique is useful in a lot of circumstances - many times, it relieves you of having to think up a lot of elaborate ideas for a room where you really don't want the player prowling around. 17.5 The Art of Avoiding a Seagull ---------------------------------- As long as the seagull in the harbour is sitting on the pollard, Olaf steers well clear of it when walking about. He simply walks where the room file FLOOR: statements say he can move! However, as soon as the seagull is scared off, Olaf is free to approach the pollard and pick up the feather. This is made possible by two FLOOR and one NFLOOR command executed in the cutscene where the seagull takes off (4.scene). Having chased the seagull away, one problem remains: The next time we re-enter the room, we want things to be the way they are now, and not according to how they are set up in the room file statements. A room flag comes to the rescue here - it allows us to "remember" the seagull status between visits to the room. Room flag 1 for the room (room 3) is used - as long as it is zero (the initial state), the seagull is on the pollard. As soon as the bird is scared off, we set the flag to 1 with a SETRF 1=1 command in the cutscene. This room flag is tested in a DACT: statement - if it is set to 1, the bird is moved to the roof of the shed, and the default floor definitions are changed exactly the same way as in cutscene 4. Remember, as long as the LIGHTS ON command has not been used, the scene remains black and we can move anything we want around without the player being aware of what is done! 17.6 A Spitting Image --------------------- The spitting llama on offer by Ali Harrod is composed of two animations, because I decided a single one would be too large. Instead, the llama itself is one animation, and the "spit" is another, very small one, animated by an AMAL "Move" command. The movement of the llama and spit animations are synchronised - the llama being displayed on top of the spit. (Well, almost synchronised. If you leave the llama sequence on and walk away for a quarter of an hour, you will notice that things have become a little strange when you return. But who could keep away from the game that long, anyway? And if you don't like it, you can always make one big animation of the whole thing!) 17.7 A Map Room --------------- I had planned on only delivering the first four rooms with GRAAL, but ended up giving you seven. The reason is some quite interesting techniques were used in room 5, which may come in handy. Room 5 is an outline map of the East, showing the towns of Constantinople, Gurgan and Baghdad. The thing is, there is no Olaf, and nothing to do except watch a short cutscene and, when revisiting, point to one of the three towns. Also, this room does not use the command area at all - instead, the scene area itself takes up more space, and the command area is hidden. Olaf was done away with by a simple CHAR OFF command in a DACT: statement - nothing strange about that (once you read the on-line reference). Remember that the main character will always be made visible when entering a new room, unless you put it away again with CHAR OFF. Because we don't need the command area for this room, each GOTO command leading into this room from other rooms is preceeded with a COMAREA OFF command. (See the load/save room above for more about hiding the command area.) In the room itself, a room flag for room 40 (the save/load room) is set to indicate the status of the command area (shown or hidden) - this flag is used in the save/ load procedures, as described in "The Load / Save Room." on page 58. We need to make sure the command area is replaced when entering a new room. The only rooms Olaf can go to from room 5 is room 6 and room 7, so in each of these, a COMAREA ON command in the DACT: statements prior to LIGHTS ON restores the command area. (Keep the COMAREA ON commands close to LIGHTS ON to make sure the command area disappears/re-appears in sync with the scene area.) By now, we have ensured the map, and ONLY the map, is shown on screen. The only thing the player can do in room 5 is to point to one of the three exits placed just over the towns on the map. I have chosen to display the exit names for the towns in the normal fashion when the mouse cursor moves over them, although I might just as well have put a blank space instead of names in the EXIT statements. The names of the towns are written on the map itself, and it shouldn't have taken the player too long to figure out where to click, anyway. 18 The On-line Monitor ======================== GRAAL's on-line monitor is a great help when things go wrong in your scripts. It allows you to examine flags and other information "on the fly", and also make temporary corrections. This helps to lower the number of times you have to restart GRAAL during the tests. (Naturally, the monitor cannot be called up from an encrypted game unless there is a DEBUG: statement in graal.main.) To invoke the monitor, simply press the [G] key. The monitor window pops up, covering the lower part of the screen. Here's a description of what it contains: Information lines At the very top are two lines of general information showing * The current room. * The last starting position used. * The current floor. * Whether the character is (should be) visible or not. The information in line two is mainly of interest in multiple- character games: * The number of the character currently under player control. * The number of the inventory currently used. * The number of the character following the controlled character (if any). Command field and < <- Execute > button, message field In this text field, you can type any valid GRAAL command, and then make GRAAL execute it with the < <- Execute > button next to the field. These are the commands your are likely to use most: * GOTO to jump to another room (or reload the current one). This command also automatically closes the monitor and thus replaces the old (2.0) monitor's < <- GOTO > button. * SETOF and SETRF to set flags. While GRAAL takes care of your request, the text * executing * will be shown in the message field at the very bottom of the window. If it goes OK, the text * OK * is shown. If GRAAL couldn't make sense of what you typed, the text * error * is shown instead. Make sure you get the syntax correct - often, any mistakes will make the dreaded GRAAL run-time error screen appear. Some rules: * You can only enter one command at a time. * You cannot enter conditions. * All input is automatically converted to upper case. * You can use ROBJ, SOBJ, RBOB and SBOB references. * While anything is possible, not everything is smart or even relevant at all times. Commands you probably don't want to execute from the monitor include SAVE, LOAD, MARK, RESUME and others that re-arrange a lot of stuff in GRAAL. < Back to GRAAL > button This button quits the monitor. Remember that some changes you attempt in the monitor may require re-loading the current room to take effect, in which case you should end the monitor session by executing a GOTO command instead. List buttons There are three buttons to list important information: * < Object List > shows a list of all objects - numbers, locations and flag contents. * < Room List > shows the contents of all room flags for all rooms. * < Inventories > shows a list of the contents of each inventory. < Trace > button This is a toggle button, deciding whether the single-trace debug mode is active or not. Click once to activate. The trace console will open at the top of the scene area. Then click < Back to GRAAL> and provide GRAAL with some input. As soon as GRAAL starts working on an input sentence, all conditions and commands about to be executed are shown in green in the trace console. For each command, you have to press a keyboard key to continue through the script. The full stop key is a good choice, because it also allows you to skip the pauses caused by commands like SAY and W(ait). The text colour in the trace window changes from green to red while the command is being executed. An empty trace window means GRAAL is waiting for more player input. GRAAL with the trace console active. Here it waits for us to acknowledge the next action - loading a sound sample for the bell. Note: In the trace console, object and image references are NOT converted back to ROBJ, RBOB, etc. references. For example, SBOB1 will show up as number 61 or something like that. To deactivate the trace mode, call up the monitor again and click < Trace > once more. The trace mode can also be activated and deactivated from within scripts with the TRACE ON and TRACE OFF commands. 19 Macros =========== Macros allow you to record a sequence of player input selections, store them in a file, and play them back later. The primary use is for testing - being able to play the same sequence of events back over and over again, and having it done automatically, makes testing a whole lot easier. They are especially useful for running through parts of the game which are really "finished", but still need to be tested from time to time to check that no alterations you have made to other parts of the game affects them, or when changes to scripts means you cannot use old saved game files to put you in the desired part of the game. The macro functions only work in development mode. In encrypted games, they are not available unless there is a DEBUG: statement in graal.main. 19.1 Starting a Macro Recording ------------------------------- 1. Start the game. Load a saved game, or go to the position from which you want to start the macro recording by playing the game in the normal way. 2. Press the [R] key. A message telling you that macro recording is activated is shown very briefly in the scene area. 3. From now on, every command you execute, and every exit or dialogue line you choose, will be recorded to memory. 19.2 Saving a Macro ------------------- 1. When you have reached the point where you want the macro to stop, press the [R] key again. 2. A dialogue box pops up, asking for a macro file name. The name you type will be suffixed with the text ".macro" 3. Click the "Save" button. The macro file is now stored in the development directory. 19.3 Playing a Macro -------------------- 1. Put the game is in EXACTLY THE SAME POSITION as when you started the macro recording. 2. Press the [P] key. A dialogue box appears, asking for the macro file name. Type the name - you do not have to enter the ".macro" part. 3. Click the "Load" button. 4. The contents of the macro are now re-played before your very eyes. Sit back, watch, and enjoy! 5. You may abort the playing of the macro at any time by pressing the [Esc] key between commands. Tip: Before playing a macro, you may want to put the text display at maximum speed by pressing the [ I ] key a number of times first. 19.4 Restrictions to Macro Playback ----------------------------------- The original timing of the player input is not preserved in the macros. When a macro is played back, execution of the next command starts as soon as the previous one is finished. This means macros are not suited for recording parts where the timing of player input is critical. In other words, if you are using the GRAAL timer functions, stop to think before you record macros. Changing the N_GLOBALBOBS:, N_SECTIONBOBS:, GLOBALOBJS: or SECTIONOBJS: statements offsets the image and object numbers, and previously recorded macros will stop working. That's a very good reason to set them reasonably high right from the beginning. 20 "Productifying" Your Adventures ==================================== 20.1 The Basics --------------- While developing your adventure, you have all the required files in one, big, happy development directory. When you need to distribute your finished work (or test versions) to other people, problems arise: 1. You only want to distribute the files needed for the adventure - not the GRAAL docs, utility programs and temporary work files which you probably also have in the development directory. 2. If the game should be playable from diskettes, you need a way to tell GRAAL which files are on which diskette, and you probably want to duplicate some frequently used files onto all the game diskettes. 3. Perhaps you want to encrypt and compress the files, saving disk space and making it very much harder for players to find the solution by cheating. This is how to go about it: 1. You put the information about which files belong to the finished game, and which diskette(s) they should be placed on, in the diskinfo.graal file. Use the GREP program (described below) to help you out. 2. This step is optional and can only be done by registered users: You run the GPRO program, which uses the diskinfo.graal file to copy all the required files from the development directory to a test directory (which must also be on hard disk). This makes it possible to test if all required files really were specified correctly in the diskinfo.graal file before making diskettes. It is during this step that GPRO also offers an option to encrypt and compress selected files. 3. You run the GDC program - either from the development or the test directory depending on whether you did step 2 above - which uses the diskinfo.graal file to copy the game files to diskettes. It also formats and labels each diskette so that GRAAL knows what diskette names to look for when disk swapping during play becomes necessary. 20.2 The diskinfo.graal File ---------------------------- GPRO and GDC rely on a "diskinfo" file to tell them which files should be copied, and which diskette each file is meant to end up on. A diskinfo file must contain the following: On line 2 (and nowhere else): The common part of the delivery diskette volume name, for example MYADVENTURE_DISK When GDC does its stuff later, the diskettes will then be labelled MYADVENTURE_DISK A MYADVENTURE_DISK B and so on. Below line 3: The names of all the files, grouped according to delivery diskette. Each file name is on its own line, preceded by the diskette suffix and a space. For example: A 1.room means the file 1.room is delivered on MYADVENTURE_DISK A. Remember: The files should be grouped according to volume, and the groups should be sorted alphabetically, starting with everything on diskette A. You may have as many comment lines and empty lines in between the file entries as you like. The following stuff should ALWAYS be on diskette A: 1) GRAAL_2 * The main program. It does not have to be called GRAAL_2 - rename it to anything you want your adventure called. 2) FONTS * A special entry which copies the entire fonts: drawer in your development directory. 3) graal.main The graal.main file 4) diskinfo.graal * 5) The picture files for the command and dialogue areas (if you don't specify DEFAULT, in which case the graphics included in the GRAAL_2 program itself are used). 6) The resource file for requesters (suffix .rsb). If you use the DEFAULT, no entry is needed - it's already in the GRAAL_2 program itself. The asterisk (*) after some of the file names tells GPRO not to compress and encrypt these files (see below). Apart from the files above, always mark all user documentation and icon (.info) files with asterisks in the same manner!! 20.3 GREP --------- Once your adventure becomes reasonably big, you may find it a bit difficult to keep track of all the files you use. The GREP program starts by inspecting the graal.main file, and from there it goes on to find all references to all files used by your adventure.(This, of course, requires that a proper START_ROOM: statement exists in graal.main, otherwise it will not find all the information.) GREP creates a report over what files are used where, and also gives you helpful suggestions regarding the contents of your diskinfo.graal file and some of the statement settings in graal.main. This information is saved in a file called graal.report. You can start GREP in two ways: * From the shell: Switch to the development drawer, type "run GREP". * From the Editor: Select the "Create Report" option in the GRAAL menu. The resulting file will automatically be loaded into a new window in the Editor. 20.4 GPRO --------- The GPRO program is used to copy the files that make up your adventure (the ones that should go on the delivery diskette) from the development directory (which can be a right old mess) to a test directory, containing only what is needed to run the adventure. You should test the adventure thoroughly in the test directory, making sure everything is included, before making the delivery diskettes. (GDC is automatically copied from development to this test directory by gpro, because you need it there to make the diskettes.) This program is only available to registered users (in other words, it needs the personal keyfile to work). Unregistered users are confined to copying the game files directly onto the delivery diskettes from the development directory using GDC, and then testing the diskettes. Starting GPRO """"""""""""" GPRO runs from CLI only. Open a shell, and switch to your development directory. Then type "RUN GPRO". (Don't forget the "RUN" bit, or GPRO may lock up during the copying process!) GPRO now checks if there is a valid graal.key file in the directory. If not, it will say so, urge you to register GRAAL, and terminate. The user interface is as follows: Encrypt: < > Yes: Compress and encrypt files not marked by an asterisk in the diskinfo.graal file. See "Compressing and encrypting" below. < > No: Do a normal file copy. Simulation: < > Click this if you just want to test the contents of the diskinfo file. The Copy function will just "go through the motions", showing what would happen if you had been copying for real. Diskinfo: You can choose the name of the diskinfo file to use here. You can, for example, have one diskinfo file for demo versions and one for "live" versions in your development directory. (I use this facility to produce a GRAAL delivery from the "Olaf" development directory, which normally produces only the "Olaf" game itself.) Note that the selected file is renamed "diskinfo.graal" (the default name) in the destination directory, and therefore, "diskinfo.graal" is the name that should ALWAYS be used when referring to the diskinfo file IN the diskinfo file! Destination: The name of a hard disk directory, which, by the way, must exist already. GPRO saves the names of the last diskinfo file and destination directory in a file, and so remembers the settings until the next time it is used. Status bar A green stripe shows how far the copying has progressed. Message field A text shows what is currently going on during the copy operation. Copy and Exit buttons Really... you'll just have to find out for yourself! Compressing and encrypting """""""""""""""""""""""""" Almost all files can be compressed and encrypted during the copying process. There are two benefits to this: You save disk space, and both graphics and text files are rendered unreadable to your users except through the GRAAL_2 program. The following files/diskinfo entries should NEVER be compressed during copying: GRAAL_2 icon files documentation files graal.key diskinfo.graal To make sure a file is never encrypted, just put a space and an asterisk after the file name in the diskinfo.graal file, for example: A Disk.info * A GRAAL_2 * A GRAAL_2.info * Of course, you may want to compress GRAAL_2 to save disk space, but do so before the final copying process, and use a utility that creates a self-decompressing executable file (like PowerPacker or CrunchMania). Note that encrypted games ALWAYS require the keyfile to run, so include an entry for the keyfile (on diskette A) in the diskinfo file when you produce the final, encrypted master diskettes. The compression routine puts the emphasis on speed rather than efficiency. On average, 30%-40% less space is used by a compressed adventure. The percentage gained varies greatly with the structure and complexity of the files. Some examples: 120K tracker module gained 42% 24K complex bg picture gained 20% 12K simple clipart picture gained 54% 24K script file gained 50% 48K IFF sample w. "silent" parts gained 38% GRAAL games with compressed files require up to 200K or so extra RAM space to do their job. Running a reasonably large adventure thus takes a little more than 1,5MB... On fast machines, I perceive a performance increase running compressed games, but perhaps that's only my imagination... It's not unreasonable, though, that the reduced disk access more than makes up for the unpacking time. On slow machines, the unpacking time becomes more noticeable, and running a GRAAL game on an unexpanded 68000 machine with no memory cacheing can be a nuisance. To help out a little, consider NOT compressing and encrypting long sound samples, and perhaps you could leave the tracker modules alone, too. Because the tracker modules are probably the biggest files you have, this will also save some working space (perhaps a 100K or so). 20.5 GDC -------- GDC is the program that copies the game files to the final delivery diskettes. You MUST use this program to prepare the diskettes. However, GDC is not intended for making copies of the game. Just use GDC to make the "master diskettes", and then use some proper diskette copying software for the copies. Note: ALWAYS wait for disk activity to finish completing before responding to any prompt telling you to switch diskettes or that the copying procedure has finished! If you have run GPRO, the GDC program was copied to the test directory automatically, and you should run it from there. If you don't have access to GPRO, you run GDC directly from the development directory. GDC runs from CLI only. Open a shell, and switch to the appropriate directory. Then type "RUN GDC". (Don't forget the "RUN" bit, or GDC may lock up during the copying process!) Format radio buttons To prepare the diskettes, and label them properly, GDC first formats each diskette. This can be done quickly, if the diskette has been preformatted, or in the normal fashion, in which case the previous formatting status of the disk is not important. Check Sizes button This is normally done automatically when you start GDC. The "gauges" or "meters" labelled A, B, and so on, are updated to show how much space is used on each disk. If you have specified too much for a certain volume in the diskinfo file, the top of that meter turns red to show that you must edit the diskinfo file and re- distribute the files to make it all fit. (We're talking standard DD diskettes here, of course.) If you have left GDC running while editing the file, you could use the button to re-calculate the space requirements. On the other hand, it might be a good idea to exit the program, make sure you update the right file in the right place, and only then re-run GDC... Status bar When you press Copy, each diskette meter in turn is gradually emptied, and this line starts growing instead to show how far the copy operation has progressed. Message field If anything goes wrong, this is where you will get told. Copy and Exit buttons Once more, pretty obvious... You don't need more than 18 diskettes, do you? Please! Tell me you don't! EXTREMELY NICE TIP: It's good practice to keep the diskinfo.graal file updated during development. Start GDC now and then to see if the distribution of files seem about right with respect to the space requirements... Also, use GREP to check that the diskinfo.graal information is correct. 21 The Editor =============== 21.1 Introduction ----------------- This is a neat little (well, growing bigger all the time, actually) editor, making life in the GRAAL script-writing lane much easier than it otherwise would be. At first, you may find the concept behind it all slightly confusing. While other "user-friendly" games development systems opt for point-and-click control of everything, storing the results away in cryptic databases, GRAAL is basically made up of ASCII scripts that can be created using any text editor. While this means more typing and requires a deeper understanding of what's going on, it also has some definite advantages. It means greater flexibility in your creations, a better overview, and a total freedom when it comes to documenting the scripts via comment lines. And the GRAAL editor steps in to bring you the best of the "point'n'click world", too. It makes the typing of the scripts a lot easier, and you will not want to be without it. In short, the editor spares you from annoying things such as trying to remember what script does what, what the parameters of that "OBJECT:" statement mean, and what the coordinates of your last 6 FLOOR: and PATH: definitions actually looks like on screen. The end result is the same as you would get with any other editor, though - ASCII script files with lists of GRAAL statements and commands. In addition, the GRAAL editor has the following advantages: * It handles multiple scripts in multiple windows simultaneously, with easy switching, copying and pasting between them. * It is connected to the on-line reference, giving help on statements and commands. * It keeps track of used and unused room, section, scene, and ptrn numbers. * Although many features are GRAAL-related, it is perfectly possible to use this editor to edit any kind of ASCII text file. You will probably find it a good alternative. Enjoy! The editor handles files up to 5000 lines long. (If you have GRAAL scripts that long, you are probably in need of professional help :-) 21.2 System Requirements ------------------------ This editor needs Workbench 2.0 or better to work. amigaguide.library v. 34 or later must be in your LIBS: drawer. (This can be found for free on Aminet.) On AGA machines, the editor screen "clones" your Workbench setting by default. If you have a hi-res Workbench, it uses a hi-res screen; with a Productivity Workbench, it opens in Productivity mode... you get the picture. Just make sure that your Workbench is at least 640 pixels wide, and everything should operate smoothly. (The screen mode can be customised using the tooltypes in the GRAAL Editor icon - see the end of this chapter.) On non-AGA machines, a normal hi-res, non-interlaced screen is always used. Also note that the editor must be placed in your game development library on your hard disk for all file fetching routines to operate without problems. The GRAAL.guide file should also be placed in the same directory. 21.3 Known Bugs & Irritating Facts ---------------------------------- * A block marked for editing and contained in a single screen line is sometimes not properly highlighted on screen. However, the copy/cut/delete functions still work. * Adding lines to the end of the file in Overstrike Mode doesn't work properly. * If you use a 68030 or better processor, you may have to turn CPU caches off before using the Editor. Otherwise, graphics in the graphical editing functions may not display properly and make you unnecessarily confused. The way to switch off caches is to open a CLI shell, and type CPU NOCACHE NOBURST 21.4 Creating a New Script -------------------------- Since the editor expects to be placed in your GRAAL development directory, it checks for a graal.main file in the current directory at start-up - without such a file, you don't really have much of a development environment! If there is no graal.main file, the editor asks if one should be created. If you answer "yes", a template for such a script will be created in the editing window (which makes up the main part of the editor display). You can also use the "New" option in the "Project" menu to create a new file. The "New" option has six suboptions. The first one, "empty", just opens a new, empty editing window on top of the first one. The editor handles up to ten script windows simultaneously, and you can switch between them quite easily with the "Select Window" option in the "Edit" menu (or [Amiga>+[W>). The suboption "graal.main" creates a graal.main script template, as discussed above. The last four suboptions, ".room", ".section", ".scene", and ".ptrn" creates a template for the specified script type. Before the template is shown, a requester pops up showing a recommended script number - this number is the first number not already occupied by any of the existing scripts. You can change it if you wish, but remember that it's a waste of space leaving unnecessary gaps in the number sequences. The requester also has a gadget for a short script description - you should enter a meaningful description of the room, cutscene or whatever here. This comment is placed in the first (comment) line of the script, and you will see why it's so useful is a very short while... in the next section, as it were! 21.5 Working with the Editor ---------------------------- Loading Existing Scripts """""""""""""""""""""""" Just like the "New" option, the "Load" option, also in the "Project" menu, has the same selection of suboptions as the "New" option. (The only difference is that "empty" is called "general" here.) "Load general" brings up an ordinary file requester. "Load graal.main file" loads the graal.main straight away - not much use asking for its name, because it's always the same. "Load .room file" and so on brings up a list requester showing the numbers and descriptions (see above) of all existing scripts of the desired type, neatly sorted in ascending order. Most of the time, you probably want to open a script in a new window, which is why you should use the "Load Another" option instead. It looks exactly like the "Load" options, but in this case, the suboptions have keyboard short-cuts ([amiga>+[3-8>). Learn to use them, as this is the quickest way to open scripts. Note: .scene files with a space in the name will not be properly treated by the loader. Simply put, do not use spaces in file names. The Templates and the Syntax Checker """""""""""""""""""""""""""""""""""" Some statements in the templates have suggested parameters already filled in but in most cases, there is no point in giving a suggestion because the correct parameters are very much up to yourself. You can see this quite easily: 1. Create a new .room script, making the editor give you a room script template. 2. Now press the button marked "Syntax". This will make the editor check the script in the current window for syntax errors, and it will not be very long before it comes upon a statement with no parameter filled in. It then displays an error message telling you about the problem, and it also marks the statement where the error occurs. The syntax checker is a great help, but it does not find every possible error. This is what it does: * It checks the names of all statements. * It checks that all mandatory statements are in place. However, note that some statements may depend on others to work, and this is not checked by this function. Be particularly careful with graphics, and make sure the correct CLPART: statement is in effect in every situation requiring CLPART pictures! * It checks the number of parameters for all statements (except for statements with a variable number of parameters). * For all parameters that may consist of conditions, commands, or both, it checks the name of each condition and command. If any error is found, the offending statement / command is highlighted, and the nature of the error is shown in a requester as described above. All this should make development a little less frustrating. However, GRAAL itself checks a lot of other stuff too, and will still throw runtime errors at you from time to time. Further improvements will probably appear over time. Note: The syntax checker uses the file name suffix to determine what statements and commands are allowed - so it can only be used in files following the GRAAL naming conventions. And it does NOT work with .ptrn files. Amigaguide Help """"""""""""""" If you place the cursor on a statement or command word and press the HELP key, the amigaguide reference file graal.guide is opened with the relevant topic displayed. (The small button does the same thing.) Note that just like the syntax checker, the help function uses the file name suffix to determine what statements and commands are allowed - so it can only be used in files following the GRAAL naming conventions. Normal Editing Functions """""""""""""""""""""""" I will not bother you too much about the functions that you are likely to encounter in any text editor. You should find the find & replace options, and the other options of the "Edit" menu, quite adequate for the job at hand. Just a few words about useful keyboard keys: [shift]+[down arrow] [shift]+[up arrow] These keys scrolls the script one page at a time. [shift]+[right arrow] Moves the cursor past the last character of the line. [shift]+[left arrow] Moves the cursor to the beginning of the line. [control]+[right arrow] Moves to the next semi-colon of the line; that is, to the next GRAAL statement parameter. [Esc] Closes the current window. [Enter] Exits a string gadget (for example, in the Find window), or carries out a function (for example, "Find" in the find window, once the cursor is not in a string gadget any more). Other available short-cut keys are all listed in the menus. Marking Text Using the Mouse """""""""""""""""""""""""""" Apart from marking text blocks with [amiga>+[1> and [amiga>+[2>, you can use the mouse: 1. Click the first character of the block. 2. Hold down a [shift> key and click the character immediately to the right of the last character of the block. (Clicking the first character of a line will mark the entire previous line.) The Status Bar """""""""""""" Some useful bits of information are shown in the "status bar" immediately above the editing windows: * Cursor row (r) and column (c) position. * Insert (I) or overstrike (O) write mode. * Number of changes made since the last save. Note that some "big" operations, like inserting a block of text, only count as one change each! * Time. The clock is only updated when you do something in the editor, like moving the cursor. button """""""""""" The button (which has a small GRAAL symbol on it) tries to start the GRAAL driver as a separate process. By default, it assumes the name of the GRAAL driver program is GRAAL_2. This can be changed using tooltypes in the GRAAL Editor icon. (See the end of this chapter.) "Quick LOCATE" Buttons """""""""""""""""""""" To help you quickly locate those parts of a script file which are most often edited, four buttons have been provided. For example, clicking takes you to the first occurrence of "ACTION:" in the file. Switching between Windows """"""""""""""""""""""""" When writing GRAAL scripts, you very often need to make changes to two or more script files almost simultaneously. Fortunately, the GRAAL editor really excels at this. Use [amiga>+[w> to open a window containing a list of all currently open editing windows and their contents. In addition, all windows where unsaved changes exist are marked with an asterisk ( * ) before the window number. Click on any name in the list, and that window will become active and placed on top of the other windows. You can also use the cursor keys and select a window with the [enter> key. In fact, the GRAAL text editing functions have been designed to make as little use of the mouse as possible - the keyboard is much faster once you get accustomed to using all short-cut keys. If you need to view more than one script at the same time, just resize the editing windows and place them next to each other - nothing could be simpler. (Though I must confess I don't use this much myself - window switching is so much easier!) 21.6 Creating a Report ---------------------- The "Create Report" option in the GRAAL menu starts the GREP program, provided it is in the development drawer. When the program has finished, the resulting report (always called graal.report) is loaded into a new window in the Editor for viewing (and possibly some cutting and pasting as well). The GREP program is described elsewhere in this manual. 21.7 The Parameter Editor ------------------------- Instead of typing the parameters of all statements and commands, separating them with ";" or "," characters, you can edit the parameters in a window, with each parameter neatly contained in its own string gadget. This is how to do it: 1. Place the cursor on a statement or command - the actual NAME, mind you, not on one of the parameters. 2. Press [right Amiga] + [E] or click the button. 3. A window opens, with all parameters neatly laid out in string gadgets. The number of string gadgets available equals the number of parameters. Repetitive parameters (surrounded by brackets {} in the syntax description) only get one string gadget. You could type the parameters there, but it's often easier to do these in the normal editor "typewriter" mode. The lead text for each gadget is taken from the syntax help - if it's longer than 15 characters, the leftmost characters will not be visible, which may look a little funny at times. Oh well... The Parameter Editor window - this one with an OBJECT: statement loaded. Keyboard Short-cuts """"""""""""""""""" There are a number of short-cut keys to help you reach the different parts and functions of the window. They can only be used when the cursor is not in an input string gadget. That means after you have entered text into a gadget, press [Enter] to exit the gadget to make the short-cut keys available. Specifically: * When you press the [Tab] key, the next string gadget (following the last activated one) will be activated. * When you press the [Enter] key whilst not in an active gadget, or click , any changes you have made will be inserted into the script file. * When you press the [Esc] key or click , the changes you've started to make will be forgotten, and the window is closed without any alterations to the script. * When you press [Help] or click , the amigaguide help for the current statement or command is shown. When you've done reading up on the subject, press [Esc] to return to the parameter window. * The graphical editing functions have keyboard short-cuts [F1] to [F7], as listed further on. Optional Parameters """"""""""""""""""" Optional parameters are shown in blue. Consult the on-line reference for information about when to use them (and not). Cycle Buttons """"""""""""" If the button to the right of a string gadget is available, you can press this to cycle through the valid alternatives for the parameter. The contents of the gadget will change as you click the button repeatedly. UPPERCASE text entered by the cycle button should be kept as is. Occasionally, a text in lowercase may appear, which you should change to a proper value. For example, if the text "obj" is shown as one of the cycle alternatives, this means you should replace "obj" with a proper object number. Graphical Editing """"""""""""""""" A lot of parameters have to do with specifying co-ordinates, positions and other stuff related to a backdrop picture. You very sledom have to enter the values of these parameters manually - instead, there are a number of special functions to let you do this graphically. If a statement or command contain parameters which can be edited in this way, one or more of the special editing buttons beneath the string gadgets will become available. They also have keyboard short-cuts in the form of keys [F1] to [F8]. Usually, the editor finds the relevant backdrop picture and room file to use automatically, but may occasionally ask you for a file name when it cannot decide which part of the adventure you are referring to. Sometimes, the editor asks "Reload the object and image data?". If you haven't altered any images, or switched rooms or anything since the last time you used the graphical editing functions, you can answer "no", which speeds up the process. If the backdrop picture is one of the rooms in your game, all previously defined objects placed in that room are also shown for reference. In many cases, floors and paths are also shown, with their respective numbers shown close to the center of the each floor and path. If the backdrop picture is wider than the screen, use the left and right cursor keys to scroll it. Note: If objects overlap, the editor does not bother to sort them in the proper order. The details of all the "graphical editing" operations are explained below, and there is also a brief help text on a screen directly below the picture you are about to edit. Once you are done, press "Enter" to save the changes, or "Esc" to cancel. Important Tips """""""""""""" * Make sure all statements and commands specifying picture file names, which help the editor choose the right file, are entered as early as possible in the script-writing process. * Remember that the editor mainly loads data from the files saved to disk, not from unsaved versions of the files still in the editor. Therefore, you should usually save changes before going to the parameter editor. * When selecting character images in multiple character games, note that most character-related statements and commands expect you to specify the image of character 1, which will be replaced by the corresponding image for the currently controlled character automatically. See "Multiple Characters and Inventories" on page 42. Now, a closer look at the "graphical editing" buttons: [F1] """"""""""" An area or "frame" is a rectangle that can be moved around the screen and re-sized. It is used to cut out clipart graphics, and for specifying areas for exits, floors, and a number of other things. To re-size, click and drag the bottom left corner (the little square) of the rectangle. To move the rectangle, click and drag anywhere else on the screen. If you use this option to edit the cut-out frames for BOB images, you will get a number of rectangles on screen corresponding to the number of images to be cut out by the ...BOBS: statement. Use the leftmost rectangle to re-size: all duplicate frames will also be re- sized automatically. To alter the spacing between the frames, use the up and down cursor keys. Editing areas for a BOBS: statement. If you look closely, you may be able to see the 10 cut-out frames on the second row of images in this screen shot (it's easier in real life :). [F2] """"""""""""""" This edits the position of an image, and possibly also the image number. If the previous position and image used are known, the object or image will start out in its old position. Click and hold the mouse button. Drag the mouse to move the image to the desired location and release. (If it's an object, a copy of the image will remain the object's previous position when you drag the image.) To select another image, use the up and down cursor keys. To flip the image left/right, press the "x" key. Note: When you save the changes with the "Enter" key, the selected image will normally be placed in the "image" parameter. However, if the "image" parameter previously contained an animation sequence or a PTRN specification, it will NOT be affected. This is to prevent a lot of hard work being undone by an over-smart editor... [F3] """"""""""""""" This is exactly the same as editing an image position, except the parameters specify the upper left corner of the image, not the hotspot position. This is nothing YOU have to worry about - the Editor will make the correct button available and also take care of which co-ordinate goes where. [F4] """"""""""""""" Very similar to the previous two, but only available when editing an object. This sets the main character's position relative to the object, used in the MOBJ command. The image used for the main character can also be altered. The same rules as for the object positioning apply. As from GRAAL 2.2, the Editor asks you if the character width should be taken into consideration. Answering "yes" means GRAAL will calculate the position of the edge of the character closest to the object, rather than the center of the image. This is only a concern if you have multiple characters with varying widths that can try to manipulate the object. [F5] """"""""""" This one edits the line for a PATH: statement. Each point on the line (there may be up to 6 of them) has a "handle" in the form of a small square. Just click within the handle and drag to move the point to a new place. To add a new point, press the "arrow up" key. The new point will be inserted between the last and the second last point. To delete a point, press the "arrow down" key. It is always the second last point that is deleted. [F6] """""""""" This one's a little different. Many commands require colour numbers to be specified, and this helps to pick the correct palette index number directly from the palette of the relevant backdrop picture. When the picture is shown, a palette overlays the upper left corner of the picture. The text above the screen tells you to click on a colour - the "normal ink" colour for things like text displays, and the "background ink", which is the colour most functions use to erase or clean up unwanted parts of the picture. The "highlight ink" colour is only used in the sentence display area. It is the colour used when a completed sentence is highlighted during command execution. [F7] """"""""""" Not a very graphical function, but this button can be used to select a file name. If you have an AGA machine, the file requester that pops up will show only files of certain types, depending on the statement or command you are currently editing. For example, for the BG_IFF: statement, only picture files will be shown; for the TRACK command, only music modules will be shown. The filter settings can be changed using the tooltypes in the GRAAL Editor icon. See the end of this chapter. If it's a room file that is wanted, the Editor always uses the special "load room" requester which also shows the room descriptions. <3D> [F8] """"""""" This one edits the position of the 3D scaling lines in the 3D: statement. Just drag each line to its proper position along the y axis. Each line has a box attached to the top - the box represents the scale of the character, so the line with the smallest box should be the one furthest up the picture, and so on. Inserting New Statements or Commands Using If you place the cursor on an empty line and use , a list requester pops up asking you if you wish to insert a new statement. All valid statements (according to the script type) are shown in the list. Select a statement with the up and down arrow keys, or with the mouse. With a statement selected, you can also click the button or press [Help] to read the amigaguide help for the statement. Select the statement with [Enter], the button, or by clicking it a second time with the mouse. A new line containing the statement will be inserted at the cursor position, and the parameter editor window is opened automatically. Similarly, positioning the cursor on a line that has a statement, but neither on the statement nor the existing command names, brings up a requester asking if you wish to insert a new condition or command. Be careful not to insert a new command in the middle of parameters belonging to another command... Note: .scene files can't contain statements. Therefore, it's always the condition/command list that appears when using the function in an empty space. 21.8 Icon Tooltypes ------------------- Some aspects of the Editor's operation can be changed using the following tooltypes: SCREEN=WB|NTSC|PAL WB: The editor will open in the current Workbench screen mode. NTSC: The screen opens in hires NTSC mode. PAL: The screen open in hires PAL mode. (Note: The SCREEN tooltype only works with AGA machines.) GRAAL=name Sets the name of the GRAAL driver program being started with the Editor´s button. IMAGEFILTER=filter Specifies which files should be shown by the file requester when the FILE button in the Parameter Editor window is used to find images. The default is #?.iff|#?.pic|#?.i16|#?.i32|#?.i64 TRACKFILTER=filter Specifies which files should be shown by the file requester when the FILE button in the Parameter Editor window is used to find music modules. The default is #?.trk|#?.track|#?.mod|#?.sng SAMPLEFILTER=filter Specifies which files should be shown by the file requester when the FILE button in the Parameter Editor window is used to find samples for sound effects. The default is #?.snd|#?.raw|#?.8svx CHECKONSAVE=YES|NO If this is set to yes, a syntax check will be automatically performed as soon as you try to save a script file. If an error occurs and you click the button in the error report box, the file will not be saved. Clicking allows you to save the file with the errors in it. PAINTAPP=path:name [arguments] The path and name of a paint program, which can be launched directly from the Editor's GRAAL menu. Some paint programs may accept command line arguments and even a file name. In this case, put {f} in the place of the file name - GRAAL will then open a file requester, using the imagefilter specification, before starting the paint application. (This works wonderfully well with DPaint.) 21.9 Editor Keyboard Shortcuts ------------------------------ ("a" means the key must be combined with the right [Amiga] key.) a[3] Open new window & Load any file a[4] Open new window & Load graal.main a[5] Open new window & Load .room script a[6] Open new window & Load .section script a[7] Open new window & Load .scene script a[8] Open new window & Load .ptrn script a[S] Save a[A] Save As a[P] Print a[?] About a[Q] Quit a[W] Select Window a[I] Insert Mode a[O] Overstrike Mode a[F] Find a[N] Find Next a[R] Replace a[1] Mark Block Start a[2] Mark Block End a[T] Top a[B] Bottom a[C] Copy a[X] Cut a[V] Paste a[D] Delete Current Line a[Z] Undo "Delete Current Line" a[J] Stack windows a[L] Tile windows horizontally a[M] Tile windows vertically a[K] Check Syntax a[E] Edit Parameters a[G] Launch GRAAL a[H] Create and load GREP report a[U] Launch paint program [Shift] + [Left Arrow] Start of line [Shift] + [Right Arrow] End of line [Shift] + [Up Arrow] Page up [Shift] + [Down Arrow] Page down [Ctrl] + [Right Arrow] Next parameter ( ";" character ) [Help] Show Amigaguide help for current statement / command [Esc] Close current window / requester [Enter] Exit current input string gadget, or close requester and execute function (depending on current situation). [Tab] Activate next input string gadget (can only be done if previous string gadget has been deactivated with [Enter] first). [F1] Run GRAAL from Editing Window [F2]-[F5] Quick locate buttons in Editing Window [F1]-[F8] Editing buttons in Parameter Editing Window 22 Hints and Tips =================== Here are some general hints and tips that may prove useful. 22.1 Flags ---------- * Avoid setting flags in cutscenes, if you have a choice. It's hard to keep track of the games' status in the main script files if the setting of flags is "hidden from sight" in the cutscenes. (And forget I mentioned I've done just the opposite in a few places. Do as I say, not as I do! :-) * Since all variables have the initial value 0, it is good practice to let that value represent the initial state of the object, room, situation, etc. * Use room flags for all things that relate to the scene as a whole, rather than the flags of a particular object. * Remember that ALL aspects of room objects and section objects get reset as soon as you leave the room or section. You can compensate for this using room flags to track room object states, and then set the objects up in whatever way they should be by using DACT statements. * Use the room flags for room 0 as "global flags" pertaining to the game as a whole. Room 0 is never used as a "real" room in any adventure. 22.2 Diverse ------------ * During the development of a game, you often wish to start the game in an odd location with the objects and flags required set up in a special way. To keep your proper game scripts "clean", set up a special testing room and call this as the START_ROOM. Get objects and set flags using DACT:s, and in the last DACT:, simply GOTO the location you wish to test. * Keep a template containing comments for all the ACTION: statements in a separate file, and copy it to the end of each new room and section script. This way, you have a map over what command has what number handy in all scripts. 23 Questions and Answers ========================== Q: Anything I should think about when assigning BOB numbers to objects? A: Use numbers below 60. Make sure a BOB number is never used for more than one thing at a time in the same room. Otherwise, no: No information is connected to or "belongs to" BOB numbers and their use, so there are no other fixed rules. Q: What about animation channels then? A: Same thing. Look up the reserved channel numbers in graal.guide, and make sure you never try to use the same channel for two things in the same room! Q: What are the rules for room object use? A: A room object can only exist in one room - therefore, it can never be picked up or added to the inventory. Nor can you use its object flags for very much, because they will be reset each time you exit the room. ROBJ references should only exist in .room files, never in .sect or graal.main! Q: What are the rules for section object use? A: A section object only exists within one section, and preferably disappears totally during the first visit to the section - otherwise, you must keep track of how the objects have been handled via room flags or such devices, if you happen to re-enter the section. In other words, take particular care if your adventure is designed in such a way that you can go back to, for example, section 1 from section 2 - not only must you be sure that section 1 still looks okay with respect to section object use, but also, the section 2 section objects will suffer the same problems! Even if you haven't "solved" section 2 yet completely, going back to section 1 will end your first visit to section 2 and thus reset your section objects for section 2!! SOBJ references should only be used in .room and .sect files, not in the .main file. Q: I need some very precise movement paths for my character in some situations, and the floor system is not quite up to the job. A: There are a couple of ways. A) Try using PATH: statements. These allow you to connect otherwise unconnected floors using "twisting" paths. Read more in the room PATHS: statement in the on-line reference. B) Use an un-named exit. When you specify an EXIT: with no description, GRAAL shows no exit name in the scene area, nor does it put a "Go to ..." message in the sentence box when the exit is clicked. That way the un-named exit is just a "clickable area" in the scene area, and you can use ACTION: 0;... statements for it to do anything you like. 1. Put an un-named exit over the destination on the screen your character should reach using a special movement or animation. 2. In the ACTION: statements, use whatever commands you need to transport the character to the destination point: Perhaps first an ordinary CMOVE to the closest edge of the actual floors, and then OMOVE 0... to make the final part (up the ladder, down the hole, or whatever). Note: Remember, if you move the character outside the normal floor area, you are in a bit of trouble if he must also be able to return: If you click outside your unnamed exit, the normal floor system will try to move the character the normal way, and if it is no longer in any floor area... well, problems arise. They can be dealt with, though, using some careful planning. The easiest way is to make sure the player does not get the opportunity of clicking anywhere before the character is safely back on a legal floor again! Some clever use of a number of un-named exits together with SHOWEXIT and HIDEEXIT commands may do the trick. Q: I have the need for menu-style pictures with multiple user options. A: Yes, why not indeed? Just use EXIT: statements with no name/ description to define the clickable areas needed on screen, and then ACTION: 0;... statements to handle the player input. Or, define room objects that are actually buttons. Or, use the multiple inventories and put your menu selecting in a special inventory, then access them with some special "select" command. There's more than one way to fling an otter... Q: I want a way to show the player's score at any time! A: The neatest (and quickest) way is probably to put a "SCORE" button in the command area using the VERB_ZONE: and VERB_TEXT: statements in the graal.main file. VERB_TEXT: allows you to define "direct verbs", that is, commands that do not wait for or use an object. If you define a verb "SCORE" and make that a direct verb, you can then use a TEXT command to display the score held in a flag (preferably a room flag for room 0 - as mentioned elsewhere, these make excellent "global flags"). Q: I don't quite understand the FLOOR: statements. A: The best description is in graal.guide. Make sure you read ALL the information about FLOOR: and PATH: there - it's even got some diagrams! Then look at one of the rooms in the demo adventure to put theory to practice. Q: I'm trying to run the GRAAL editor and GRAAL in parallel, but changes I make to the scripts in the editor do not seem to take effect, even though I'm sure I have saved them to disk. A: Check this: 1. You must exit the room / situation where updates were made and then re-enter to force a reload of the scripts in question. Alternatively, use the "Go to" button in the on-line monitor, which also forces a reload. 2. You must have MAX_CACHE: 0 in graal.main before starting GRAAL for this. Otherwise, an old copy of the script file still in memory will probably be used instead of your updated version. 3. Changes to graal.main NEVER take effect without restarting the game. Q: After playing a tune with the TRACK command, samples played with the SAM command get caught in a loop! A: Naughty you - you have probably used the undocumented MED- module feature of GRAAL! It can play MED modules (MMD0 and MMD1 formats), provided you have the file extension ".med" in the module name. However, this causes the above bug in the sample routines to appear - this is Amos's fault. I know there exists an Amos bugfix or work-around for this, but I DON'T HAVE IT. If anyone has seen it, mail it pronto, and the med support will be made official! Q: The command area behaves strangely - it doesn't go away when I tell it to in CUTSCENE commands. A: You have probably not put it back correctly in a previous cutscene. All sequences of events that start with either CUTSCENE ...,NF or CUTSCENE ...,F must end with an equivalent CUTSCENE ...,N or CUTSCENE ...,S. ALWAYS restore the command area before doing a DSET - it may seem the DSET restores it for you after the dialogue has ended, but not really 100%. This goes for the COMAREA command, too. COMAREA OFF is just another way of saying CUTSCENE "blank file",NF, and COMAREA ON is equivalent to CUTSCENE "blank file",N Q: The song I'm playing with the TRACK command doesn't stop after playing through once, but starts over in a weird tempo. A: Unfortunately, the tracker "stop song" command 0FFE stopped working with the tracker command set I started using in GRAAL 2.1. Fortunately, there is a way around this: At the very end of the song, put a blank block, and have that block repeat itself by putting a tracker "jump" command (0B..) in it. Q: 1. A scaled character changes its size when it starts moving/ stops moving. 2. A character following the controlled character is not of the same size! A: You have been unlucky with the way the 3D scaling zones (in the room 3D: statement) coincide with the FLOOR: settings. There are a number of things you can try to make it all look nicer: 1. Make sure the 3D zone boundaries are not set too close to a "character position" like EXIT: points, START_POS: points or object-handling positions. This gets rid of problem 1. 2. Make sure each floor is within one and only one scaling zone, and add some space for the following character´s y offset around the floor edges as well. Then connect the floors with paths. This should get rid of problem 2.