Tennis

Let’s code a simple game of single player tennis inspired by the classic Pong. We’ll code a paddle that we can move up and down the screen with the d-pad or crank. When the ball hits the top, right, and bottom of the screen, it’ll bounce off it. If it goes past our paddle and off the left side of the screen, it’ll be game over. We’ll keep track of how many hits we get. And to add a little difficulty to our game, we’ll make the ball get a little bit faster over time.

Start off by creating a new folder called tennis with a source folder that contains source/main.lua.

Put the following into source/main.lua:

playdate.graphics.fillRect draws a rectangle on the screen and fill it black (the default fill color). The first parameter is the x position, the second is the y position, the third is the width, and the fourth is the height. Our code says to draw a rectangle at 36 pixels in, 80 pixels down, with a width of 12 pixels and a height of 48 pixels.

Let’s make it so we can move the paddle. This won’t be too different from moving text around the screen. But this time let’s use a table to keep track of the paddle position and use key-value pairs to make our data structure more clear.

Lua is quite flexible in that it allows key-less tables, like we saw with the different names, local names = { "Playdate", "Goku", "Bulma", "Piccolo" }. But Lua also allows us to specify keys and values for easily accessing and changing them. We’ll see this in action, but here’s an example of the alternative way of using a table:

The values of player can be accessed with dot syntax (player.name which returns the string "Oolong") or with bracket syntax (player["health"] which returns the number 10).

Let’s update source/main.lua to introduce a paddle table that has an x and y position:

We’ve refactored our code to keep track of the paddle’s position in a table named paddle. Very convenient.

Bonus: put the paddle’s width and height into the paddle variable and reference it from the variable when drawing the paddle.

Let’s move the paddle. We’ll start with the d-pad and then support the crank. Much like with moving the text, we’ll check for the up and down input on the d-pad.

Update source/main.lua to be:

Our expanded code moves the paddle up and down by paddle.s—a new entry in our table that represents the paddle’s speed. By having it live in just one place, it’s easy to change the value to find a speed that feels right. Try changing s around to find a speed that feels good to you.

We also had to make sure we clear the screen every update with playdate.graphics.clear().

Did you notice that the paddle can be moved off the screen? Penalty! Out of bounds! Well, no, not really. But a bad player experience. Let’s make it so that the paddle can’t go outside the bounds of the screen of the Playdate.

We’ll introduce a condition within our checks for buttons being pressed. For up input, we’ll check to see if the paddle’s y position is less than or equal to 0, and if it is, then we’ll set it to 0. For down input, we’ll check to see if the height of the paddle plus its y position is greater than or equal to 240, which is how many pixels tall the Playdate is.

Let’s code that up in source/main.lua:

Now our paddle stops at the top and bottom of the screen. We have to check that the paddle’s y position plus its height is less than the screen height because paddle.y is the top of the rectangle. And the x position is the left side.

There’s an aspect of this code that I don’t love, and it’s 240. When coding, a number that’s present without any context to its meaning is known as a magic number. It’s difficult to know what 240 means at first glance. While we know it’s the height of the Playdate’s screen, it’s not obvious. Our goal is to write code that’s easy to understand. We could make a variable, local screen_height = 240 and reference that. But we’ve got another option that’s a little more futureproof. Playdate provides an API to get the height of the display: playdate.display.getHeight()

This introduces a variable displayHeight that’s set dynamically from the Playdate SDK and removes the magic number.

Let’s whip the crank out and have turning it move the paddle up and down. Cranking forward will move the paddle down, while cranking backwards will move up. The Playdate SDK provides the playdate.getCrankChange() function, which returns two values: the degrees of angle change since the last time the function was called and an accelerated change value based on how fast the player is moving the crank. We’ll use the second value, the accelerated change, since it feels better.

Add the code to source/main.lua between the d-pad input checking and the boundary checking:

The first return value, _crankChange, is prefixed with an underscore to signify that it’s not used. Then we take the acceleratedCrankChange variable and add it to paddle.y. This works because cranking forward returns a positive value and cranking backwards returns a negative value. Just what we need.

(debugging with print to see the crank values)

Bonus #1: swap acceleratedCrankChange for _crankChange when adding to paddle.y and see how that feels.

Bonus #2: how would you increase or decrease the crank change to refine the paddle movement?

Similar to how we drew a rectangle for the paddle, we’ll draw a circle to represent the ball.

At the very top of source/main.lua, we need to import the graphics core library. We’ll also set up a ball table variable for tracking that data.

Then at the bottom of the playdate.update() function, call playdate.graphics.fillCircleAtPoint:

r represents the radius of the circle in pixels.

Bonus: Adjust the r radius of the circle to find a size that seems appropriate.

Let’s take a brief moment to refactor our calls to playdate.graphics to follow the best practices suggested by the Playdate SDK.

We’ll introduce a constant value called gfx to make our code a bit more concise. It also makes our code slightly faster. Win-win!

Update the top of source/main.lua to add the following line below the graphics import:

<const> means that the value is constant. It shouldn’t change nor be reassigned.

Then in playdate.update() replace playdate.graphics with gfx:

We’ve coded two moving objects already—the text from Chapter 1 and the paddle in our tennis game. They responded to user input via the d-pad and crank. The ball in Tennis will move automatically. Instead of checking for player input, we’ll just modify the ball’s position in each update of the game loop.

In source/main.lua below the paddle boundary checking and above the drawing, increase the ball’s x position by 2 pixels every loop:

Run the game and see what happens. The ball moves to the right. Going, going, gone! It disappears off the screen. It’s still moving, deep into space. We just can’t see it.

Bonus: Refactor the code to put the ball’s speed of 2 into the ball table.

Much like how we check for the top and bottom of the screen to stop moving the paddle, we’ll check to see if the ball has hit the right side of the screen. If it has, then we’ll change its direction.

Quite a few changes have been made. First, s was added to the ball table to represent its speed. 2 pixels per update felt too slow, so it’s been increased to 4.

The direction is encoded in the sign of ball.s—positive means move right, negative means move left. While it’s not super clear to combine speed and direction into one variable, that’s okay, it’ll end up going away when we introduce angles.

We set a variable for the displayWidth just like we did for displayHeight but call getWidth() instead. We need it for checking the boundary of the ball.

When we change the ball.x, we use ball.s instead of the magic number from the last section. And we multiply it by -1 to change the direction. *= means multiply the value on the left by the value on the right and assign that new value to it. Multiplying by -1 changes the sign of the direction.

If the ball is moving right, we’re increasing its x value, so ball.s is positive. But if we want the ball to move to the left, we need to subtract ball.s from ball.x. By multiplying ball.s by -1, it subtracts 4 from ball.x in future loops. To make the ball move right again, multiply it by -1 to turn it positive. This directional modifier is quite powerful and a regular staple of game programming.

Then we check if the ball’s x position plus its radius (r) are greater than or equal to the width of the screen. If it is, we set the ball’s position to the furthest right edge and change the direction to -1 so it moves to the left in the next game loop call of playdate.update().

Similarly but for the left side of the screen, we check if the ball.x is less than or equal to the ball’s radius (r). If it is, we set the ball.x to the ball.r and change the direction to move to the right.

The boundary checking for the ball is slightly different than our paddle as the origin point of the circle is in the center, not the upper left. This means we need to factor this into our logic. Try changing if ball.x <= ball.r then to if ball.x <= 0 then and see what happens. (And then undo it because it’s not what we want moving forward).

While it’s fun to watch the ball move back and forth, it flies right through our paddle. Let’s make it so that when the ball overlaps with the paddle, it changes direction.

To bounce the ball off of the paddle, we’ll check to see if the circular ball overlaps the rectangular paddle. This is where we introduce non-trivial math into our game in the form of trigonometry. Don’t worry if you don’t know much trig, I’ll break it down and explain it.

We’ll also introduce our first custom function to encapsulate the logic. Our playdate.update() function is getting a bit long and unwieldy, so by putting code into functions, we can keep it clear and focused.

Right below where we update the ball’s x position we’ll add a conditional check with the new function we’re adding: circleOverlapsRect. We pass in the ball (our circle) as the first parameter and then the paddle (our rectangle) as the second parameter. If the circle does overlap the rectangle, meaning the ball hit our paddle, we’ll flip the ball’s direction by changing the sign of its speed.

The circleOverlapsRect function takes a circle and rect as arguments. There are some comments that start with -- to explain the code a bit.

Let’s breakdown the determination of closestX and closestY. It checks to see what point within the rect is closest to the circle by comparing the center of the circle to the bounding box of the rect.

The distance formula is then used to determine the distance between the closest point in the rect and the center of the circle. If the distance is less than or equal to the circle’s radius (circle.r), then it means the circle is overlapping the rectangle.

Our code in playdate.update() is getting complex and unwieldy. Let’s refactor the code we’ve got into separate functions that we call from within playdate.update(). Putting code into functions serves three key purposes:

1. Functions help us reuse code rather than repeating it multiple times.
2. Functions break our code down into smaller parts which are easier to understand.
3. Functions self-document our code by grouping lines together into something with a name.

Our current source/main.lua looks like this:

I see three functions we can extract:

1. Moving the paddle: movePaddle()
2. Moving the ball: moveBall()
3. Drawing our shapes: draw()

Here’s what our refactored code looks like:

All we’ve done is move our code into separate functions and then call them within playdate.update(). It’s a lot easier to reason about and refer to the code.

The call to the circleOverlapsRect function did not get moved into its own function because it’s simple enough to just stay put. It wouldn’t fit naturally into movePaddle() or moveBall() since it deals with both of them. If collision detection gets more complicated, then it might make sense to move it into its own function.

Now that our code is cleaned up a bit, let’s make the game more exciting. Let’s introduce angles to make the ball bounce all over the screen.

