By Jeff Fulton

In this STOS Tutorial we cover setting up a development environment in the Hatari Emulator, and do a simple Blitter Hello World example.

Many people would like to to start programming games on retro hardware but have no idea where to start. This was me just a few months ago. I scoured every Atari ST magazine looking for Tutorials and documentation on GFA Basic 3.6 and STOS to see which would be the right environment to start working on some game samples and demos targeting the Atari STE. While I think GFA, C, and Atari Game Tools all look like great ways to make games, I just have not yet been able to wrap my head around how to get them to work the way I want to (yet). I have the most documentation for GFA, but very little of it is for targeting the STE series of computers, especially the Blitter chip, hardware scrolling, and Digital Stereo sound capabilities.

I am sure I will explore these and Assembly language in the future, but for now I have chosen to explore the speedy final edition of Compiled STOS using both the Blitter/STE extensions and the Missing Link Extension. The Missing Link Extension doesn’t specifically target the STE or Blitter, but instead greatly speeds up STOS Sprite, Text, and other operations on all ST machines, even the original stock STF and STFM machines.

To get started we are going to look at a way that everyone can get going with STOS using the same environment. Because of this, I have chosen to use the Hatari Emulator and a local GEMDOS hard drive on my laptop rather than using my STE hardware.

Note: This setup works fine on my Ultra Satan and on an IDE Image that I created to use in am emulator also.

One reason to use the GemDos drive is so we can later move to a Windows/ Mac / Linux code editor called VSCode that has an extension written by the geniuses at https://StosCoders.com for STOS development. When you start to create larger STOS programs you will find yourself limited by the small editing window and line numbers in the STOS editor. The VSCode extension solves this and much more. We will get to that in time.

Download the STOS Hard Drive Folder

The first thing you will want to do is unzip the file below file. It contains a folder that should be the root of a GEMDOS hard drive. You can place it anywhere on your local hard drive. Just remember where you put it =)

Download my full STOS install folder

When you open up the zip the contents will look like this:

I have taken the contents of the STOS disks and have compiled them together to create a set of folders that we can start using right away.

Inside the COMPILER and STOS folders I have added extensions for Missing Link, STE/Blitter, Maestro and a couple more we might get to in these tutorials.

If you need a refresher on STOS or have never used it before, you should probably download the manual from AtariMania.com or Archive,org and the Game Makers Manual (AtariMania.com) . Both of these will get you familiar with all that the main STOS package offers, what these folders contain, and other information. I will be covering all lines of code we write in as much detail as I can, so there is no need to have those read to do the Tutorials. It can’t hurt to have more knowledge though. I don’t profess to be a complete expert on all areas of STOS right now either, but by the time this tutorial series ends we will all have an extra level of comfort in making STOS games for all ST machines and especially the STE machines.

Note: There are other great STOS resources you might want to check out before continuing: (these are where I collected most of my knowledge and downloads for STOS)

EXXOS STOS Pages

STOSCODERS.COM

Facebook STOS Coders Group

The TUTS folder is where I will be saving the lessons and files needed for each tutorial. I will be uploading updates to this folder as we go along. First two lessons that we will cover in the first video on the Blitter chip and STOS. Blitter1.bas will be the Hello World example we will use at end of this tutorial. Blitter2.bas will be part of the next Tutorial.

Setting up Hatari to use the STOS GemDos Hard

You should download and install Hatari

You can use EMUTos 1.0 for these examples or any TOS 1.62 or above image that you might find.

You can Find EMUTos 1.0 here.

Specifically, I will be using “etos256uk.img”. This is the STE UK version that will run at 50Hz. I using the 50 HZ version because everything is STOS is created to run at 50HZ. You can run at 60HZ US, but I prefer to run it at the correct speed for the best results.

1. Start the Hatari application and press F-12. This will bring up the menu screen.

If you are new to Hatari, I will give some general steps here to get it setup for our development. We will be saving this off as a separate configuration file in Hatari so we can use always be sure to have the correct setup when we want to start developing in STOS. We will do that after all of the configurations are complete.

If you have previous Hatari configurations and want to have them, you should click the [Save config] button now. Follow the instructions to save your old config.

2. From this Menu, select the [ROM] button and select the TOS image you want to use. And click on [OK] and then [Back to Main Menu]

3. Select the [System] Button from the main menu and make these selections

Select STE. I always select Blitter in ST mode, and that may help in later tutorials. It’s not necessary for our STE Tutorials, so that’s is up to you. Leave everything else as it is in the picture below.

Click the [Back to main menu] button

4. Select the [CPU] Button and make sure it is set at 68000 / 8Mhz. Leave everything else the same as you see it. I have made a couple modifications from the defaults that seem to help with keeping Hatari running smoothly.

Press the [Back to main menu] button

