----------------------------------------------------------------------------- AMOS BASIC VERSION 1.36 UPDATER By François Lionet AMOS (c) 1990 / 1991 / 1992 / 1993 Europress Software Ltd. ----------------------------------------------------------------------------- Important copyright notes --------------------------- The AMOS Basic 1.36 Updater is public domain. You can (and you are encouraged to) copy and distribute it freely. It does not mean AMOS Basic itself is public domain. Copyright remains on the interpreter, and on the updated version. You need AMOS Basic V1.1, V1.21, V1.23, V1.3, V1.31, V1.32, V1.34 to make the adaptation. ------------------------------------------------------------------------------ Move the mouse pointer to read the text. ------------------------------------------------------------------------------ Foreword. ------------------------------------------------------------------------- Welcome to a new update of AMOS! This update of the software brings you only one new thing, but a big one: it works on a AA machine. You can now start AMOS from a AA workbench, and flip between them as normal. If you own V1.34 of AMOS, you will find that this is the only modification to the software. If you intend to compile programs and make them available to the Amiga community, make sure that you compile them with Compiler V1.36, which also works under the AA chipset. The V1.36 Compiler Updater is also available in PD. If you own a previous version of AMOS, this version will bring you a much safer environment, better accessories: a lot of work has been done between V1.2 and V1.34 of AMOS... Make sure you read all the documentation to receive all the information about the new instructions... All the best! François 01/02/1993. Contents. --------------------------------------------------------------------------- * Enhancements to V1.34 * Bugs removed from V 1.31 * New instructions in V 1.36 * Manual main bugs * Safe AmigaDos EXECUTE function * Time and Data procedures * Modifications up to V 1.2x - Bob flipping - Serial port (modified since V1.23!) - Multi-tasking - Folders - Interlace - Other bits - Converting your 1.2 .Env file to 1.3 Introduction. ----------------------------------------------------------------------------- AMOS Basic has gone through a number of changes during the course of its existence. Rather than rest on our laurels, we've steadily updated the system to include many new features suggested by AMOS users. Incredibly enough, we've placed these improvements on the public domain. Special updater discs are available from the official AMOS PD. library or your local PD. library. So whatever your version of AMOS Basic, you can upgrade to the latest system for the price of a disc. Here's a list of the versions of AMOS Basic to date: AMOS 1.1 The original! AMOS 1.2 This included several new commands such as a BANK SWAP. There was also a whole new set of SPRITE flipping routines introduced which allowed you to display a single image in several orientations. The file-selector was completely reworked, and allowed you to change the current disc by pressing the RIGHT mouse button and simply clicking on the new device name with the mouse. The UP/DOWN arrows were repositioned at the top of the scroll bar for maximum speed, and the PARENT button was repositioned to the far left corner and reduced in size. AMOS 1.23 Added the SERIAL extension, SPRITE compactor and procedure locking utility. AMOS 1.3 This version comes with the compiler and includes a range of turbo-charged Bob and screen copy routines written by Gary Symons. These optimise the performance of commands such as SCREEN COPY and PASTE BOB/ICON, leading to dramatic speed improvements in many games. AMOS 1.31 Only minor internal modifications done since version 1.3. AMOS 1.34 By cleaning up the code dramatically, we've been able to get rid of many little but annoying problems. It also includes major enhancement to the music routines. AMOS 1.36 AMOS now works on a AA machine. Improvements (from 1.31). ------------------------------------------------------------------------- * AMOS now works on a AA machine. You can as usual flip between a AA workbench and the AMOS Program. The new method used on a AA machine makes it impossible to work under interrupts. That's why you will discover that it Amiga-A does not respond when a disc activity is taking place, but only when disc access is over. The new method used on a AA machine makes it impossible to work under interrupts. That's why you will discover that it Amiga-A does not respond when a disc activity is taking place, but only when disc access is over. * Versions.AMOS. This little program will explore the whole contents of your AMOS_System directory, and load the beginning of each file. It will look for a special string that contains the version number, and display it onto the screen. You will know at a glance all the version numbers of your programs! * The directory system has been totally re-written. You can now, safely use DIR$= to set the current directory, and it does not leave a Lock as it used to. More than that, =DIR$ does not crash any more when it cannot find a disc in the drive. The file selector now automatically sets the dir to the current path when you select a file. Note that the SET DIR button still works, if you want to quickly set the directory, without loading a file. To sum-up, AMOS now has one current path, automatically set by the file selector or by the DIR$= instruction. * Hexadecimal and binary tokenisation now stops on spaces. It makes possible to tokenise such a line: If A=$1234 And B=2 It was impossible before, as the A of "And" was used as part of the hexadecimal number! * AMOS now closes the workbench under 2.0. If you want to prevent that, you have to use the configuration program, in the SET EDITOR menu. New in version 1.36, the CLOSE WORKBENCH instruction will not have any effect if you choose not to close the workbench in the configuration program. More than just preventing AMOS from closing the workbench upon loading, it is preventing any AMOS program from closing it. You are now the master of your own Workbench! * The Requester now appear under AMOS on a 2.0 system. It does not crash as it used to sometimes under 1.3. The disc-inserted detection has been improved, it detects all disc-changes now. It also works with one option requesters. * The disk-font library only loads when you call it the first time. It means you may have to re-insert the Workbench disc upon running a new program, as you would do if it was using floating point numbers. * Load IFF accepts new colour palettes, with colours defined on 8 bytes, instead of 4 (this palette are saved by some new software). * Physical drives are now listed in the device list (in file selector and in =Dev First / =Dev Next). Some devices (like "Work:") are defined in both logical and physical list. You will find them twice in the list. This is normal! * Copy now works with ODD addresses, and ODD lengths. I should have done this improvement much sooner. * You can now recover from an "Out of variable space" error, it does not stop the program as it used to. All you'll have to do in this case, is free a couple of strings from memory. * Sound samples of any length are perfectly played. * Autoback 2 mode does not produce a flash in the bobs as it used to, sometime. It gives a much better display. On the other hand, pasting and printing in this mode will take one VBL longer than before. Bugs removed (from V1.31). -------------------------------------------------------------------------- * ICONS used to be in transparent mode upon loading, instead of being in replace mode, as stated in the manual. * CBLOCK did not work for blocs larger than 480 pixels. * The inactive mouse-zone (when the mouse pointer was exactly over the top of the horizontal slider, no keyboard input was processed) has been removed. * The disappearing line bug has been removed from the editor! * Def Fn does not crash any more with no parameters. * Set Rainbow does not crash with negative parameters in definition strings. * Error n instruction now reports errors over 50. * AMOS now saves Workbench icons properly, not all placed over each other, as it used to! * EVERY command works fine. At last. * PLOAD used to leave a lock in the system. * =DRIVE() does not display a requester if the device does not exist. This was really stupid, as this instruction was used to determine existing devices! * Music banks are now detected upon running. It means you can safely save them with the program. * Arrays now work fine when you access elements higher that 65536. * On Menu Proc used to block the machine under certain circumstances. * Bobs can now be displayed on VERY large bitmaps. * Marks did not work on A3000. * Opening procedures with errors within, used to position the cursor at the beginning of the text. * INPUT #x,A$(n) did not ask for a proper string space. The result in worse cases was a crash, as the incoming string erased crucial AMOS pointers. * Note on serial interface problems. A lot of users have reported to us problems when they were using the serial extension. Their programs used to work the first time, and crash on the next RUN. Amazingly enough, this bug does not come from AMOS, but from Commodore. Commodore released a few years ago a bugged version of the serial.device. Bad luck, this bugged version happened to be duplicated on our AMOS Master. At that moment we didn't realise this. As soon as we were made aware of the problem, we re-mastered the AMOS discs. But too late, some version of AMOS have got the wrong device. The updater will save a good version of the serial.device on the copy of your AMOS Master. New music instructions. ----------------------------------------------------------------------- The music extension has been considerably enhanced. We've listened to your requests: * Playing Soundtracker modules. SoundTracker is moving too fast for us. Every month or so, a new program pops up, with new instructions, making the SoundTracker converter obsolete. The SoundTracker converter works fine with modules up to NoiseTracker V2.0. Above this version, some effects may be badly converted. Anyway, you thought that this converter program was not a very good idea. That's why we have directly implemented a Tracker player in the music extension. The chosen one is "Startracker player", because it contains all the latest and main effects (today!), and it has the ability to play synthetic instruments. Here are the new instructions: TRACK LOAD "Name_Of_The_Module",Bank ------------------------------------ Load up a tracker module into a chip memory bank. It will of course it reserve the bank for you, and choose the correct bank size. If AMOS detects a Startracker synthetic instrument file (which must have a ".NT" extension appended to the file name), it will load it AS WELL into the bank. In fact you don't have to worry about it. TRACK PLAY [Bank],[Pattern] --------------------------- Plays a tracker module loaded into a bank. "Bank" is the number of the bank to be played. If omitted, it is the last loaded with the TRACK LOAD instruction, or upon running, bank number 5. "Pattern" is the first pattern to be played. Use this with caution, as NO CHECK is done on the number of the pattern. You can very simply crash the computer by giving a bad value. This parameter is intended to allow you to have more than one music in a tracker bank... TRACK LOOP ON / OFF ------------------- Enable or disable looping when the tracker music is finished. TRACK STOP ---------- Stops a tracker music being played. IMPORTANT NOTES: ----------------- The Tracker-playing instructions are implemented to give you a quick way of playing modules. It is not as powerful as the normal AMOS music system. For example : * Do not play a normal AMOS music while playing a tracker module, this can lead to unpredictable results. * Do not start any sample, or sound effect when a Tracker module is played. * A Tracker module uses and initialises all four voices, even if your music is only on 3 or 2. So do not play any sample on the other voices you think are free. They are not! * VOLUME instructions do not have any effect on the Tracker music, but =VU METER works fine with a Tracker module. ... if you want to make sound effects while a music is playing, then you should use the Soundtracker converter, and the normal AMOS Music system... Improvements in sample playing: -------------------------------- Here again we have listened to your complaints! You'll be happy to know that you can now play samples of any length, and that the small tick at the beginning have been removed. But much more than that, we have made it possible to play samples bigger than the actual memory of your Amiga, with the new double-buffer sample instructions. Floppy users : sorry, these new instructions will not be useable by you, but at a very low sample playing rate (like 4000-5000 Herz). The disc data output speed is just too low. Theses new instructions were designed mainly for CDTV and multimedia purposes... A working example of this instruction is given in the file "Sample_Double_Buffering.AMOS" you will find on your updated disc. I have commented this example very carefully, so that everything is clear to you. Before running this example, you have to create (or grab) a sound-sample, any size (preferable big), and copy it onto your hard-drive. You can easily understand that we could not put a 2 Megabytes sample on the updater disc! SLOAD File_Number,Length TO Address ----------------------------------- A new instruction intended to load parts of a sample, but it can be used in many other ways. This instruction is an extended BLOAD "File_Number" is the number of a file opened previously with the OPEN IN File_Number,"Name" instruction. "Length" is the number of bytes to load. If this number is bigger than the actual size of the file, then only the remaining bytes are loaded, without errors. You'll get an error if you try to load once more after the end has been reached. "Address" is the destination address. Of course, the memory must have been previously reserved. The advantage of this instruction, is that you can set the position of the file pointer with the POF()= instruction before using SLOAD. As you can see, this instructions can have a lot more usage than just loading samples... SAM SWAP Voices TO Address,Length --------------------------------- This instruction initialise the sound-swapping. The actual swapping will only occur when the actual buffer has been totally played through the speaker. The swap is done under interrupts, so you will not hear any tick in the sample. "Voice" is a bit pattern to define the voice concerned, just like in the SAM RAW instruction. "Address" is the address of the next buffer to play. Of course, it must be in chip memory. "Length" is the number of bytes to play. =SAM SWAPPED(Voice_Number) -------------------------- This function returns a boolean value (TRUE -1, or FALSE 0). It is the key function in synchronising double buffer players. "Voice_Number" is the number of the voice you want to have information about (0 to 3). Do not make mistake, is it NOT a bitpattern. It returns TRUE if the sample swapping has occurred, it means the new buffer you have initialised with the SAM SWAP instruction is being played at the very moment. It returns FALSE if not. Practically, you can only load a new part of the sample in the free buffer, when the SAM SWAPPED instruction returns you a TRUE value. It returns FALSE if the sample swapping has NOT happened. SAM STOP [Voice_Pattern] ------------------------ This simple instruction seems to have been forgotten in the instruction set since the beginning. The only way to stop a sample playing, was to use the PLAY instruction! "Voice_Pattern" is a bit pattern defining the voices to be stopped, like in the SAM RAW instruction. All voices will be affected if you omit it. NOTE: it is perfectly possible to have an AMOS music bank playing on 2 voices, and double-buffered samples playing on the last 2. (hey, but not a Tracker module, if you remember what I told you!) Other new instructions (from 1.31). --------------------------------------------------------------------------- * =COL(Bob) --------- Well, in fact, it is not a new instruction, but a good enhancement to the collision detection method. To detect a collision, I remind you, you have to use one of the collision detection functions (=BOB COL(), =SPRITE COL(), =BOB SPRITE COL(), =SPRITE BOB COL()). When this function returns a TRUE value, you have to explore the =COL() reserved array to find out which bob or sprite created the collision. The problem, is that you had to write a loop exploring sequentially all the COL() array. This was eating a lot of processor time. You could see certain games slowing down when some bobs were colliding. I wanted to do something to correct it. But what? The problem with AMOS, is that if I change the syntax or the behaviour of one instruction to please certain people, it may (and surely will) not be compatible with thousand of existing programs! So I found a -rather tricky- solution to this problem. =COL(Number) behaves normally if you send it a POSITIVE number as an argument, this keeps it compatible with all existing programs. If "Number" is negative, AMOS will first remove the sign, i.e. turn it into a positive number. Then it will explore the COL() array himself, and find the first non-zero value higher than -Number. Then it will not return TRUE or FALSE as it used to, but the actual number of the bob colliding. To get the next bob colliding, simply call it again with a this number, minus one.. Example, this small and fast loop, will give all bobs colliding with bob zero: B=Bob Col(0) BB=0 Repeat BB=Col(-(BB+1)) If BB Print "Bob";BB;" is colliding..." Endif Until BB=0 You can certainly remark that with this method, it is impossible to get the collision of bob number zero. That's why I say this was not perfect... =DISC INFO$("Name") ------------------- ...is a new instruction that returns information on any disc. "Name" is the name of a file or a directory of the disc you want to have information about. The string returned has the following form: "NAME_OF_THE_DISC:XXXXXXX" , where XXXXXXX is the free space on the disc. To get both, use this simple method: A$=DiscInfo$("Df0:") C=Instr(A$,":") N$=Left$(A$,C) F=Val(A$,C+1) Print "Name of the disc :";N$;" Free space:";F = PRG STATE (returns the current status of a program) ----------------------------------------------------- =PRG STATE This little handy function let you know how your program was launched. It returns three possible values: 0 : if your program was run under the AMOS interpreter. 1 : if your program was run under RAMOS run-only. -1 : if your program is compiled. Getting the system date and time. --------------------------------------------------------------------------- You will find on your updated disc a program called "GET_TIME.AMOS". This program includes two procedures to get the time and date from the system. Time. ----- Call the procedure, and you'll have in Param$ the current clock time under the following format: 00:00:00 _TIME$ Print Param$ ... 11:04:04 Date. ----- This procedure returns the current date in Param$: _DATE$ Print Param$ ... 21/06/1991 Safe AmigaDos EXECUTE. ------------------------------------------------------------------------------ It is perfectly possible to launch an external program from AMOS. But in order to do so, you have to know some of the AmigaDos internal functions. That's why you will find on your updated disc a small program with a procedure called _EXECUTE. Just transmit an AmigaDos command to this procedure, and it will launch it out of AMOS. To run an external program, use: _EXECUTE["RUN >NIL: