STOS BASIC FAQ/INSTRUCTIONS
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
| 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.