GRAAL 2.1 The Adventure Creator's Manual Copyright (c) 1997 Per Thulin =================================================================== 1 Contents =================================================================== 1 Contents 2 Introduction 2.1 Copyright Notice(s) 2.2 Credits 2.3 About the Manual 2.4 Release Info 2.5 Notation Conventions 3 (Finally:) The 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 File 3.6 The .room Files 3.7 The .section Files 3.8 The .scene Files 3.9 The .ptrn Files 3.10 Running an Adventure 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 (Lights! Camera! Action!) 9 Using Exits 10 The DACT: Statements 11 Having a Chat 12 Multiple Characters and Inventories 12.1 Multiple Character Graphics 12.2 Character Objects 12.3 Switching Characters 12.4 Inventory Switching 12.5 Characters Following Characters Around... 12.6 Helpful Conditions 12.7 Things to Consider 12.8 Space-saving Tip 13 Character and Graphics Design 13.1 Size 13.2 Colour 13.3 Pointer Shapes and Colours 13.4 Designing Animations 13.5 All About 3D and Hotspots 14 Cutscenes 14.1 Hop, Skip and Jump 14.2 No Breaks! 14.3 Nesting 15 Special Techniques or "How The Heck Did He Do That?" 15.1 Speaking In a Foreign Tongue 15.2 An Automated Room 15.3 The Art of Avoiding a Seagull 15.4 A Spitting Image 15.5 A Map Room 15.6 A Small Guy 16 The On-line Monitor 17 Macros 17.1 Starting a Macro Recording 17.2 Saving a Macro 17.3 Playing a Macro 17.4 Restrictions to Macro Playback 18 "Productifying" Your Adventures 18.1 The Basics 18.2 The diskinfo.graal File 18.3 GPRO 18.4 GDC 19 The Editor 19.1 Introduction 19.2 System Requirements 19.3 Known Bugs & Irritating Facts 19.4 Creating a New Script 19.5 Working with the Editor 19.6 The Parameter Editor 19.7 Inserting New Statements or Commands Using 19.8 Editor Keyboard Shortcuts 20 Hints and Tips 20.1 Flags 21 Questions and Answers =================================================================== 2 Introduction =================================================================== 2.1 Copyright Notice(s) ------------------------------------------------------------------- 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 tutorial manual. 3. An AmigaGuide on-line reference (graal.guide), the definitive authority on all GRAAL statements and commands. This, too, contains a page with links to new and updated topics for each release. This manual contains: 1. This introductory section, describing what GRAAL is and what it is not. 2. A tutorial section, describing how GRAAL was used to create the first seven rooms of the Olaf Longhair adventure (the demo portion of which is supplied with this release of GRAAL). 3. More in-depth discussions on some of the trickier concepts - dialogues, graphics, and so on. 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.1 brings you: * 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 controlable characters' walking, talking, and general fiddling around. * 32- or 64-colour (EHB), automatically scrolling background screens, 320 to 640 pixels wide. * Fully configurable command area and graphics set-up. * "Unlimited" number of locations (rooms), objects, characters, dialogues, etc. * 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. * Also automatically detects extra memory and uses this as cache memory to avoid unnecessary disk access. * Side-view "simulated 3D" scenes with foreground, "middle", and background objects. * Animated objects and characters. * Pixel-perfect detection of objects. * 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 definition system - for defining legal movement paths and automatic negotiation of obstacles. * Cut-scenes with or without cutscene indicators. Nested cut- scenes are possible. * 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 bring you: * Dynamic depth-scaling of characters. * 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. =================================================================== 3 (Finally:) The 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 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 3D 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, amking 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 File ------------------------------------------------------------------- "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 Files ------------------------------------------------------------------- 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 Files ------------------------------------------------------------------- .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 Files ------------------------------------------------------------------- .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 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. Enough of this already. Ready to start on an adventure? =================================================================== 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, and 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 best ways 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 statements that can be set almost immediately. The 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 - GRAAL Demo Version" 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: ... 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. Read the comments in the graal.main file, that's the best way to learn about them. At this point, we will not get much further without bringing the big star, our main character, the man, Olaf Longhair himself, into play! 4.2 The Hero - What a Character! ------------------------------------------------------------------- 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 four sections: 1. BOB images for system use occupy slots 1-10 by default. This includes the image for the cutscene indicator, up- and down-arrows for various lists, and so on. This reserved area is not really necessary any more - GRAAL 2 can store all user interface graphics in any global BOB position - but it's kind of a left-over from previous versions. The practical upshot of this is that you actually have 10 more global bobs than the number you specify with the N_GLOBALBOBS: statement. However, if you want to keep things neat and tidy, I recommend you use numbers 1- 10 for "system graphics"only, and store "game graphics" in other locations. 2. Global BOB images are those that are kept in memory at all times, for example all Olaf's basic movements. The number of slots used for these are defined with the N_GLOBALBOBS: statement. 11 is always the starting number for this range. Make an educated guess how many of these you'll need. "Olaf" uses about 40, which translates to images 11 to 50. 3. 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 4. 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: 40 N_SECTIONBOBS: 30 N_ROOMBOBS: 70 This means that right now, we believe we need 40 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... More CLPART: and BOBS: statements follow upon this first one, until all basic images we need have been loaded into the image bank. Now that the images we need for Olaf's basic behaviour is available, we can tell GRAAL a little about their basic properties and how they should be used. CHARACTER_HEIGHT: 40 CHARACTER_WIDTH: 22 are two statements stating Olaf's approximate and average height and width. These values are used to position Olaf properly on the background in relation to walls, and also to place the text representing Olaf's speech at a proper distance above his head. (In 2.1, an optional extra parameter to further adjust the text display versus the character height was added: See graal.guide for details.) CHARACTER_COL: 9 Olaf's speech will be shown as text with colour no. 9. Use a rather bright colour, which along with the automatically added black border around the text should make it readable enough. 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. But I'm too lazy!) 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) So far, all we have done is to specify still images. Now we enter into the gruesome, yet strangely attractive world of animation! And yes, AMOS Pro users will immediately give a cry of joy: It's AMAL! AMAL is AMOS Pro's animation language, and yes, GRAAL uses the same syntax for animations. So let's see what we've got 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. 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.) WALK_SPEED: 1.2 This statement just adjusts the speed with which the character walks. Especially when walking sideways, you wish it to look like it is the character's feet that actually propel him across the floor - watch some really bad cartoons, and you will spot how the characters "glide" across the floor as if it was made of ice! The proper value here depends on how large steps your character takes in your animations. Do a little experimenting! 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. Up to eight TALK_MAP:s may be specified in all. 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 proper! 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 which sets the updating speed of the scene area. The higher the number, the slower the screen updating, and the more graphics GRAAL is capable to shift between updates. To keep animations etc. from becoming jerky, the number must be set high enough to cope with all graphics. Actually, this only becomes a real problem when the background is scrolling, so the number set here is only used during such scrolls. At all other times, the update rate is 3. And in this room, the whole thing 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 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 went into colour numbers 16-31 in the 32-colour palette, and the 16 standard colours used for Olaf and any other common BOBs and images were copied into the palette in places 0-15 (see the Master Classes for more info on handling colours). The background file is defined with the BG_IFF: 1BG.IFF statement. In GRAAL version 1, the height of the background iff:s must be 120, but the width 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).. 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".) 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;113;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 parameters, "1-1/ 2-2", describe how Olaf navigates between the two 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;5;60;12;119;10;116;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. The ROOMBOBS: ... statements that comes next 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! 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 - they can't be picked, up, altered, or anything like that!). In the graal.main file, locate the line OBJECT: 16;piece of\paper;8;VIS;56;RBOB6;60;119;14;0; //14;with;PICK;0;8;47;LOW;WD;an;this;it (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 of 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! 60;119; is the x and y position of the RBOBs hotspot. 14;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. //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 - 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 objects 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 then 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! You should remember that GRAAL is quite flexible in many ways, one being that there exists GRAAL commands to alter many of the object's properties, such as the name, visibility, location and so forth at any time during 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. Characters which are involved in dialogues must always be specified as global objects. The bartender, starting out as the "bearded man", is one example. 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 RBOBs, 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 disappears 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, you must have at least one section file in your adventure, 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 (Lights! Camera! Action!) =================================================================== We now have the lights and the camera, so to speak. But precious little action. (Well, the lights aren't actually turned on yet. That is done with a LIGHTS ON command, explained further on!) 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 on 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. 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 1;.... "IFOBJ 1" is a condition telling us that the rest of this ACTION should only be executed if our object was number 1. It wasn't - it was SOBJ1 - so we continue to the next statement. ACTION: 2;IFOBJ ROBJ1;.... No luck here, either. We weren't after the plate of spam, known as ROBJ1, so we continue, and quickly find that there are no more ACTION:s for verb 2 in the room file. 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 handle 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 lines in the graal.main file - the two objects especially handled in the 1.room file were there because they are handled a little differently from most of the rest. Going on to the graal.main file then, 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 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! =================================================================== 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;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). 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 Having a Chat =================================================================== There are few things that breathe life into a graphic adventure the way good gialogues 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 in the graal.main file. There is nothing special with the definition: Just make sure the object cannot be picked up, visible, and placed in the room where the dialogue takes place. Also, assign an animation channel to it. Each "speaking partner" has his or her own unique number, which is defined by a DLG statement in the graal.main file (below the OBJECT statements). The same "partner" can be involved in any number of dialogues. DLG: 1;5;11;-20;A 0,(RBOB4,12)(RBOB6,24)... 1; means this is speaking partner 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. 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;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 behaves 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; This command engages us in dialogue number one and tells GRAAL to add the four dialogue alternatives 3, 7, 9, and 11 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, and 11. 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 and 11 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. However, if he (which is unlikely) 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. 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. =================================================================== 12 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). Starting with GRAAL 2.1, you can 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 avdenture 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.) 12.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. 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 conatining 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. 12.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: character;object;startimage;endimage;startfloor character 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. Examples: CHAR: 1;1;11;40;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. CHAR: 2;20;41;70;1 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. 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. 12.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. 12.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 REMOVE commands always work with the currently selected inventory. To place things in another inventory than the currently selected, you must use the REMOVE command specifying the inventory in a similar way to the OBJECT: statement room number: REMOVE 4,U,I2 would move object 4 to inventory 2. The parameter "U" indicates that the move is made from the current directory, since U means we wish to update the inventory display to show the change, but REMOVE can equally well move the object from any other location. 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... 12.5 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). 12.6 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. 12.7 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. 12.8 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). =================================================================== 13 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! 13.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? 13.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. 13.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 13.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. 13.5 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 tells which point of the image will actually be placed at the x and y coordinate specified for an object. 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 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. 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 all of the 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. 14.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! 14.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 statement 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. 14.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 to stop the cutscene indicator symbol flickering on the screen. The master scene should be called with parameter ,S because when it's finished, the whole scene is finished. 2. Then, Olaf tries to speak hindi or something like that, and gets punched out. 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. =================================================================== 15 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 it goes to prove that I have tried not only to solve specific "Olaf" 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 of limited use. 15.1 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". 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!). 15.2 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 that does not end 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. 15.3 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! 15.4 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!) 15.5 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 rooms 5 and 7, 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. 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. There are no objects in the room, and although you can try to manipulate the objects in the inventory, whatever happens will not get through to you, because Olaf is not there to tell you about it. However, three small exits placed just over the towns on the map provide three ways to get on with the game. I have chosen to display the exit names the normal way, 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, and it shouldn't have taken the player too long to figure out where to click, anyway. 15.6 A Small Guy ------------------------------------------------------------------- Character scaling is not well supported in GRAAL at the moment, but thanks to the system's flexibility, you can (partially) ignore that! To prove it, I have made a big Baghdad panorama in room 7, requiring Olaf to be shown at a quarter of his normal size. Tough job? Not very. The secret is the BOBS command, which can be used to switch the global BOB images to a new size. I simply took the Olaf_Original.IFF picture containing the standard animations for Olaf, halved its size, and re-saved it under a different name. When Olaf arrives at Baghdad, all graphics are replaced using BOBS commands and the new picture CLPART file. In addition, for this sunset scene I also altered the colour scheme for the Olaf images slightly. It blends better with the background picture that way. There is one problem here which you must be aware of: Loading saved games does not automatically restore global BOB images. So, if you are in Baghdad (Olaf small) and load a saved game placing him in, for example, room 2, he will still be small. Or would be, if we did not do anything about it. Well, this is not too difficult to take care of. Each time GRAAL loads a stored position (or executes the RESUME command, which is, in effect, a "load from RAM:"), it immediately looks for ACTION: statements containing the special "verb" -2. This means that all we need is an ACTION: -2;... statement in the graal.main file being able to determine whether the global BOBs should be reloaded or not. To achieve this, and keep track of Olaf's looks, I used a room flag belonging to room 0. Room 0 is a "dummy" room which is never used in a game, so there are actually 20 excellent "global" room flags there, which can be used to keep track of "global game states". So, if room flag 1 for room 0 is 1, (i.e. IFRF 0,1=1), Olaf needs a change of clothes. The change is taken care of by some BOBS statements in a cutscene file, restoring the original BOB images. And that's that. Like this: ACTION: -2;IFRF 0,1=1;CUTSCENE 17,H and the contents of 17.scene is simply: /* The correct graphics file CLPART Olaf_Original.iff /* Some BOBS commands to load the images BOBS 10;11;... ...you get the picture. (And so does GRAAL.) =================================================================== 16 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. Some of you may have liked the old-style monitor better in this respect, but that one a) didn't work properly in some cases, and b) required a lot more code for less flexibility. With the new monitor, you can rest assured everything you execute through the monitor behaves exactly as it would if it had been typed in a script. These are the command 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 usre 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 exeuting a GOTO command instead. List buttons There are three buttons to list important information: * < List Objects > shows a list of all objects - numbers, locations and flag contents. * < List Rooms > 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 monitor window 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 being executed are shown in the trace window. For each one, you have to press a keyboard key to continue through the scripts. 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. 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 61 or something like that. To de-activate the trace mode, call up the monitor again and click < Trace > once more. The trace mode can also be activated and de-activated from within scripts with the TRACE ON and TRACE OFF commands. =================================================================== 17 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. 17.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. 17.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. 17.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. 17.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 timer functions, stop to think before you record macros - is the timing in the sequence going to affect the result of the playback or not? =================================================================== 18 "Productifying" Your Adventures =================================================================== 18.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. 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. 18.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 filename is on its own line, preceeded 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!! 18.3 GPRO ------------------------------------------------------------------- The GPRO program is used for copying 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!) The user interface is as follows: +------------------------------------------------+ | | | Encrypt: < > Yes < > No Simulation: < > | | | | | | Diskinfo: [ diskinfo file name ] | | | | | | Destination: [ destination directory name ] | | | | | | ============================================== | | | | | | [ message field ] | | | | | | ( Copy ) ( Exit ) | | | +------------------------------------------------+ 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 diskinfo.graal To make sure a file is never encrypted, just put a space and an asterisk after the filename 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-decrompressing executable file (like PowerPacker or CrunchMania). 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). 18.4 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!) The user interface is as follows: +------------------------------------------------+ | | | Format: < > Quick < > Normal ( Check Sizes) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | A B C D E F G H I J K L M N O P Q R | | | | ============================================== | | | | | | [ message field ] | | | | | | ( Copy ) ( Exit ) | | | +------------------------------------------------+ 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 pre-formatted, 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, 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 d*mn 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 should 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, and start GDC now and then to see if the distribution of files seem about right with respect to the space requirements... =================================================================== 19 The Editor =================================================================== 19.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 in "unreadable" 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 the way YOU feel like. The 2.0 version of the GRAAL editor now 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 the "OBJECT:" statement were, 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 :-) 19.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, so 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. On non-AGA machines, a normal hi-res, non-interlaced screen is 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. 19.3 Known Bugs & Irritating Facts ------------------------------------------------------------------- * Sometimes when you re-size a window other than the currently active, the display in that window becomes corrupted. Put the window in front and activate before re- sizing, this should help you avoid any problems. In most cases, you are better off using the "Select Window" functions to switch between windows, anyway. * 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. 19.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! 19.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 "Open & Load" option instead. It looks exactly like the "Load" options, but in this case, the suboptions have keyboard shortcuts ([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 some suggested parameters already filled in. In most cases there is no point in giving a suggestion, though, 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. 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. 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. Amigaguide Help If you place the cursor on a statement or command word and press the HELP key, the amigaguide reference file 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 anymore). Other available shortcut 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. "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 occurence 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 shortcut 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!) 19.6 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... Keyboard Shortcuts There are a number of shortcut 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 shortcut 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 shortcuts [F1] to [F6], as listed further on. Optional Parameters Optional parameters are shown in blue. Consult the on-line reference for information abot 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, GRAAL expects you to replace this with an object number. Graphical Editing A lot of parameters have to do with specifying co-ordinates, positions and other stuff related to a backdrop picture. If there are parameters which can be edited in this way, one or more of the six buttons beneath the string gadgets will become available. They also have keyboard shortcuts in the form of keys [F1] to [F6]. 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 actually affecting. 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" to speed up the process. The details of all the "graphical editing" operations are explained below. Once you are done, press "Enter" to save the changes, or "Esc" to cancel. If the backdrop picture is larger than the screen, use the left and right cursor keys to scroll it. Important Tips Two points to remember: 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. Also, remember that the editor loads such data from the files SAVED TO DISK, not from unsaved files in the editor itself. Therefore, save before using the parameter editor. Background Graphics 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. If you edit a floor or an exit, previously defined floors and exits are shown. Note: While you move the object you are editing around the screen, you will sometimes erase these other, pasted-on objects. To restore them, just press the left or right cursor key. Also, if objects overlap, the editor does not bother to sort them in the proper order. Keeping the left or right cursor key down for a while should allow you to see all the objects revealed (although flashing wildly) even if they overlap. Now, a closer look at the five "graphical editing" buttons: [F1] An area is a rectangle that can be moved around the screen and re-sized. 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 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. If you use to edit floors or exits, all floors and paths or exits are also shown on the screen (except the one being edited), and the system tries to print the number of each near the middle of the corresponding area. [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. The image being edited will start flashing in weird colours. Drag the mouse to the desired location and release. To alter the image, use the up and down cursor keys. To flip the image left/right, press the "x" key. (However, this will not be automatically registered in the "image" parameter). When you save the changes with the "Enter" key, the image last used 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. (You don't have to choose the correct button yourself - only the relevant one will be available.) [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 when using the MOBJ command. The image used for the main character can also be altered. The same rules as for the object positioning apply. [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. 19.7 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 an existing command, though... Note: .scene files can't contain statements. Therefore, its always the condition/command list that appears when using the function in an empty space. 19.8 Editor Keyboard Shortcuts ------------------------------------------------------------------- [3] Open new window & Load any file [4] Open new window & Load graal.main [5] Open new window & Load .room script [6] Open new window & Load .section script [7] Open new window & Load .scene script [8] Open new window & Load .ptrn script [Amiga] + [S] Save [A] Save As [P] Print [?] About [Q] Quit [Amiga] + [K] Check Syntax [E] Edit Parameters [W] Select Window [I] Insert Mode [O] Overstrike Mode [F] Find [N] Find Next [R] Replace [1] Mark Block Start [2] Mark Block End [T] Top [B] Bottom [C] Copy [X] Cut [V] Paste [D] Delete Current Line [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 de-activated with [Enter] first). [F1]-[F6] Graphics editing functions in Parameter Editing Window =================================================================== 20 Hints and Tips =================================================================== Here are some general hints and tips that may prove useful. 20.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. =================================================================== 21 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 may 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 SHOW EXIT and HIDE EXIT 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: 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" command in the on-line monitor, which also forces a reload. 2. When GRAAL crashes or is interrupted by Ctrl-c, files are left in RAM: . Most of them, like the script files, .iff files, .snd files and so on are erased when GRAAL is restarted, but some oddly-named graphics and sound files may be left there, being used instead of your altered versions. If you have made some change to sound or graphics that doesn't take effect, quit GRAAL with a regular QUIT command, and check what's in RAM: . 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 used an undocumented 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!