Author - Neil Halliday

Welcome to episode five of our Let’s Remake Manic Miner series. Today we are going to look at making Miner Willy move around the Y axis of the screen. So, in the immortal words of Eddie Van Halen… Might as well jump! Cue cheesy music video, big hair, and flamboyant costumes… Oh, what the hell, here’s a link on YouTube so you can listen while you read!

What is Jumping?

It may seem obvious to you and me, but what actually is jumping? According to Wikipedia…

Jumping or leaping is a form of locomotion or movement in which an organism or non-living (e.g., robotic) mechanical system propels itself through the air along a ballistic trajectory. 

https://en.wikipedia.org/wiki/Jumping

But what does that mean in terms of a game? Well, it’s really dependent on what you are trying to achieve. Looking at the definition above, we can pick out a few words to look at:

Locomotion, movement, propels are all basically the same thing: some form of movement.

Air… hmm, so we know we’re moving through air, but when we’re not jumping, we’re not moving through the air. Does it mean, therefore, that we just stop and float? Of course not; there is that little thing called gravity, that invisible force that causes mutual attraction between all things that have mass. We know about it, but a game doesn’t. But what does gravity do? Simply put, it constantly pulls us down towards the ground until we reach it or land on something that cannot be pulled any further. Like when you are in the upstairs of your house, you are still being pulled towards the ground, but the floor stops you from getting there. Remove the floor, and down you go. If you want to see gravity in action, watch Felix Baumgartner!

A trajectory is essentially a path of movement, and a ballistic trajectory is the motion of an object that is moving in a gravitational field.

Few! We now know, though, that our jump is comprised of a few elements, but we can pick just the two that we need: trajectory and gravity.

Gravity

Gravity is a really easy thing to implement. Effectively, you just pull your character down (increase the Y position) by an ever-increasing amount until you reach terminal velocity. Usually, this is done using a decimal value that steadily increases over time and then gets added to your Y position. To represent this, we need two variables: SPEED and GRAVITY. We constantly increase SPEED by GRAVITY and then add SPEED to our YPOS, thus moving the character down the screen. If we hit the ground or an immovable object of some form, the SPEED variable is reset to zero, ready for the process to start again. A simple jump can then be created by setting the SPEED variable to a negative number to create upward velocity.

You can learn more about jump mechanics in this great YouTube video. It’s not in English, but the subtitles are great, and it does explain jump mechanics very well.

So let’s implement this into our game, shall we? No, we’re not going to do that! It was really interesting to learn how jumping works, but this is not what Manic Miner does. But at least you know how to implement jumping for your other projects!

Manic Miner Jumping

The way Miner Willy jumps is far more prescriptive than the process we described above. When Willy jumps, he travels a predetermined path and keeps going until he hits something or lands on something, in which case he stops. If Willy completes his jump (i.e., his ending vertical position is the same as his starting position), he then falls in a straight line until he hits the ground.

While he is jumping, he cannot change direction, and he cannot jump again. Once you’re jumping, that’s it—you better hope you did it right! Of course, this is one of the skills required to play Manic Miner.

The Jump Parabola

We learned above about the ballistic trajectory, but how would we go about creating something like that without the technique described at the beginning of this episode? The answer is quite simple and quite cheaty, but because of the movement of Miner Willy, it works perfectly for us. We will use a sine wave. Not all of a sine wave, just 180 degrees of a sine wave, which creates an appropriate parabola to work with. To make things easier, though, we will define a full 360-degree sine wave. Let’s add the following code:

@InitMinerWilly
    dim mwan(319) : for xpos=0 to 319 : mwan(xpos) = 1 + ((xpos mod 8)/2) : next xpos
    dim jmps(359) : for ang = 0 to 359 : jmps(ang) = -(sin(rad(ang))*20) : next ang
    MWD = 0 : MWWS = 1 : MWWC = 2 : MWWCC = MWWC : MWXPOS = 16 : MWYPOS = 80
    gosub @SetOFS
    return

There is not much further to explain here, as we have been through for/next loops and arrays, but what about the sin and rad commands?

Now we need to make sure that we adjust Miner Willy’s Y position on the screen by the jump. But, before we can do that, we need to be able to identify the state that Willy is in (hopefully not the state that we find our hero in at the beginning of Jet Set Willy!). Let’s talk a little bit about finite state machines.

What is a Finite State Machine?

This will likely be a new concept for a lot of people, but it’s really very simple. It is a mechanism for allowing something to be in exactly one of an infinite number of different states at any given time. This model can be used for many different types of applications, but it is massively used within gaming, particularly in instance-based languages such as Games Maker Studio from YoYo. They are used, amongst many other things, for indicating the state of a character—what it is currently doing.

Examples of this could be idle, walking, shooting, flying, or, in our case, jumping.

So what we can do is create a series of variables to capture Willy’s state.

@InitMinerWilly
    FALLING = 1 : JUMPING = 2
    dim mwan(319) : for xpos=0 to 319 : mwan(xpos) = 1 + ((xpos mod 8)/2) : next xpos
    dim jmps(359) : for ang = 0 to 359 : jmps(ang) = -(sin(rad(ang))*20) : next ang
    MWD = 0 : MWWS = 1 : MWWC = 2 : MWWCC = MWWC : MWXPOS = 16 : MWYPOS = 80 : MWSTATE = FALLING : MWJMPANG = 0 : MWVSPD = 0
    gosub @SetOFS
    return

We’ve defined two variables, FALLING and JUMPING, which have different values. We’ve then created a new Miner Willy variable, MWSTATE (Miner Willy State), so we can determine what our hero is currently doing. By default, because of the effect of gravity, we say that the default state of Miner Willy is falling.

Finally, we’ve created MWJMPANG (Miner Willy Jump Angle) so we know at what position in the jmps Miner Willy is currently in, and finally MWVSPD (Miner Willy Vertical Speed) so we can ultimately make Willy drop to the floor (this is simulating our gravity, if you like). We’ll use this later on, but it’s better to get the definition out of the way.

We’ve got our different states, and we’ve assigned the default to Willy. Our next task is to actually make Willy jump. This happens when the fire button on the joystick is pressed, so we need to make a small amendment to our joystick routine, but there is also some setup that we need to do, such as signaling that Willy is jumping, etc. Let’s create a new subroutine first.

@StartJump
    MWSTATE = JUMPING : MWJMPANG = 2 : MWVSPD = 0
    return

As you can see, we are setting MWSTATE to be JUMPING, setting our current jump angle (MWJMPANG) to be 2, and resetting the vertical speed (MWVSPD) so that we are not moving vertically – We’ll explain that later on!

Let’s read the joystick fire button and call the @StartJump subroutine.

@ReadJoystick
    JL = jleft : JR = jright : JF = fire : JSTCK = (JL or JR)
    if JF then gosub @StartJump
    if not(JSTCK) then MWSPD = 0 : else MWSPD = MWWS : if JL then MWD = -1 : gosub @SetOFS : else MWD = 0 : gosub @SetOFS
    return

Nothing is going to happen if we run our routine now, because we are not using any of the new variables we have just created. So let’s affect Miner Willy with our jump logic.

@DisplayMinerWilly
    if MWSTATE = FALLING then MWVSPD = 1 : else MWVSPD = 0 : MWJMPANG = MWJMPANG + 2 : MWSTATE = JUMPING : if MWJMPANG > 180 then gosub @ResetJump
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,MWYPOS,mwan(MWXPOS) + MWOFS
    return

We’re saying here that if Miner Willy is FALLING, then his vertical speed (MWVSPD) is 1, so as to move him down the screen. else, we set his vertical speed to 0, increase the jump angle by 2, and set his state to JUMPING. We then check MWJMPANG and if it has reached 180 degrees, we call the @ResetJump subroutine to stop Willy from jumping.

The @ResetJump subroutine looks like the following:

@ResetJump
    MWSTATE = FALLING : MWJMPANG = 0
    return

In this routine, we simply reset Miner Willy’s state to FALLING and clear the MWJMPANG.

Finally, we can use all of the above to affect the Y position of our hero:

@DisplayMinerWilly
    if MWSTATE = FALLING then MWVSPD = 1 : A = MWYPOS : else MWVSPD = 0 : A = MWYPOS + jms(MWJMPANG) : MWJMPANG = MWJMPANG + 2 : MWSTATE = JUMPING : if MWJMPANG > 180 then gosub @ResetJump
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,A,mwan(MWXPOS) + MWOFS
    return

So, you can give that a run, and you will see that Miner Willy now jumps when we press the fire button. BUT… and it’s a big but… You can press fire again while Willy is jumping, and it all goes wonky. Not only that, but you can change directions! Argh! Don’t panic; it’s easily solved. We can just use our state engine on the joystick input routine and bypass some stuff—whoop!

