A.C.E. 2/ACE CD 2.iso/FILES/DOCS/AMOSDOC.LHA/AmosPart1.doc

Text File | 1994-11-27 | 87.8 KB | 2,177 lines

                         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 "<Touch 'n' Type Demo>                                            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 V<Base Then V=Top
        If V>Base 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...