Our ball is just moving along the x-axis, which isn’t very exciting. We want to make our ball move all over the screen. This means, yes, more math! We need to keep track of the angle of our ball and use that in conjunction with our speed to determine its velocity.

Play your game on the Playdate Simulator and upload to your Playdate to play test it if you haven’t yet. It’s starting to get fun!

There are some major changes in the code with how we’re handling the ball movement.

First, we introduce ball.a to represent the ball’s angle of movement. It’s in degrees and initially set to 195, which is to the right and down a little bit. (180 would be straight to the right.) We’ll use the angle when determining how to change the x and y position of the ball based on its speed.

In playdate.update() we set the ball.a to a random value between 160 and 200 degrees minus ball.a. This turns the ball around and gives it a little bit of random variance to prevent the ball from getting deadlocked in a straight line.

draw(), movePaddle(), and circleOverlapsRect() remain unchanged. But moveBall() gets entirely overhauled.

Let’s break down the two key parts:

Since the ball is moving at an angle, both its x and y position need to change based on that angle. More trigonometry!

We convert the ball’s angle to radians, which we need for working with the sine (math.sin()) and cosine (math.cos()) functions. We calculate the change in the x position based on the cosine of the angle times the ball’s speed. The y position is similar but we use sine instead. The foundation of this formula is using the unit circle to determine angular velocity.

After we change the x and y position, we check to see if the ball has collided with the top, bottom, left, and right side of the screen. For the left and right side along the x axis, we subtract the current ball.a from 180 to flip the horizontal movement. For the top and bottom collisions along the y axis, we multiply the ball.a by -1 to keep the horizontal direction the same but change the vertical direction.

Let’s make it so the ball gets faster each time it hits the paddle. This will make the game more challenging the better we get at it.

To make the ball go faster, all we need to do is increase ball.s in our if circleOverlapsRect(ball, paddle) then conditional check in playdate.update().

It quickly gets out of hand and the ball moves way too fast. So let’s set a max upper speed by adding max_s to our ball table and checking to see if ball.s is beyond it.

There’s something really fun about using the crank to hit the ball around! We’re starting to get our first glimpses at the fun and joy of making games.

Let’s keep track of the score for each round and reset it to zero if the ball hits the left wall. We’ll also reset the ball to its initial position, speed, and angle when the left wall is hit. We need a new variable, score, that we’ll set and draw on the screen. We’ll also keep track of the initial values we want to track for resetting the game.

There’s nothing too new here. Lots of using the fundamentals we already learned. Except for the assigning of ball.initX, ball.initY, etc. Basically what the code does is that after we create the ball, we take the values and assign them to a separate entry in the table. Because ball.x, ball.y, etc. are going to change throughout the game. We want to be able to easily reset to those initial values.

We’re almost done with Tennis. Let’s polish it up a little bit more.

Our game is feeling a bit quiet, don’t you think? The Playdate SDK offers a lot of options for playing sound effects, from samples to files to an included synth. We’ll add some simple MIDI sound effects to our game whenever the ball hits anything.

We create a new synth variable using the kWaveSine constant. And we use that in the new playSFX function, which takes a note and plays it on the synth for a quarter of a second. The second parameter, 1, is the volume of the sound effect. You can see that for each wall the ball hits, we play a different note. This is more pleasing than repeating the same sound over and over. And the sound when the ball hits the paddle is also different.

Bonus: Similar to how we greeted a random name in the first chapter, create a table of music notes and randomly select one when the ball hits the paddle.

That’s Tennis! Our version is complete, at least for now. We learned a whole lot in this chapter. We wrote our own functions, drew shapes, implemented angular velocity, created and changed a whole bunch of variables, and made something that’s a little fun. Nice work.

Here’s the finished code for this chapter:

130 lines of code. That’s respectable for our first Playdate game. If you’ve got someone you can share your Playdate with, show them what you made!

There’s a lot you could do to expand Tennis into something more fun. Here are some ideas to take it to the next level:

• Make the game two player by introducing another paddle. Player 1 controls the left paddle with the d-pad and Player 2 controls the right paddle with the crank.
• Add multiple balls that spawn after reaching certain score thresholds!
• Add collectibles to aim for or even bricks to break.
• Add pinball-style bumpers that the ball can hit.
• Make the ball appear larger when it hits the paddle or a wall.
• Shake the paddle when it’s hit by the ball.
• There’s a small bug—sometimes the ball and paddle can get stuck on each other. How would you separate them when they collide based on the position of the ball when it hits the paddle?
• In future chapters we’ll learn about saving data. Make it so that the high score is saved between play sessions. When a new high-score is reached, modify the score text to let the player know!
• Adding a mute setting would be nice!
• Rework the paddle’s movement to use acceleration and factor its current velocity into the angle the ball is bounced off at (e.g., if the paddle hits the ball while the paddle is moving up, the ball should also move up and to the right).

Tennis was a lot to soak in. Let’s take a breather by coding up a simple little utility for our Playdate: a clock.