The GRAAL Herald 1

home *** CD-ROM | disk | FTP | other *** search

/ The GRAAL Herald 1 / GraalHerald1.lha / GraalHerald1 / Editor.txt < prev next >

Wrap

Text File | 1996-11-27 | 21KB | 565 lines

Note: This text has been revised since the 2.0 beta 1 release! The GRAAL Script Editor ======================= Version 2.0 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 requires more typing and a deeper understanding of the internal workings of the system, it also has some big 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 doing it. 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 :-) System Requirements ------------------- This editor needs Workbench 2.0 or better (preferably 3.0+) 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. 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. WORKING WITH THE EDITOR ======================= 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! Loading Existing Scripts ------------------------ 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 replaced by "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 i 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. 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. 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> Close the current window. <enter> Exit a string gadget (for example, in the Find window), or carry 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: 1 Cursor row (r) and column (c) position. 2 Insert (I) or overstrike (O) write mode. 3 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! 4 Time. The clock is only updated when you do something in the editor, like moving the cursor. "Quick Positioning" Keys ------------------------ To help you quickly locate those parts of a script file which are most often edited, four buttons have been provided. For example, clicking <ACTION:> 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!) THE PARAMETER EDITOR ==================== Would you believe me if I told you there's an editor in the editor? Well, it's true. Instead of typing in the parameters of statements and commands, separating parameters with ";" or "," characters, you can edit the parameters in a window instead, with each parameter neatly contained in its own string gadget. This is how to do it: Place the cursor on a statement or command - the actual NAME, mind you, not on one of the parameters. Press right Amiga + E or click the <Edit Parameters> button. 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... When you press the Enter key, any changes you have made will be inserted into the script file. Press the Esc key if you want to forget about the changes you've started to make. Optional Parameters ------------------ Optional parameters are shown in blue. Consult the on-line reference if you do not know what they are used for. 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. amigaguide help --------------- You can open the amigaguide reference for the statement or command being edited by pressing the HELP key or clicking the small "?" button. 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 five buttons beneath the string gadgets will become available. 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. Background Graphics ------------------- If the backdrop picture is one of the rooms in your game, all previously defined objects placed in that room is 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're 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. Kepping 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. 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. 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. Now, a closer look at the five "graphical editing" buttons: <Area> ------ 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 <Area> 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. <Position> ---------- 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... <Pastepos> ---------- 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.) <Char.pos> ---------- 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. <Line> ------ 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. <Ink> ----- 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. Inserting new statements or commands using <Edit Parameters> ----------------------------------------------------------- If you place the cursor on an empty line and click <Edit Parameters>, 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 press the <?> to read the amigaguide help for the statement. Select the statement with the <Enter> key, the <OK> 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 paremeters 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 <Edit Parameters> function in an empty space.