@ReadJoystick
    if MWSTATE = JUMPING then goto @EndReadJoystick
    JL = jleft : JR = jright : JF = fire : JSTCK = (JL or JR)
    if JF then gosub @StartJump
    if not(JSTCK) then MWSPD = 0 : else MWSPD = MWWS : if JL then MWD = -1 : gosub @SetOFS : else MWD = 0 : gosub @SetOFS
@EndReadJoystick
    return

So, what we are doing here is essentially saying: If Miner Willy is jumping, then I don’t want to read the joystick any more and change our speed or jumping variables, so just goto the @EndReadJoystick label instead. Once you’ve jumped, you’d better hope that it was the right jump to make.

Let’s Apply Gravity

We’ve not done anything with our gravity as of yet, so we can do that now. Remember, gravity continuously pulls an object down, so it’s really very simple to implement. Let’s create a new subroutine to apply gravity to our MWYPOS.

@ApplyGravity
    MWYPOS = MWYPOS + MWVSPD
    if MWYPOS > 80 then MWYPOS = 80
    return

Literally, all we are doing here is adding Miner Willy’s vertical speed to his Y position. By doing it this way, we can simply change the value of MWVSPD to 0 when he hits something. I’ve put a quick if statement in there on the MWYPOS variable just so that we can stop Willy from falling off the bottom of the screen. We’ll remove that once we get a background and some collision detection in place.

All that is left is to apply the gravity:

@DisplayMinerWilly
    gosub @ApplyGravity
    if MWSTATE = FALLING then MWVSPD = 1 : A = MWYPOS : else MWVSPD = 0 : A = MWYPOS + jmps(MWJMPANG) : MWJMPANG = MWJMPANG + 2 : MWSTATE = JUMPING : if MWJMPANG > 180 then gosub @ResetJump
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,A,mwan(MWXPOS) + MWOFS
    return

And there we go! Miner Willy walks and jumps now! Yippee.

And so, we’ve reached the end of another exciting episode of Let’s Remake Manic Miner. As always, the source files can be found in the GitHub repository.

In our next episode, we will start to look at how to build an environment for Miner Willy to walk around in. Until then… Happy STOSing.

Welcome to episode four of our Let’s Remake Manic Miner series. Today we are going to look at animating Miner Willy as he moves around the screen.

How We Normally Do It

Animating characters is usually straight-forward; in fact, you could say it’s probably one of the easiest things you can do with your sprite. Effectively, you just need to cycle around a series of images while your character is moving, and then when the character stops, you stop cycling around the image. If the character changes direction, you reset the animation frame for the start animation of the new direction.

So, let’s do that, shall we? No, we won’t do that, because that is not how Manic Miner works, it does something that I never really thought of before, but it’s quite a clever trick that Matthew Smith did, and it saves a bunch of processing time too! Let’s ask ourselves…

What Would Matthew Smith Do?

I’ve spent long hours looking at how Miner Willy is animated, and it had me puzzled for a while. I tried various different things, but I could just not get it to look right. After a bit of a break and doing some other things and thinking, my mind came to a simple conclusion: Willy’s animation frame is tied to his X position on the screen. This is why he keeps animating when jumping, and also why, no matter how you’ve moved about on the screen previously, you always end up with the same frame of animation when Miner Willy is in the same position.

You can try this out for yourself by playing the Central Cavern level and walking left to the brick wall. Miner Willy will stop mid-walk and not animate any further. Move around the screen, jump, do random things—when you walk back to the left, the frame of animation is always the same! Try some other things too, such as walking off the first platform. Miner Willy will always be in exactly the same frame of animation. If we were to use the standard method as described above, this would most certainly not be the case. Therefore, his animation frame is tied to his X position!

Now, this sounds like a bit of a cop-out, but in fact, it’s absolute genius! If you base the character’s animation frame on their current X position, there are no complex animation calculations such as counting frames or resetting when you change direction—none of that! Therefore, you are saving lots of CPU instructions and making your game run faster, which, when working with something like the ZX Spectrum, the more you can squeeze out of the CPU, the better. So, when I say genius, that’s exactly what it is.

How Do We Do This In STOS?

So, how do we replicate this within STOS?  Well, it’s really pretty simple really, we just define an array that holds the correct animation frame to show at the different horizontal positions on the screen. We know that our Miner Willy sprite has just four frames of animation, and we know that sprite #1 is walking to the left. Therefore our Miner Willy sprites are as follows:

So, what we can do is predefine which sprites to use and store them in an array so that we don’t have to be calculating which frames to be using all the time. We can then use the direction variable (MWD) to adjust the frame accordingly by an offset. The less calculations we have to perform per frame, the quicker our game logic will run.

