GBP STOS Basic & Compiler Extension Manual


Welcome to the STORM Developments/GBP Software STOS basic and compiler extensions. Many thanks for your interest in this program, and thanks also for your registration fee. Your details have been placed in our registration database, allowing us to keep track of registered users and also send free program updates to those who want them.

We are sure that you will enjoy using the compiler version of the extension, and also hope that your programs will now be enhanced because of the use of GBP.

We would like to hear from you in the future to keep in touch with how you are getting on, solve any problems that you might have, or listen to any ideas that you may have about future extensions. Please do not hesitate to get in contact with any of the GBP team.


Before we begin, I and the rest of the GBP team would like to thank a couple of people and publishers who were a great help during the writing of this extension.

Billy Allen: Thanks for Misty & The Missing Link, it really inspired us to get GBP finished. Many thanks for the letters, and I hope that I shall hear from you quite soon.

Steve Jarrett: Thanks for all the comments about the extension.

Rick Dunlop: Again, thanks for taking the extension in, and I hope you didn’t mind me sending you a new version every week. How are you going with the PC? What’s up?? Are your routines not fast enough to work on an ST????? (joke.. I think!)

Stephen Hill: Thanks for creating such a wonderful book called “The Game Maker’s Manual”. It was really useful while I was originally coding and finally debugging the extension. I hope you write a follow-up.

Sigma Press: Thanks for publishing Stephen’s book!

Abacus Software: Thanks for publishing the “Atari ST Internals” book. It should play a major part in any assembler or ST programmers book collection!


Although this extension has been tested to it’s full abilities, GBP Software or any member of GBP Software cannot be held responsible for anything that may happen to computer equipment of any kind during the use of the extension. Basically, you’re on your own if it does go wrong!


These extensions and accompanying documentation are the SOLE copyrights of GBP Software, and may not be ripped off, copied, sold without our prior knowledge, or be changed in any way, including the documentation. It is an offense to copy the compiler extension without written permission from GBP Software. The BASIC extension and the DOCUMENTATION are shareware and can be copied freely. The Shareware release may be used for a 30-day period before registration becomes necessary.

Remember, copying copyrighted material is a criminal offense. Please register this product to make sure that GBP Software will continue to produce great-quality STOS extensions in the future.

Thank you for your attention.
Neil Halliday.

The Commands

Well, here’s the bit you have all been waiting for: the commands! I must apologise at this point, as all the commands are not in any sort of logical order, but I will try to keep them together. I will also try to include demo programs where applicable.

NOTE: All addresses that are mentioned in this extension must be passed as actual addresses, as the routine will not work by simply passing the bank number. i.e., the extension will bugger up if you use…

            Eplay 10,length(10),0,0,1

As the routine will play from memory address 10 instead of bank 10. So you will have to call it like this…

            Eplay start(10),length(10),0,0,1

Ok??? For more information about that, consult your STOS manual.



Syntax: Lights On

Description: This is a very nice command that will turn on the drive lights for disk drives A & B. This command will allow you to produce effects that have been seen in demo screens where the drive lights pulse to a piece of music and has also been seen recently at the beginning of Crack Art.



Description: The opposite of the last command. You have read the last command, haven’t you? As mentioned about pulsing the drive lights to music, here is the routine:

10 dreg(0)=1 : call 10 : rem * Call music Init
20 loke $4d2,start(10)+8 : rem * Install on VBL
30 if psg(8)>12 then lights on : else lights off
40 wait vbl : goto 30
50 :
60 loke $4d2,0 : bell : rem * Turn music off

The above routine will work with a MAD MAX music file loaded into bank 10, but if you don’t have any MAD MAX music you can use the normal STOS music (VERY CRAP!) by making these amendments:

10 rem * Routine to flash lights to CRAP MUSIC!
20 music 1

For more information about the PSG command, turn to your manual pages 265 & 266 (Ha! That will fool all you people who are using a copy of STOS!!! Buy the original, you SAD people!).


Syntax: X=PREADY

Description: This function tells you if the printer connected to the Parallel port is online or not. The variable X will contain the status of the printer, and can only take 2 forms.. TRUE (-1) if the printer is on line and ready to receive data, or FALSE (0) if the printer is set to anything else. Try the following small program to test this out:

10 X=pready
20 if X then bell
30 goto 10

This program will test the printer, and if it is online, it will sound the STOS bell repeatedly; otherwise, if your printer is offline, nothing will be heard. For more information about true and false statements, consult your STOS manual, page 227.


Syntax: X=EVEN(NUM)

Description: The even command will return if the input value is even or odd. The output variable X will contain true if NUM was even or FALSE if NUM was odd:

