Author - Neil Halliday

For me, making sure our code is structured correctly is an important part of programming. STOS is a very unstructured language; it doesn’t have any kind of function or procedure that we can create to make stand-alone “black box” routines. As a result of this, every variable that is created is global in scope; in other words, if you define a variable, ALL of your program can access that variable.

One of the reasons I created the VS Code STOS extension was to bring at least a little bit of structure to the code structure of STOS. Of course, this is only applicable when viewing the code within the VS Code environment. Once the code is output in the STOS format, it’s pretty ugly, but we really don’t need to worry about that. We can also annotate our code better within VS Code by using the non-transferred comments that only exist in our code editor, and not the final STOS basic file.

So, what we will try to do during this series is create as clean a code set as we can, with lots of comments to explain what is going on for you lovely people that are reading. Hopefully, this will enable you to take the code and do something else with it. I don’t mind what you do with it, but please don’t just distribute it and call it your own. Make sure you create something new and exciting, and all I ask is that you give me a little credit—that’s all.

In this section, we will just do some simple preparations for our main program code. Nothing clever, just the usual housekeeping that we need to do for a STOS program to run how we want.

Creating our Project

This is a simple enough process. Using the command pallet within VS Code, use the function called STOS: The Game Creator: STOS New. This will launch a series of questions about your new STOS project and where to save it on your computer. You can follow detailed instructions on how to do this on the overview page.

Once you’ve got your project created, you will have your main.stos file, which is the main program file that we will be using to write our code.

You will also need to create an area somewhere that either STOS on your ST or your emulator has access to. This is where you will need to copy the project assets and, ultimately, your build.asc file so you can test it out.

Setup Code

When you start a new STOS project in VS Code, you get the initial comments section at the top of the code, just as a reminder that it was me that created the program. So we’re going to remove that and add our first comments as a description of what the project is.

rem *** Manic Miner - STOS Basic Recreation
rem ***
rem *** Written by Neil Halliday / STOS Coders
rem *** June 2023
rem ***
rem *** main.stos : main program file 

So what’s going on there?  Well, the rem command is short for “remark” – in other words, it’s a comment. Having rem on a line of code means that everything after that command is regarded as just a comment and is not any kind of executed code. Even if you had valid code after the rem, it would still be treated as a comment until the next line.

The rem command is a valid STOS command, and is transferred to our final STOS program code, and will be visible within the listing within STOS. We will also be using other types of comments that will not be transferred to STOS, which will be explained later on.

Screen Setup

Now that we have our comments done, we will do some basic setup of the screen. This is to setup how STOS controls the screen and switch off some of the STOS elements that are not required when running a full-screen, low-resolution game.

key off : curs off : click off : flash off : mode 0 : hide on : auto back off : anim off : synchro off
palette $000,$777,$005,$007,$500,$700,$504,$707,$050,$070,$055,$077,$550,$770,$555,$777

Not crazy code, but let’s explain what each of the commands do.

Our second line of code sets the colour palette of the screen. It is simply a list of colours in colour number order, starting with colour 0 (the background and border colour). You don’t have to specify all the colours when you call the command, but you always have to specify them in the correct order. Note: The standard palette command in STOS is not compatible with the STE, so your number ranges here have to conform to the standard ST 512 colour palette numbers ($000 to $777).

Loading Our Assets

What are assets? They are the things that we use within our program, such as sprites and sound effects. They are loaded into STOS memory banks for use during the program’s execution. Lots of programs perform data loads at different points in the game to conserve memory, but as our program is going to be super small anyway, we will just load them upfront. We’re targeting a 512kb ST for this program, so if we start to run out of memory, we can refactor this bit, but we should be fine.

To cater for any refactoring that may be required, we’ll put our loading of assets code in a separate place. We already know that we don’t have procedures within STOS, so we will do the next best thing. We will use a VS Code label and create a subroutine. Now we can call it whenever we want, from wherever we want.

It’s not a perfect way of doing this, but it’s the best we have, and it works well for my needs.