Let’s modify our initialisation routine so that we precalculate the frames that represent each X position on the screen.

@InitMinerWilly
    dim mwan(319) : for xpos=0 to 319 : mwan(xpos) = 1 + ((xpos mod 8)/2) : next xpos
    MWD = 0 : MWWS = 1 : MWWC = 2 : MWWCC = MWWC : MWXPOS = 16 : MWYPOS = 80
    return

We’ve introduced some new commands there, so let’s walk through them and determine what they are doing.

Our MWAN array now contains the appropriate animation frame to use based on the X position on the screen. We now need to update our sprite command to make sure we are using the appropriate frame.

@DisplayMinerWilly
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,MWYPOS,mwan(MWXPOS)
    return

Let’s build and run our project to see what we have. If you move your joystick left/right now, you should see Miner Willy walk – look at him go! But, one major draw back, he’s always facing to the left. That’s because our frames of animation we have calculated only register frames 1 to 4. We need a way to make him face to the right. Remember that MWD variable we created previously? That’s where this comes in, because we can now use that to create an offset to point to the correct animation frame.

We could do some complex mathematics here to transform the frame number to the right place, but complex maths means more processor time, so let’s just keep it simple and quick instead. We will create an offset flag that holds a number that needs to be added to the frame. If Willy is walking to the left, then the offset will be 0. If Willy is walking to the right, then the offset will be 4. When we add this offset to the animation frame number, Willy will be facing in the correct direction. Ok, so let’s make a few code changes:

Firstly, we create a new subroutine called @SetOFS, this is what we will use to set what our frame offset should be, using the MWOFS (Miner Willy OFSet) variable.

@SetOFS
    if MWD = 0 then MWOFS = 4 : else MWOFS = 0
    return

next, we need to call this new subroutine from a couple of places.

@InitMinerWilly
    dim mwan(319) : for xpos=0 to 319 : mwan(xpos) = 1 + ((xpos mod 8)/2) : next xpos
    MWD = 0 : MWWS = 1 : MWWC = 2 : MWWCC = MWWC : MWXPOS = 16 : MWYPOS = 80
    gosub @SetOFS
    return

@ReadJoystick
    JL = jleft : JR = jright : JF = fire : JSTCK = (JL or JR)
    if not(JSTCK) then MWSPD = 0 : else MWSPD = MWWS : if JL then MWD = -1 : gosub @SetOFS : else MWD = 0 : gosub @SetOFS
    return

As you can see on the second section of code, we are calculating the new offset when MWD changes.

And finally, we now need to utilise the offset on the Miner Willy sprite.

@DisplayMinerWilly
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,MWYPOS,mwan(MWXPOS) + MWOFS
    return

Let’s build our project and see what we have. Success! Miner Willy is walking in the direction he is facing. Well, he’s running actually, so we will need to slow that down a little bit, but we can tackle that later.

For now, that’s the end of this episode. Check in for the next episode where we will be making Willy jump. Remember, you can find the various episode source codes and assets on the Manic Miner Github page.

Displaying Miner Willy

So, we want to make Miner Willy move then? Well, we can’t do that unless he’s shown on the screen. In our previous episode, we created our game loop, and so we need to make an adjustment to that loop in order to call our display routine for Miner Willy.

repeat
    gosub @DisplayMinerWilly
    gosub @WaitVBL
until false

For our subroutine, we will keep it simple for the moment and just place Miner Willy at a specific location on our screen.

@DisplayMinerWilly
    sprite 1,100,100,1
    return

We have already learned about the label and the return command in previous episodes, but what else are we doing here? We’ve introduced a new command:

Let’s transpile our program, load it into STOS, and run it. We should simply get Miner Willy, frame 1, at position 100,100 on the screen. It works! But now we need to make him move.

A Moving Willy

We need to define some form of mechanism to make Miner Willy move. In the ZX Spectrum version of Manic Miner, this was done purely with keyboard input. We could do the same for our game, but for ease, I’ve decided to use the joystick to control our hero. We therefore need to read some input from the joystick, which STOS has some handy routines to deal with.

Before we can do anything in terms of joystick input, we need to do some setup so we can control the position of Miner Willy. We always need to know his current x and y positions on the screen so that we can increment them as required for walking and jumping. We need to do this in a series of variables, which we will need to initialise before trying to display Miner Willy. There’s also some additional setup that we will do too but won’t use for the moment; this is to cater for the fact that we are not going to use either the sprite movement or animation routines that are built into STOS.

