STOS BASIC FAQ/INSTRUCTIONS: Difference between revisions

From Atari Wiki
Jump to navigation Jump to search
(Begin Wikification)
No edit summary
Line 2,241: Line 2,241:
 
[[Category:Programming languages]]
 
[[Category:Programming languages]]
 
[[Category:STOS BASIC]]
 
[[Category:STOS BASIC]]
[[Category:Programming]]
 

Revision as of 11:47, 13 October 2011

STOS ... The Game Creator

The Function Keys

The upper window contains a brief list of the current function key assignments. Whenever you press one of these keys, the string associated with it will be entered on the screen, just as if you had typed it yourself. You can also assign a separate set of strings to the shifted versions of these keys, which can also be displayed by pressing the shift key.

You can also access these function keys by clicking the left mouse button with the pointer over the function key description. Pressing the right hand mouse button has the same effect as pressing the shift key.

For further details see the descriptions of the commands KEY and KEYLIST.

HELP

This displays a rather complex looking dialogue box to which there are three parts.

The top section contains a list of the 4 programs held in memory at the moment. The current program is highlighted and this may be moved with the cursor keys to select one of the other three programs. You will see the top line alter to show you which program is being edited. See the section on multiple programs for further information.

The second part of the menu displays a list of the accessories loaded. To call up any accessory, press the associated function key.

The last line of the help menu displays the amount of free memory left.

To exit from the Help menu, press the HELP key again.

Editing Keys

caption
Command Description
Control + C Stop the program being executed.
Undo Pressing this twice redraws the screen and reinitialises the editor. It then lists the last line that caused an error.
Clr Clears the editor window.
Up Arrow Moves the cursor up one line.
Down Arrow Moves the cursor down one line.
Left Arrow Moves the cursor left one character.
Right Arrow Moves the cursor right one character.
Return Enters the line at the current cursor position.
Delete Deletes the character under the cursor.
Shift + Delete Deletes the line under the cursor.
Control + J Joins two lines together.
Backspace Deletes the character left of the cursor and moves the cursor left one character.
Home Moves the cursor to the top left hand corner of the editor window.
Esc Enter multi-display mode. See the section on multiple programs for further information.
Spacebar Suspends a listing. Press the spacebar again to resume.
Insert Toggles between insert and replace mode. Insert mode is signified by a slightly thicker cursor.

Loading/Saving Basic programs

LOAD filename Load the file into memory for editing
SAVE filename Save the current program to disk
FLOAD "*.BAS" Load a file using the file selector
FSAVE "*.BAS" Save a file using the file selector

Running a program

RUN Runs the program from the first line
RUN no Runs the program from line no.
RUN file$ Load and run the program stored in file$
CONT Restart a program halted by Control + C or STOP

Entering a STOS Basic program

AUTO Automatic line numbering
AUTO start Start automatic line numbering from the line number start
AUTO start,inc Starts from the line start and increments each successive line by the number inc.
RENUM Starts by setting the first line number in your program to 10, and then renumbers each succeeding line in units of 10.
RENUM number Sets the first program line to number and renumbers all the other lines in increments of 10.
RENUM number,inc Starts at line number and increments each successive line by inc.
RENUM number,inc,start-end Renumbers lines from start to end, beginning with line number, and incrementing each proceeding line by inc.
LIST [first-last] Lists the current program.
SEARCH s$ Search for the position of any string within a Basic program. To repeat the search, enter SEARCH on it's own.
SEARCH s$,start-end Will search only within the lines specified.
CHANGE a$ TO b$ [,start-end] Will change all occurrences of a$ to b$, a range may also be specified.
DELETE [first-last] Deletes some or all of the lines of a program.
MERGE file$ Merge a file into the current program. Existing lines will be overwritten by any new lines of the same number.

Debugging a program

FOLLOW
Single step through the program. The next line can be stepped through by pressing any key.
FOLLOW [first-last]
As FOLLOW but only traces the given range.
FOLLOW variable list
This takes a list of variables separated by commas and prints them out after every instruction executed. As before, you can step through the program by pressing any key.
FOLLOW variable list,first-last
As before, but only traces the variables

within a given range.

FOLLOW OFF
Turns off the action of the FOLLOW command.

MULTIPLE PROGRAMS

STOS Basic allows you to have up to four programs in memory at any one time. These may be completely independent of each other. If you suddenly decide to change the configuration of the editor for instance, you could easily load the CONFIG.BAS program into a separate segment of the ST's memory without interfering with your current program.

If you press the HELP key and move the highlighted bar with the cursor keys to one of the other slots and press HELP again, you will see that the program area is empty. You can enter another program, and run it, independently of the program in area 1.

MULTI n
Displays a number of programs simultaneously. Note, n can take the values 2-4 only.
FULL
Expands the current program window into the full screen area.

Splitting programs in the Editor

You can also use the MULTI command to split a single program into a number of seperate sections. This can be done with the Help menu. Position the program cursos over program 1 and press the left and right arrow keys. As you can see, the text cursor is moved between four different boxes on the program line. Move the cursor to the first box and type in 1000 followed by Return. This sets the end point of the first part of the program to line 1000.

If you now exit back to the editor and type MULTI 2, thr program will be split into two windows. You can choose between these two windows by using the mouse pointer by moving into the desired window and clicking on the left hand mouse button.

Each box on the program line represents a different section of the listing. You can therefore use this technique to split a program into four separate parts. It is important to note that this has no effect on any existing segments, and you can page through each of the programs stored in memory using the Help menu as usual. All four of these programs can be split in exactly the same way without interfering with each other.

GRAB
Copy all or part of a program segment into the current program.

The GRAB command allows you to combine a number of subroutines stored in separate program segments into one complete program. This enables you to test each subroutine in your program independently.

The syntax of the GRAB instruction is:

GRAB n
Copy program number n into the current program, where n ranges from 1 to 4. Any attempt to use the number of the current program in this instruction will generate an error.
GRAB n,first-last
Only copies the lines between first and last into the current program.

System commands

SYSTEM
The system function is used to quit STOS and return to GEM.
RESET
Reinitialise the editor and redraw the current screen.
NEW
Erase the current program
UNNEW
Attempts to recover the last program erased by NEW.
CLEAR
Erase all variables and memory banks defined by the current program, also reposition the data pointer to the start of the data.
FREE
Return the number of free bytes in memory and force garbage collection.
ENGLISH/FRANCAIS
Select language to be used by STOS.
FREQUENCY
Switch between 50Hz and 60Hz.
UPPER
Change listing mode to uppercase. Lists commands in upper case and variables in lower case.
LOWER
Change listing mode to lower case. Lists commands in lower case and variables in upper case.
KEYLIST
Lists out the Function keys ready for editing

Naming conventions for variables

Variable names must NOT contain any of the following keywords:

TO, STEP, THEN, ELSE, XOR, OR, AND, GOTO, GOSUB, MOD, AS

and they must begin with a letter and be no more that 31 characters in length.

Types of variables

Integers
STOS uses these by default since it is faster, and STOS is designed for creating games. Each integer is stored in 4 bytes and can range from ñ2147483648
Real numbers
These are suffixed with the # character. They correspond directly to double precision floating point variables. Each real number is stored in 8 bytes and can range from -1.797692 E+308 to +1.197693 E+307. These numbers are accurate to 16 decimal digits.
String variables
These variables are always suffixed with the $ character and can range from 0-65500 characters long. They are NOT terminated with a chr$(0).
Arrays
Any of the above variable types can be made into an array in the usual fashion with the DIM statement and can have any number of dimensions, but each dimension is limited to a maximum of 65535 elements.

Constants

As 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.

In addition to using decimal notation, you can also use hexadecimal and binary notation. Binary numbers are signi- fied by preceding them with the character % and hexadecimal numbers are always preceded by the $ character.

Note that any numbers you type in are converted into a special internal format which is expanded back when you list the program. This will often lead to minor discrepancies between the number you entered, and the number displayed. The value of the number will however, remain completely unchanged.

Floating point constants are always distinguished from integers by the presence of a decimal point in the number. If the point is not used, then it will be taken to be an integer. Since STOS has to convert between integer and floating point, and integer numbers included in floating point arithmetic will be calculated over 25% slower.

Arithmetic operations

The following operations may be used in numeric expressions: (listed in order of priority)


^ Power
/ and * Divide and multiply
MOD Modulo operator (Produces remainder of a division)
+ and - Plus and minus
AND Logical AND
OR Logical OR
XOR Logical XOR
INC var Add 1 to an integer variable. This is considerably faster that using var=var+1
DEC var Subtract 1 from an integer variable.


String operations

Most basics will allow you to join two strings together with a command, such as:

                   A$ = "STOS" + " Basic"
                   PRINT A$
                   STOS Basic

In addition to this, STOS Basic also lets you perform subtraction with string variables as well. This operation works by removing all occurrences of the second string from the first:

                   PRINT "STOS BASIC" - "S"
                   TO BAIC
                   PRINT "STOS BASIC" - "STOS"
                   BASIC
                   PRINT "A String Of Ascii Characters" - " "
                   AStringOfAsciiCharacters

Comparisons between two strings are performed on a character by character basis using the Ascii codes of the characters.

Common String Functions

LEFT$(v$,n)         There   are  two  distinct  forms  of   these 
RIGHT$(v$,n)        commands.  The first version is identical  to 
MID$(v$,s,n)        the  standard  Basic uses of  this  function, 
                    resulting  in a portion of the  string  being 
                    returned.   The  second  will  allow  you  to 
                    replace  a section of a string with  another. 
                    See the example below.

               10 A$="** Basic"
               20 LEFT$(A$,4)="STOS"
               30 PRINT A$
               run
               STOS Basic

