Amiga ISO Collection

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

/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / FF-GRAA1.DMS / in.adf / Editor.text < prev next >

Wrap

Text File | 1996-05-09 | 19.4 KB | 488 lines

The GRAAL Script Editor ======================= 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 some of the trickier 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 gives help on the syntax of 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 object, image, exit, and floor related statements. * 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. 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. * Marking a block that extends over the last actual text line in a file may cause problems. Avoid. * 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.) * .scene and .ptrn file templates have some commented-out statements in them, indicating these statements can optionally included in yous scripts. As you know if you have read the GRAAL documentation, .scene and .ptrn files do not contain statements at all, so thing is plain wrong. Sorry 'bout that. Will fix this in the next release! 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 ".scene" 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. Syntax Help ----------- If you place the cursor on a statement or command word and press the HELP key, a simple syntax help is shown in the screen title bar. Explanations: [...] This part is optional UPPERCASE This parameter must be typed as shown here. ...|... A separator separating alternative options for the parameter. {...} This parameter is repetitive. E.g., {command|condition} means any number of GRAAL commands and/or conditions, separated by semi-colons, may be placed here. ...|list This parameter may be list of values like the one on the left hand side of the | character - the values in the list must be separated by | characters. Note that after having run the syntax checker, the cursor is placed on the failing statement or command, which means you can press <help> immediately for further information. Also note that 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. If further help is required, refer to the graal.guide on-line reference. 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 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. 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 STATEMENT EDITORS ===================== The Statement Editors are a bunch of functions helping you edit some of the most complex statements in the GRAAL language. The Object Editor ----------------- Let's start with the most complex of all, the OBJECT:/ROOMOBJ:/SECTIONOBJ: statement. This is available both from the "Object" button and the "Edit Object" option in the "GRAAL" menu. What happens when you choose the option depends on whether the cursor was placed on an OBJECT: statement line when it was invoked. If so, the parameters of that statement is edited: Otherwise, GRAAL will assume that you want to create a new object. This means once you save the edits, this will create a new OBJECT: statement line at the cursor position. Note: The editor is clever enough to recognise whether you are in a .main, .room, or .section script, and will adjust to an OBJECT:, ROOMOBJ:, or SECTIONOBJ: accordingly. The same goes for the other editors handling statements which are differently named depending on the script type in which they appear. Okay, what happens when we call upon the object editor, then? First, we get a new window, displaying all the object parameters in a much nicer way than the ordinary statement syntax. Most are represented by string gadgets which must be properly filled in, a few with fixed options are represented by text cycle gadgets - click on one of these to cycle through the possible settings. For example, "Visible:" just switches between "yes" and "no". If you press the <OK> button, the object editor window closes, and: * If the cursor was on an existing OBJECT: statement, this line will be replaced with the updated version. * Otherwise, a new statement line will be inserted at the cursor position. If you press <Cancel>, nothing will happen to the script. Editing the Object Position On-screen ------------------------------------- The trickiest part of GRAAL coding is getting on-screen coordinates right. In the object editor, there is a < <-Edit > button next to the string gadgets dealing with the object position and appearance. Press this, and you will be able to place the object correctly against the background picture using the mouse. To achieve this, the editor will ask for two files: First, it asks you to name a .room file. This is because it is about to create a list of all available images that you could possibly want to use for the object, and it need information about the .room file to know which BOB images to load. Next, it asks for the name of the background picture against which you want to place the object. For example, if you are editing a ROOMOBJ: in room 1, the two files would probably be "1.room" and "1BG.IFF" (if you follow the naming standards of my example adventure). By now, the background picture should have appeared on screen. If you are editing a new statement, the first image fount in the graal.main file is displayed in the bottom left corner of the picture. Hold the left mouse button down and drag the mouse - the image will follow. Press the down arrow key - the image shown will change and "cycle through" all the images found in the graal.main, selected .room and .section scripts. Simply select the proper image and place it in the proper place in the picture. If the background picture is wider than the screen, you can scroll it with the left and right arrow keys. Press <enter> if you wish to save the position, or <esc> to cancel the operation. If you were editing a new statement, or an old statement which defined the object image as a single BOB image (not a pattern or an animation sequence), both the object position and the object image specification will be updated. When the statement contains an animation sequence or pattern, only the position is updated, so as not to spoil any earlier work you may have put into the specification of the image/animation/pattern. The BOB Image Editor -------------------- The rest of the editors don't have their own fancy "parameter windows" like the Object Editor - they simply don't have enough parameters to justify that. Instead, they only help with the graphical side of things, much like the "edit position" part of the Object Editor. To illustrate this, the BOB Image Editor is next. It only edits five of the eight parameters in BOBS:, ROOMBOBS: and SECTIONBOBS: statements: x, y, width, height, and x-offset. If you create a new statement with the editor, you must make sure to complete the statement by filling in the other three parameters correctly yourself. The BOB Image Editor also needs the name of a picture file - this is the "clipart" picture from which the BOB images should be cut out. Before you invoke the editor, select the proper file name using the "Change Picture" option in the "GRAAL" menu: All editors will continue to use the same picture file unless this option is used to change the file name. Once the clipart picture is shown, click and drag the mouse. You should see a small square move across the picture from the upper left corner: This is the cut-out frame. Now release the button, select a point in the bottom right corner of the frame, and drag again. This will re-size the frame. All you have to do now is place the frame around the image you want, and adjust the size. Save the information with the <enter> key, which updates, the script. If the ...BOBS: statement says that more than one image should be cut out (which is specified in the first parameter), a number of horisontally aligned frames, equal to the number of images being cut out, are shown agains the clipart picture. Use the leftmost frame to frame the first image. Then, you can adjust the spacing between the frames with the up and down arrow keys until each frame is properly placed around its image. The Exit Editor --------------- The Exit Editor works much like the BOB Image Editor. Remember that you want to edit against the proper background picture, so switch to the proper file with <Change Picture> first! You will see all exits in the room marked as white rectangles, each numbered with the exit number. All except the one on which the cursor was placed - this is shown as a resizable, movable frame just like the one in the BOB Image editor. Place it and re-size it using the mouse. You can also specify the exit point - This is the point which the character will move to when the MEXIT command is given. It is initially shown as a small cross-hair in the bottom left corner of the picture. Point to the cross-hair, and drag it to where you want the exit point. As always, if the picture is larger than the screen, use the left and right arrow keys to move around. The Floor Editor ---------------- VERY similar to the Exit Editor, this one - shows all the floors and their numbers. The Coordinate Editor --------------------- There are many other statements and commands requiring object coordinates at some point. This simple little editor does the trick - it does not produce full-blown statements or commands, it just inserts x and y coordinates, separated by commas, at the current cursor position. It allows you to position any of the available images just like in the Object Editor, switching the image used with the up and down arrow keys. Neat or what? Don't leave home without it! COPYRIGHT INFO ============== The GRAAL Script Editor 1.0 is part of the unregistered GRAAL 1.0 shareware package. It has been my first project in Blitz 2 Basic and can be used for any purpose free of charge. Has someone come up with an Amal emulation library for Blitz yet? If so, I will spend the next year converting GRAAL to Blitz. 256-colour city, here we come! ( -not- :)