Amiga Format CD 8

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

/ Amiga Format CD 8 / amigaformatcd08.iso / screenplay / utilities / graal / editor.text < prev next >

Wrap

Text File | 1996-10-15 | 19KB | 512 lines

The GRAAL Script Editor ======================= Version 2.0 beta Introduction ------------ This is a neat little (well, not that small, 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, GRAAL is still only made up of ASCII scripts that can be created using any text editor. The GRAAL editor is just a helping hand, making entry of the statements a lot easier. 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. Why, then, should you use the GRAAL editor, and not any other editor? * It handles multiple scripts in multiple windows with easy switching, copying and pasting between them. * It is connected to the on-line reference, giving help on statements and commands. * It performs basic syntax checking. It doesn't mean you won't get some run-time errors in GRAAL, but not the really stupid ones caused by obvious typing errors. * It simplifies coding and editing of everything that has to do with the graphical aspects of the system - areas, object positions, colours, etc. * 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! * It 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 to work. On AGA machines, it "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 ---------- * 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. * The ASL file requester which so conveniently filters out files you do not want to see only works on AGA machines - non-AGA machines use the Blitz2 standard file requester. (This is because I couldn't get the ASL requester to open on the GRAAL Editor screen on WB 2.05 - it kept popping up on the Workbench screen no matter what, which was very irritating to say the least.) 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 next three suboptions, "graal.main", ".room", and ".section" opens a new window and places a template for the selected script type there. The last two suboptions are for ".section" and ".ptrn" scripts respectively, and do not have templates. Note the file name stated in the top border of the window - for all script types, the file name is (partly) created when you select "New". However, .room, .section, .scene, and .ptrn files are not numbered, so you need to supply the correct number before the type suffix. This means the first time you save the file, use the "Save As" option in the "Project" menu. Once the file name is correct, you can use the "Save" option instead. Loading Existing Scripts ------------------------ Just like the "New" option, the "Load" option (also in the "Project" menu) has a number of suboptions. The only thing they do is make the file requester show only the correctly named files. For example, the ".room" suboption only brings up a list of all ".room" files, making the search for the correct script quicker and easier. The "general" suboption shows all the files in the directory. 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. 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: Create a new graal.main script, making the editor give you a graal.main 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: * The names of all statements are checked. * 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! * The number of parameters for all statements are checked (except for statements with a variable number of parameters). * For all parameters that may consist of conditions, commands, or both, the name of each condition and command is checked. 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. 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 them 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 or exits except the one being edited are also shown on the screen, and the system tries to print the number of each floor or exit near the middle of the corresponding area. Note: In this version, you cannot edit the PATH: parameters graphically. However, when you edit FLOOR:s, any PATH:s defined in the script show up as lines in the picture. <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. <Point> ------- This is, eh, not used for anything right now!. It would allow you to specify a single point by dragging a cross-hair to the proper position, should the need arise. But there isn't. Any need. For that. In any. Statement or command. In this release. (Perhaps in the next one?) <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.