INSTR(d$,s$[,p])    Search for occurences of s$ in d$. The option 
                    of starting at character p is also  included. 
                    If  no match can be found,  a value of  0  is 
                    returned.

                        Array operations

SORT var$(0)        This  allows you to sort all the elements  in 
                    an  array into ascending order  with  amazing 
                    speed.  This array can be composed of  either 
                    strings,  integers or floating point numbers. 
                    The  var$(0) indicates the starting point  of 
                    the table to be sorted.  This starting  point 
                    must  always be set to the first item in  the 
                    array (item zero).

MATCH(var(0),s)     The MATCH function searches through a  sorted 
                    table,  and returns the item number in  which 
                    the  value s was found.  If s is  not  found, 
                    then  MATCH returns a  negative  number.  The 
                    absolute  value of this number  contains  the 
                    index  of  the first item which  was  greater 
                    that  s.  Providing  the array  is  only  one 
                    dimension,  it can be of type string, integer 
                    or real.  Before MATCH can be used, the array 
                    should  always  be  sorted  using  the   SORT 
                    command.

                          Memory banks

STOS  Basic  includes  a number of powerful  facilities  for  the 
manipulation of sprites,  screens and music. The data required by 
these functions needs to be stored along with the Basic  program. 
STOS  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-15.  Many of these banks can be used for all types 
of data, but some are dedicated solely to one sort of information 
only such as sprite definitions. Every program stored in the ST's 
memory has it's own separate set of banks.

There  are  two different forms of  memory  bank;  permanent  and 
temporary.  Permanent banks only need to be defined once, and are 
all subsequently saved along with your program,  temporary  banks 
are erased rom memory by the CLEAR command.

Types of memory bank

Each memory bank can be one of the following different types.

Class          Stores                        Restrictions   Type

Sprites        Sprite definitions            Only bank 1 (1)  P
Icons          Icon definitions              Only bank 2 (1)  P
Music          Music                         Only bank 3 (1)  P
3D             Future 3D extension           Only bank 4 (4)  P
Set            Holds new character sets      Banks 1-15       P
Screen         Stores a complete screen      Banks 1-15       T
Datascreen     Stores a screen               Banks 1-15       P
Work           Temporary workspace           Banks 1-15       T
Data           Permanent workspace           Banks 1-15       P
Menu           Menu lines                    Bank 15     (2)  T
Program        Machine-code program          Banks 1-15  (3)  V

Footnotes:

(1)  Bank  is  not  really  general  purpose.   It  is  allocated 
     automatically by the appropriate accessory,  or when a  bank 
     of this type is loaded.
(2)  Reserved  automatically  by MENU commands.  Usable  only  by 
     programs which don't use menus.
(3)  Reserved as either Work or Data. Renamed when program loaded 
     into bank.
(4)  Reserved for future expansion.
(P)  Permanent memory bank
(T)  Temporary memory bank
(V)  Variable between permanent or temporary.

LISTBANK            Lists  the  numbers of  the  banks  currently 
                    reserved  by  a  program,  along  with  their 
                    location and size.
                    S := Start address of the bank
                    E := End address of the bank
                    L := Length of the bank

HEXA ON/OFF         Sets  the LISTBANK to decimal or  hexadecimal 
                    notation.

RESERVE             Any banks used by sprites,  music,  icons, 3D 
                    extensions,   and  the  menus  are  allocated 
                    automatically  by  the  system.  The  RESERVE 
                    command  allows  you to  allocate  any  other 
                    banks which you require.  Each different type 
                    of  bank has it's own individual form of  the 
                    RESERVE instruction.

     RESERVE AS SCREEN bank        Reserves  a temporary bank  of 
                                   memory for a screen. This bank 
                                   is always 32K long.
     RESERVE AS DATASCREEN bank    Reserves  a permanent bank  of 
                                   memory  32K long for use as  a 
                                   screen.  This screen is  saved 
                                   along  with your  program,  so 
                                   it's great for title screens.
     RESERVE AS SET bank,length    Reserves  a permanent bank  of 
                                   memory  length bytes long  for 
                                   use as a character set.
     RESERVE AS WORK bank,length   Reserves a temporary bank  for 
                                   use  as  a  workspace   length 
                                   bytes long.
     RESERVE AS DATA bank,length   Reserves  a permanent bank  of 
                                   memory  length bytes long  for 
                                   use as a workspace.

Please  note that bank may be any number between 1  and  15,  but 
since banks 1-4 are used by the system,  it's wise to leave these 
alone.  Length  is automatically rounded to the nearest 256  byte 
page.

Copying banks

When  using these memory banks,  it's often useful to be able  to 
transfer  the contents of one bank to another.  This can be  done 
with the BCOPY command.

BCOPY #source TO #dest   BCOPY copies the entire contents of bank 
                         number source to bank number dest.

BGRAB prgno[,b]          BGRAB copies one or more banks stored at 
                         program  number prgno into  the  current 
                         program.  Program  numbers  between  1-4 
                         denote  one of the four  programs  which 
                         can be stored in memory at anyone  time. 
                         Numbers 5-16 represent an accessory.
                         If  the  optional bank number b  is  not 
                         included, then all the banks attached to 
                         program number prgno are copied into the 
                         current program,  and any other banks of 
                         memory which are linked to this  program 
                         are erased.  Otherwise,  the bank number 
                         specifies  one  bank  which  is  to   be 
                         transferred  into the  current  program. 
                         All other banks remain unaffected.

ERASE b                  Delete  the  contents of memory  bank  b 
                         from  the program's memory and free  the 
                         bank.

=START([prgno,]b)        This function returns the start of  bank 
                         b  from either the current  program,  or 
                         the program specified.  prgno can be 1-4 
                         for  each of the four programs  or  5-16 
                         for the accessories.

=LENGTH([prgno,]b)       This function returns the length of  the 
                         bank specified.

                       Saving and loading

SAVE
     This  instruction provides  general and starightforward  way 
     of  saving  a STOS Basic program on  the  disc.  Unlike  the 
     equivalent  instruction  found  in most  other  versions  of 
     Basic, STOS also allows you to save a variety of other types 
     of information.  This is determined by the extension of  the 
     filename used in the SAVE command.  Here is a summary of the 
     various data types, along with their extensions.

     Type of information      Extension      Comments
     Basic Programs           .BAS           Normal basic program
     Accessories              .ACB           Load using ACCLOAD
     Images                   .PI1,PI2,PI3   Degas format screen
                              .NEO           Neochrome format
     Memory Banks             .MBK           One memory bank
                              .MBS           All current banks
     Basic Variables          .VAR           All current vars.
     Listings                 .ASC           Ascii format
     RUN-ONLY programs        .PRG           GEM programs

If  none of these extensions is found,  STOS  automatically  adds 
.BAS

.ACB files  are  simple  Basic  files  which  may  be  loaded  as 
accessories.  To  create  them,  write your program in  Basic  as 
normal, but save it with the different extension. You can load it 
either  as  an accessory using ACCLOAD or a Basic  program  using 
LOAD.

Image Files. You can also save the current screen, bank or memory 
address as an image file in degas or neochrome format using  this 
method.

     SAVE "Filename.???"[,address of screen]

Memory Banks:      SAVE "Filename.MBK",b
                   SAVE "Filename.MBS"
Variables:         SAVE "Filename.VAR"
Listings:          SAVE "Filename.ASC"
Blocks:            BSAVE file$, start TO end
                    Save the memory from start to end as a binary 
                    file.
(All  of the above saves can be re-loaded into STOS by  replacing 
the LOAD or BLOAD with SAVE or BSAVE.)

BLOAD file$,addr    The  file  file$  will  be  loaded  into  the 
                    address specified.
BLOAD file$,#bank   The  file file$ is loaded into the  specified 
                    bank.

                         The accessories

ACCLOAD             Loads  any  of the accessories  into  memory. 
                    Either specify which file to load, or use "*" 
                    to load all the accessories from disk.
ACCNEW              Erases all the accessories from memory.
ACCNB               Returns  the value of zero if the program  is 
                    not  an accessory,  else it returns a  number 
                    between 4 and 15

                         Sprite Commands

SPRITE n,x,y,p      Display  sprite  number n on  the  screen  at 
                    coordinates x,y using image p.

     n is the number of the sprite, which can range from 1-15. It 
     is  the number which will be used to identify the sprite  in 
     any subsequent calls to MOVE and ANIM instructions.

     x and y are the coordinates of the point on the screen where 
     the sprite is to be drawn. Unlike normal screen coordinates, 
     these  can take negative values.  The x coordinate can  vary 
     from -640 to +1280, and y coordinate from -400 to +800. This 
     allows  you to move a sprite off the screen without  causing 
     an error.

     p specifies which of the images in bank 1 is to be used  for 
     a particular sprite.  The only limit to the number of  these 
     images is the amount of available memory.

     Each sprite has an invisible handle through which it can  be 
     manipulated,  called a Hot Spot.  Whenever we draw a sprite, 
     we always specify the coordinates of the hot spot.

Moving a sprite

