Tutorial 16: Creating a Game using the Sprite Functions

Welcome back! In this tutorial we will be creating a simple game using the sprite functions covered in the previous project.

We'll be using the same ship assets from the brilliant Untied Games along with some awesome meteorites.

In this game, our ship will always be falling downwards. The challenging part is that we will have to press the A button to keep our ship flying. This might remind you of a game you've played before!

Let's start just like before by creating the player sprite from an image file:

  1. playerSpr = createSprite()
  2. playerImg = loadImage( "Untied Games/Player ships", false )
  3. setSpriteImage( playerSpr, playerImg )

Next we'll need to set the location of the sprite.

To help us out with this, we should create a variable which stores the width and height of the screen since we'll need these numbers a lot going forward:

Make a couple of new lines from line 1. This will move our other lines down slightly:

  1. screen = { gwidth(), gheight() } 
  2.
  3. playerSpr = createSprite()
  4. playerImg = loadImage( "Untied Games/Player ships", false )
  5. setSpriteImage( playerSpr, playerImg )

We have defined a variable called screen which stores a vector. This vector has an x property of gwidth() and a y property of gheight(). This means we can now access the width or height of the screen by using screen.x or screen.y. Very helpful!

With that done, we should create a variable which will store the scale multiplier for our sprites. It will save us some typing in the future to do this! Add the following new line:

  1. screen = { gwidth(), gheight() } 
  2. scale = { screen.y / 270, screen.y / 270 }
  3.
  4. playerSpr = createSprite()
  5. playerImg = loadImage( "Untied Games/Player ships", false )
  6. setSpriteImage( playerSpr, playerImg )

The scale variable stores a vector to use in our setSpriteScale() functions. By using screen.y / 270 our scale will change depending on whether the console is docked or undocked. We use the same number for both the x and the y parts of the vector so that our sprites scale evenly.

Now we can create a variable which will store the player position for easy reference:

  1. screen = { gwidth(), gheight() } 
  2. scale = { screen.y / 270, screen.y / 270 }
  3.
  4. playerSpr = createSprite()
  5. playerImg = loadImage( "Untied Games/Player ships", false )
  6. setSpriteImage( playerSpr, playerImg )
  7. playerPos = { screen.x / 20, screen.y / 2 }

We've called the variable playerPos. It stores a vector with a particular location on screen. We can now access the position using playerPos.x and playerPos.y.

Lastly, we might want to store the player velocity in a variable too to make things easier later on in the program. Let's add a Zero vector for now:

  1. screen = { gwidth(), gheight() } 
  2. scale = { screen.y / 270, screen.y / 270 }
  3.
  4. playerSpr = createSprite()
  5. playerImg = loadImage( "Untied Games/Player ships", false )
  6. setSpriteImage( playerSpr, playerImg )
  7. playerPos = { screen.x / 20, screen.y / 2 }  
  8. playerVel = { 0, 0 }

Alright, let's use the sprite functions to make use of all this information.

 10. setSpriteAnimation( playerSpr, 0, 0, 0 )
 11. setSpriteScale( playerSpr, scale )
 12. setSpriteLocation( playerSpr, playerPos )

Drawing and Moving the Player

Alright! Let's create a loop to draw the sprite on screen.

 14. loop
 15.     clear()
 16.     updateSprites()
 17.     drawSprites()
 18.     update()
 19. repeat

Currently our loop only puts the sprite on screen. Let's add some controls to this program. First, we'll want to recalculate the screen and scale variables in the loop. This will mean that if we change from handheld mode to TV mode by placing the console into the Nintendo Switch dock, the screen and scale will be updated so it looks right:

 14. loop
 15.     clear()
 16.     screen = { gwidth(), gheight() }
 17.     scale = { screen.y / 270, screen.y / 270 }
 18.     setSpriteScale( playerSpr, scale )
 19.     updateSprites()
 20.     drawSprites()
 21.     update()
 22. repeat

There we go. Now we can use the screen and scale variables in the loop without worrying if the console is handheld or TV mode. To make the scale actually change, we use the setSpriteScale() function in the loop on line 18.