10 input A
20 if even(A) then bell : else boom



Description: This function allows the printer configuration to be set. The variable VAR is a bit vector with the following meaning:

BitnumberOff (0)On (1)
0Dot MatrixDaisy Wheel
2Atari PrinterEpson or Compatible
3Test Mode (DRAFT)Print Mode (NLQ/LQ)
4Centronics PortRS-232 Port
5Continuous SheetSingle Sheet
15Always 0Always 0

As an example, the following statement would set the printer to:

  • Dot Matrix Type
  • Monochrome
  • Epson or Compatible
  • Test Mode (DRAFT)
  • Centronics Port
  • Continuous Sheet

The bit number, as you will have noticed, is binary, with bit 1 being on the far right. This binary number can be substituted for the decimal equivalent, so the command:


Is equivalent to:


The printer’s parameters can be read by passing -1 as the input variable. The value will be returned as X.



Description: The special key command sets or returns the current status of the special keys (i.e., Shift(s), Alt, Ctrl, and Caps). The status can be set by passing variable I as a positive integer, and by passing I as -1, the status can be read.

10 print "Current Status :"; special key(-1)

The value returned by special key is an 8 bit value that is read in the following way:

0Right Shift Key
1Left Shift Key
2Control (CTRL) Key
3Alternate (ALT) Key
4Caps lock
5Right Mouse Button (CLR/HOME)
6Left Mouse Button (INSERT)

If the bit is set, then the button is active.


Syntax: HCOPY X

Description: The annoying thing about STOS is the fact that no matter how good your games, demos etc.. are, they can always be interrupted by the system HARDCOPY command (ALT & HELP). Well, that is no longer the case. This command will turn off and turn on the system Hardcopy! By passing X as 1, we turn ALT & HELP on, and by passing X as 0, we turn ALT & HELP off!

10 hcopy 0 : rem Turn HARDCOPY off
20 wait key
30 hcopy 1 : rem Turn HARDCOPY on

File Commands



Description: The D CRUNCH command allows you to unpack files compacted with the most popular packers around (up to now). By passing ADDR as the address of your compressed data, it will be decompressed by the recognised file format. The extension can unpack several different formats, which will be shown in a little while, but before we do, a little word of warning! The de-pack routines are a0 -> a0 routines, which means that any compressed data will be overwritten during decompression. It also means that memory banks will have to be reserved for the original file length of the data; otherwise, you face overwriting some data that you may need and, in some cases, even crashing your ST.



Description: All recognised packer formats have a special header to tell them from one another.. This command will return in variable X, what packer the data at address ADDR was compressed with. If the packer type is not recognised then the return value will be 0. Otherwise the value stands for:

1Speed Packer 2
2Atomik v2.5
3Ice v2.11
4Automation v5
5Ice v2.40
6Fire v2.0
7Speed Packer 3



Description: This command returns the uncompressed size of the packed file located at address ADDR.



Description: This command is used in conjunction with a GBP file bank, and returns the position in memory of file N, located in the GBP filebank that can be found at address ADDR. A GBP bank allows many files to be stored in just one memory bank, which programmers will understand that means loads of data loaded, and still loads of banks left.



Description: This command will return the length of file N, found in the GBP bank located at address ADDR.



Description: This command returns the offset of the file N, compared with the start of the GBP file bank. i.e file two may by 1024 bytes from the start of the bank. NOTE: The GBP bank builder accessory can be found along with the extension files.

Graphics Commands



Description: This is a very fast version of the STOS cls command. It will clear 32000 bytes from the address specified by ADDR. It can be used to clear memory banks or screen addresses (eg. physic). However if you are clearing a memory bank you must pass the parameter as the start of the bank. e.g..

10 fastwipe start(BNK)

Where bank BNK is a reserved screen bank, if you just want to clear a screen address then substitute start(BNK) for the address of the screen. e.g..

10 fastwipe physic

You may have seen the wipe command in the The Missing Link extension? Well, no we haven’t ripped/stolen the routine, it was mine in the first place and I sent it to the chaps, I never got credited for it (snarl), anyway.. This new version is even faster (Shove that up your jumper Top-Notch! haw haw!).



Description: This command will allow you to unpack a Degas Elite compressed PC? pictures. You must set up a normal STOS screen bank to hold the resulting unpacked picture.This routine SHOULD work in all three resolutions, but I haven’t tested it yet. Try this small routine:

10 key off : curs off : mode 0 : hide
20 reserve as screen 10
30 reserve as work 11,(length of PC? file)
40 bload "FILENAME.PC?",11
50 elite unpack start(11),start(10)
60 screen copy 10 to physic
70 get palette(10)