@LoadAssets
erase 1 : load "MANIC.MBK",1
return

We now need to make a call to our @LoadAssets subroutine. This is done using the STOS gosub command, and we can make a call to that at the beginning of our program. So, we add the line to the top of our program after the call to the palette command.

gosub @LoadAssets

And that’s it! We’re done for now. We have our screen setup, and we have our assets loaded. If you want, you can transpile the program, load it into STOS and run it. You won’t get much out of it other than a blank screen and an “OK” at the bottom, but at least you know it’s working.

The Game Loop

Probably the single most important element of any game is it’s gameplay loop. This is the section of code that is continually executed during game play and allows us to control, well, everything. If we want to create a game that is as flexible as possible and easy to understand what is going on, I highly recommend making your game loop as simple as possible. I approach this by writing specific sections of code that perform specific game logic tasks. With a language like STOS, this can become quite messy, but using the VS Code development environment really helps us here. So, let’s create our game loop.

repeat
    gosub @WaitVBL
until false

Pretty simple right? Well, yeah it will be at this point in time, but as you can see, I’m making a call to the @WaitVBL subroutine. By using this technique, we can make our game loop very simple and add new subroutines and call them from our game loop without making things ugly in terms of code. So, what’s going on in our game loop?

Now we need to put the code in place for our @WaitVBL subroutine.

@WaitVBL
screen swap : doke $ff8240,$222 : wait vbl : doke $ff8240,$000
return

So why do we change the colour of the border before and after the wait vbl command?  Well, this is a clever little trick that let’s us see how quickly our game is running. The border will be black before all our routines are called, and it will then turn grey for the amount of time that it takes for the vertical blank to return to the top of the screen. The larger the section of black, the more CPU time is being used to perform our code.

The Atari ST in low and medium resolutions run at either 50hz or 60hz depending on where you are located in the world. Therefore, the VBL returns to the top of the screen either 50 or 60 times per second. In other words, the screen redraws at 50 or 60 frames per second. Most games on the ST run at half this speed, and it’s quite rare to actually find a game that runs at full frame rate on a standard ST. Our aim is to make sure everything runs in a single VBL; however, this is particularly hard to achieve when writing programs in STOS. But let’s see what we can do. If your area flashes a lot, it’s likely you are over a single VBL, whereas if the grey colour is solid – good job, you’re running at 50/60 frames per second!

That’s All For Today

That’s all that we are going to cover in this section. Join us in episode three, where we will look at getting Miner Willy to walk and jump.

So, what is Manic Miner?  Perhaps you have been living under a rock, or perhaps you are just not old enough to remember the game that changed how we view platform games. For those who don’t know what Manic Miner is, let me explain…

Manic Miner is a platform-based game written for the ZX Spectrum by a [then] 16-year-old Matthew Smith and published by Bug-Byte in 1983. It was republished later in the same year by Software Projects, a company set up by Matthew, Alan Maton, and Colin Roach. Although Matthew worked as a freelance developer for Bug-Byte, an oversight in his contract enabled him to take Manic Miner with him when he left – ooops! There is a fantastic documentary on Matthew Smith, produced by Kim Justice, on YouTube. I highly recommend you watch it.

Inspired by Miner 2049er, which was published for the Atari 8-bit family in 1982, Manic Miner has been called one of the most influential platform games of all time. It has been ported to many home computers, consoles, and mobile devices.

To get a more full flavour of Manic Miner, check out the full walkthrough video on YouTube published by RZX Archive. You might want to turn the volume down after a few minutes to save your ears from bleeding! That said, Manic Miner was the first ZX Spectrum game to feature in-game music combined with sound effects while you played!

Game Play

You control Miner Willy as he attempts to escape from 20 different caverns by collecting various flashing items to activate the exit portal. Once the portal is activated, you must jump into it to progress to the next cavern. All this must be done before your oxygen supply runs out and while avoiding various deadly obstacles (known as nasties in the game) and enemies (guardians) that wander around the caverns along predefined paths. Once you have successfully traversed all 20 caverns, the game starts again from the beginning. Scoring is based on the items that you collect, and bonus points are awarded for the amount of remaining oxygen you have when you reach the portal. An extra life is awarded for each 10,000 points scored.