Now let's apply some controls:

 14. loop
 15.     clear()
 16.     screen = { gwidth(), gheight() }
 17.     scale = { screen.y / 270, screen.y / 270 }
 18.    
 19.     c = controls( 0 )
 20.    
 21.     playerVel = { c.lx * screen.x / 4, screen.y / 3 - c.a * screen.y / 1.5 }
 22.
 23.     setSpriteSpeed( playerSpr, playerVel )
 24.     setSpriteScale( playerSpr, scale )
 25.
 26.     updateSprites()
 27.     drawSprites()
 28.     update()
 29. repeat

We've added some space between the lines in the program above to make things a little more clear.

There are three new lines here and they can be seen on line 19, line 21 and line 23.

First, we use the controls() function to store the state of the controls into a variable. We've called this variable c.

Next, we update the playerVel variable. In the curly brackets are the two ways we want to affect the velocity.

 21.    playerVel = { c.lx * screen.x / 4, screen.y / 3 - c.a * screen.y / 1.5 }

We want to be able to move the ship back and forth slightly to speed up and slow down. We are using the left control stick (c.lx) to do this.

Since the control stick returns a value between -1 and 1, the effect of this will be very tiny indeed. We have multiplied this by screen.x / 4} to enhance the movement speed, and by using the {screen.x variable here we can make sure the speed is the same in handheld or TV mode.

Similarly, for the y axis velocity, we use the screen.y to move the ship down at a speed dependent on the screen size. We minus the value of the A button (c.a) to move the ship upwards. Since the A button is either 0 or 1, we multiply this by screen.y / 1.5 to give us a stronger effect.

In order to make the movement actually take place, we need to apply the new values in the playerVel variable to the sprite velocity.

On line 23 we use the setSpriteSpeed() function to apply the values in the playerVel variable to the player sprite.

Run the program and get a feel for moving around the screen! Remember, you must hold the A button in order to move up and the left control stick will speed up and slow down the ship.

Creating Boundaries

At the moment, we can move our player off screen. This isn't very good and will make the game too easy. Let's introduce some restrictions to how far the player can move.

Below, we use a new function called clamp() to restrict the values of the playerPos variable. This very useful function can save us lots of if statements when used correctly. The first value in the brackets is the value to restrict, the second is the lower limit and the third is the upper limit.

 14. loop
 15.     clear()
 16.     screen = { gwidth(), gheight() }
 17.     scale = { screen.y / 270, screen.y / 270 }
 18.    
 19.     c = controls( 0 )
 20.    
 21.     playerVel = { c.lx * screen.x / 4, screen.y / 3 - c.a * screen.y / 1.5 }
 22.
 23.     playerPos = getSpriteLocation( playerSpr )
 24.
 25.     playerPos.x = clamp( playerPos.x, screen.x / 10, screen.x - screen.x / 10 )
 26.     playerPos.y = clamp( playerPos.y, screen.y / 10, screen.y - screen.y / 10 )
 27. 
 28.     setSpriteLocation( playerSpr, playerPos )
 29.     setSpriteSpeed( playerSpr, playerVel )
 30.     setSpriteScale( playerSpr, scale )
 31.
 32.     updateSprites()
 33.     drawSprites()
 34.     update()
 35. repeat

To understand why we are using the values screen.x / 10 and screen.x - screen.x / 10 let's visualise what we are achieving:

In the picture, the yellow outer box outlines the actual Nintendo Switch screen. The width and height of that screen is stored in the screen.x and screen.y variables.

The white inner box outlines the boundary we have created.

If the player position becomes more or less than the boundaries of our inside box, our clamp() function limits the values.

In order to actually place the player sprite on screen at the restricted positions, we must set the sprite location using the setSpriteLocation() function. To make this work, we use the getSpriteLocation() function on line 23 to make sure our player sprite is always placed at the location it should be.

Creating Obstacles

It's not really a very fun game unless we have something to do! Let's create a bunch of flying rocks to avoid.

First, we'll need to load the images we need and create the sprites.

We'll be using more of the brilliant Untied Games assets for this. There are 4 different asteroid assets to use. We will store all of these into an array.

We'll need to do the following changes before the main loop:

 14. rockImgs = [
 15.     loadImage( "Untied Games/Asteroid A", false ),
 16.     loadImage( "Untied Games/Asteroid B", false ),
 17.     loadImage( "Untied Games/Asteroid C", false ),
 18.     loadImage( "Untied Games/Asteroid D", false )
 19. ]

Here is the array of images. With this, we can access any of the images with something like rockImgs[1].

Next up we must create the array of information we'll use for the rocks which appear on screen. We'll call this array rocks and we'll be creating it just beneath the images array:

 21. array rocks[50] = [
 22.     .spr = 0, 
 23.     .pos = { 0, 0 },
 24.     .vel = { 0, 0 }
 25. ]

That's that! We've created an array of 50 elements, each one with three properties. Each rock will have a .spr property to store the sprite, a .pos property to store the position on screen and a .vel property to store the velocity.

Now let's populate this array with information it needs. We'll need a for loop for this:

 27. for i = 0 to len( rocks ) loop
 28.     n = random( 4 )
 29.     rocks[i].spr = createSprite()
 30.     setSpriteImage( rocks[i].spr, rockImgs[n] )
 31.     rocks[i].pos = { screen.x + random( screen.x * 2 ), random( screen.y ) }
 32.     rocks[i].vel = { - random( screen.x / 5 ), random( 33 ) - 16 }
 33.     setSpriteAnimation( rocks[i].spr, 0, 39, random(11) + 10 )
 34.     setSpriteLocation( rocks[i].spr, rocks[i].pos )
 35. repeat

This for loop counts up to the length of the rocks array. Let's look at each line in detail:

 28.     n = random( 4 )

First, we create a variable called n which stores a random number out of 4 possibilities. This gives us 0, 1, 2 and 3. This random number will be used to select a rock image from the rockImgs array.

 29.     rocks[i].spr = createSprite()
 30.     setSpriteImage( rocks[i].spr, rockImgs[n] )

On line 29 we use the createSprite() function to create a sprite for each rock. On the next line, we use the setSpriteImage() function to set a the randomly selected rock image to the sprite.

 31.     rocks[i].pos = { screen.x + random( screen.x * 2 ), random( screen.y ) }

Next, on line 31, we set the .pos property of each rock to store a position. We want the rocks randomly distributed over the y axis, so the y part of the vector is random( screen.y ). Since we want to start with no rocks on screen and have them travel towards us, the x part of the vector is screen.x + random( screen.x * 2 ). This makes sure the rocks are a random amount further than the edge of the screen to begin with.

 32.     rocks[i].vel = { - random( screen.x / 5 ), random( 33 ) - 16 }

On line 32 we set the .vel property for each rock that will be used for the velocity. The speed the rocks travel towards us needs to depend on the screen size, otherwise in handheld and TV mode the rocks will feel like they move at very different speeds. We use a random number chosen out of screen.x / 5. We must put a - in front of the function random to make sure the asteroids travel towards us instead of away!

We want the rocks to move up or down slowly to really add variety. For this we use a random number out of 33 in the y part of the vector, but if we minus 16 from the result we have a range of -16 to 16 giving us randomly chosen upwards or downward movement at a range of speeds.

 33.     setSpriteAnimation( rocks[i].spr, 0, 39, random( 11 ) + 10 )

On line 33 we set the animation for each rock. Each asteroid image has 40 frames of animation, so our start tile is 0 and the end tile is 39. For the animation speed we have used a random number between 10 and 20 to animate the rocks at different speeds.

 34.     setSpriteLocation( rocks[i].spr, rocks[i].pos )

Finally, we set the location of each rock sprite using the setSpriteLocation() function.

Still here? I bet you're thinking "Wow, this project rocks!"

...

What do you mean it was a terrible joke? Alright let's move on.

Drawing the Rocks on Screen

Now that we've got all the information we need in the rocks array, we can draw them to the screen. We'll be going back into the main loop for this. Because we've inserted lots of new code before the loop, the line numbers are a little different now. To make sure you are adding code in the right place, make sure your main loop looks like the one below before we get started:

 37. loop
 38.     clear()
 39.     screen = { gwidth(), gheight() }
 40.     scale = { screen.y / 270, screen.y / 270 }
 41.    
 42.     c = controls( 0 )
 43.    
 44.     playerVel = { c.lx * screen.x / 4, screen.y / 3 - c.a * screen.y / 1.5 }
 45.
 46.     playerPos = getSpriteLocation( playerSpr )
 47.
 48.     playerPos.x = clamp( playerPos.x, screen.x / 10, screen.x - screen.x / 10 )
 49.     playerPos.y = clamp( playerPos.y, screen.y / 10, screen.y - screen.y / 10 )
 50. 
 51.     setSpriteLocation( playerSpr, playerPos )
 52.     setSpriteSpeed( playerSpr, playerVel )
 53.     setSpriteScale( playerSpr, scale )
 54.
 55.     updateSprites()
 56.     drawSprites()
 57.     update()
 58. repeat

We need to add a for loop before the updateSprites() line. Go to line 54 and create a couple of new lines:

 53.     setSpriteScale( playerSpr, scale )
 54.
 55.
 56.
 57.     updateSprites()

We'll be adding the for loop starting on line 55. We must count over each rock in the rocks array and do a number of things for each one:

 55.     for i = 0 to len( rocks ) loop
 56.         setSpriteScale( rocks[i].spr, scale )
 57.         setSpriteSpeed( rocks[i].spr, rocks[i].vel )
 58.         rocks[i].pos = getSpriteLocation( rocks[i].spr )
 59.         rockSize = getSpriteSize( rocks[i].spr )
 60.         if rocks[i].pos.x + rockSize.x / 2 < 0 then
 61.             rocks[i].pos = { screen.x + random( screen.x ), random( screen.y ) }
 62.             setSpriteLocation( rocks[i].spr, rocks[i].pos )
 63.         endif
 64.     repeat
 65.
 66.     updateSprites()
 67.     drawSprites()
 68.     update()
 69. repeat

Phew! That's quite a complex looking bit of code right there. Fear not, it's actually quite simple if we take it step by step.

 56.         setSpriteScale( rocks[i].spr, scale )

The first thing we do in the for loop is to set the scale of each rock using the setSpriteScale() function.

 57.         setSpriteSpeed( rocks[i].spr, rocks[i].vel )

Next, we want to apply the speed for each rock to the sprite. We use the setSpriteSpeed() function, applying the vector stored in rocks[i].vel to each sprite. This line moves each rock across the screen and up or down depending on that rock's y velocity.

 58.         rocks[i].pos = getSpriteLocation( rocks[i].spr )

Next up we update the each rock's position variable to be the location of the sprite. Doing this allows us to write neater code later in the for loop. We are going to be checking each rock's position in just a minute and this gives us a neat way to check a rock's current position.

 59.         rockSize = getSpriteSize( rocks[i].spr )

Similarly, here we are creating a variable called rockSize and using it to store the size of each rock on screen. This will be a very useful variable in just a minute!

 60.         if rocks[i].pos.x + rockSize.x / 2 < 0 then
 61.             rocks[i].pos = { screen.x + random( screen.x ), random( screen.y ) }
 62.             setSpriteLocation( rocks[i].spr, rocks[i].pos )
 63.         endif

When a rock travels off the left side of the screen, we must do something to bring it back to the right hand side. Otherwise we would need a huge number of rocks! This if statement allows us to re-use each rock in the array when it has traveled off screen.

We check if the x position of the right side of each rock (rocks[i].pos.x + rockSize.x / 2) has become less than 0. If it has, we update the rocks[i].pos variable to be a random amount further than the right side of the screen on the x axis (screen.x + random( screen.x )) and a random position on the y axis (random( screen.y )). Finally we use the setSpriteLocation() function to update the location of the sprite.

Done!

Run the program to see our rocks flying across the screen towards us. When a rock travels off the left side of the screen, it will eventually come back on screen from the right!

Practise maneuvering around the rocks! We're about to add collision.

Colliding with the Rocks

Before we write the code which allows us to collide with a rock, it would be very cool if we could see some sort of explosion effect happen when we do.

Luckily, we have plenty of awesome explosion effects! You know the drill, we need to load an image and create a sprite. Add the following lines just before the main loop (you'll have to create a couple of lines of space):

 37. expSpr = createSprite()
 38. expImg = loadImage( "Untied Games/Explosion 09", false )
 39. setSpriteImage( expSpr, expImg )

As usual, we create a variable to store the image file. We've called ours expImg. Next we create another variable (expSpr which stores the sprite.

Another thing we'll need to do is to set the visibility of this sprite to false. We do not want to see the explosion yet, only when we collide with a rock. Add the following line:

 40. setSpriteVisibility( expSpr, false )

The setSpriteVisibility() function is incredibly useful and nice and simple. The first argument is the sprite variable and the second is either true for visible or false for invisible.

Lastly, we'll need some sort of flag to tell us whether the player is alive or not. This should be a true or false variable at the start of our program. Add the following line just before the loop line:

 41. alive = true

Now we have everything we need to make the explosion effect happen, we just need to collide with a rock!

This next bit of code will take place in the for loop which draws the rocks because we must check the distance between the player and each rock.

Below is the whole for loop for clarity:

 61.     for i = 0 to len( rocks ) loop
 62.         setSpriteScale( rocks[i].spr, scale )
 63.         setSpriteSpeed( rocks[i].spr, rocks[i].vel )
 64.         rocks[i].pos = getSpriteLocation( rocks[i].spr )
 65.         rockSize = getSpriteSize( rocks[i].spr )
 66.
 67.         if rocks[i].pos.x + rockSize.x / 2 < 0 then
 68.             rocks[i].pos = { screen.x + random( screen.x ), random( screen.y ) }
 69.             setSpriteLocation( rocks[i].spr, rocks[i].pos )
 70.         endif
 71.        
 72.         if distance( playerPos, rocks[i].pos ) < rockSize.x / 2 - 50 and alive then
 73.             alive = false
 74.             setSpriteAnimation( expSpr, 0, 89, 14 )
 75.             setSpriteLocation( expSpr, playerPos )
 76.             setSpriteScale( expSpr, scale )
 77.             setSpriteVisibility( expSpr, true )
 78.             setSpriteVisibility( playerSpr, false )
 79.         endif
 80.     repeat
 81.
 82.     updateSprites()
 83.     drawSprites()
 84.     update()
 85. repeat

Our new section of code is the if statement starting at line 72. As usual, we'll go through this line by line:

 72.         if distance( playerPos, rocks[i].pos ) < rockSize.x / 2 - 50 and alive then

For us to collide with a rock our position must overlap with the rock's position. We check if the distance between the centre of our ship (playerPos) and the centre of each rock (rocks[i].pos) is less than half the size of that rock minus 50 pixels ( < rockSize.x / 2 - 50). The 50 pixels part is really personal preference, changing this number will make the collision looser or tighter.

The second part of the if statement check is whether the alive variable is true. We only want to collide with a rock once.

 73.             alive = false

The first thing we do in the if statement is to make the alive variable false. This means we can only collide once. Once we do, the if statement can no longer be true.

 74.             setSpriteAnimation( expSpr, 0, 89, 14 )

Next up we set the animation for the explosion sprite. Our explosion sprite has 90 frames, beginning with 0 and ending at 89. A speed of 14 gives us a nice looking explosion, feel free to change this!

 75.             setSpriteLocation( expSpr, playerPos )

Now we must set the location of the explosion sprite to be the same as the player position! We wouldn't want the explosion happening in a random place on screen.

 76.             setSpriteScale( expSpr, scale )

Next we set the scale multiplier for the explosion sprite. Simple enough!

 77.             setSpriteVisibility( expSpr, true )
 78.             setSpriteVisibility( playerSpr, false )

These next two lines set the visibility for the player to false and the visibility for the explosion to true. Without these, we wouldn't see anything!

That's that. We're so close to the finish line!

We have one last thing to do. Once the explosion animation has finished we want to set the visibility back to false. without this the explosion animation will keep looping forever!

We'll need an if statement just before the updateSprites() function:

 82.     if getSpriteAnimFrame( expSpr ) >= 89 then
 83.         setSpriteVisibility( expSpr, false )
 84.     endif
 85.
 86.     updateSprites()
 87.     drawSprites()
 88.     update()
 89. repeat

As you can see, this part comes just before the last 4 lines of the loop.

We use the getSpriteAnimFrame() function to check which frame of animation our explosion is currently on. Since we know that the explosion's last animation frame is frame 89, we have an easy way to check if it's finished.

We use the setSpriteVisibility() function one last time to make the visibility false once it reaches the end of its animation cycle.

Complete!

Congratulations on making it through the tutorial! Now you can customise the game to your heart's content. If you unfortunately break anything at all, you can find a complete version of the program just below. Feel free to copy and paste all the code below into a new project file:

  1. screen = { gwidth(), gheight() } 
  2. scale = { screen.y / 270, screen.y / 270 }
  3.
  4. playerSpr = createSprite()
  5. playerImg = loadImage( "Untied Games/Player ships", false )
  6. setSpriteImage( playerSpr, playerImg )
  7. playerPos = { screen.x / 20, screen.y / 2 }  
  8. playerVel = { 0, 0 }
  9.
 10. setSpriteAnimation( playerSpr, 0, 0, 0 )
 11. setSpriteScale( playerSpr, scale )
 12. setSpriteLocation( playerSpr, playerPos )
 13.
 14. rockImgs = [
 15.     loadImage( "Untied Games/Asteroid A", false ),
 16.     loadImage( "Untied Games/Asteroid B", false ),
 17.     loadImage( "Untied Games/Asteroid C", false ),
 18.     loadImage( "Untied Games/Asteroid D", false )
 19. ]
 20.
 21. array rocks[50] = [
 22.     .spr = 0, 
 23.     .pos = { 0, 0 },
 24.     .vel = { 0, 0 }
 25. ]
 26.
 27. for i = 0 to len( rocks ) loop
 28.     n = random( 4 )
 29.     rocks[i].spr = createSprite()
 30.     setSpriteImage( rocks[i].spr, rockImgs[n] )
 31.     rocks[i].pos = { screen.x + random( screen.x * 2 ), random( screen.y ) }
 32.     rocks[i].vel = { - random( screen.x / 5 ), random( 33 ) - 16 }
 33.     setSpriteAnimation( rocks[i].spr, 0, 39, random( 11 ) + 10 )
 34.     setSpriteLocation( rocks[i].spr, rocks[i].pos )
 35. repeat
 36.
 37. expSpr = createSprite()
 38. expImg = loadImage( "Untied Games/Explosion 09", false )
 39. setSpriteImage( expSpr, expImg )
 40. setSpriteVisibility( expSpr, false )
 41. alive = true
 42.
 43. loop
 44.     clear()
 45.     screen = { gwidth(), gheight() }
 46.     scale = { screen.y / 270, screen.y / 270 }
 47.    
 48.     c = controls( 0 )
 49.    
 50.     playerVel = { c.lx * screen.y / 4, screen.y / 3 - c.a * screen.y / 1.5 }
 51.
 52.     playerPos = getSpriteLocation( playerSpr )
 53.
 54.     playerPos.x = clamp( playerPos.x, screen.x / 10, screen.x - screen.x / 10 )
 55.     playerPos.y = clamp( playerPos.y, screen.y / 10, screen.y - screen.y / 10 )
 56. 
 57.     setSpriteLocation( playerSpr, playerPos )
 58.     setSpriteSpeed( playerSpr, playerVel )
 59.     setSpriteScale( playerSpr, scale )
 60.
 61.     for i = 0 to len( rocks ) loop
 62.         setSpriteScale( rocks[i].spr, scale )
 63.         setSpriteSpeed( rocks[i].spr, rocks[i].vel )
 64.         rocks[i].pos = getSpriteLocation( rocks[i].spr )
 65.         rockSize = getSpriteSize( rocks[i].spr )
 66.
 67.         if rocks[i].pos.x + rockSize.x / 2 < 0 then
 68.             rocks[i].pos = { screen.x + random( screen.x ), random( screen.y ) }
 69.             setSpriteLocation( rocks[i].spr, rocks[i].pos )
 70.         endif
 71.        
 72.         if distance( playerPos, rocks[i].pos ) < rockSize.x / 2 - 50 and alive then
 73.             alive = false
 74.             setSpriteAnimation( expSpr, 0, 89, 14 )
 75.             setSpriteLocation( expSpr, playerPos )
 76.             setSpriteScale( expSpr, scale )
 77.             setSpriteVisibility( expSpr, true )
 78.             setSpriteVisibility( playerSpr, false )
 79.         endif
 80.     repeat
 81.
 82.     if getSpriteAnimFrame( expSpr ) >= 89 then
 83.         setSpriteVisibility( expSpr, false )
 84.     endif
 85.
 86.     updateSprites()
 87.     drawSprites()
 88.     update()
 89. repeat