5. Memory setup. I like to have gobs of memory available, and you will see that as we start using more samples and extensions, memory will become tight in 1MB or lower. Our first demos will most likely run on any STE machine, but having more memory will allow us to do a lot more in later tutorials. 4MB is the Max we can use with the STE so 4MB it is.

Selected 4MB and click on the [Back to Main Menu] button

6. Hard Drive selection. This is where we set up the GemDos “STOS_harddrive_for_tutorials” folder you downloaded earlier. Make sure you have unzipped that folder in to a safe spot on your local hard drive.

Like this:

This is in windows, but it should be the same for any file system. It is not important where you put the the files, just that when we select the folder these directories are in the root of the GemDos Hard Drive.

From the Hatari Main Menu click on the [Hard Disks] button. A screen similar to this will pop up. I have no drives selected. For now, if you have any, eject them.

Now we will choose the folder you downloaded and unzipped as the GemDos Hard Drive. Click the [Browse] button in the GEMDOS section and select the folder that contains the files and subfolders from the zip.

When you select the folder it will show the contents. The Basic208.tos file should be in this folder along with config.bas and autoexec.bas (as seen above along with protect.bas and desktop.inf)

Click the [OK] button.

Notice that the GEMDOS hard drive will now point to the folder we selected. Make sure that “Write Protection” is turned off.

Click the [Back to main menu] button.

7. Next we are going to save this configuration. I save a lot of different configuration in Hartari for doing videos and testing out games. The normal save file is called “hatari.cfg”. You can use thiat name and it will default to this STOS setup every time you start up Hatari. I’m not going to do that, I’m going to save a new config called “hatari_STOS_STE.cfg”

On the main menu, click on the [Save Config] button. On the next screen, edit the file name to be the config name you would like to use.

The file name editing is done at the top next to the “file:” prompt. It’s easy to miss. You can see that I have changed “hatari.cfg” to “hatari_STOS_STE.cfg”.

Click on [OK] and we are ready to reboot the emulator

Rebooting Hatari

Make sure you select the (0) Reset Machine option on the Hatari main menu screen and click the [OK] button. This will reboot the emulator into the GEM Desktop.

The desktop will come up and look similar to this is you are using EMUTOS

Set the MOUSE to be contained in the Emulator Window
One of the things I dislike about Hatari is how the mouse easily leaves the ST/GEM screen when it gets to the edges. It makes working on anything that uses the mouse very difficulty on the emulated ST.

To Fix this, Press the RIGHT ALT key and the M key at the same time. Now you will need to press F-12 (or the RIGHT ALT key and the M key again) to use the mouse with the other applications. You will find working on the ST much easier now. If you don’t like this, just press the RIGHT ALT key and the M key to release the mouse.

I’m going to set up a few defaults that will make working with the STOS a little easier. First, I am going to set the resolution to Medium and open up the C drive.

Depending on the version of TOS you are using, you will change the Medium resolution either with OPTIONS–>Change Resolution or OPTIONS–>PREFERENCES–> Medium

When that is complete, I set the text of view of the files to be text with View–>Show as text

Next I double-clicked on the C Drive, and opened it wide and long to display as much of the root of the hard drive as passible. It came out looking like this:

Now save the desktop with OPTIONS–>Save Desktop and we are ready to run STOS!

Running STOS

Double-Clock the BASIC208.TOS program file and STOS will load. I have configured the Autoexec.bas file to do a couple things like load the compiler and make the MissingLink extension the registered version on load. We won’t get into the details now, but you can always load it up in STOS (it is .bas program) and take a look. After the screen flashes a couple times, it will look like this:

Getting into STOS

I won’t be covering the full STOS editor in these tutorials, but I will cover anything that we need to use, so while I recommend that you download and have the manual ready incase you come up with any questions, it won’t be necessary unless you want to start exploring on your own, which is highly recommended. We are going to jump right into a Blitter hello world simple program to end this Tutorial and give you a head start.

Blitter Hello World Tutorial (blitter1.bas)

Even though above I mentioned that you don’t need to read the STOS manual to get started, you should have the chapter on the editor handy just in case you want to get to know any commands I don’t cover or don’t cover in enough details.

I have saved a blitter1.bas file in the TUT folder, I don’t recommend that you load it up and use it. You can, but I don’t learn very well that way, and I also don’t think that I should teach that way either. It’s a cop out and it means you are just running examples rather than typing them in and seeing how they are constructed.

Some credit where credit is due

Before we get started. We are going to be using the Asa Burrows STOS Blitter extension. You can download it and read the instructions at the ESSOS Extension Page. You don’t need to install it as I have already pre-installed it, but if you want the documentation it is available in that download.