Let’s create a new subroutine for initialising everything we need for Willy.

@InitMinerWilly
        MWD = 0 : MWWS = 1 : MWWC = 2 : MWWCC = MWWC : MWXPOS = 16 : MWYPOS = 80 : MWSPD = 0

There are a fair few variables there! I’ve tried to use logical naming conventions for them, but let’s go through them one by one and describe what they are used for:

We now need to make a call to our initialisation routine and also update our sprite command so that we are not forcing Willy to always be at position 100,100 on the screen. So we do that after we have loaded our assets. We may need to move this later on, but it serves it’s purpose here for the moment.

gosub @LoadAssets
gosub @InitMinerWilly

Now, we need to update our sprite command so that we are using the newly created MWXPOS and MWYPOS variables.

@DisplayMinerWilly
    sprite 1,MWXPOS,MWYPOS,1
    return

OK, let’s transpile our program, load it into STOS, and see what we have. You should now see that Miner Willy has moved positions. He’s further to the left and higher up the screen. That means that our sprite positioning with MWXPOS and MWYPOS is working, and we can begin to manipulate those with the joystick input.

Joystick Input

To get Miner Willy to move, we need to read the joystick data stream. STOS provides joystick input commands, so we will use them. Let’s go ahead and create a new function that we can call whenever we want to read the joystick.

@ReadJoystick
    JL = jleft : JR = jright : JF = fire : JSTCK = (JL or JR)
    return

Let’s breakdown the calls that are being used:

The above is simple enough, but why are we storing the state of the joysticks in variables? Well, we do this for a couple of reasons. Essentially, the input from the joystick is a continual stream of data being thrown at STOS. If we used the direct joystick commands throughout our source code, we could end up with some strange results as the joystick states may be different whilst our code is executing. For example, making Miner Willy do something at a point in which he shouldn’t be doing it. In addition to this, we would force STOS to perform additional reads and therefore consume more processor time at each call. By storing the values within variables, we only read the joystick once per VBL and therefore save a bunch of processing power.

Now we need to make sure that we call the routine to get the values from the joystick. We must do this within the game loop, so add the following code:

repeat 
    gosub @ReadJoystick 
    gosub @DisplayMinerWilly 
    gosub @WaitVBL 
until false

Applying Movement to Willy

We’ve got Miner Willy all set up now, and we have our variables available for changing his X and Y positions on the screen. We’ve also started to feed joystick input into our JL, JR and JF variables. Now that we’ve got that in place, we need to make Miner Willy move. Earlier, we created the MWSPD variable to hold the current speed at which Miner Willy is walking. It is this variable that we manipulate in order to signal that movement is to occur. We do this within the @ReadJoystick section of code.

@ReadJoystick
    JL = jleft : JR = jright : JF = fire : JSTCK = (JL or JR)
    if not(JSTCK) then MWSPD = 0 : else MWSPD = MWWS : if JL then MWD = -1 : else MWD = 0
    return

Let’s break down that new line of code that we have just added in:

We now know in which direction Miner Willy is facing (MWD) and at what speed he is moving (MWSPD). This information can now be used to update the MWXPOS variable accordingly. We’ll add this code into the @DisplayMinerWilly section.

@DisplayMinerWilly
    if MWD = 0 then MWXPOS = MWXPOS + MWSPD : else MWXPOS = MWXPOS - MWSPD
    sprite 1,MWXPOS,MWYPOS,1
    return

Transpile the code and see what happens. You should have a Miner Willy that now moves left and right on the screen using the joystick.

That’s all for this episode, folks. In the next episode, we will look at animating Miner Willy using a very interesting technique!

In the meantime, you can find the various episode source codes and assets on the Manic Miner Github page.

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 publish 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 objects 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 enemies and deadly obstacles 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 objects that you collect, and bonus points are awarded for the amount of 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 colour 10×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 will need to 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 & Floors

There are various wall & 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 dissolve 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!

Baddies

There are various different types of baddies, and they are all of varying size too. The one common factor of them is they all have 8 frames of animation (4 left & 4 right) and either move up/down or left/right. They move on a set pattern, but are not necessarily linked to the floors they are placed on. Each screen has a varying number of baddies. If Miner Willy hits a baddie, a life is lost and the level resets back to the beginning.

Obstacles

As with the walls, all obstacles 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.

Collectables

For Miner Willy to progress to the next cavern, all the flashing collectable objects need to be picked up. All collectables 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 made use of the ZX Spectrum foreground and background flash function – 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.