AMOS FULL DOCUMENTATION Typed in by MR.SPAGHETTO/ACCESSION. Edited by PARASITE. How was it all done? AMOS Basic was designed and progrqammed by François Lionet. His clever ideas and inspirational work have produced what we feel to be by far the best high-level programming language available on the amiga to date. AMOS was developed using the following programs: DEVPAC II Assembler - HiSoft Deluxe Paint III - Electronic Arts Pix Mate - Progressive Peripherals & Software Cross-Dos - Consultron Mini Office Professional Communications - Database Software Mandarin Software would like to thank the following people for their kind help during the development of AMOS: Allistair Brimble, Aaron and Adam Fothergill of Shadow Software, Peter Hickman, Rico Holmes, Commodre UK for the international keyboard layouts (an the Amiga), Commodore France for the help with the A1000 problem, 17-Bit Software for samples and demos, Martyn Brown for fonts and support, Virus Free PD for Soundtracker, Simon Cook for his constructive comments and bugfinding, Lee, Alex, all other AMOS developers for their kind help and all of you who have waited patienly for this software. We hope, like us, you feel it was well worth the wait. This manual (the original , not this ASCII file) was written using WriteNow on the Apple Macintosh and paged up with Page Maker. Copyright Notice Amos will enable you to create some very impressive software. It is very important that you acknowledge AMOS in your programs using a phrase such as "Written by John Smith using AMOS", and, where possible, include the AMOS Sprite. If your program is released commercially, the words " AMOS © 1990 Mandarin/Jawx " must be included on the back of the packaging and in the printer instructions. 1: INTRODUCTION WELCOME to the exciting world of AMOS - The Creator! As you know, the Amiga is a truly amazing computer. For the first time, all that power is at your fingertips. In Septemper 1988, Mandarin Software released STOS Basic for ST. This made history as the first programming language to reach number one in the ST Gallup games charts! Now STOS has been rewritten from the gound up to produce AMOS Basic for the Amiga. AMOS Basic includes a vast range of over 500 commands - many of which are staggeringly powerful. You can, for instance, bounce a screen, or animate a sprite using just a single Basic instruction. AMOS is not just another version of Basic - it's a dedicated games creation system which comes with its own built-in Animation Language (AMAL). AMAL programs are executed 50 times a second using a powerful interrupt system. They can be used to generate anything from the attack waves in an arcade game, to a silky-smooth hardware scrolling efect. At the same time, your Basic program can be doing something completely different! Whatever you knowledge of programming, AMOS has something to offer you. If you have newer written a game before, the prospect of creating your first game may be quite daunting. But do bear in mind that many of the all-time classics are uncomplicated programs with one or two original features - just look at Tetris for example. The strength of your game will depend on the quality of your ideas, and not just your programming skill. With a little help from AMOS, you'll be able to produce professional-looking games with just a fraction of the normal effort. All you really need is imagination. If you've written a game in AMOS basic, don't keep it to yourself. Mandarin Software is very keen to publish any program written using AMOS. Don't worry if your programming is a little rough. If your ideas are good enough, you could have a real future as a professional games writer. So please send us your programs. Mandarin would also be delighted to hear your comments or suggestions for the AMOS system. Several features in AMOS were taken directly from the ideas which were sent to us from existing STOS users. Address your correspondence for the attention of Richard Vanner, Development Manager, Mandarin Software, Adlington Park, Adlington, Macclesfield SK10 4NP. 2: GETTING STARTED AMOS Basic is a truly remarkable package, capable of creating games which were previously beyond your wildest dreams. All this powerful features which make the Amiga so irresistible have been incorporated into this amazing system. With help of AMOS Basic you can develop programs which would tax the skills of even the most expert assembly language programmer. You can for instance, effortlessly animate up to 56 hardware sprites simultaneously! This is a real achievement, especially when you consider that the Amiga's hardware only actually provides you with eight. If you need even more action on the screen, you can use the Amiga's blitter chip as well. Blitter objects can be created in any graphics mode you like, including HAM! The only limit to the number of bobs on the screen is the amount of available memory. Any combination of the Amiga's graphics modes can be displayed on the screen at once. Hardware scrolling isn't jsut possible, it's easy! There's a built-in SCREEN OFFSET command which allows you to perform the entire process directly. In fact, the only hard part of AMOS Basic is knowing where to start! AMOS supports over 500 Basic commands, and if you're never used Basic before, you may feel a little overawed by the sheer scale of this system. When you're in unfamiliar territory, it's always useful to have a *GUIDE* (Thanks to me!, Mr.Spaghetto ;-) to show you around and point out some of the notable landmarks. That's the purpose of this chapter. Backup AMOS *now* ! Before continuing however, it's vital that you back up the entire AMOS Basic package on fresh discs. This will safeguard your copy of AMOS against accidental mistakes. You'll now be able to play around with the system as much as you like, without the risk of destroying something important. If the worst comes to the worst, we at Mandarin will be happy to replace your disc for a nominal handing charge. But you'll obviously be deprived of AMOS Basic while it's being re-duplicated. The installation procedure varies depending on your precies set-up, but it can usually be accomplished in a matter of minutes. How to backup? If you have got this Ascii file into your hands, you propably also have some cool copy-prog, for example; X-Copy, D-Copy or other... Place the originals into a safe place and use the fresh copies now. Loading AMOS Basic As you might expect, AMOS Basic can be executed in a variety of different ways. You can, for instance, load AMOS directly from the Workbench by selecting its icon with the left mouse button. Once you've entered AMOS in this way, you will be able to flick back and foth to the Workbench by pressing the Amiga and A keys from the keyboard. In practive however, the Workbench consumes valuable memory which would be better used to hold your Basic programs. So if you're a serious user, you'll propably prefer to boot up AMOS as part of your normal start-up sequence. This will allow you to achieve the maximum possible results from the AMOS system. To load AMOS Basic: * Turn off your Amiga and wait for about ten secs. * Place a backup of the AMOS program disc (disc 1) into DF0: * Now switch on your Amiga. AMOS will load into memory automatically. * Hit a key to remove the information box and thus enter the AMOS system. AMOS tutorial The first thing you'll see when you enter AMOS Basic is the editor window. This is extremely easy to use, and if you've a little previous experience with computers it should be self-explanatory. Feel free to experiment as much as you like. The AMOS editor is quite intelligent, and you are unlikely to make any serious mistakes. Now you've seen the editor window, It's time to explore some of the features that make AMOS Basic really stand out from the crowd. Loading a program We'll start off by showing you how you can load one of the terrific games from the AMOS data disc. We'll take the Number Leap game as an example: * Insert the AMOS_DATA disc into drive DF0: * Hold down an Amiga key on the keyboard and press "L". This will bring up a standard file selector on the screen. * Click on the disc drice label DF0 to inform AMOS that you have changed the disc. * At the centre of the file selector there will be a list of programs which can be loaded into AMOS Basic. * To select the Number Leap program, just position the mouse pointer over the file: Number_Leap.AMOS The file you have chosen will be highlighted accordingly. * Once you've chosen your file, you can load it by clicking twice on the left mouse button. Your game will now be entered from the AMOS DATA disc and you will be returned to the original editor screen. The contents of this window will be updated to display your new program listing. * You can run this program by selecting the RUN button from the main menu area (or hit F1 if you're feeling lazy). The editor screen will now disappear completely and Number_Leap will be executed in front of your eyes. After you've played with this game to your satisfaction, you can exit to AMOS Basic by pressing the CTRL and C simultaneously. CTRL+C provides an effective way of breaking into the vast majority of AMOS programs. It can be disabled from within your program using a BREAK OFF command for extra security. When the program has been broken into yu can flick straight back to the editor by pressing the Spacebar key from the keyboard. Deleting a program Now that we've finished with the Number Leap program, we can erase it from memory with the NEW command. You won't find this option on the main menu, as it's been placed in a separate SYSTEM menu. This can be brought into view by moving the mouse pointer over the menu window and holding down the right mouse button. To delete a program: * Ensure the mouse pointer is over is over the menu area. * Hold the Right mouse button down to bring up the SYSTEM menu. * While the button is depressed, move the pointer over the NEW option and select it with the Left mouse key. Alternatively, you can execute this option directly from the keyboard by pressing Shift+F9. * Type Y to confirm the operation or N to abort. * If the current program hasn't been saved, you'll been asked whether to store it onto the disc. If you select the YES option, you'll be presented with an AMOS file selector. Otherwise your program will be totally erased. Direct mode We'll now have a quick look at the direct mode. This forms the centre of the AMOS Basic package and allows you to experiment with your routines and immediately observe the effects. It's important to recognize that all the screens, sprites, and music defined in your program are completely separate from the Editor window. So no matter what you do in direct mode, you'll be able to return to your listing with just a single keypress. * Enter direct mode by pressing ESCape. The editor window will slide away and you'll be presented with the main program display. Towards the bottom of this area will be a small screen which can be used to enter your direct mode commands. Try typing the following line, pressing Return to "execute". Print "Your name" Insert your name between the quotes to print your names on the Amiga's screen. Now press the UP and DOWN arrows from the keyboard to move the window around the display area. As you can see, the Direct mode window is totally independent of the main program screen. Animation! 7 So much for the Direct mode. Let's experiment with some of the AMOS Basic sprite instructions. Before we can use these commands, we'll need to load a set of sprite images into memory. Stay in direct mode and enter the indented lines in bold as you come to them. Listing the sprite files We'll begin by listing all the available sprite files to the Amiga's screen. * Ensure that the AMOS DATA disc is still in the DF0: * Display the disc file directory with the line: Dir "AMOS_DATA:Sprites/" This will display the sprite files we've supplied on the AMOS data disc. These files contain all the images which are used in the various example programs. You can create your own images using the Sprite definer accessory on the AMOS Program disc. The sprite definer incorporates a host of powerful drawing features which make it extremely easy to generate professional-quality animation sequences in your games. Loading a sprite file We can now load these sprites using the LOAD command. The sprites will load into a special memory bank so don't except to see any sprites to appear yet! Let's enter the sprites used by the Number Leap game with the following command: Load "AMOS_DATA:Sprites/Frog_Sprites.abk" If you make a mistake, hit F1 to get your previous line. This line can be then edited using the normal cursor keys and may be re-executed by pressing Return. Now let's also load up a music file using a similar load command: Load "AMOS_DATA_Sprites/Funkey.abk" In order to check whether the sprites and music have been succesfully loaded into memory, we'll call up the LISTBANK instruction like so: Listbank This prints a line like: 1 - Sprites S:$0682B0 L:000040 3 - Music S:$043878 L:0081FE Don't worry if the numbers do not correspond as they will change depending on the available memory. The number of sprites we've just loaded can be returned directly with the LENGTH function. Print Length(1) ( result: 64 ) Setting the sprite colours Each set of sprite images has its own set of colour values stored on the disc. Since these can be very different from your current screen colours, it's useful to be able to GRAB the colours from the sprite bank and copy them into an existing screen. This can be accomplished with the GET SPRITE PALETTE command. Enter the line: Get Sprite Palette All the colours in the main program screen will change immediately, but the direct mode window will be completely unaffected because it's been assigned its own separate list of colour values by the AMOS system. Displaying a sprite Sprites can be displayed anywhere on the screen using a simple AMOS Basic sprite command. Here's an example: Sprite 8,129,50,62 Animating a sprite Let's animate this object using The "AMos Animation Language". AMAL is a unique animation system which can be used to move or animate your objects at incredible speed. Note that when you're entering the following example programs, it's essential to type each line *exactly* as its appreas in the listing, as otherwise you may get an unexpected syntax error. Sprite 8,129,150,62 Amal 8,"Anim 0,(62,5)(63,5)(64,5);" : Amal On The program above animates a small duck on the screen. Whilst it's being manupulated, the sprite cn be moved around using the SPRITE command. Example: Sprite 8,300,50, Moving a sprite Now for some movement! Sprite 8,129,150,62 : A$="Anim 0,(62,5)(63,5)(64,5);" A$=A$+"Loop: Move 320,0,100; Move -320,0,100; Jump Loop" Amal 8,A$ : Amal On This programs animates the duck and moves it back and forth across the screen, using just three lines! Although the instructions between the quotes may look like Basic, they're actually written in AMAL. All AMAL programs are executed 50 times a second and they can be exploited to produce silky smooth animation effects independently of your Basic programs. Just to prove how amazing AMAL really is, hit ESC to jump back to the Basic editor. After a few moments, return to direct mode. Your sprite will still be bouncing accross the screen as if nothing had happened! Music maestro! For a finale, let's play the music! Ensure you're still in direct mode, turn up the volume on your monitor and start the music running the MUSIC command like so: Music 1 By the way, you can stop the music with the command: Music Off The joyrney continues Hopefully, you'll now have a pretty good idea of what AMOS Basic can achieve. But so fat we've only looked at a tiny fraction of AMOS Basic's power. As you experiment with the AMOS package, you'll quickly discover a whole new world, full of exciting possibilities. AMOS Basic can't, of course, transform you into an expert games programmer overnight. Like any programming language, it does take a little time to familiarise yourself with the entire repertoire of commands. We'll therefore end this section with a few guidelines to help you on your way. Hints and tips * The best way to learn about AMOS is to create small programs to animate sprites, scroll screens or generate hi-score tables. Once you've created a little confidence, you'll then be able to incorporate these routines into an actual game. * Don't be overawed by the sheer size of the AMOS Basic language. In practive, you can achieve terrific effects with only a tiny fraction of the 500 or so commands available from AMOS. Start by mastering just a couple of instructions such as SPRITE and BOB, and then work slowly through the various sections. As you progress, you'll gradually build-up a detailed knowledge of the AMOS system. * Although we've attempted to make this package as easy to use as possible, a thorough groundging of the general principles of Basic programming is invaluable. If you're new to Basic, you may find it helpful to purchase an introductory text such as "Alcock's Illustrating Basic. (Cambridge University Press.) * Plan your games carefully on paper. It's amazing how many problems can be completely avoided at the early design stages. Never attempt to tackle really large projects without prior preparation. It's the easiest way to get permanently lost. * When you're writing a game, try to concentrate on the quality of the game play rather than the special effects. The graphics and music can always be added later if the idea's are good enough. 3: THE EDITOR The AMOS editor provides you with a massive range of editing facilities. Not only is it exceptionally powerful, but it's also delightfully easy to use. All commands can be executed either directly from the screen, or via an impressive range of simple keyboard alternatives. It's so friendly in fact, that if you've a little experience with computers, you'll propably be able to use it straight out of the box. One of the most exciting features of this sytem, is that the listing is displayed completely separately from your main program screen. So you can instantly flick from your program display to the editor window using a single keypress (ESCape). If you've plenty of memory, it's also possible to load several programs in AMOS Basic at a time. Each program can be edited totally independently, and it's possible to efforlessly switch between the various programs in memory by pressing just two keys from the editor. The first thing you see after AMOS has loaded into memory is a standard credit screen. Applause applause! Press a key to remove this window and enter the editor. The menu window At the top of the screen, there's a menu window containing a list of the currently available commands. This forms the gateway to all AMOS Basic's powerful editing features. Command can be quickly executed by moving the mouse pointer over an item, and hitting the left mouse button. Each command is also assigned to a particular function key. In addition to the main menu, there are also a number of other menus. The most important of these menus is the SYSTEM menu. This can be brought into view by either holding down the right mouse button, or pressing the shift key from the keyboard. The SYSTEM manu contains a range of options such as LOAD, SAVE, NEW, etc. Like the main menu, all options can be executed using either the left mouse button, or by pressing an appropriate function key. The information line I L=1 C=1 Text=40000 Chip=91000 Fast=0 Edit:example The markers at the far left display the editor mode ((I)nsert or (O)verwrite). There's also an indication of the (L)ine and (C)olumn you are presently editing. Alongside these markers is a list of three numbers: TEXT: Measures the amount of memory which has been assigned to the editor window. This can be adjusted within AMOS Basic using a simple SET BUFFER command from the SEARCH MENU. CHIP: Free Chipmem 12 FAST: Free Fastmem; Whenever possible, this will be used. EDIT: Displays the name of the program you are currently editing. Initially this area will totally blank, but when you load or save a program to disc, the new filename will be automatically entered to the information line. The editor window The editor window forms the heart of the AMOS system, and allows you to type your Basic program listings directly from the keyboard. All text is inserted at the current cursor position, which is indicated by a flashing horizontal line. At the start of your session, the cursor will always be placed at the top left hand corner of the editing window. It can be moved around the current line using the left and right cursor keys. Your line can be edited on a character by character basis using the Delete and Backspace keys. Delete erases the character immediately underneath the cursor, whereas Backspace deletes the character to the left of this cursor. As an example, type the line: print "AMOS" When you press Return, your new line will be entered into AMOS Basic. Anything AMOS recognices as a command will be immediately converted to special format. All Basic commands begin with a Capital letter and continue in lower case. So the previous line will be displayed as: Print "AMOS" Similarly, all AMOS variables and procedures are displayed in CAPITALS. This lets you quickly check whether you've made a mistake in one of your program lines. Supposing for instance, you'd entered a line like: inpit "What's your name;";name$ This would be displayed as: Inpit "What's your name;";NAME$ Since INPIT is in UPPER case, it's immediately obvious that you've made an error of some sort. Ok. Now for a little fun. Move the cursor under the Print command you entered a few moments ago and type in the following lines of Basic Instructions. centre " 13 do x$=inkey$ : if x$ <> "" then print x$ loop Don't forget to press the Return key after each and every line. Now move the cursor through your new program using the arrow keys. Finally, press the F1 to run this program. The EDITOR WINDOW will disappear and a separate PROGRAM display will flip into place. The program now expects you to type in some text from the keyboard. As you can see, the program screen has its own independent cursor line. This is totally separate to the one used by the editor. So you can play about as much as you like, without changing your current editing position. After you've finished, press CTRL+C to abort the program. A thin line will now be displayed over the screen. This can moved using the up and down cursor arrows. Program Interrupted at line 4 >>>Loop Pressing the space bar at this point would return you back to editor. But since we've already seen the editor, let's have a brief look at the Direct mode instead. Hit the ESCape key to flip this mode into place. An introduction to Direct mode DIRECT mode provides you with an easy way of testing your Basic programs. For the time being, we'll examine just a couple of its more interesting features. All direct mode commands are entered into a special screen which is completely indepentent from the program display. You can move this screen up or down using the arrow keys. At the top of the window, there's a list of 20 function key assignments. These represent a list of commands which have been previously assigned to the various function keys. They can be accessed by hitting the left or right Amiga-keys in combination with one of the various function keys. Whilst you're in direct mode, you can execute any Basic instructions you like. The only exceptions are things like loops or procedures. As with the editor, all commands should be entered into the computer by pressing the Return key. Here are some examples: Print 42 ANSWER=6. Print ANSWER*9 Curs Off Close Workbench (Saves around 40k but ABORTS multi- tasking operations!) It's important to recognize that no matter what you do in direct mode, there will be absolutely no effect on the current program listing. So you can mess about to your heart's content, with no risk of deleting something in your Basic program. It's now time to return to the Editor window. So wave a fond farewell to Direct mode, and enter the editor by pressing ESCape. Loading a program We'll now discuss the various procedures for loading and saving your programs on the disc. As usual, these options can be executed either from the MENU window or using a range of simple two-key commands from the editor. The fastest way to load a program is to hold down either of Amiga keys, and press the letter L. You'll now be presented with the standard AMOS file selector window. Nowadays, file selectors have become a familiar part of most packages available on the Amiga. So if you've used one before, the AMOS system will hold no real surprises. However, since the file-selector is such an integral part of AMOS Basic, it's well worth explaining it in some detail. The AMOS file selector Selecting a file from the disc couldn't be easier. Simply move the cursor over the required filename so that it's highlighted in reversed text. To load this file into memory, click twice on the left mouse button. Alternatively, you can enter the name straight from the keyboard, and just press Return. If you make a mistake, and wish to leave the selector without loading a file, move the mouse over the Quit button and select it with the left button. AMOS will abort your operation and display a "Not Done" message on the information line. As an example, place you COPY of the AMOS program disc into the internal drive and press AMIGA+L to load a file. If you've been following out tutorial, AMOS will give you the option of saving the existing program first. Unless you've made any interesting changes, press "N" to anter the file-selector. Otherwise, see "saving a program" for further instructions. When the file selector appears, look out for a file with the name "Hithere.AMOS". Once you've found it, load it. The following listing will be loaded to amos basic. Rem Hi there AMOS users Cls 0 : Rem Clear the screen with colour zero Do Rem get some random numbers X=Rnd(320):Y=Rnd(200):I=Rnd(15):P=Rnd(15) Ink I,P : Rem add a little colour Text X,Y,"Hi there!" : Rem graphic text Loop Move the text cursor over the text "Hi There!" and insert you own message. Now press F1 to run the program. The program display will rapidly fill up with dozens of copies of your text. Press CTRL+C to exit from this routine. Saving a Basic program Return to the editor window, and type ALT+S to save your current program onto the disc. If you feel like a change, hold down the right mouse key and click on the "Save as" option from the SYSTEM menu with the left button. Either way you'll jump straight back to the AMOS file selector window. You should now enter the name of your new file straight from the keyboard. As you type, your letters will appear in a small window at the bottom of the selector. Like the editor, there's a cursor at the current typing position. This cursor can be moved around using all the normal editing keys Finally, press Return to save your prog to disc. Scrolling through your files If your disc is reasonably full, the standard selection window won't be able to list the entire contents of your disc at once. You can page through the listing using the scroll bar to the left of the selection window. Changing the current drive To the right of the file window, there's a list of drive names. The precise contents of the window will naturally depend on the devices you've connected to your Amiga. If you have several drives, you can switch between them by simply clicking on the appropriate name. The directory of this drive wlil now be entered into the selection window. Changing the directory When you search through the directly listing, you'll discover several names with an asterix character "*" in front of them. These are not files at all. They are entire directories in their own right. You can enter one of these folders by selecting them with the left mouse button. You may then choose your files directly from this folder. Note that only the files with the current extension ".AMOS" will be displayed. Once you've opened a directory, you can set it as the default using the SETDIR button. The next time you enter the file selector or obtain a directory listing with DIR, your chosen folder will be entered automatically. Similarly, you can move back to the previous directory by clicking on the PARENT button. Setting the search path Normally, AMOS will search for all filenames with the extension ".AMOS". If you want to laod a file with another extension such as .BAK, you can edit the search pattern directly. This can be acomplished in the following way. Move the text cursor to the PATH window by pressing with the up arrow from the keyboard. Now type your new path and hist Return. A full description of the required syntax can be found in the section on the DIR command. WARNING!: AMOS uses its own individual search patterns which are very different from the standard Amiga Dos System. If you're unsure, delete the entire line up to the current VOLUME or DRIVE name and hit Return. This will present you with a full list of ALL the files on the present disc. Using the file selector Interestingly enough, it's also possible to call this file-selector directly from your own programs. For a demonstration, enter DIRECT mode and type the following line: Print Fsel$(*.*) After you've chosen a file, the name you've selected will be printed straight onto screen! See FSEL$ for a detailed explanation of this command. Editor tutorial We'll now have a brief look at some of the more advanced editing features available from the AMOS editor. We'll start by loading an example program from the disc. Just for a challenge, we've placed this in a separate MANUAL folder on the AMOS program disc. Insert your COPY of the program disc into your Amiga' Scrolling through a listing Alongside the main editor window are two "scroll bars". These allow you to page through your listing with the mouse. Move the mouse pointer over the Vertical bar and hold down the left button. Now drag the bar down the screen. The editor window will scrolls moothly downwards through the listing. You can also scroll the program using the Arrow Icons at the top and bottom of this bar. Clicking on these icons moves the line exactly one place in the required direction. At the far bottom of the editor window, there's a horizonal scroll bar. This can be used to move the window left and right in exactly the same way. If you prefer to use the keyboard for your editing, you'll be pleased to discover that there are dozens of equivalent keyboard options as well. For example; CTRL+UP Arrow shift the listing to the previous page. CTRL+DOWN Arrow moves the listing to the next page All the keyboard options obey the same basic principles. So once you've familiarised yourself with one command, the rest are easy. A full list of these commands can be found towards the end of this chapter. Now we've looked at the program. It's time to actually change something. Search through the program listing until you find the line: ALERT[50,"Alert box","","Ok","Cancel",1,2] This calls a Basic procedure which displays a working alert box on the screen. The format of this procedure is: ALERT[Y coord,Title 1$,Title 2$,Button 1$,Button 2$,Paper,Ink] Let's change this alert to something a little more exciting. Move the cursor over the above statement, and edit the line with the cursor keys so that it look like so: ALERT[50,"Exterminate!","Securitate","Yep!","Yep!",1,3] Execute the program by pressing F1 or selecting RUN from the main menu. You'll be given the unique option of stopping the lamest Amiga-group in the World in its tracks. Select a button with the mouse and make your choice! In practive, you can change the title and the buttons to literally anything you like. Feel free to use this routine in your own progs. Hopefully, the above example will have provided you with a real spur to use procedures in your own programs. In order to aid you in this task, we've built a powerful range of special editing features into the AMOS editor. Label/procedure searches If your program is very long, it can be quite hard to find the starting points of your various procedure definitions. We've therefore included the ability to jump straight to the next procedure definition in your program, using just two keys (Alt+Arrow) For an example, place the cursor at the start of the listing and press Alt+down arrow. Your cursor will be immediately moved to the beginning of the first procedure definition in the current program (ALERT). You can repeat this process to jump to each procedure definition in turn. This system is not just limited to procedures of course. It also works equally well with Labels or line numbers. So even if you don't need procedures, you'll still find a use for this feature. Folding a procedure definition If you build up your programs out of a list of frequently used procedures, your lisings an easily be cluttered with the definitions of all your various library routines. Fortunately, help is at hand. With a simple call to the Fold command, you can hide away any of your procedure definitions from your listings. These routines can be used in your program as normal, but their definitions will be replaced by a single Procedures statement. Example: Position the cursor anywhere in the definition of ALERT and click on the Fold/Unfold option from the menu window. Bing! The contents of your procedure will vanish into thin air! Despite this, you can run the program with no ill effects. The only change has been in the appearance of the listing in the editor window. Just select Fold/Unfold again, and your procedure will be expanded to it's fully glory. It's also possible to fold ALL the procedures in your program at once. This uses an option on the SEARCH menu called "Close All". To bring the Search menu onto the screen, click on the button with the same name, or press F5 from the keyboard. Now select the Close All button to remove the procedure definitions from the current program. The effect on EXAMPLE 3.1 is dramatic! The entire program now fits into just a single screen. So you can instantly see the procedures we've been using in the program. Each procedure definition can be edited individually by expanding it with the Fold/Unfold button. Or you can unfold the whole program with "Open All" from the Search menu. Search/Replace The search/replace commands provided by the AMOS Basic editor are accessed through a special Search menu which can be called up either from the menu window or by pressing function key F4. Finding an item We will continue our tutorial with a brief look at of some of the Search/replace instructions. Let's start with the FIND command. This can be executed either directly from the Search menu or using the keys CTRL+F. When you select this command, you'll be asked to enter the search string. For example, hit CTRL+F and type "Rem" at the prompt. AMOS ill now search for the next "Rem" statement in your program, starting from the current cursor position. If the search is succesful, then cursor will be replaced over the requested item. The search can now be repeated from this point with the "Find Next" option (CTRL+N). Replace Supposing we wanted to change all the Rem statements in a program with the equivalent "'" characters. This could be accomplished with the "Replace" command. In order to use this option, it's necessary to define the replacement string. So the first time you call up replace, you will always be asked to enter this string from the keyboard. Press CTRL+R, type in ' (apostophe) at the prompt and hit the return key to enter it into the computer. You now set the search string with the "Find" option like so: * Press CTRL+F to select the FIND option. * Type "Rem" into the information line. * The cursor will then be moved straight to the next Rem statement in your program listing. To change this to the replacement string and jump to the next occurrence, select Replace (CTRL+R) once again. Alternatively, if the Rem is in the middle of the line, you'll need to skip it, because AMOS only allows you to substitute a quote for this command at the start of a line. You can avoid this problem and jump directly to the next item in your program using "Find Next". Cut and paste The AMOS Block commands allow you to cut out parts of your programs and save them in memory for future use. Once you've created a block, you can copy it anywhere you like in the current listing. Here's an example of this feature in action. Let's take the previous ALERT program, and cut out a single procedure. Place the mouse pointer over the first line of the INVERT procedure, and depress the right mouse button. We can now enter this procedure into a block using the mouse. As you move the mouse, the selected area will be highlighted in reverse. We can now grab this area into memory using "Cut". When you press CTRL+C from the keyboard, the procedure will be removed from the listing and stored into memory. It's now possible to paste this block anywhere you like in your program. For the purposes of our example, move the text cursor down to the bottom of the listing, and call the Paste optin with CTRL+P. The INVERT procedure wlil now be copied to the current cursor position. Multiple programs and accessories Multiple programs Although AMOS only allows you to edit a single program at a time, there's no limit to the number of programs which can be installed into memory, other than the amount of available storage space. Once you've installed a program in this way, you can execute it straight from Editor window with the "Run Other" option. Supposing, for instance, you encounter a problem in one of your programs. AMOS will let you effortlessly swap your existing program into memory so that you can freely experiment with the various possibilities until you find a solution. After you've finished, you can now grab your new routine into memory with the cut option, and flick back into your original program by pressing just two keys! The new routine can the be pasted into position, and you can continue with your program as before. The ability to stop everything and try out your ideas immediately, is incredibly valuable in practice. Another possibility is to permanently keep all the most commondly neede utilities such as the sprite definer or the map editor in the memory. You can now access these utilities instantaneously, whenever you need them. In fact, AMOS includes a special ACCESSORY system which makes this even easier. The utility programs can be given total access to all the memory banks in your main programs. So the sprite definer can grab the images straight from your current program, and modify them directly. This tehcnuque speeds up the overall development process by an amazing degree! Let's have a quick demonstration of these facilities. Enter the following small prog into the editor: Print "This is program One" Boom We can now push this program into memory using the push command. This is called up by pressing AMIGA+P. You'll then be asked to enter the name of your program from the information line. Type in a name like "Program1" at this point. The edit screen will be cleared completely. The new window is totally separated from your original program. As a demonstration, enter a second routine like so: Print "This is program Two" Shoot This program can now be executed from the editor window using RUN (F1). but when your return you can immediately jump to the old one with the "Flick" option. Try pressing AMIGA+F. As before, you'll be asked to enter a name for your program. Use a name like "program2" for this purpose. The editor will now jump straight to your original program as if by magic. It's possible to repeat this process to jump back and forth between the two programs. Each program is entirely independent and can have it's list of own banks and program screens. So far, we've only discussed how you can use two programs at a time. However, you can actually have as many program in memory as you like. These programs can be selected individually using the "Run Other" and "Edit Other" options from the Menu window. When you call these commands, a special "program" selector will be displayed on the screen. The program selector is almost identical to the familiar AMOS file selector. The only difference is that it allows you to choose a program from memory rather than from the disc. You can select a program by simply highlighting it with the mouse cursor and clicking once on the left button. Accessories In order to distinguish accessories from normal Basic programs, they're assigned a ".ACC" extension instead of the more usual ".AMOS". Accessories can be loaded into memory like any normal program using the "Load Other" command. Load Other presents you with a normal fileselector which can be used to load an accessory program from the disc. After the accessory has been installed into memory you will be returned straight back to your current program. You can now run this accessory at any time using the Run Other option from the menu window. Simply move the mouse pointer over your required accessory and press the left button. Alternatively, you can load all the accessories from the current disc using the Accnes/Load feature. This option can be found on the System menu which is displayed when you hold down the right mouse button. Accnew/Load erases all existing accessories and loads a new set from the current disc. For a demonstration, place the AMOS Program disc into your drive, and click on the Accnew/Load button from the System menu. The HELP accessory will be quickly loaded into memory. HELP is a special accessory because it can be called up directly by pressing the HLEP key. We've packed this program with all the information you'll need about the accessor yprograms supplied with AMOS Basic. All you need to do, is just follow the prompts which will be displayed on the screen. Direct mode The Direct mode window can be entered from the editor by pressing the ESCape key at any time. As a default, the window is displayed in the lower half of the screen, with the program screen in the background. If you run a program that changes the screen format, displays windows, animates sprites etc, then all this screen data will remain intact. So you can move the DIRECT window around or flip back to the editor to make program changes without destroying the current program screen. This DIRECT mode window is totally independent and is displayed on its own front level screen. Whilst you're within direct mode you can type any line of AMOS Basic you wish. The only commands you cannot use are loops and branch instructions. You only have access to normal variables (as distinct from the loca bariables defined in a procedure). Direct mode editor keys ESCape Jump to the editor window Return Executes the current line of commands DELete Delete character under cursor/ Backspage Delete character to the left of the cursor Left Arrow Move cursor left Right Arrow Move cursor right Shift+Left Skip a word to the left Shift+Right Skip a word to the right Shift DELete Deletes entire line. Shift BACK Ditto Help Displays the function key definitions to the direct window. F1 to F10 These keys remember the last 10 lines you've entered from the direct mode. F1 displays the latest one entered, F2 the second to last, etc. The memory area used by this system is always cleared when you return to the editor window or run one of your programs. The menu window There's a detailed explanation of all the options which are available from the main menu window. Default menu This gives you various commands that allow you to operate the editor, plus give you access to the block and search menus. RUN (F1) Runs the current program in memory TEST (F2) Cheks the program syntax INDENT (F3) Takes the current program and indents the listing. BLOCKS MENU (F4) Displays the Blocks menu. SEARCH MENU (F5) Displays the Search menu RUN OTHER (F6) Runs a program or accessory in memory EDIT OTHER (F7) Edits a program which has previously installed into memory using the "Load Other" or "Accnew/Load". OVERWRITE (F8) Toggles between insert and overwrite -editing modes. FOLD/UNFOLD (F9) Takes a procedure definition and folds it away inside your program listing. Normally, it's possible to re-open a folded procedure by repeating the process. Place the cursor over a folded procedure and click on FOLD/UNFOLD. If you feel the need for extra security you can also call up a special LOCK accessory from the AMOS Program disc. This will ask for a code word, and will lock your procedures so that they can't be subsequently examined from AMOS Basic. Simply fold your required proceduers and load FOLD.ACC using the LOAD OTHERS command. Full instructions are included with the utility. The real beauty of this system is that it allows you to create whole libraries of your routines on the disc. These can be loaded into memory as a separate program (See LOAD OTHER). You can now cut out the routine you need and copy them directly into your main program. So once you've written a routine, ou can place it into a procedure and reuse it again and again. If you're intending to use this sytem, there are several points to concider.  * Whenever you fold or unfold a procedure a syntax check is made of the entire program. If an error occurs the operatoni will not be performed. So it's vital that you keep back-up copies of all your procedures in Unfo The system menu 24 LOAD (SFT+F1 / AMIGA+L) Loads an AMOS Basic Program SAVE (SFT+F2 / AMIGA+S) Saves the current Basic Program SAVE AS (SFT+F3 /SFT+AM+S) Saves the prog with another name MERGE (SHIFT+F4) Enters the chosen prog at the current csrs position without erasing the current program. MERGE ASCII (SHIFT+F5) Merges an Ascii version of an AMOS Basic 25 program with the existing program in memory AC.NEW/LOAD (SHIFT+F6) Enters a new accessory set from the disc LOAD OTHERS (SHIFT+F7) Loads a single accessory from the disc NEW OTHERS (SHIFT+F8) Erases accessorie(s) from memory NEW (SHIFT+F9) Erases the current program from memory QUIT (SHIFT+F10) Exits AMOS and returns control to the CLI The blocks menu BLOCK START (CTRL + B/F1) Sets the starting point for the current block BLOCK END (CTRL + E/F6) Defines the end of a block BLOCK CUT (CTRL + C/F2) Removes the selected block into memory 26 BLOCK PASTE (CTRL + P/F7) Pastes the block to the current csrs position BLOCK MOVE (CTRL + M/F3) Move the block to the current cursor position erasing the original version completely BLOCK STORE (CTRL + S/F8) Copies the block into memory. BLOCK HIDE (CTRL + H/F4) Deselects the block you've highlighted BLOCK SAVE (CTRL + F9 ) Saves the current block on the disc as an AMOS program SAVE ASCII (CTRL + F5 ) Stores your selected block on the disc as a normal text file. BLOCK PRINT (CTRL + F10) Outputs the selected block to the printer The search menu FIND (ALT + F1) Enters a string of up to 32 chars and searches through your text until a match is found. FIND NEXT (ALT + F2) Searches for the next match you specified FIND TOP (ALT + F3) Searches from the top of program the string rather than starting from the crsr position REPLACE (ALT + F4) Activates REPLACE mode. The effect of this command varies depending when it's used: * Before a FIND You'll now be asked to enter the replacement string from the keyboard * After a FIND If the search operation was succesful, the text and the current cursor position will be swapped with the replacement string. REPLACE will now jump to the next occurrence of the search string. REPLACE ALL (ALT + F5) Replaces ALL copies of a word in your prog. LOW <> UP (ALT + F6) Changes the case sensitivity used in search commands OPEN ALL (ALT + F7) Opens all closed procedures in your program CLOSE ALL (ALT + F8) CLoses all procedures in your program SET TEXT B (ALT + F9) SET TEXT BUFFER. Changes the # of chars available to hold your listings. SET TAB (ALT + F10) Sets the number of chars which the crsr will be moved when the user presses the TAB key. Keyboard macros =KEY$= (define a keyboard macro) KEY$(n)=command$ command$)=KEY$(n) KEY$ assigns the contents of command$ to function key number n. (1-20) Keys from one to ten are accessed by pressing the function key in conjuction with the left Amiga button. Similarly, numbers from eleven onwards are called with a right Amiga Fn combination. Command$ can be any string of text you wish, up to maximum of 20 characters. There are two special characters which are directly interpreted by this function: ' (Alt+Quote) Generates a Return code ' (single Quote) Encloses a comment. This is only displayed in your key lists. It's totally ignored by the macro routine. Examples: ? Key$(1) Key$(2)="Default" Alt+F2 Key$(3)="'Comment print" In practice, this macro system can prove incredibly useful. Not only can you speed up the process of entering you Basic programs, but you can also define a list of standard inputs for your Basic programs. These would be extremely effective in an adventure game, as can be seen from the program EXAMPLE 3.2 in the MANUAL folder. If you wish to generate a keypress which has no ASCII equivalent such as up arrow, you can optionally include a scancode in these macros. This is achieved using the SCAN$ function. =SCAN$ (return a scan code for use with KEY$) x$=Scan$(n,[,m]) n is the scancode of a key to be used in one of your macro definitions. m is an optional mask which sets the special keys such as CTRL or Alt, in the following format: Bit Key Tested Notes 0 Left SHIFT 1 Right SHIFT 2 Caps Lock Either ON or OFF 3 CTRL 4 Left ALT 5 RIght ALT 6 Left AMIGA Commodore key on some keyboards 7 Right AMIGA If a bit is set to a one, then the associated button is depressed in your macro. Examples: KEY$(4)="Wheee!"+Scan$($4C) KEY$(5)="Page Up!"+Scan$($4C,%00010000) Conserving memory CLOSE WORKBENCH (closes the workbench) CLOSE WORKBENCH Closes the workbench screen saving around 40K of memory for your programs! Example: Print Chip Free,Fast Free Close Workbench Print Chip Free,Fast Free CLOSE WORKBENCH can be executed either from direct mode, or inside on of your Basic programs. A Typical program line might be: If Fast Free=0 Then Close Workbench This would check for a memory expansion and close the Workbench if extra memory was not available. CLOSE EDITOR (close editor window) CLOSE EDITOR Closes the Editor window while your program is running, saving you more than 28K of memory. Furthermore, there's absolutely NO effect on your program listings! If there's not enough memory to reopen the window after your program has finished, AMOS will simply erase your current display and revert back to the standard DEFAULT screen. You'll now be able to effortlessly jump back to the Editor with the ESCape key as normal. What a terrific little instruction! Inside accessories We'll now explore the general techniques required to write your own accessory programs. These are really just specialised form of the multiple programs we discussed a little earlier. As you would expect, they can incorporate all the standard Basic instructions. Accessories are displayed directly over your current program screen and the music, sprite, or bob animations are automatically removed from the screen. Your accessory should therefore check the dimensions and type of this screen using the SCREEN HEIGHT, SCREEN WIDTH and SCREEN COLOUR commands during its initialisation phase. If the current screen isn't acceptable, you may be forced to open a new screen for the accessory window or to erase the existing screens altogether with a DEFAULT instruction. Any memory banks used by your accessory are totally independent of the main program. If it's necessary to change the banks from the current program, you can call a special BGRAB command. BGRAB (grabs the banks used by the current program) BGRAB b BGRAB "borrows" a bank from the current program and copies it into the same bank in your accessory. If this accessory bank already exists, it will be totally erased. When the accessory returns to the editor, the bank you have grabbed will be automatically returned to your main program along with any changes. b is the number of a bank from 1 to 16. Note that this instruction can only be used inside an accessory. If you try to include it in normal program, you'll get an appropriate error message. PRUN (run a program from memory) PRUN "name" Executes a Basic program which has been previously installed in the Amiga's memory. This command can be used either from the direct mode, or within a program! In effect, PRUN is very similar to a standard procedure call, except that any bobs, sprites or music will be totally suspended. Note that it's impossible to call the same program twice in the same session. After you've called it once, any further attempts will ignored completely. =PRG FIRST$ (read the first program loaded into memory) p$=PRG FIRST$ This returns the name of the first Basic program installed in the Amiga's memory. It's used in conjunction with the PRG NEXT$ command to create a full list of all the currently available programs. =PRG NEXT$ (returns the next program installed in memory) p$=PRG NEXT$ PRG NETX$ is used after a PRG FIRST$ command to page through all the programs installed in Amiga's memory. When the end of the list is reached, a value of "" will be returned by this function. Example: N$=Prg First$ While N$<>"" Print "Program" ";N$ N$=Prg Next$ Wend =PSEL$ (call program selector) n$=PSEL$("filter"[default$,title1$,title2$] PSEL$ calls up a program selector which is indential to the one used by the Run Other, Edit Other, Load Others, and New Others commands. This can be used to select a program in the usual way. The name of this program will be returned in n$. If the user has aborted from the selector, n$ will be set to an emptry string "". "filter" sets the type of programs which will be listed by instruction. Typical values are: "*.ACC" List all the accessories in memory "*.AMOS" Only displays the AMOS programs which have been installed. "*.*" List all programs currently in memory. For further details of the system see the DIR command. default$ holds the name of a program which will be used as a default. title1$,title$ Contains up to two lines of text which will be displayed at the top of the selector. See EXAMPLE 3.4 in the MANUAL folder for a demonstration. The HELP accessory Whenever the HELP key is pressed from the Editor window, AMOS automatically executes an accessory with the name HELP.ACC if it's available. Unlike normal accessories, this is displayed directly over the editor window. Special access is provided to the current word you are editing. The address of this word is placed in an address register and can be read using the AREG function. The editor control keys Finally, here's a full list of the various control keys and effects: Special keys ESC Takes you to direct mode Editing keys Backspace Deletes the character to the immediate left of crsr. DELete Deletes the character underneath the cursor RETURN Tokenises the current line. If you move onto a line and press RETURN it will split the line SFT+BCKS/CTRL+Y Deletes current line CTRL+U Undo. Return the last line when in overwrite mode. CTRL+Q Erase the rest of chars in the line from crsr position CTRL+I Insert a line at the current position The cursor arrows Left,Right Moves cursor one space to the left/right Up,Down Moves cursor one line up/down SHIFT+Left,Right Positions the cursor over the previous/next word SHIFT+up,down Move cursor to the top/bottom line of the current page CTRL+up,down Displays the previous/next page of program SHIFT+CTRL+up,dn Move to start/end of text AMIGA+up Scrolls text up without moving the cursor AMIGA+down Scrolls text down under the cursor AMIGA+left,right Scroll program to the left/right on the current line Program control AMIGA+S Saves your program under a new name AMIGA+SHIFT+S " " current name AMIGA+L Loads a program AMIGA+P Pushes the current program into a mem and creates a new program. AMIGA+F Flips between two progs stored in memory AMIGA+T Displays next program in memory. Cut and Paste CTRL+B Set the beginning of a block CTRL+E Set end point of a block CTRL+C Cut block CTRL+M Block move CTRL+S Saves the block in memory without erasing it first CTRL+P Paste block at current cursor position CTRL+H Hide block. Marks CTRL+SHIFT+(0-9) Defines a marker at the present cursor position. CTRL+(0-9) Jumps to a mark Search/Replace ALT+UP Arrow Searches backwards through your program to the next line which contains a label or procedure definition. ALT+DOWN Arrow Searches down through yur program to find the next label or procedure definition CTRL+F Find CRTL+N Find Next CTRL+R Replace Tabs TAB Move the entire line at the cursor to the next TAB pos. SHIFT+TAB Move the line to the previous Tab position CTRL+TAB Sets the TAB value 4: BASIC PRINCIPLES This chapter discusses the ground rules used to construct AMOS Basic programs and shows you how to improve your programming style with the help of AMOS Basic procedures. Variables Variables are the names used to refer to storage locations inside a computer. These locations hold the results of the calculations performed in one of your programs. The choise of variable names is entirely up to you, and can include any string of letters or numbers. There are only a couple of restrictions. All variable names MUST begin with a letter and cannot commence with an existing AMOS Basic instruction. However it is perfectly permissible to use these keywords inside a name. So variables such as VPRINT or SCORE are fine. Variable names must be continuous, and may not contain embedded spaces. If a space is required, it's a possible to substitute a "_" character instead. Here are some examples of illegal names. The illegal bits are underlined to make things clearer. WHILE$, 5C, MODERN#, TOAD ----- - --- -- Types of variables AMOS Basic allows you to use three different types of variables in your programs. Integers Unlike most other Basics, AMOS initially assumes that all variables are integers. Integers are whole numbers such as 1,3 or 8, and are ideal for holding the values used in your games. Since integer arithmetic is much faster than the normal floating point operations, using integers in you programs can lead to dramatic improvements in speed. Each integer is stored in four bytes and can range from -147'483'648 to +147'483'648. Examples of integer variables: A, NUMBER, SCORE, LIVES Real numbers In AMOS Basic these variables are always followed by a hash (#) character. Real numbers can hold fractional values such as 3.1 or 1.5. They correspond directly to the standard variables used in most other versions of Basic. Each real variable is stored in four bytes and can range between 1E-14 and 1E-15. All values are accurate to a precision of seven decimal digits. Examples: P#, NUMBER#, TEST# String variables String variables contain text rather than numbers. They are distinguished from normal variables by the $ character at the end. The length of your text can be anything from 0 to 65'500 characters. Examples of string variables: NAME$, PATH$, ALIEN$ Giving a variable a value Assigning a value to a variable is easy. Simply choose an appropriate name and assign it to value using the "=" statement. VAR=10 This loads the variable VAR with a value of 10. A$="Hello" This assigns string "Hello" to a variable A$. Arrays Any list of variables can be combined together in the form of an array. Arrays are created using the DIM instruction. DIM (dimension an array) DIM var(x,y,z,...) DIM defines a table of variables in your AMOS Basic program. These tables may have as manu dimensions as you want, but each dimension is limited to a maximum of 65'000 elements. Example: Dim A$(10),B(10,10),C#(10,10,10) In order to access an element in the array you simply type the array name followed by the index numbers. These numbers are separated by commas and are enclosed between round brackets (). Note that the element numbers of these arrays always start from zero. Example: Dim ARRAY(10) ARRAY(0)=10:ARRAY(1)=15 Print ARRAY(1);ARRAY(0) ( result: 15 10 ) Constants Constants are simply numbers or strings which are assigned to a variable or used in one of your calculations. They are called constants because they don't charge during the course of your program. The following values are all constants: 1, 42, 3.141, "Hello" As a default, all numeric constants are treated as integers. Any floating point assignments to an integer variable are automatically converted to a whole number before use. Examples: A=3.141:Print A ( result: 3) Print 19/2 ( result: 9) Constants can also be input using binary or hexadecimal notation. Binary numbers are signified by preceding them with a % character, and hexadecimal numbers are denoted by a $ sign. Here's number 255: Decimal: 255 Hexadecimal: $FF Binary: $11111111 Note that any numbers you type in AMOS Basic are automatically converted to special internal format. When you list your program these numbers are expanded back into their original form. Since AMOS Basic prints all numbers in a standard way, this will often lead to minor discrepancies between the number you entered and the number which is displayed in your listing. However the value of the number will remain exactly the same. Floating point constants are distinguished from integers by a decimal point. If this point is not used, the number will always be assumed to be an integer, even if this number occurs inside a floating point expression. Take the following example: For X=1 To 10000 A#=A#+2 Next X Every time the expression in this program is evaluated, the "2" will be laboriously converted into a real number. So this routine will be inherently slower than the equivalent program below: For X=1 To 10000 A#=A#+2.0 Next X This program executes over 25% faster than the original one because the constant is now stored directly in floating point format. You should always remember to place a decimal oint after a floating point constant even if it is a whole number. Incidentally, if you mix floating point numbers and integers, the result will always be returned as a real number. Example: Print 19.0/2 ( result: 9.5 ) Print 3.141+10 ( result: 13.141 ) Arithmetic operations The following arithmetic operations can be used in a numeric expression: ^ power / * divide and multiply MOD modulo operator (remainder of a division) + - plus and minus AND logical AND OR logical OR NOT logical NOT We've listed these operations in descending order of their priority. This priority refers to the sequence in which the various sections of an arithmetic expressions are evaluated. Operations with the highest priority are always calculated first. INC (add 1 to an integer variable) INC var INC adds 1 to an integer variable using a single 68000 instruction. It is logically equivalent to the expression var=var+1, but faster. Example: A=10:Inc A:Print A ( result: 11 ) DEC (subtract 1 from an integer variable) DEC var This instruction subtracts 1 from the integer variable var. Example: A=2:Dec A:Print A ( result: 1 ) ADD (fast integer addition) ADD v,exp [,base TO top] The standard from of this instruction immediately adds the result of the expression exp to the integer variable v. It's equivalent to the line: V=V+EXP The only significant difference between the two statements is that ADD performs around 40% faster. Note that the variable v must be an integer. Example: Timer=0 For X=1 To 1000 Add T,X Next X Print T,Timer ( result: 500500 7 ) The second version of ADD is a little more complicated. It is effectively identical to the following code (but faster): V=V+A If VBase Then V=Base Example: Dim A(10) For X=0 To 10:A(X)=X:Next X V=0 Repeat Add V,1,1 To 10 Print A(V) Until V=100:rem This is an infinite loop as V is always less than 10! As you can see, ADD is ideal for handing circular or repetitive loops in your games. String operations Like most versions of Basic, AMOS will happily allow you to add two strings together. A$="AMOS"+" Basic" Print A$ ( result: AMOS Basic ) But AMOS also lets you perform subtraction as well. This operation works by removing all occurrences of the second string from the first. Print "AMOS BASIC"-"AMO" ( result: S BASIC ) Comparisons between two strings are performed on a character by character basis using the Ascii values of the appropriate letters: "AA"<"BB" "Filename"="Filename" "X&">"X#" "HELLO"<"hello" Parameters The values you enter into an AMOS Basic instruction are known as parameters. i.e Inc N Add A,10 Ink 1,2,3 The parameters in the above instructions are N,A,10,1,2 and 3 respectively. Occasionally, some of the parameters of a command can be ommitted from an instruction. In this case, any unused values will automatically be assigned a number by default. Example: Ink 5,, This changes the ink colour without affecting either the paper or outline colours. Line numbers and labels Labels Labels are just a convenient way of marking a point in your AMOS Basic programs. They consist of a string of characters formed using the same rules as AMOS variables. Labels should always be placed at the start of the line, and must be followed immediately by a ":" character. There should be no spaces between the label and the colon. Example: TESTLABEL: Print "Hi There!" Goto TESTLABEL This program can be aborted by pressing CTRL+C... Procedures Procedures allow you to concentrate your efforts on just one problem at a time without the distractions provided by the rest of your program. Once you've written your procedures you can then quickly combine them in your finished program. AMOS procedures are totally independent program modules which can have their own program lines, variables, and even data statements. PROCEDURE (create an AMOS Basic procedure) Procedure NAME[parameter list] : : End Proc[Expression] This defines an AMOS Basic procedure called NAME. NAME is a string of characters which identify the procedure. It is constructed in exactly the same way as a normal Basic variable. Note that it's perfectly acceptable t ouse identical names for procedures, variables and labels. AMOS will automatically work out which object you are referring to from the context of the line. Procedures are similar to the GOSUB commands found in earlier versions of Basic. Here's an example of a simple AMOS procedure: Procedure ANSWER Print "Forty-Two!" End Proc See how the procedure has been terminated with an END PROC statement. You should also note that the Procedure and the End Proc directives are both placed on their own separate lines. This is compulsory. If you type the previous procedure into AMOS Basic as it stands, and attempt to run it, nothing will happen. That's because you haven't actually called the new procedure from your Basic Program. This can be achieved by simply entering its name at the appropriate point in the program. As an example, enter the following line at the start of the program and run it to see the result of the procedure. ANSWER IMPORTANT! When you are using several procedures on the same line, it's advisable to add an extra space at the end of each statement. This will avoid the risk of the procedure being confused with a label. For example: TEST : TEST : TEST Performs the test three times. TEST:TEST:TEST Defines Label TEST and executes test 2x Alternatively, you can preclude your Procedure calls with a Proc statement like so: Proc ANSWER Example: Proc ANSWER Procedure ANSWER Print "Forty-Two" End Proc If you run this program again, the procedure will be entered, and the answer will be printed out on the screen. Although the procedure definition is positioned at the end of the program, it's possible to place it absolutely anywhere. Whenever AMOS encouters a Procedure statement, it installs the procedure and immediately jumps to the final End Proc. This means there is no danger of accidentally executing your procedure by mistake. Once you've created a procedure, and tested it to your satisfaction, you can suppress it in your listings using the fold option from the main menu. These folding procedures reduce the apparent complexity of your listings and allow you to debug large programs without the distractions of unimportant details. You can restore your procedure listings to the screen at any time by selecting the 'unfold menu option'. Local and global variables All the variables you define inside your procedures are independent of any other variables used in your program. These variables are said to be "local" to your particular procedure. Here's an example which illustrates this: A=1000:B=42 TEST Print A,B Procedure TEST Print A,B End Proc It should be apparent that the names A and B refer to completely different variable depending on whether they are used inside or outside the procedure TEST. The variables which occur outside a procedure are "global" and cannot be accessed from within it. Let's take another example: Dim A(100) For V=1 To 100: A(V)=V:Next V TEST_FLAG=1 APRINT End Procedure APRINT If TEST_FLAG=1 For P=1 To 100 Print A(P) Next P Endif End Proc This program may look pretty harmess but it contains two fatal errors. Firstly, the value of TEST_FLAG inside the procedure will always have a value of zero. So the loop between the IF and the ENDIF will never be performed. That's because the version of TEST_FLAG within the procedure is completely separate from the copy defined in the main program. Like all variables, it's automatically assigned to zero the fist time it's used. Furthermore, the program won't even run! Since the global array a() has been defined outside ARPINT, AMOS Basic will immediately report an "array not dimensioned" error at the line: Print A(P) This type of error is extremely easy tomake. So it's vital that you treat procedures as separate programs with their own independent set of variables and instrcutions. There are a couple of extensions to this system which make it easy for you to transfer information between a procedure and your main program. Once you're familiar with these commands you'll have few problems in using procedures successfully in your programs. Parameters and procedures One possibility is to include a list of "parameter definitions" in your procedure. This creates a group of local variables which can be loaded directly from the main program. Here's an example: Procedure HELLO[NAME$] Print "Hello ";NAME$ End Proc The value to be loaded into NAME$ is entered between square brackets as part of the procedure call. So the HELLO procedure could be performed in the following ways: Rem Loads N$ into NAME$ and enters procedure Input "What's your name";n$ HELLO[N$] HELLO["Stephen"] As you can see, the parameter system is general purpose and works equally well with either variables or constants. Only the type of the variables are significant. This process can be used to transfer integer, real or string variables. However you cannot pass entire arrays with this function. If you want to enter several parameters you should separate your variables using commas. For example: Procedure POWER[A,B] Procudure MERGE[A$,B$,C$] These procedures might by called using lines like: POWER[10,3] MERGE["One","Two","Three"] Shared variables Another way of passing data between a procedure and the main program is to use the SHARED instruction. SHARED (defina a list of global variables) SHARED variable list SHARED is placed inside a procedure definition and takes a list of AMOS Basic variables separated by commas. These variables are now treated as global variables., and can be accessed directly from the main program. Any arrays which you declare in this way should of course have been previously dimensioned in your main program. Example: A=1000:B=42 TEST Print A,B Procudure Test Shared A,B A=A+B:B=B+10 End Proc TEST can now read and write information to the global variables A and B. If you want to share an array you should define it like so: Shared A(),B#(),C$() : Rem Share arrays A,B# and C$ GLOBAL (declare a list of global variables from the main program) GLOBAL variable list When you're writing a large program, it's commonplace for a number of procedures to share the same set of global variables. This provides a simple method of transferring large amounts of information between your various procedures. In order to simplify this process, we've included a single command which can be used directly in your main program. GLOBAL defines a list variables which can be accessed anywhere inside your Basic program, without the need for an explicit SHARED statement in your procedure. Returning values from a procedure If a procedure needs to return a value which is only local to itself, it must use the following command so that it can inform the calling PROCEDURE command where to find the local variable PARAM (return a parameter from a procedure) PARAM The PARAM functions provide you with a simple way of returning a result from a procedure. They take the result of an optional expression in the END PROC statement, and return it in one of the variables PARAM, PARAM#, or PARAM$ depending on its type. Example: MERGE_STRINGS["Amos"," ","Basic"] Print PARAM$ Procedure MERGE_STRINGS[A$,B$,C$] Print A$,B$,C$ End Proc Note that END PROC may only return a single parameter in this way. The PARAM functions will always contain the result of the most recently executed procedure. Here's another example, this time showing the use of the PARAM# function. CUBE[3,0] Print Param# Procedure CUBE[A#] C#=CUBE#*CUBE#*CUBE# EndProc[C#] Leaving a procedure POP PROC (leave a procedure immediately) POP PROC Normally, procedures will only return to the main program when the END PROC instruction is reached. Sometimes, however, you need to exit a procedure in a hurry. IN this case you can use the POP PROC function to exit immediately. Local DATA statements Any data statements defined inside one of your procedures are held completely separately from those in the main program. This means each procedure can have its own individual data areas. Hints and tips Here are a few guidelines which will help you make the most out of your AMOS Basic procedures: * It's perfectly legal for a proceduces to call itself, but this recursion is limited by the amount of space used to store the local variables. If your program runs out of memory you'll get an appropriate error. * All local variables are automatically discarded after the procedure has finished executing. Memory banks AMOS Basic includes a number of powerful facilities for manipulating sprites, bobs and music. The data required by these functions needs to be stored along with the Basic program. AMOS Basic uses a special set of 15 sections of memory for this purpose called "banks". Each bank is referred to by a unique number ranging from 1 to 15. Many of these banks can be used for all types of data, but some are dedicated solely to one sort of information such as sprite definitions. All sprite images are stored in bank 1. They can be loaded into memory using a line like: Load "AMOS_DATA:Sprites/Octopus.abk" There are two different forms of memory bank: Permanent and temprorary. Permanent banks only need to be defined once, and are subsequently saved along with your program automatically. Temporary banks are much more volatile and are reinitialized every time a program is run. Furthermore, unlike permanent banks, temporary banks can be erased from memory using the CLEAR command. Types of memory bank AMOS Basic supports the following types of memory bank: Class Stores Restrictions Type Sprites Sprite or bob definitions Only bank 1 Permanent Icons Holds icon definitions Only bank 2 Permanent Music Contains sound track data Only bank 3 Permanent Amal Used for AMAL data Only bank 4 Permanent Samples The Sample Data banks 1-15 Permanent Menu Stores MENU definition banks 1-15 Permanent Chip work Temporary workspace banks 1-15 Temporary Chip data Permanent workspace banks 1-15 Permanent Fast work Temporary workspace banks 1-15 Temporary Fast data Permanent workspace banks 1-15 Permanent RESERVE (reserve a bank) RESERVE AS type,bank,length The banks used by your sprites or bobs are allocated automatically by AMOS. The RESERVE command allows you to create any other banks which you might require. Each different type of bank has its own unique version of the RESERVE instruction. RESERVE AS WORK bankno,length Reserves "length" bytes for use as a temporary workspace. Whenever possible this memory area will be allocated using fast memory, so you shoudn't call this command in conjunction with instructions which need to access to Amiga's blitter chip. RESERCE AS CHIP WORK bankno,length Allocates a workspace of size "length" using chip ram. You can check whether there's enough chip ram available with the CHIP FREE function. RESERCE AS CHIP DATA bankno,length Reserves "length" bytes of memory from chip ram. This bank will be automatically saved along with your AMOS programs. Bank may be any number between 1 and 15. Since banks 1 to 5 are normally reserved by the system, it's wisest to leave them alone. Note that the only limit to the length of a bank is the amount of available memory. LISTBANK (list the banks in use) LISTBANK lists the numbers of the banks currently reserved by a program, along with their location and size. The listing is produced in the following format: Number Type Start Length Normally the length of a bank is returned in bytes, but in case of sprites and icons the value represents the total number of images in the bank instead. The reason for this is that the storage of each image can be anywhere in the Amiga's memory, the bank is therefore not a continuous block of memory. So don't BSAVE a sprite bank, simply use SAVE "filename.abk" Deleting banks During the course of a program you may need to clear some banks from the memory so as to load in additional data. Sprites may need to change for a new part of a game or a special piece of music is required to be played. The ERASE command gives you quick control for data deletion. ERASE (delete a bank) ERASE b ERASE deletes the contents of a memory bank. The bank number b can range from 1 to 15. Note that any memory used by this bank is subsequently freed for use by your program. Bank parameter functions If you want to have direct access to the bank data using commands such as poke, doke and loke then use these commands to find a bank's address in memory and its size. =START (get the start address of a bank) s=START(b) This function returns the start address of bank unmber b. Once it's been removed, the location of the bank will never subsequently change. So the result of this function will remain fixed for the lifetime of the bank. Example: Reserve As Work 3,2000 Print Start(3) =LENGTH (Get the length of a bank) l=length(b) The LENGTH function returns the length in bytes of bank number b. If the bank contains sprites then the number of sprites or icons will be returned instead. A value of zero indicates that bank b does not exist. Exaple: Reserve as work 6,1000 Print Length(6) Erase 6 Print Length(6) Loading and saving banks Some programs will require many banks of information, a good example is an adventure. This would need to load various graphics and sounds for the different locations within the games domain. An Amiga 500 would have great difficulty holding all this data at once and so it's best to simply load the data at the appropriate time of use. LOAD (Load one or more banks) LOAD "filename"[,n] The effect of this command varies depending on the type of file you are loading. If the file holds several banks, then ALL current memory banks will be erased before the new banks are loaded from the disc. However if you're loading just a single bank, only this bank will replaced. The optional destination point specifies the bank which is to be loaded with your data. If it's omitted, then the data will be loaded into the bank from which it was originally saved. Sprite banks are treated slightly differently. In this case the parameter n toggles between two separate loading modes. If n is omitted or is assigned a value of zero, the current bank will completely overwritten by the new sprites. Any other value for n forces the new sprites to be *appended* to this bank. This allows you to combine several sprite files into the same program. Example: LOAD "AMOS_DATA:Sprites/Octopus.abk" SAVE (Save one or more banks onto the disc) SAVE "filenami"[,n] The SAVE command saves your memory banks onto the disc. There are two possible formats: SAVE "filename.ABK" This saves *ALL* currently defined banks into a single file onto your disc. SAVE "filename.ABK",n The expanded form just saves memory bank number n. One should also be sure to use the extension ABK at the end of the filename as this will ensure you can identify that the file contains one or more memory banks. BSAVE (Save an unformatted block in binary format) BSAVE file$, start TO end The memory stored between "start" and "end" is saved on the disc in file$. This data is saved with no special formatting. Example: BSAVE "Test",Start(7) TO Start(7)+Length(7) The above example saves the data in memory bank 7 to disc. The difference between this file and a saved file as a normal bank is that SAVE writes out a special blank header that contains information concerning the bank. This header is not present with a BSAVED file so it cannot be loaded using LOAD. WARNING: The sprites an icon banks are not stored as one chunk of memory. Each object can reside anywhere in memory. Because AMOS uses this flexible system of data storage you simply can't save the memory bank using BSAVE. BLOAD (load binary information into a specified address or bank) BLOAD file$, addr The BLOAD command loads a file of binary data into memory. It does not alter the incoming information in any way. There are two forms of this function. BLOAD file$, addr File$ will be loaded from the disc into the address addr. BLOAD file$, bank File$ will be loaded into bank. This bank must have been previously reserved, otherwise an error will be generated. Also be sure not to load a file that is larger than the reserved bank, otherwise it will over run the bank and start corrputing other areas of memory! Memory fragmentation Sometimes, after a busy editing session, you may get an "Out of Memory" error, even though the information line implie Finding space for your variables As a default, all variables are stored in a memory area of exactly 8k in length. Although this may seem incredibly meagre, it's easily capable of holding around 2 pages of normal text, or 2000 numbers. We've intentionally set it as small as possible so as to maximize the amount of space available for your screens and memory banks. SET BUFFER (set the size of the variable area) SET BUFFER n Sets the size of the variable area in your current program to "n" kilobytes. This must be the FIRST instruction in your program (excluding Rems). Otherwise you'll get an appropriate error message. For an example of this feature see EXAMPLE 4.1 in the MANUAL folder. SET BUFFER should be used in your program whenever you get an "out of string space error". Increase the value in 5k increments until the error disappears. If you run out of memory during this process, you'll propably need to reduce the requirements of your program in some way. See the CLOSE WORKBENCH and CLOSE EDITOR commands for more details. =FREE (return the amount of free mem. in the variable area) f=FREE FREE returns the number of bytes which are currently available to hold your variables. This value can be increased as required using the previous SET BUFFER command. Whenever FREE is called, the variable area is reorganized to provide the maximum space for your variables. This process is known as "garbage collection", and is normally performed automatically. Due to the power of AMOS Basic, the entire procedure is usually accomplished practically instantaneously. But if your variable area is bery large and you're using a lot of strings, the garbage collection routine might take several seconds to complete. Conceivably, this could lead to a unexpected delay in the execution of your programs. Since the garbage collection is totally essential, you may need to add an explicit call to the FREE command when it will cause the least amount of harm in your program. NOW LOAD PART TWO...