Also the first few parts of this Tutorial are modified from a file I found in the STE extension download on my hard drive. I don’t know where it came from exactly because I downloaded A LOT of files when I got started and this showed up in the mix. All I know is that a person named J.J. wrote it and I have modified it for my purposes. It seems to have come from the STOSSER Disk Magazine. Many STOSSER magazines on disk are available at Archive.org and STOSCoders.com. They are an invaluable resource. When I find the issue number and exact name of the author I will give full credit and a link.

Let’s start TYPING!

In the editor, if you find your the cursor is in a strange spot, or just want to re-orient to the top of the edit window, you can type “default” or “cls“. “default” (don’t type the “” marks) will set all of the editor defaults back to when you loaded STOS. It won’t unload any files or anything like that, but it will get a running program out of memory and reset the cursor. The program listing in memory will still be present.

“cls” will simply clear the current window in the current selected resolution. I like “default ” better as it will take a mode 0 program (low resolution) and reset the screen back to Medium (mode 1) for editing purposes.

So, what are we doing to do as a Blitter “hello” world? We are going to load a screen and display it using standard STOS commands and then use the MOST SIMPLE Blitter command to clear the screen. That’s it. I’ll add the display of “Hello World” to the program (it’s not in the program on the hard drive folder), but the fun is in the Blitter. Of course this isn’t a lot of fun yet, but getting your feet wet is all about making small advances.

NOTE: I just saw that if you choose the UK TOS that the ” key is not next to the enter key on the emulated ST, but actually the SHIFT-2 key where the @ is. You can easily change out to the USA TOS if this bothers you, but make sure to set the machine to run at 50HZ

Here is a screen shot of what we are going to type in. I will go through this line by line after you have had a look.

Listing:

10 rem stosser blitter example by J. J.
20 rem simple screen clear
22 mode 0: hide: flash off: curs off
25 reserve as screen 10
30 load "back1.pi1", 10: get palette(10): physic=10
40 wait key
50 blit cls pjysic
60 default
70 print "Hello world"

Lines 10 and 20
These are REMark statements that don’t do anything other than give us information about the program

Line 22
This line sets up the screen and defaults for running out program.
mode 0 – this sets the program to run in low resolution
hide – this hides the mouse. As you can see, you can put multiple STOS commands on a single line separated by a colon “:”
flash off – one of the colors in the 16 color palette is set to be flashing through all of the colors unless you turn this off. See the manual for details.
curs off – thus turns of the blinking edit cursor

Line 25
reserve as screen 10 – This allocates one of the STOS memory banks to hold a screen that we will load in. See the manual for a full description of memory banks.

Line 30
load “back1.pi1” – this loads in a background graphic., This graphic is in the TUTS/STE folder where the blitter1.bas and blitter2.bas files are. This is where you will save this program so it will be able to find this file. This file will NOT be embedded with the basic program so it will always need to be in the folder you specify when the program is run. See “reserve as data screen” in the manual for a method to store loaded screens with the .bas file.
get palette(10) – This command will change the current palette of 16 colors to those of the loaded in screen. If you did not do this, the screen would have the standard STOS palette mapped to it when the program is run, and it will look UGLY.
physic=10 – Normally in STOS “physic” will be the memory location of the screen currently displayed. So, we loaded a screen into memory bank 10, but to actually display the screen we have to so something with it. The most simple thing we can do with a loaded in screen is just make the “physic” screen memory address = the memory bank and it will be displayed to the user.

Line 40
wait key – The wait command. It has many forms and you should look up more details on it in the manual. This version waits to any key to be pressed and then moves to the next line.

Line 50
blit cls physic – All this does is clear the screen, or does it? At its core, yes, it simply clears the screen. But to the computer it does magic. Where the regular CLS command actually needs to go into every screen memory address and set it to 0 using up valuable CPU time, this command does the same thing with the Blitter in a faster way and independent of other running code. Now, We don’t have any other code running, so the effect is pretty minor, but later, we can use this to great effect.

Line 60
default – This sets back all of the editor defaults.

Line 70
print “hello world” – What’s a hello world program that doesn’t actually print “hello world” at the end?

Here is the code running before a key is clicked:

Here is what it should look like after you press a key while this image is displayed.

Note: I found this image on a STOS disk, I love it, but it’s It is not mine. I think it was delivered with Degas Elite or STOS.

Some simple editing help:

list – will list you program

run – will run your program

CTRL-C – will break you program while running it.

Saving your program

1. Make sure the cursor is on a blank line and press F5 or use the mouse and click on the f5: save”*.bas” in the editor menu.
2. Select the C drive and the TUTS/STE folder.
3. You will see blitter1.bas there already. You can save over it or give it a new name. Make sure to add the .bas at the end.
4. Make sure this is the same folder as the “back1.pi1” file

Running the program.

After you have saved it in the same folder as the back1.pi1 (GEMDOS c:\TUTS\STE\blitter1.bas) you should be able to run the program and see the same results

That’s all for the first Tutorial, we will cover more fun Blitter zarjaz in the next tutorial.