MOVE X n,m$    This defines a list of horizontal movements  which 
               will be subsequently performed by sprite number n.
               m$ contains a sequence of commands which determine 
               the speed and direction of the sprite:
                    "(sp,st,ct)[A]"
     SP  is the speed of the sprite in 50ths of a second and  can 
     range from 1 (v.fast) to 32767 (v.slow)

     ST is the step size, i.e. how many pixels it will be moved.

     CT  is  the  number of times that  this  particular  set  of 
     commands will be obeyed. 0 indicates that the movement is to 
     be repeated indefinately. This can range from 0 to 32767.

     E.G. The command
               MOVE X 1,"(1,5,60)(1,5,-60)"
     will  move sprite 1,  5 pixels to the right every 50th of  a 
     second,  60 times,  then move it 5 pixels to the left  every 
     50th of a second, 60 times. Movement will then stop.

     The optional A can take either L to signify that,  once  the 
     command list has finished,  it is to be restarted or Looped. 
     It may also be followed by a number (e.g.  L100) which  will 
     cause the sprite to be restarted from this coordinate.

     Additionally,  it  can take the form of Ex which will  cause 
     the  sprite to stop when it reaches point x on  the  screen. 
     NOTE that the sprite must actually reach point x exactly for 
     this  to  work.  If  the sprite passes  this  point  without 
     stopping on it, it will not work.
     e.g. MOVE X 1,"(1,2,100)E150" will work whereas
          MOVE  X 1,"(1,2,101)E150" will not as the  sprite  uses 
          points 149 and 151, but not 150.

MOVE Y n,y$    Acts  in the same way to MOVE X but will move  the 
               sprite along the Y coordinate.  Both commands  may 
               be  used  together  to  cause  a  sprite  to  move 
               diagonally.

MOVE ON/OFF [n]     Before any sprite movements you have  defined 
                    by  MOVE  X  and  MOVE  Y  commands  will  be 
                    performed,  they need to be initiated by  the 
                    instruction MOVE ON.  n specifies the  sprite 
                    whose  movement is to be switched on or  off, 
                    and  if  omitted,  the  command  affects  all 
                    sprites.

MOVE FREEZE [n]     This command can be used to temporarily  halt 
                    one or all of the sprites on the screen. This 
                    can  then  be  restarted  with  the  MOVE  ON 
                    command.

=MOVON(n)           Return the state of a sprite.  If the  sprite 
                    is  currently stationary,  it will  return  0 
                    (False).

=X SPRITE(n)        Return the X coordinate of the sprite n.
=Y SPRITE(n)        Return the Y coordinate of the sprite n.

LIMIT SPRITE [x1,y1 TO x2,y2]
                    This command allows an area of the screen  to 
                    be  used to display the sprites  rather  than 
                    the entire screen.  If any sprites leave this 
                    area,  they  will disappear from the  screen. 
                    The  x1,y1  coordinates define the  top  left 
                    coordinate  of  the rectangle and  the  x2,y2 
                    coordinates define the bottom right.  All the 
                    X  coordinates specified are rounded down  to 
                    their nearest multiple of 16.  To cancel this 
                    command, use LIMIT SPRITE with no parameters.

Animation

ANIM n,m$           This  enables you to page through a chain  of 
                    sprite   images  one  after   another.   This 
                    sequence will be executed at the same time as 
                    your sprite is being displayed, even if it is 
                    also being moved.

     n refers to the number of the sprite to which the  animation 
     is to be applied.

     m$ holds the animation control string in the same way as the 
     movement commands do. This takes the format:
          "(Image,Delay)[A]"

     Image  specifies  which image is to be used  by  the  sprite 
     (refer to parameter p of SPRITE) to be displayed during each 
     step of the animation.

     Delay  specifies the amount of time that the image  will  be 
     held on the screen before the next image is displayed.  This 
     delay is specified in 50ths of a second.

     Again, then optional parameter A can be used to specify that 
     the  animation string is to be repeated upon  completion  by 
     including L.

ANIM ON/OFF [n]     This  command  is used the same way  as  MOVE 
                    ON/OFF  to turn the animation control  on  or 
                    off.
ANIM FREEZE [n]     This  command is used to temporarily  suspend 
                    animation until ANIM ON is reissued.

Controlling the sprite using the mouse

CHANGE MOUSE m      This  allows you to completely  redesign  the 
                    shape of the mouse cursor. m gives the number 
                    of the image to be used, as follows:
     1         Arrow (Default)
     2         Pointing Hand
     3         Clock

     If you specify a value greater then 3,  then this is assumed 
     to refer to sprite image m-3.

=X MOUSE       Return the X coordinate of the mouse.
=Y MOUSE       Return the Y coordinate of the mouse.
=MOUSE KEY     Return the state of the mouse buttons:
          0    No button has been pressed
          1    Left button pressed
          2    Right button pressed
          3    Both buttons pressed
LIMIT MOUSE [x1,y1 TO x2,y2]
          Restricts  the mouse pointer to a rectangle defined  by 
          x1,y1  as  the top left hand corner and  x2,y2  as  the 
          lower right hand corner and also positions the mouse in 
          the centre of the box.  LIMIT MOUSE with no  parameters 
          will cancel this command.
HIDE [ON] Will hide the mouse pointer and maintain a count of how 
          many  HIDE  commands have  been  used.  The  equivalent 
          number  of  SHOW commands must be used to  restore  the 
          mouse.  HIDE ON will override the count and always hide 
          the mouse.
SHOW[ON]  Will  show the mouse in the same way as HIDE will  hide 
          it.

Reading the joystick (Port 1)

=JOY      Returns a bit pattern showing which way the joystick is 
          being moved.

          BIT No.   Significance
               0    Up
               1    Down
               2    Left
               3    Right
               4    Fire button pressed

=JLEFT    Returns TRUE if the joystick is being moved left.
=JRIGHT   Returns TRUE if the joystick is being moved right.
=JUP      Returns TRUE if the joystick is being moved up.
=JDOWN    Returns TRUE if the joystick is being moved down.
=FIRE     Returns TRUE if the fire button has been pressed.

Detecting collisions with a sprite

=COLLIDE(n,w,h)     Test  sprite  number n  for  collisions  with 
                    other sprites. The collision is detected from 
                    the  Hot  Spot of the sprite over an  area  w 
                    wide and h high.  The return is a bit pattern 
                    with   the  appropriate  bits  1-15  set   if 
                    collision   with  these  sprites   has   been 
                    detected.

Detecting collision with rectangular blocks

SET ZONE z,x1,y1 TO x2,y2
          Defines one of 128 rectangular zones which can then  be 
          tested  using  the  ZONE command for  the  presence  of 
          either the mouse or a sprite. z specifies a number from 
          1-128  which represents the zone to be  created.  x1,y1 
          and  x2,y2  denote  the  top  left  and  bottom   right 
          coordinates of the zone.

=ZONE(n)  This searches the zones for the presence of sprite n. n 
          can range from 0-15 with 0 representing the mouse. This 
          function will return 0 if no zone can be  detected,  or 
          else  it  will  return the zone number  the  sprite  is 
          currently in. Note, only the first zone may be found.

RESET ZONE [z]      Reset one or all zones.

Detecting collisions with an irregular shape

=DETECT (n)         Return the colour directly under the Hot Spot 
                    of the sprite specified (0-15).

PUT SPRITE n        Place  a  copy  of sprite  n  on  the  screen 
                    directly under the sprite's current position. 
                    This doesn't affect the sprite in any way.

GET SPRITE x,y,i[,mask]
                    Grabs   an   image  off   the   screen   from 
                    coordinates  x,y  to image i  in  the  sprite 
                    bank.  This  image must already exist in  the 
                    sprite  bank  as  it's  dimensions  are  used 
                    during the grab. The optional mask allows you 
                    to set which colour is to become transparent. 
                    This  is usually colour 0  (the  background), 
                    but  some interesting effects can be made  by 
                    altering this.

Sprite Priority

PRIORITY ON/OFF     Determines which sprite priority system is to 
                    be used.  ON is used to give priority to  the 
                    sprites with the largest Y coordinate. If you 
                    are using this method, it is advisable to set 
                    the hot spot of the sprites to the bottom  of 
                    the sprite.
                    OFF   is  the  default  system  which   gives 
                    priority to sprite 0..1..2... ...15

The Background

AUTOBACK ON/OFF     ON (default) causes all graphics commands  to 
                    operate  on  the  foreground  and  background 
                    screens.  OFF  causes these operations to  be 
                    performed on the foreground screen only. (Use 
                    this  mode  only  if you are  not  using  the 
                    sprites or the mouse.)

Miscellaneous sprite commands

UPDATE [ON/OFF]     Turn on or off the automatic updating of  the 
                    sprites.  UPDATE used on it's own will redraw 
                    any sprites which have changed their position 
                    since their last update.

REDRAW              Redraw all the sprites regardless of  whether 
                    they have changed position.

OFF                 Turn off all the sprites.

FREEZE              Temporarily  freeze all sprite  movement  and 
                    music.

UNFREEZE            Resume   any   sprite  movement   and   music 
                    suspended by FREEZE.

                         Music and Sound

PLAY [voice,]pitch,duration
          Plays  a pure note of pitch for the specified  duration 
          (in 50ths of a second). If voice (1-3) is omitted, then 
          the  note will be played on all three voices  simultan-
          eously.

                              Octave
               0    1    2    3    4    5    6    7
Note                          Pitch
C              1    13   25   37   49   61   73   85
C#             2    14   26   38   50   62   74   86
D              3    15   27   39   51   63   75   87
D#             4    16   28   40   52   64   76   88
E              5    17   29   41   53   65   77   89
F              6    18   30   42   54   66   78   90
F#             7    19   31   43   55   67   79   91
G              8    20   32   44   56   68   80   92
G#             9    21   33   45   57   69   81   93
A              10   22   34   46   58   70   82   94
A#             11   23   35   47   59   71   83   95
B              12   24   36   48   60   72   84   96