This will unpack the picture from bank 11 to bank 10, and then display it on the screen. Once the picture has been unpacked, the palette can then be grabbed in the normal way. Screens can also be unpacked directly to the screen, i.e.

elite unpack start(11),physic

The palette for the picture can then be installed by using the command:

get palette(physic)



Description: This command does exactly the same as the ELITE UNPACK command, except that it will unpack a TINY compressed image.



Description: Again this command is the same as ELITE UNPACK & TINY UNPACK, although this routine will packed an image file saved in the Crack Art format (CA?).


Description: This command is to be used in conjunction with the CA UNPACK command, and will actually create a compressed Crack Art image file from a standard STOS screen bank. ADDR is the source image, ADDR2 is the destination for the compressed image, PAL is the address of the palette data to be used, which will usually be ADDR+32000, and MODE is the pictures screen resolution (0=Low, 1=Medium, 2=High). The value returned is the length of the compressed picture file. This routine should help you sort this out:

10 reserve as screen 10
20 L=ca pack physic,start(10),physic+32000,0
30 bsave "picture.ca1",start(10) to start(10)+L

This routine will compress the current physical screen into bank 10, and then save it. The variable L contains the compressed length of the image file.


Description: The SETPAL command will install a new palette that is located at address ADDR. It is useful for storing large palette changes in a memory bank, and then setting them when every they are needed. The format for the data is just the standard degas format, in that it is 16 words, each word representing the colour 0 – 15.

10 reserve as work 10,32 : mem=start(10)
20 restore 80 : for lp=0 to 15 : read(x)
30 doke mem,x : mem=mem+2
40 next lp
50 :
60 setpal start(10) : wait vbl : end
70 :
80 data $000,$111,$222,$333,$444,$555,$666,$777
90 data $000,$111,$222,$333,$444,$555,$666,$777

This routine will copy some values into memory bank 10, and the set the palette from it.


Description: The BCLS command, will erase a set amount of scanlines on any desired bit plane of the screen. The address of the screen is passed in ADDR, and the number of scanlines to erase is passed in the variable ADDR:

10 bcls physic,10

This will clear 10 scanlines on plane 1 of the physical screen. The other planes of the screen can be selected by increasing the screen address by 2.

+0 = Plane 1
+2 = Plane 2
+4 = Plane 3
+6 = Plane 4



Description: The mirror command is quite powerful, in that it can mirror parts of the screen, in three ways.. Normal, Halved or Doubled. The mirror option is passed in the OPT variable, and can take the form:

1 = Normal
2 = Half Copy
3 = Double Copy

Variable ADDR is the source address of the image, and SYPOS is the source Y pixel offset. ADDR2 is the destination screen address, and DYPOS is the destination Y pixel offset. NUM is the number of lines to mirror. i.e.

10 mirror 1,physic,0,physic,100,32

This will mirror the STOS key box to the middle of the screen… Try putting it into a loop, and see what happens when you move the mouse over it!

STE Commands



Description: This command will set the main volume of the STE sound output to VOL. The input value can take the form 0 – 40 (40 being the loudest).

10 rem ** STE fade out
20 for LP=40 to 0 step -1
30 for LP2=0 to 15 : wait vbl : next LP2
40 dac volume LP : next LP



Description: This command sets the amount of treble that is output from the STE sound. TREB can take the form 0 – 12 (0 = -12dB, 6 = 0dB, 12 = +12dB).


Syntax: BASS BAS
Description: Same as above, but sets the amount of bass instead.


Description: EPLAY allows hardware sample playing on STE machines, or machines that have the extended sound capability. STRT is the start address of the sample, and LENGTH is the length of the sample. SPEED variable sets the replay speed of the sample, which can be:

0 = 6.258 kHz
1 = 12.517 kHz
2 = 25.033 kHz
3 = 50.066 kHz

The MODE variable sets mono/stereo playback of the sample.. 0 = stereo, 1 = mono. And finally, PLAYMODE can be.. 0 = stop, 1 = play once, 3 = loop forever.

Although the sample replay can be stopped using the EPLAY command, I have also added an ESTOP command, that can also be used to stop the sample.


Syntax: ESTOP

Description: This will stop the hardware sample replay interrupt, and stop ANY sample that is playing under STE hardware.


Syntax: X=EPLACE

Description: This command does the same as the SAM PLACE command that already exists in STOS, however, it returns the address in memory that is currently being played by the STE hardware. It can be used for doing all sorts of nice effects including frequency meters or oscilloscopes:

10 rem ** Oscilloscope routine
20 key off : curs off : hide : mode 1
30 :
40 eplay start(10),102400,1,0,3 : rem ** Play sample, looping
50 :
60 repeat : fastwipe physic
70 for LP=0 to 50 : X=peek(eplace)
80 if X>128 then X=X-255
90 X=X/8 : plot LP,100+X,1 : rem ** Plot sample byte
100 next LP
110 wait vbl : until false


Syntax: X=JAR
Description: This command will return if a “Cookie Jar” exists on the computer. If a “Cookie Jar” does exist then true (-1) will be return, else 0. This command is to be used in conjunction with the following command:


Syntax: X=COOKIE(STR$)

Description: This command will read the information on the cookie STR$. STR$ must be passed as one of the official Atari Cookies, otherwise no value will be return. A list of all the Cookies and return values follow:

_CPUThe number here is the decimal value of the last two digits of the processor present in the machine, indicating which CPU of the 68000 family it is: 00,10,20,30. For instance the value 30 represents 68030 processor
_VDOThe high word of this cookie contains a number from 0 to 2 which indicates what type of video shifter is fitted:

0 = Standard ST video shifter
1 = STE video shifter
2 = TT Graphic chip
_SNDHere it is the bits which tell us about the sound hardware. Bit 0 set indicates the presence of the Yamaha sound chip, bit 1 of the DMA sound chip.
_MCHThis cookie also uses the high word, so that the low word can be used for version changes, and the value describes the overall machine:

0 = Standard ST
1= STE
2 = Mega ST
3 = TT
_SWIThis cookie is used to indicate the positions of the configuration switches on Mega STE’s and TT’s. At present these switches are unused.
_FRBThis longword value will be the address of the FASTRAM buffer, or 0 if no FASTRAM buffers are fitted. This cookie is not found on normal ST & STE machines.
10 if jar then X=cookie("_CPU")
20 print "You have a 680";using "##";x;" Processor"


Syntax: X=XPEN
Description: This command returns the x screen position of the STE light pen/gun.


Syntax: Y=YPEN
Description: This command returns the y screen position of the STE light pen/gun.

10 repeat
20 if fire then plot xpen,ypen : shoot
30 until false

That’s All Folks!

Yes, that’s all the commands in this great extension.. So go away and have some fun using them.


You may have noticed that there is an extra basic extension on the disk. Well it’s the follow up extension.. GBP II, and this time it’s going to be deadly. The extension is very much like the blitter extension, being in a very early stage. There is no documentation as of yet (it is currently being written). I will however go over a few of the command within this text file so that you can get the feel of the extension and get to use it a little bit.

The extension itself is primarily for use on STE machines, as most of the command are based around the specific hardware. Although some commands will actually work on older ST machines, but it is not really worth running. The commands themselves range from accessing an Atari powerpad/Jaguar controller (both ports!). Centronics/Parallel joystick routines, screen savers, and hardware scrolling.


Coding and Research : Neil Halliday
Some Commands : Bruno Azzara
Ideas and Design : Neil Halliday, Bruno Azzara & Geoff Harrison
Documentation: Neil Halliday
Demo Programs : Neil Halliday

Other GBP Products

Look out for these other exciting products from GBP, available now from all good public domain libraries.

Slider – a brilliant PD sliding puzzle game with 3 levels.
Rubik’s Magic Strategy – A PD conversion of the brilliant Rubik’s Magic Strategy
Go Moku – A great conversion of the ancient Japanese board game. This program is licenseware, and is only available through Budgie UK.
Playmate II – an interrupt GEM music player that can recognise up to 28 different music formats, and allows you to play music while you work.

Contact Addresses


Neil can also be contacted through the Ad.Lib BBS.. Tel 0191-370-2659. The board is open 24 hours a day, and goes 2400-14400 baud.

Thanks for your interest in this program, and I hope you have lot’s of fun using and exploring the possibilities of STOS basic and GBP.

Neil Halliday and the rest of GBP Software team 1994/1995.

THE END ! ! ! !

About author View all posts Author website

Neil Halliday

Neil started coding in STOS in 1989 just after it was released in the UK.

During those 31 years he has written numerous demo screens, routines, games and extensions, most of which are now lost due to a massive hard disk crash. What remains on floppy disk is still being discovered and posted on the STOS Coders website and stored in the cloud for everybody to enjoy (or laugh at).

Neil is the author of the GBP Extension which added some pretty cool commands to STOS, along with the "Development" extension that enabled enhanced STE functionality, including probably one of the simplest hardware scrolling routines around.

Along with Bruno Azzara, Geoff Harrison and Mike Halliday we had loads of fun back in the day trying to push STOS to it's limits. We are all now enjoying bringing our knowledge to a new generation of STOS Coders.

Leave a Reply

Your email address will not be published. Required fields are marked *