Sprite (Tutorial)

Sprites were introduced to MegaZeux in version 2.65, primarily as a method of making it easier to implement large object representations in the game (for example, engines for handling a multiple character player or enemies). They include many features such as collision detection, easy drawing, and configurable draw order. Despite being designed to make coding easier, many MZXers avoid their use in favor of more traditional methods such as overlay buffering and hand-rolled collision routines. This is largely out of a perception that Sprites are difficult to use.

Sprite Tutorial

Despite the mystery and trepidation that generally surrounds them, sprites are not that hard to work with and are designed to be easy to use, with the right program model. Two common and effective models, which can be used together or alone depending on the requirements of the engine, are the sprite-layer model and the sprite-object model. The structure of your code will depend on the application and the model being used, but there are some basics to cover first.

The Basics

All sprites, regardless of their function, require some basic initialization and setup before they can be used. First, you need to set aside space on the board (or the Vlayer) for the sprite source image. You don't even have to put anything there yet, some advanced techniques construct the image data dynamically. But you need a block of space that is going to be used for sprite data. Next, all sprites need initialization code somewhere that designates this area.

set "spr#_refx" to XCOORD      These counters specify the x coordinate, y coordinate,
set "spr#_refy" to YCOORD      width, and height of the bounding rectangle for the source image
set "spr#_width" to WIDTH      Replace # with the number of the sprite, from 0 to 255.
set "spr#_height" to HEIGHT    Counter interpolation is acceptable and in fact common for this.

Finally, all sprites need to be placed somewhere in order to be viewed. While "spr#_x" and "spr#_y" counters do exist, and they can be written to place and move the sprite, we recommend you treat them as read-only and use the "put" command for readability and clarity of purpose:

put c?? Sprite # at X Y        # is the number of the sprite to be placed, as a parameter.  Can be a counter.

Exercise 1.1: Making a sprite based player

A common application for sprites is to have all actors in the game, including the player, be represented by sprites. This lends itself well to a sprite-object model, but we'll come to that later. Our first exercise will be to make a player sprite that can be moved around with the arrow keys.

1. First, start editing a new world, and draw a customblock smiley face on the board. It doesn't really matter what it looks like, or where it is, but for the sake of example put it at (80,0) off the right edge of the screen, and make it 3x3 characters large.
2. Create a new robot called "sprite" to handle the sprite drawing and moving code. I like to put my control robots in a horizontal line starting at (1,0), but again, it really doesn't matter. The very first line of the robot should be "lockplayer", just to keep the player from moving around.
3. Let's use sprite 0 for our player. So, the next 4 commands should be:

   set "spr0_refx" to 80

   set "spr0_refy" to 0

   set "spr0_width" to 3

   set "spr0_height" to 3

4. Now we need a control loop that draws the sprite and handles input.

   : "drawloop"

   wait 1

   put c?? Sprite p00 at "x" "y"

   if uppressed then "up"

   if leftpressed then "left"

   if rightpressed then "right"

   if downpressed then "down"

   goto "drawloop"

   Note that x and y will default to 0 since they haven't been used yet. It's generally a good idea to keep this information in a pair of local counters and initialize them along with the rest of the sprite data.

5. Now, you just need code to modify the values of "x" and "y" for each label "up", "left", "right", and "down".

   : "up"

   dec "y" by 1

   goto "drawloop"

   And the rest should be obvious: inc "y" by 1 for "down", dec "x" by 1 for "left", and inc "x" by 1 for "right".

Exercise 1.2: Improving and generalizing the code

That's it, you can now test your world and move the sprite around. You'll notice that the sprite gets "stuck" if you move it off the top or left of the board, and disappears off the bottom right. That's because we didn't do any bounds checking. In fact, there are a lot of improvements we can make to this code before we move on.

1. First let's make the sprite initialization dynamic. This may seem like more work now, but it'll make things much easier when you want to play with a lot of objects later, and decide that you need to reallocate sprite numbers. We'll declare local counters for the sprite draw location while we're at it.

   set "local" to 0

   set "local2" to 5

   set "local3" to 5

   set "spr&local&_refx" to 80

   set "spr&local&_refy" to 0

   set "spr&local&_width" to 3

   set "spr&local&_height" to 3

   : "drawloop"

   wait 1

   put c?? Sprite "local" "local2" "local3"

2. We also need some bounds checking. I prefer to define variables for zone boundaries, but we'll use constants with expressions for now.

   : "up"

   if "local3" <= 0 then "drawloop"

   dec "local3" by 1

   goto "drawloop"

   : "down"

   if "local3" >= "(25-'spr&local&_height')" then "drawloop"

   inc "local3" by 1

   goto "drawloop"

   Remember that "local3" is "y".

3. You also probably noticed that the previous movement routine favored certain directions over others; you can fix this by turning the label calls into subroutines (with diagonal movement as a free bonus!)

   if uppressed then "#up"

   ...

   : "#up"

   if "local3" <= 0 then "#return"

   dec "local3" by 1

   goto "#return"

This leaves us with this final code:

lockplayer
set "local" to 0
set "local2" to 5
set "local3" to 5
set "spr&local&_refx" to 80
set "spr&local&_refy" to 0
set "spr&local&_width" to 3
set "spr&local&_height" to 3
: "drawloop"
wait 1
put c?? Sprite "local" "local2" "local3"
if uppressed then "#up"
if leftpressed then "#left"
if rightpressed then "#right"
if downpressed then "#down"
goto "drawloop"
: "#up"
if "local3" <= 0 then "#return"
dec "local3" by 1
goto "#return"
: "#down"
if "local3" >= "(25-'spr&local&_height')" then "#return"
inc "local3" by 1
goto "#return"
: "#left"
if "local2" <= 0 then "#return"
dec "local2" by 1
goto "#return"
: "#right"
if "local2" <= "(80-'spr&local&_width')" then "#return"
inc "local2" by 1
goto "#return"

(More to come...)

External Links

Saike's Sprite Tutorial - Slightly out of date with regards to other MZX features.