VOLUME [v,]intensity
          Allows the volume of one or all of the voices (1-3)  to 
          be altered from 0 to 15

CLICK ON/OFF   Turn key click on or off

MUSIC n        Play  tune  number  n  from  the  music  bank   by 
               interrupt.
MUSIC OFF      Turn the music being played off.
MUSIC FREEZE   Temporarily suspend the playing of the music.
MUSIC ON       Resume playing the music temporarily frozen.

TEMPO s        Change  the tempo of the music from 1 (v.slow)  to 
               100 (v.fast).
TRANSPOSE df   Transpose  a  piece of music from -90  to  +90  (1 
               corresponds to a semi-tone).
=PVOICE(v)     Return  the position within the  specified  voice, 
               the music is currently at.
VOICE ON/OFF [v]    Turn one or all of the voices on or off.

Predefined sound effects

BOOM           Generate a noise sounding like an explosion.
SHOOT          Create a sound like a gun firing.
BELL           Simple bell sound.

NOISE [v,]p    Produce white noise of frequency 1 (v.high) to  31 
               (v.low) on one or all of the voices.
ENVEL t,s      Activate one of the 16 envelopes (t) to the  speed 
               (s)  which  may  range from 1  (v.fast)  to  65535 
               (v.slow)

                       Graphics Functions

INK index      Set  the colour of all subsequent graphic  drawing 
               operations.  (0-15 in low res,  0-3 in medium res, 
               0-1 in monochrome).

COLOUR index,$RGB
               Set  the  colour  of  a specific  pen  to  a  $RGB 
               setting.

=COLOUR(index) Read the current colour setting of a specific pen.

PALETTE list   This  allows  you to set the entire palette  to  a 
               list of colours,  like an expanded COLOUR command. 
               Note  that the number of parameters  taken  varies 
               with each if the resolutions.

PLOT x,y[,index]
               Plot  a single point in the current  or  specified 
               pen colour.

=POINT(x,y)    Return  the  current colour (pen)  of  a  specific 
               point on the screen.

DRAW [x1,y1] TO x2,y2
               Draw a line between specified coordinates,  or the 
               last point plotted.  Note that this line is always 
               solid  and unaffected by SET LINE for  speed.  For 
               styled lines, use the POLYLINE command.

BOX x1,y1 TO x2,y2
               Draw  a  hollow box with the top left  and  bottom 
               right hand coordinates being specified.

RBOX x1,y1 TO x2,y2
               Draw a hollow box with rounded edges.

POLYLINE [x1,y1] TO x2,y2 [TO x3,y3....]
               Draw a polygon using the current line style.

ARC x1,y1,r,sø,eø
               Draw  an arc centre x1,y1 radius r from sø to  eø. 
               Note  that  angles are calculated in  radians  (0-
               3600)  and start from the 3 o'clock  position  and 
               travel anticlockwise.

EARC x1,y1,r1,r2,sø,eø
               Draw an elliptical arc as above.

SET LINE mask,thickness,startpoint,endpoint
               Set  the current line style to mask which is a  16 
               bit binary pattern for the line,  thickness is the 
               thickness  of the line and can vary from 1 to  40. 
               The  startpoint  and  endpoint are  the  line  end 
               styles and can be either:
               0 : SQUARED
               1 : ARROWED
               2 : ROUNDED

PAINT x1,y1    Fill and enclosed area in the current colour.

BAR x1,y1 TO x2,y2
               Draw a filled bar.

RBAR x1,y1 TO x2,y2
               Draw a rounded filled rectangle.

POLYGON x1,y1 TO x2,y2 [TO x3,y3....]
               Draw a filled polygon.

CIRCLE x1,y1,r Draw a filled circle.

PIE x1,y1,r,sø,eø
               Produce a pie chart

ELLIPSE x1,y1,r1,r2
               Draw an ellipse.

EPIE x1,y1,r1,r2,sø,eø
               Produce a filled elliptical pie.

SET PAINT type,pattern,border
               Select a fill pattern.
               Type can range from 0 to 4:-
               0    Surface is not filled at all
               1    Surface is filled with the current INK
               2    Surface  is filled with one of the 24  dotted 
                    patterns
               3    Surface  is  filled with one of the  12  line 
                    patterns
               4    Surface is filled with a user-defined pattern

               Pattern  can range from 1 to 24 or 1-12  depending 
               on the type.

               Border has only 0 (no border) or 1 (border)

SET PATTERN address of pattern
               This  is  used  to install  a  user  defined  fill 
               pattern  for the user-defined fill option  of  SET 
               PAINT.  The address of pattern refers to where  in 
               memory the new pattern is to be found.
               Each  pattern is 16 points high by 16 points  wide 
               and takes up two byte words for each colour plane.
               The easiest way of creating them is to define a 16 
               by 16 sprite and then use the following routine to 
               find the address of the sprite.

               if mode=0 then PLANES=4
               if mode=1 then PLANES=2
               if mode=3 then PLANES=1
               s=1 : rem sprite to be indexed
               SP=leek(start(1)+4*(mode+1))+start(1)+4
               SPB=SP+(S-1)*8
               POS=leek(SPB)+SP+32*PLANES
               set paint 4,1,1
               set pattern POS

               Another way is A$=SCREEN$(physic,1,1 to 16,16)
                              SET PATTERN A$

FLASH index,"(colour,delay)(colour,delay)...."
               Set any of the 16 colours to flashing.
               Index is the colour number to be animated.
               Delay  is  the number of 50ths of a  second  which 
               must elapse before the next colour is used.
               Colour is the standard RGB format.

SHIFT delay[,start]
               This   command  allows  you  to   produce   colour 
               rotation. Delay is the number of 50ths of a second 
               which  must  elapse before the colour  palette  is 
               rotated.  The optional start allows you to specify 
               which  is  the first colour in the palette  to  be 
               rotated, if omitted, the value of 1 will be used.

GR WRITING mode
               This  sets  up  the mode which will  be  used  whn 
               writing graphics text. Four modes are available:

               1 : Replace (Overwrite anything)
               2 : Transparent  (Put  only  the  ink  colour   on 
                    screen)
               3 : XOR (Combine with existing graphics)
               4 : Inverse Transparent (Plot only colour zero)

POLYMARK x1,y1[;x2,y2[;x3,y3......]]
               Place  a polymark on the screen at  the  specified 
               coordinates.

SET MARK t,s   Set the current polymark to the required type  (t) 
               and size (s). Type can be :
               1 : Point (1 size only)
               2 : +
               3 : *
               4 : Square
               5 : Diagonal cross
               6 : Diamond
               Size can be any one of eight,  ranging in 11 point 
               increments from 6 to 83 pixels wide.

MODE n         Change screen to mode (n) : 0=low res, 1=med res.

=MODE          Return the current mode, 0-3

DIVX/DIVY      Hold the width and height of the current  graphics 
               screen according to the current mode.

CLIP x1,y1 TO x2,y2
               Define  the  tope  left and bottom  right  of  the 
               clipping  rectangle.  Any graphics  drawn  outside 
               this area will not be shown.

CLIP OFF       Disables the clipping rectangle.

                           The Screen

Multiple Screens

STOS Basic holds two screens in memory at any one time. The first 
is  called  the  physical screen,  and is  the  screen  which  is 
actually  displayed.  There is also a separate background  screen 
which is used by the sprite commands.

BACK           is  a  variable  which holds the  address  of  the 
               background screen.

PHYSIC         Is  a  variable  which holds the  address  of  the 
               physical screen currently being displayed.. If you 
               load a different address into this  variable,  the 
               screen  will  be  immediately  redrawn  using  the 
               screen stored at this address.  The value assigned 
               can  either be an address,  or the number  of  the 
               memory bank in which the screen is stored.

LOGIC          This is the screen which text and graphic commands 
               operate  on.  Normally,  this and PHYSIC hold  the 
               same  address  so that you can see what  is  being 
               drawn  to the screen.  However,  it  is  sometimes 
               useful  to have the pictures drawn on  a  separate 
               screen  and then displayed.  This can be  done  by 
               setting LOGIC to the address of an area or  memory 
               bank  onto  which the image can  be  created,  and 
               then,   when  it  is  finished,  display  it  with 
               PHYSIC=LOGIC.

SCREEN SWAP    This  swaps  the addresses held in  the  variables 
               PHYSIC  and LOGIC.  This enables you to  instantly 
               switch from one screen to another.

DEFAULT        Returns  the  initial value of one  of  the  three 
               screens.

               DEFAULT BACK   Returns initial value of BACK
               DEFAULT PHYSIC Returns initial value of PHYSIC
               DEFAULT LOGIC  Returns initial value of LOGIC

               When you are using multiple screens, it is easy to 
               lose track of the original screen addresses.  This 
               function is often used to restore these values.

               PHYSIC=DEFAULT PHYSIC
               BACK=DEFAULT BACK
               LOGIC=DEFAULT LOGIC

Reserving a screen

STOS  can  have any number of screens held in memory at  any  one 
time.  The following instructions allow you to allocate a  memory 
bank to hold one of these screens.

RESERVE AS SCREEN n
               Reserves  the bank number n as a temporary  screen 
               32768 bytes long.

RESERVE AS DATASCREEN n
               Reserves  the bank number n as a permanent  screen 
               32768  bytes long.  This will be saved along  with 
               your program.

Loading a screen

STOS lets you load a screen directly into an address or a  memory 
bank from either a DEGAS or NEO format.