Deconstructing the Game

As with any game you want to create, you need a plan. In our instance, this process is a little easier because we already have a finished game that we can reference. But we do need to break the game down into it’s component parts so we understand what we need to do and can identify any challenges that we may experience during the programming. From this, we can plan our STOS activities and hopefully cater for any hurdles before they become problematic. There’s nothing worse than getting part way through something and realising “Oh crap! How can we deal with that?” and having to refactor a load of stuff.

Gameplay Graphics

Let’s have a look at the Manic Miner graphics and how we are going to use them.

Miner Willy

Our hero is a fairly simple single-color 16×16 sprite with a total of 4 animation frames to cover walking and jumping in one direction. What is going to be really interesting about the Miner Willy sprite is the hot spot positioning. Manic Miner has some pretty serious pixel-perfect jumps that need to be made. I hope we can replicate them appropriately.

STOS has a minimum sprite width of 16 pixels, so we match in this respect. We will therefore define Miner Willy as a 16×16 sprite, and it will take the first 8 sprites in our STOS sprite bank. Four sprites for walking to the right, and four sprites for walking to the left. There are no individual jumping sprites, as they are just the same walking sprites with a vertical movement.

His starting point in the game is usually the same, regardless of the level, which is 16,112. There are a couple of levels where this changes, but it’s not very often.

Walls and Floors

There are various wall and floor graphics throughout the game that stop Miner Willy from walking to certain places within the level; however, the common factor is that they are all 8×8 pixels and follow repeatable patterns. This makes it nice and easy for us to replicate these elements. Something that we need to note is that some floors crumble when Miner Willy stands on them for too long.

We will need to compensate for the fact that STOS can only handle a minimum of 16 pixels wide for a sprite. Not a problem, because although we are going to store these images in a sprite bank, we are going to do something whacky with them later on!

Guardians

There are two main types of guardians in Manic Miner: ones that move vertically and ones that move horizontally. Each cavern is allocated enough memory to hold eight frames of animation. What this means is that Matthew had to be clever in his guardian design. For example, if you have a sprite that is obviously facing left or right, then you can only have one guardian on the level: 4 sprites for walking left and 4 sprites for walking right. Therefore, the levels that have two guardian graphics do not have left- or right-facing sprites.

The guardians are all defined as 16×16 sprites, but in some cases, they do not fill that entire space.

If Miner Willy hits a baddie, a life is lost, and the level resets back to the beginning.

Nasties

As with the walls, all nasties are 8×8 pixels and come in the form of stalactites, stalagmites, cactus plants, and other varieties of nastiness to jump over. One touch of these obstacles, and you lose a life, and the level resets back to the beginning.

Items

For Miner Willy to progress to the next cavern, all the flashing collectable items need to be picked up. All items are 8×8 pixels, and within the game, the foreground colour attribute is rapidly switched to make them flash. We will draw these elements using colour 1, as we can apply a STOS colour cycle without affecting any of the other colours on the screen – bonus!

Exit Portals

Exit portals come in various different styles and are 16×16 in size. They have a simple inverse flash animation that makes use of the ZX Spectrum foreground and background flash functions, so we need to make sure we get the timing of this function correct. As we don’t have a flash function in STOS, we will either need to use a colour cycle or a simple inverse sprite. I’ve opted for a second sprite, as this means that we don’t have to worry about palettes or anything like that for a colour cycle.

Level Breakdown

Let’s break down the different levels that Manic Miner has. This way, we know what we have to achieve. We’ll start with “Central Cavern” (level 1) first of all, and we’ll add to this list as we progress with the episodes.

Level 1 – Central Cavern

Ok, I think we are about ready to start putting some code together. So check out Episode 2 to take a look at how we are going to get things setup.