LOAD filename$,scrn
               Where  filename$ is the name of the file on  disk, 
               complete     with      ".NEO",".PI1",".PI2",".PI3" 
               extension.  scrn can either be a memory bank or an 
               address.

GET PALETTE(n) Load  the colour settings of the screen stored  at 
               bank n into the colour palette.

CLS scr[,col[,x1,y1 TO x2,y2]]
               Clear  the screen.  The optional parameters  allow 
               you  to  specify the colour that  the  screen,  or 
               portion of the screen, is to be filled with.

ZOOM scr1,x1,y1,x2,y2 TO [scr2,]x3,y3,x4,y4
               Magnifies  any rectangular section of  the  screen 
               stored  at scr1.  scr1 and scr2 can be  either  an 
               address or a memory bank.  The coordinates specify 
               the  top left and bottom right coordinates of  the 
               area to be magnified from and to.

REDUCE scr1 TO [scr2,]x1,y1,x2,y2
               Compresses  the entire screen stored at scr1 to  a 
               rectangle  x1,y1,x2,y2  either in  the  background 
               screen,  or the screen stored at scr2.  Note  that 
               scr1  and  scr2  can be  either  memory  banks  or 
               addresses.

SCREEN COPY scr1[,x1,y1,x2,y2] TO scr2[,x3,y3]
               This  command  allows you to  copy  either  entire 
               screens  from  scr1 to scr2,  or portions  of  the 
               screen,  as  specified by the  coordinates.  Note, 
               however,  that the x coordinate is always  rounded 
               down to the nearest multiple of 16.
               These  coordinates  can also be  negative  in  the 
               ranges  shown  below.  Areas off the  screen  will 
               simply not be copied.

               Graphics mode       X Range        Y Range     
               Low                 -320 to 320    -200 to 200
               Medium              -640 to 640    -200 to 200
               High                -640 to 640    -400 to 400

=SCREEN$(scrn,x1,y1 TO x2,y2)
               Load an area of the screen into a string.
SCREEN$(scrn,x,y)=
               Load a screen held in a string to the screen.

Scrolling the screen

DEF SCROLL n,x1,y1 TO x2,y2,dx,dy
               This  command allows you to define up to 16  zones 
               for scrolling.
               n denotes the number of the zone from 1-16.
               x1,y1,x2,y2 denote the upper left and lower  right 
               coordinates of the zone.
               dx,dy  hold the number of points that the zone  is 
               to be scrolled, either up, down, left or right.

SCROLL n       Scroll zone number n in the direction specified.

Screen synchronisation

The  screen is updated by the hardware every 50th of  a  second.. 
Once the screen has been drawn, the electron beam turns off while 
it  returns  to the top of the screen again.  This  is  called  a 
vertical blank,  or VBL for short.  When this takes  place,  STOS 
performs a number of tasks,  such as moving the sprites,  playing 
music, shifting the colour palette, etc. Since a 50th of a second 
is a long time for STOS basic, this can lead to a serious lack of 
coordination between your program and the screen.  This is  where 
these commands come in.

WAIT VBL       Waits for the next vertical blank to  occur.  This 
               is generally used after PUT SPRITE or SCREEN SWAP, 
               as this is when these commands are executed.

SYNCHRO        Synchronise scrolling with sprites.
               STOS performs all sprite movements every VBL. This 
               generally works fine, but occasionally it leads to 
               an irritating synchronisation problem.
               
               Supposing  you  want to place a sprite a  a  fixed 
               point  on  a scrolling  background.  Whenever  the 
               background moves,  the sprite will move along with 
               it.  It should be easy enough to produce a set  of 
               MOVE X and MOVE Y commands which precisely  follow 
               the  movement of  the  background.  Unfortunately, 
               this wouldn't quite work as the SCROLL instruction 
               would  not  be executing at the same time  as  the 
               sprite commands.  The sprites would therefore tend 
               to drift jerkily around the screen.
               STOS,  however,  supplies you with a command  that 
               will  allow  you to move all the  sprites  on  the 
               screen at the exact time that you want them to:

               SYNCHRO ON     Turn   off   the   normal    sprite 
                              interrupt  which moves the  sprites 
                              every 50th of a second.
               SYNCHRO        Execute  all  the  sprite  movement 
                              commands once.
               SYNCHRO ON     Reverts  the  sprite  movements  to 
                              normal.  The  sprites will  now  be 
                              moved automatically every 50th of a 
                              second.

Compacting the screen

STOS  comes  with a handy accessory which allows you  to  compact 
part or all of the screen,  "COMPACT.ACB". The following commands 
are also supplied:

UNPACK bnk,scr Unpacks a screen stored in bank number bnk to  the 
               address or bank number scrn.

PACK scr,bnk   Pack the screen stored at address or bank scr into 
               memory bank bnk.

Special screen effects

APPEAR x[,y]   This  command  allows you to produce  fancy  fades 
               between  a  picture  stored in x  to  the  current 
               screen.  The parameter y can specify which of  the 
               79 fades you wish to use. Fades 1-72 always result 
               in a complete image being copied, whilst fades 73-
               79 leave the final screen slightly different  from 
               the one stored at x.

FADE speed     This  command  allows  you  to  fade  the  colours 
               between two screens.
               FADE speed          Fades  all the colours on  the 
                                   screen   to   black   in   the 
                                   specified 50ths of a second.
               FADE speed TO bank  Fades  the present colours  to 
                                   those specified in the  screen 
                                   stored in bank
               FADE speed,c1,c2,.. Fade seperate colours to a new 
                                   value.
               The  first two should speak  for  themselves,  the 
               last  one  isn't quite so obvious.  Speed  is  the 
               number  of VBL's which are to occur  between  each 
               colour change.  The list which follows is the  new 
               colours you require for colour1, colour2, colour3, 
               etc. Any colours you don't wish to change are left 
               blank.
               e.g.
               FADE 5,$777,$777,,$777,,$777
               Will,  using speed 5,  fade the current pens 0,1,3 
               and  5 to white ($777).  Colours 2 and 4 are  left 
               unchanged, as are colours 6-15.

                        Text and Windows

STOS basic allows you to print text on the screen in a number  of 
ways.  It also allows up to 13 windows each with it's own  unique 
character set.

PEN index      This allows you to specify which of the pens (0-15 
               in low res,  etc.) all subsequent text  operations 
               are to be performed in.

PAPER index    This,  like  PEN designates all future  background 
               colour.

INVERSE ON/OFF This mode switches the text and background colours 
               selected by PEN and PAPER.

SHADE ON/OFF   This fades out all subsequent text.

UNDER ON/OFF   This switches the underline mode on or off.

WRITING effect This allows you to specify the writing mode of all 
               subsequent text operations:
               1    Replacement mode (default).
               2    OR with existing screen.
               3    XOR with existing screen.

LOCATE x,y     Locates the cursor at coordinates x,y.

=XTEXT(x)      Converts  the x coordinate from graphic format  to 
               text relative to the current window.

=YTEXT(y)      Converts  the y coordinate from graphic format  to 
               text relative to the current window.

=XGRAPHIC(x)   Converts  the x coordinate from text format to  an 
               absolute screen coordinate.

=YGRAPHIC(y)   Converts  the y coordinate from text format to  an 
               absolute screen coordinate.

SQUARE wx,hy,b Draws  a  rectangle on the screen at  the  current 
               cursor  position specifying the width  and  height 
               (minimum of 3) in character positions with any one 
               of 15 different border types (see BORDER).

HOME           Sends  the cursor to the top left hand  corner  of 
               the current window.

CDOWN          Moves  the  cursor  one  space  in  the  requested 
CUP            direction.
CLEFT
CRIGHT

XCURS          Variables holding the current text coordinates  of 
YCURS          the cursor.

SET CURS t,b   Set  the text cursor size specifying the  top  and 
               bottom of the cursor (1-8).

CURS ON/OFF    Enable/disable the text cursor.

CENTRE a$      Print a line of text centred on the screen.

TAB(n)         Used with the print instruction to move the cursor 
               forward n spaces.  Unlike the usual basic command, 
               this produces a string of cursor rights,  and  can 
               be assigned to a string if required.
               X$=TAB(7)
=SCRN(x,y)     Returns  the ascii code of the character found  at 
               the  text  coordinates  relative  to  the  current 
               window.

Windows

WINDOPEN n,x,y,w,h[,b[,s]]
               Create  a  window  number n (1-13)  at  x,y  (text 
               coordinates of the top left corner of the window), 
               width  w and height h.  The options allow  you  to 
               specify one of 15 borders (see BORDER) and one  of 
               several character sets.
               There are 16 character sets available:
               1 : 8x8 (Default for low resolution)
               2 : 8x8 (Default for medium resolution)
               3 : 8x16 (Default for high resolution)
               Sets 4-16 are your own character sets.

TITLE a$       Define a title for the current  window,  centering 
               it.  This will remain until the BORDER command  is 
               issued with no parameter.

BORDER [n]     This  allows  you  to choose one  of  16  possible 
               borders for the current window. The variable n can 
               range from 1-16,  and the borders are made up from 
               characters  192-255 in the current character  set. 
               These  may be changed if necessary.  Note that  if 
               you use boder on it's own, the current border will 
               be redrawn and the title of the window erased.

WINDOW n       Set the window n to the top,  make it the  current 
               window and redraw it's contents.  Note that if the 
               window is already fully visible,  it's quicker  to 
               use the QWINDOW command.

QWINDOW n      Activate window n without redrawing it.

WINDON         Returns the number of the currently active window.

WINDMOVE x,y   Move the current window to new x,y coordinates.

WINDEL n       Delete window n.

CLW            Clear the current window.

SCROLL ON/OFF  Switch window scrolling off.

SCROLL UP/DOWN Scroll all the text in a current window up or down 
               one line.

Character Sets

RESERVE AS SET n,l
               This reserves a bank n in memory as character  set 
               storage l bytes long.  This bank is permanent  and 
               will be stored along with your program.

CHARLEN(n)     This  returns  the  length  of  a  character   set 
               specified by the number n.

CHARCOPY s TO b
               This  copies  the character set s (1-16)  to  bank 
               number b.

ICON$(n)       Generate an icon at the current cursor position.
               This will effectively draw icon number n from  the 
               bank defined. It may also be used in menu bars.

                          Menu Commands

STOS provides you with a number of clever facilities for creating 
and using menus.  Although different from their GEM  equivalents, 
they are considerably more powerful.

Creating a menu

MENU$(x)=title$[,paper,pen]
               This  allows you to specify the main  titles  that 
               will  appear  on the top line.  Title$  holds  the 
               title  of your menu,  and you are also  given  the 
               option to specify the paper and pen colours if you 
               wish.  You can define up to 10 titles this way (1-
               10).

MENU$(x,y)=option$[,paper,pen]
               This  allows you to specify the options that  will 
               appear in each drop down menu.  x is the menu  (as 
               specified  by the MENU$(x) command,  and y is  the 
               option number within the menu.  Again,  paper  and 
               pen options are available to you.

e.g            10 menu$(1)="ACTION"
               20 menu$(2)="MOUSE"
               30 menu$(1,1)="QUIT"
               40 menu$(2,1)="ARROW"
               50 menu$(2,2)="HAND"
               60 menu$(2,3)="CLOCK"

MENU ON [b][,m]
               Activates the menu with any one of 16 borders (see 
               BORDER).  The  mode is either 1 for  the  standard 
               drop down menus, or 2 for pull down menus.
               70 MENU ON 5,2
               Generates a pull down menu with border 5.

MENU OFF       Permanently  switches the menu bar off and  erases 
               it from memory.

MENU FREEZE    Temporarily  freezes  the  menu  bar  and  can  be 
               restarted with the MENU ON command.

MENU$(x,y) OFF Disables one of the menu items.
MENU$(x,y) ON  Re-enables a menu item disabled with the above.

MNBAR          These  variables hold the menu title and the  menu 
MNSELECT       options you have chosen.

ON MENU        This provides you with an interrupt driven  method 
               of selecting the menu bar.  This will allow you to 
               run  a program as normal,  but when an  option  is 
               selected,  it  will jump to one of a list of  line 
               numbers  in the same way an ON GOTO  would,  using 
               the title number returned.

ON MENU ON     Sets the entire process in operation by activating 
               the ON MENU command.

ON MENU OFF    Turns the menu off.

Icons can also be included into menu bars as well.

               menu$(2,1)=icon$(3)
               menu$(2,2)=icon$(4)
               menu$(2,3)=icon$(5),2,4

                         Other Commands

Control Structures

GOTO line number/expression
               NOTE: STOS doesn't use labels for lines, equations 
               and  variables  may be used,  but  they  will  not 
               renumber.

GOSUB line number/expression
RETURN
POP            Trash  the  return address generated  by  a  GOSUB 
               statement.

FOR..TO..STEP
NEXT           Note  that  multiple  NEXT  statements  cannot  be 
               combined.

WHILE...WEND
REPEAT...UNTIL

STOP
END

IF..THEN..ELSE Note that this is one line ONLY.

ON...GOTO
ON...GOSUB

ON ERROR GOTO line
               This allows you to trap errors within the  program 
               by  ordering  the computer to jump to  a  specific 
               line if one occurs.
RESUME         Jump back to the command that caused the error and 
               retry.
RESUME NEXT    Jump  to the command following the one  generating 
               the error.
RESUME line    Jump to a specific line.
ERN and ERL    Variables  holding  the  error  number  and   line 
               number.
ERROR n        Generate an error and exits back to STOS.

BREAK  ON/OFF  Disables or enables the Control+C checks.

KEY(x)=a$      Assign a string to one of the 20 function keys (1-
               20).  Note that the ' character is interpreted  as 
               CHR$(13).

INKEY$         Return a key press, but don't wait.

SCANCODE       Holds the scancode of the last key pressed.

CLEAR KEY      Clear out the keyboard buffer.

INPUT$(n)      A  function  which  reads n  characters  from  the 
               keyboard  and  echos  them to  the  screen  before 
               returning.

FKEY           Is  a special form of INKEY$ which will  return  a 
               value  between 0 and 20 to indicate which  of  the 
               function keys has been pressed.

WAIT KEY       Waits for a keypress.

KEY SPEED r,s  Sets  the repeat speed (r) in delays of 50th of  a 
               second and the delay between the initial  keypress 
               and the start of the repeat sequence (d) in  50ths 
               of a second.

PUT KEY a$     Writes  a  string to the keyboard  which  will  be 
               'typed'  when the computer next has  chance.  Note 
               that  the  '  character  works  the  same  way  as 
               pressing the return key.

INPUT [prompt;]variable list
LINE INPUT [prompt;]variable list

PRINT and ?
PRINT USING format$;variable list
               The format can consist of any characters with  the 
               exception of ~#+-.;^
               Their meanings are as follows:

               ~ Insert a character from the following string.
               # Insert a digit from the following number.
               + Add a plus + or - sign to the number.
               - Add only a - sign to the number.
               . Align with decimal point.
               ; Align with decimal point, but don't print it.
               ^ Print number in exponential form.

                           Disk Access

OPEN IN #channel,filename$
OPEN OUT #channel,filename$[,attribute]
               Open files for input or output only.  Channel  can 
               be from 1-10 and it is this channel that all  data 
               will  be sent to.  Filename$ is the disk  filename 
               holding  the data,  if output,  then the  existing 
               file on the disk will be erased.
               The  optional attribute allows you to specify  the 
               type of file to be created (see DIR FIRST$).

OPEN #channel,"R",file$  Opens a random access file.
OPEN #channel,"MIDI"     Opens a channel to the MIDI interface.
OPEN #channel,"AUX"      Opens a channel to the RS232 port.
OPEN #channel,"PRT"      Opens  a channel to the printer  plugged 
                         in the parallel port.

CLOSE#channel  Closes a file and writes any buffered data.
PRINT#channel,list
               Prints  a  list of data,  like  the  normal  print 
               function, to the specified channel.
INPUT#channel,list
               Like  input,  but allows you to  read  information 
               from a channel.
LINE INPUT#channel[,seperator$],list
               This acts like INPUT, reading data from a channel, 
               seperated by a <Return> rather that a  comma.  The 
               optional seperator$ is included if something other 
               that a <Return> seperates the data.
INPUT$(#channel,count)
               Inputs count characters from the file.
EOF#channel    A variable used to test for the end of a file.
LOF#channel    Return the length of a file.
POF#channel    The  variable holding the current position of  the 
               pointer within a file. This may be altered to move 
               the pointer.

FIELD#channel,length1 AS field1$,length2 AS field2$....
               Field allows you to define a record which will  be 
               used  for  random access files.  This  record  can 
               consist of up to 16 alphanumeric fields and can be 
               up to 65535 bytes long.

PUT#channel,r  Writes  the  record created by FIELD  into  record 
               position r in the file.

GET#channel,r  Reads the record r from the specified channel into 
               the field set up by the FIELD command.

PORT#channel   Test  to  see if an input device  is  waiting  for 
               information.

                           The Printer

LLIST          As List,  allows you to send your listings to  the 
               printer.
LDIR           List the directory on the printer.
LLISTBANK      List the memory bank information on the printer.
LPRINT         Print all thet follows to the printer (see PRINT)
HARDCOPY       Dump the screen as would Alternate+Help.
WINDCOPY       Unlike hardcopy,  this command prints out the text 
               in the current window.

                           Directories

DIR [path$][/W]     Lists the current directory.
DIR$=          Sets the current directory.

=DIR FIRST$(path$,flag)
               This  returns  the first file that  satisfies  the 
               pathname.  The  flag  is a number of  binary  bits 
               which  indicates  which types of file  are  to  be 
               sought.
               Bit 0 : Normal Read/Write files
               Bit 1 : Read only iles
               Bit 2 : Hidden files
               Bit 3 : Hidden system files
               Bit 4 : Volume labels
               Bit 5 : Folders
               Bit 6 : Files  which  have  been  written  to  and 
               closed.
               If you aren't sure which type you want, use -1.

               If no file exists, then a null string is returned, 
               elsewise  a 42 character string is  returned  with 
               the following format.

               Characters     Usage
               1-12      Filename
               13-21     Length of file
               22-32     Date file saved
               33-41     Time file saved
               42        File type

DIR NEXT$      Returns  the next file found as per the  setup  in 
               DIR FIRST$
PREVIOUS       Drops back one level in the subdirectories.
=DRIVE=        Variable holding the drive number (0-...)
=DRIVE$=       Varianle holding the drive letter (A-...)
DRVMAP         Variable holding a list of the drives connected in 
               binary.
DFREE          Holds the amount of free space left on a disk.
MKDIR folder$  Creates a folder
RMDIR folder$  Removes an empty folder from the disk
KILL file$     Erase a file, or series of files from the disk.
RENAME old$ TO new$      Renames a file.
                     Trigonometric functions

DEG(x)         Convert an angle expressed in radians to degrees
RAD(x)         Convert an angle expressed in radians to degrees
SIN(x)         COS(x)    TAN(x)    Sine, Cosine and Tan
ASIN(x)        ACOS(x)   ATAN(x)   Arc Sine, Cosing and Tan
HSIN(x)        HCOS(x)   HTAN(x)   Hyperbolic  Sine,  Cosine  and 
                                   Tan
PI             ã
LOG(y#)        Log base 10 of y#
LN(y#)         Natural Log of y#
EXP(y#)        Exponential of y#
SQR(y)         Square Root
ABS(y)         Absolute value
INT(y)         Integer Rounded down
SGN(y)         Find the sign of y
MAX(x,y)       Return largest value
MIN(x,y)       Return smallest value
SWAP x,y       Swap variables x and y (also strings)
DEF FN name[(variable list)]=expression
               Define a function
FN name[(variable list)]
               Call a user defined function.
RND(y)         Return a random number from 0-y inclusive
LET            Yes, this is still to be found!
FIX(n)         Set the precision of any real numbers that are  to 
               be printed out on the screen.
               If  0<n<16  then n denotes the number  of  figures 
                    after the decimal point.
               If n>16 the printout will be proportional and  any 
                    trailing zeros will be removed.
               If  n<0  then all floating point numbers  will  be 
                    expressed in exponential format.
=UPPER$(n$)    Convert n$ to upper case.
=LOWER$(n$)    Convert n$ to lower case
=FLIP$(n$)     Reverse the order of the letters in n$
=SPACE$(n)     Creates a string full of spaces.
=STRING$(a$,n) Create a string full of a$
=CHR$(n)       Return ASCII character.
=ASC(n)        Return ASCII code.
=LEN(n$)       Return length of n$.
=VAL(n$)       Convert n$ to a number.
=STR$(n)       Convert n to a string.
=TIME$=        A     variable     holding     the     time     in 
               hours:minutes:seconds
=DATE$=        A   variable  holding  the  date  in  the   format 
               DD/MM/YYYY
=FILE SELECT$(path$[,title$[,border]])
               Request for a filename using the file selector.

=HEX$(n,l)     Convert n to a hexadecimal number.  The optional l 
               requests for it to be padded out.
=BIN$(n,l)     Converts n into a binary number.
ROL[.B/.W/.L] x,y
               Rotate y left by x places. The optional .B, .W and 
               .L  tell  the instruction to treat is as  a  byte, 
               word or longword.

ROR[.B/.W/.L] x,y
               Rotate Right
=BTST(x,y)     Test bit x of number y
BSET x,y       Set bit x of number y
BCHG x,y       Change the status of bit x in number y
BCLR x,y       Clear bit x of number y
PEEK             POKE DEEK DOKE LEEK LOKE Read  or   change   the 
                 contents of memory locations.
VARPTR(variable)    Returns the address of the variable stored in 
                    memory.

COPY start,finish TO destination
               Copy a block of memory.
FILL start TO  finish,longword
               Fill an area of memory.
=HUNT(start TO finish,A$)
               Hunt through memory for a string.
WAIT x         Wait for x 50ths of a second.
=TIMER=        Timer counted in 50ths of a second.
=NOT(x)        Logical NOT operation.

REM remark
DATA variable list
               Numbers,  strings,  variables and formulae can  be 
               included.
READ variable list
RESTORE [line]
TRUE           Variable holding -1
FALSE          Variable holding 0

                           Appendix A
                         Error Messages

Error Code     Error name                                        

   0           Not Done
               A  procedure has been attempted,  but due to  some 
               condition, it has not been carried out.

   1           Bad File Format
               A  file to be loaded cannot be recognised by  STOS 
               as it is not of the correct format.

   2           Out Of Memory
               STOS has no more memory left for allocation.  Take 
               out  all  the accessories and excess  programs  to 
               free more memory.

   3           This Line Does Not Exist
               This error occurs when you have tried to delete  a 
               line which does not exist so the delete  operation 
               is aborted.

   4           This Line Already Exists
               The Auto function reports this error when it comes 
               across a line which is already in your program.

   5           Search Failed
               A  string  has been searched for  in  the  current 
               program, but it does not exist.

   6           Line Too Long
               You  have attempted to enter a line more than  700 
               characters long.

   7           Can't Continue
               STOS can't continue from the previous break.

   8           See Error 6.

   9           Follow Too Long
               STOS has been told to trace too many parameters.

   10          Printer Not Ready
               The printer is not on line.

   11          Can't Renum
               STOS  has attempted to renumber a section of  your 
               program and this action would result in a conflict 
               of line numbers.

   12          Syntax Error
               The  syntax of the error line or statement is  not 
               correct.

   13          Illegal Function Call
               You  have tried to use a function with an  illegal 
               set of parameter.
   14          Illegal Direct Mode
               A  command input in direct mode is not  recognised 
               by STOS.

   15          Direct Command Used
               A  command which is only available in direct  mode 
               has been used in the program.

   16          In/Out Error
               An  error  has  occurred  during  an  input/output 
               operation

   17          Break
               You have pressed Control+C.

   18          Non Declared Array
               An  array has been referenced which has  not  been 
               set up with the DIM statement.

   19          Type Mismatch
               An illegal value has been assigned to a variable.

   20          Function not implemented
               A function entered in STOS is not recognised.

   21          Overflow Error
               A calculation has exceeded the size of a variable.

   22          For Without Next
               A  FOR command does not have it's  mandatory  next 
               listed later in the program.

   23          Next Without For
               STOS has come across a NEXT instruction which  has 
               no FOR.

   24          While Without Wend
               The WHILE instruction has no mandatory WEND  after 
               it.

   25          Wend Without While
               A  WEND instruction has been encountered that  has 
               no matching WHILE.

   26          Repeat Without Until
               A   REPEAT   instruction   exists   but   has   no 
               corresponding UNTIL.
   27          Until Without Repeat
               The  UNTIL  instruction has  no  preceding  REPEAT 
               command.

   28          Array Already Dimensioned
               An  array  has been re-dimensioned  at  the  error 
               line.

   29          Undefined Line Number
               A  GOTO,  GOSUB  or RESTORE has  been  encountered 
               which indexes a non-existent line.

   30          String Too Long
               A   string  has  exceeded  the  limit  of   65000 
               characters.

   31          Bus Error
               An  internal  error has occurred possibly  due  to 
               incorrect  addressing  using  the  PEEK  and  POKE 
               commands.

   32          Address Error
               An odd memory address or invalid address has  been 
               accessed using the PEEK and POKE commands.

   33          No Data On This Line
               The  RESTORE  instruction has tried to  restore  a 
               line  of  data.  In this case,  the line  did  not 
               contain a DATA command.

   34          No More Data
               The READ command cannot get any more data  because 
               it has all been read.

   35          Too Many Gosubs
               STOS cannot store any more RETURN addresses.

   36          Return Without Gosub
               The program has reached a RETURN but no GOSUB  has 
               been used.

   37          Pop Without Gosub
               The  POP instruction cannot be executed outside  a 
               subroutine.

   38          Resume Without Error
               A RESUME instruction cannot be executed unless  an 
               error has occurred.

   39          User function Not Defined
               A  user  function has been accessed that  has  not 
               been set up with DEF FN.

   40          Illegal User-Function Call
               The list of parameters you inpt does not match the 
               list you specified in the DEF FN.

   41          Memory Bank Already Reserved
               An  attempt  to reserve a memory bank  has  failed 
               because it is already reserved.

   42          Memory Bank Not Defined As Screen
               A command has accessed a memory bank which must be 
               reserved  as  screen  and  thus  cannot  find  the 
               information required.

   43          Bad Screen Address
               A  screen address has been used which  is  invalid 
               for  a proper screen start  address.  The  address 
               must be on a 256 byte boundary.

   44          Memory Bank Not Reserved
               A  memory bank has been accessed and has not  been 
               reserved for use.

   45          Resolution Not Allowed
               MODE cannot be used in high-resolution monitors.

   46          Division By Zero
   
   47          Illegal Negative Operand
               Some functions cannot process negative numbers.

   48          File Not Found
               You  have tried to open or load a file not on  the 
               current disk.

   49          Drive Not Ready
               A disc drive is not ready for use.

   50          Disc Is Write Protected

   51          Disc Full

   52          Disc Error
   
   53          Bad Filename
               A  filename  has  been  used  in  an  input/output 
               procedure which is not legal.

   54          Bad Time
               The  user  has attempted to set  an  illegal  time 
               using TIME$.

   55          Bad Date
               The  user has attempted to set up an illegal  date 
               using DATE$.
   56          Sprite Error
               Parameters  for  a SPRITE command  have  been  set 
               which do not fall inside the legal limits.

   57          Movement Declaration Error
               The MOVE instruction has not been set properly.

   58          Animation Declaration Error
               The ANIM string command has not been properly set.

   59          File Not Open
   
   60          File Type Mismatch
               A  file  command  has been  used  which  does  not 
               correspond to the correct filing system.

   61          Input String Too Long
               An  incoming string is too long for a  dimensioned 
               variable. Or you may have tried to INPUT# a string 
               more than 500 characters long.

   62          File Already Open
   
   63          File Already Closed

   64          End Of File
   
   65          See Error 61.

   66          Field Too Long
               The size of the record you have created with FIELD 
               is  greater than 65535 bytes.  It's also  possible 
               that  you  have  used more  than  the  maximum  16 
               fields.

   67          Flash Declaration Error
               The FLASH command has been incorrectly called.

   68          Window Parameter Out Of Range

   69          Window Already Open

   70          Window Not Opened

   71          Window Too Small
               An attempt has been made to open a window  smaller 
               than 3x3.

   72          Window Too Large

   73          Character Set Not Defined

   74          No More Text Buffer Space
               If  you  open over 10 windows the size of  a  fill 
               screen  in either mode 1 or mode 2 then the  space 
               reserved for the data in each window gets used  up 
               and causes this error.

   75          Music Not Defined

   76          System Window Called
               The  system windows have been used in one  of  the 
               commands. These are 0, 14 and 15.

   77          System Character Set Called
               You  have attempted to replace a system  character 
               set with a custom designed one.

   78          Character Set Not Found
   
   79          Menu Not Defined

   80          Bank 15 Already Reserved
               This  bank is already reserved and must be  erased 
               if you wish to reserve it for another purpose.

   81          Bank 15 Is Reserved For Menus
               Menus are used in the current program and thus you 
               cannot use this bank for anything else.

   82          Illegal Instruction
               When  STOS is running a machine code program  this 
               error  will  occur if it finds that  the  code  is 
               invalid.

   83          Drive Not Connected

   84          Extension Not Present
               This  occurs when you try to run a  program  which 
               incorporates  new  STOS  Basic  commands   without 
               loading the relevant extension file first.

   85          Subscript Out Of Range

   86          Scrolling Not Defined
               The SCROLL command has been used but STOS  doesn't 
               have  the  information  necessary  to  scroll  the 
               screen.

   87          String Is Not A Screen Block
               A  string has been used in SCREEN$ which  has  not 
               been designed as a sprite block string.

                           Appendix B
                     Using Assembly Language

CALL address or bank
               CALL  allows you to execute any assembly  language 
               program  held in the ST's memory.  address can  be 
               either the absolute location of the code,  or  the 
               number  of the memory bank that the code  is  held 
               in.

Calling a machine code program

1              Reserve  some  memory for your routine  using  the 
               RESERVE AS DATA, e.g. RESERVE AS DATA 7,10000

2              Load the program, e.g. LOAD "file.prg",7
               NOTE  that  the code must be  in  TOS  relocatable 
               format  and  must  NOT  summon  any  of  the   GEM 
               routines.

3              Pass   any  input  parameters  using  the   pseudo 
               variables  DGRE(0)  to  DREG(7)  and  AREG(0)   to 
               AREG(6)

4              Call your program, e.g. CALL 7

Your assembly language program may subsequently change any  68000 
registers  it likes with the sole exception of A7,  and  it  must 
always be terminated with a RTS.  It must never call GEMDOS traps 
SET  BLOCK,  MALLOC,  MFREE,  KEEP  PROCESS or any  other  memory 
management functions.

TRAP n[,parameters]
               TRAP allows you to call one of the numerous  68000 
               TRAP functions.  These traps are really just large 
               libraries of assembly language functions.

               n refers to the number of the TRAP;
                    0,1,13,14 are the GEMDOS functions
                    3,4,5,6,7 are the STOS functions.

               The optional parameters specify the data which  is 
               to be placed on the 68000's stack before the  TRAP 
               function  is  executed.  As a  default  these  are 
               assumed to be of size WORD.  You can set the  size 
               directly  from  the TRAP instruction  by  using  a 
               statement such as:
                    W.expression
                    L.expression

               One  useful bonus is that you can also  include  a 
               string variable in the expression,  such as A$. In 
               this case,  the address of the string is placed on 
               the stack and a CHR$(0) is automatically added  to 
               the  end  of the variable to convert it  into  the 
               correct format.

                           Appendix F
                     Structures of the Banks

Structure of the Sprite Bank

Offset         Meaning
   0           Sprite Bank ID code ($19861987)
   4           4-byte offset to address of sprite parameter block 
               in low resolution
   8           4-byte offset to address of sprite parameter block 
               in medium resolution
   12          4-byte offset to address of sprite parameter block 
               in high resolution
   16          Number of sprites in low resolution
   18          Number of sprites in medium resolution
   20          Number of sprites in high resolution

Typical Sprite Parameter Block

Offset         Meaning
   22          4-byte offset to sprite data
   26          Width of sprite (in units of 16)
   27          Height of sprite
   28          X coordinate of hotspot
   29          Y coordinate of hotspot
   30          Start of next sprite parameter block....

Sprite Data Structure
                      The Sprite Data Block
                  Data for Mask (one bit plane)
              Sprite Data (organised in bit planes)

Structure of the Icon Bank

Offset         Meaning
   0           Icon Bank ID code ($28091960)
   4           Number of icons in bank
   6           Start of data for icon 1.  This is 84 bytes  long, 
               and uses the same format as the LINE-A sprites.
   92          Start of data for icon 2....

Structure of the Music Bank

Offset         Meaning
   0           Music Bank ID code ($13490157)
   4           Offset  from start of the bank to music number  1. 
               Set to zero if no music with this number.
   8           Offset to music number 2....
   124         Offset to music number 32 (Maximum of 32 pieces of 
               music)
   128         Length of this memory bank
   132         Name of music 1 (8 letters)
   140         Name of music 2 (8 letters).....
   380         Name of music 32 (8 letters)
   388         Start of music 1...

Inside the music definitions

Offset         Meaning             
   0           ID code that this is music data. ($19631969)
   6           Offset to music in voice 1.
   8           Offset to music in voice 2.
   10          Offset to music in voice 3.
   12          Definition  of  first tremelo/envelope  (36  bytes 
               long)
   48          Definition of second trememlo/envelope

   Start of voice 1

The Music Commands

Each note is stored as a teo-byte word ranging from 0-32767.  The 
lower  half of this word contains the pitch of the  note  (0-96). 
See PLAY for more details. The upper byte holds the length of the 
note in 50ths of a second.  The Music commands are held in either 
two  or  four bytes.  In order to distinguish  them  from  normal 
notes,  the highest bit of these commands is set to 1.  Here is a 
list  of the various commands and the numbers used  to  represent 
them in the music.

Number         Size       Command       Meaning
$8000          2 bytes    END           Signifies   the  end   of 
                                        music for this voice
$A000          2 bytes    MUSIC         Use pure tones for music.
$A100          2 bytes    NOISE ONLY    Use noise for music.
$A200          2 bytes    STOP NOISE    Turns off noise.
$A3xx          2 bytes    NOISE xx      Plays noise with pitch xx
$A400          2 bytes    STOP NTREMULO Stop mixing tremulo  with 
                                        noise
$A500          2 bytes    STOP ENVEL    Stop    using     current 
                                        envelope
$A600          2 bytes    STOP TREMOLO  Stop    using     current 
                                        tremolo
$A7xx          2 bytes    VOLUME xx     Set volume of sound to xx
$C000          4 bytes    NTREMULO      Mix  TREMULO with  noise. 
                                        Bytes 2&3 hold offset  to 
                                        tremulo definition
$C100          4 bytes    ENVEL xx      Use ENVEL xx.  Bytes  2&3 
                                        hold  offset to  envelope 
                                        definition
$C200          4 bytes    TREMULO xx    Use TREMULO xx. Bytes 2&3 
                                        hold  offset  to  tremulo 
                                        definition.
$C3nn          4 bytes    REPEAT  nn,note  Repeat music  starting 
                                        from note, nn times. Note 
                                        held in bytes 2&3.

Screen Banks

The  format of the screen banks is very straight forward  indeed. 
The first 32000 bytes of this memory hold the actual screen data, 
and the next 16 words from numbers 32000 to 32032 contain a  copy 
of  the  colour settings for this screen.  Note that  bytes  from 
32032 onwards are free, and can be used for your own purposes.

                           Appendix G
           Accessing The Programmable Sound Generator

PSG(r)

The  Atari ST incorporates a special piece of circuitry which  it 
uses to generate a wide range of sounds. 

Access  to this chip is via the PSG register,  which may be  read 
from, or written to.

WARNING:  This function is dangerous!  Incorrect usage can  cause 
serious damage to any disc in the disk drive.

Here  is  a brief list of the various sound registers  and  their 
uses:

Register       Function
   0           Bits  0-7 set the pitch in units of a single  step 
               for voice 1.
   1           Bits 0-3 set the size of each frequency step
   2           Fine control for voice 2. As register 0
   3           Coarse control for voice 2. As register 1
   4           Fine control for voice 3. As register 0
   5           Coarse control for voice 3. As register 1
   6           Bits 0-4 control the pitch of the noise generator. 
               The higher the value, the lower the tone.
   7           Control register for sound chip.
               Bit 0: Play pure note on voice 1 (1=ON, 0=OFF)
               Bit 1: Voice 2 tone ON/OFF
               Bit 2: Voice 3 tone ON/OFF
               Bit 3: Play NOISE on voice 1 ON/OFF
               Bit 4: Play NOISE on voice 2 ON/OFF
               Bit 5: Play NOISE on voice 3 ON/OFF
   8           Bits  0-3 control volume of voice 1.  If bit 4  is 
               set  to  1 then the envelope  generator  is  being 
               used,  and the volume bits are ignored. Since this 
               corresponds to a volume of 16,  this explains  why 
               you  need to set VOLUME to 16 before you  can  use 
               the ENVEL command.
   9           As register 8 but for voice 2
   10          As register 8 but for voice 3
   11          Bits 0-8 provide fine control of the length of the 
               envelope
   12          This  register  provides  coarse  control  of  the 
               length of the envelope.
   13          Bits 0-3 choose which of the 16 possible envelopes 
               is to be used.