This project is a Breakout clone. Or I guess a DX-Ball clone, since that’s how the controls work. Whee!

The video to the right shows a bit of me playing my solution. You can see that there are three main parts:

At the beginning of the game, the ball is on the paddle, and the player launches it by clicking. When the ball goes off the bottom of the screen, it is reset onto the paddle, at which point it can be launched again.

This continues until all blocks have been destroyed, which is not shown in the video, but at that point the game is over and “Congratulations!” is displayed on the screen.

Grading rubric

Note: if you submit on the late due date, 10 points will be deducted after all other grading has been done.

Also note: if you submit the wrong thing (submit a file that isn’t your project, or an outdated version of your project) and it isn’t found until the grader looks at it, you will be allowed to resubmit, but you will lose 20 points. Be careful about what you are submitting. (But if you make a mistake in what you submit before the deadline, it’s no problem. Just resubmit with the correct file. You have infinite resubmissions before the deadline.)

Code style: although there is no point category for code style, the grader may take off up to 10 points if your code is very poorly-written. Poor indentation may lose you a couple points, but mostly it’s about using the calling convention we learned; using the right registers for the right purposes; and writing/using functions correctly. Remember: keep your code neat and tidy while you write it, not at the end.

Getting familiar with the code

Download this file and extract it somewhere sensible.

Then rename the abc123_proj1.asm file. Your username is not abc123.

Overview:

and of course, _proj1.asm is the program itself.

What’s all this in _proj1.asm?

First are some includes, like usual.

Then, variables and arrays. Most of them are pretty self-explanatory. blocks represents the blocks on-screen, and has some default values in it.

You can read main and see what it does in what order. Some of the comments explain things you can change for fun.

Then there are some functions which do what they say. show_game_over_message might be something you want to change later in the project.

Finally are some stubbed-out functions that you’ll complete as you work on the project.

How to approach this

I’m gonna be a little more hands-off and kind of give you the general ideas without going into a lot of detail. Most of the concepts you need to do this project, you encountered on the labs.

Below is an image of my solution’s call graph. Click it to view it in full resolution in a new tab.

Some of these functions, I’ve already given you the code for. Others, I stubbed out. Others, I implemented myself.

You are not required to split up your program in exactly the same way that I did. But you are expected to split your program up into reasonably-sized (read: usually 40 lines or less) functions in some way. Failure to do so can lose you style points. (There is a LOT of stuff for the ball. Putting it all in one function would be overwhelming.)

Fixed-point numbers

Just like on lab 4, we are going to be representing some things as fixed-point numbers which integers where we imagine some of the places to be fractional.

In proj1_constants.asm you can see a number of constants marked (x100) which are represented this way - they are multiplied by 100, so we have “two places” of fractional accuracy.

In _proj1.asm, the paddle and ball’s coordinate and velocity variables are all going to be treated this way. Most of the time, you don’t have to do anything fancy or special, except when converting between “normal” ints and these “times 100” fixed-point ints. Again, you did this exact thing on lab 4, though there is now a SCALE constant for the scaling factor.

The reason we’re doing this is for the last part of the project, where the ball will be able to bounce off your paddle in many different angles, which would be impossible to represent with regular integers.

Drawing blocks

The blocks array is a 2D array with BLOCK_COLS columns and BLOCK_ROWS rows. Each block is BLOCK_W pixels wide and BLOCK_H pixels tall.

Right now, the blocks array has some blocks in it already. (You can refer to the BLOCK_ constants in proj1_constants.asm to see which numbers mean which colors.) But they’re not visible.

To make them visible, you have to implement draw_blocks. The blocks are drawn on the tilemap, but each block takes up two tiles instead of just one.

Any function whose name starts with display_ is given to you in the display_2254_0205.asm file. You can look them up in there, and there are comments which document them. display_set_tile is like the place_tile function you wrote in lab 3, but with one more argument.

Here is what draw_blocks needs to do, in Java pseudocode. You are allowed and encouraged to copy and paste this pseudocode as comments in your assembly so that you can keep track of what you’re working on.

// you know how to do a nested for loop by now.
for(int row = 0; row < BLOCK_ROWS; row++) {
	for(int col = 0; col < BLOCK_COLS; col++) {
		// go look at the type of the blocks array
		int block_type = blocks[row * BLOCK_COLS + col];
		
		if(block_type != BLOCK_EMPTY) {
			// block_palette_starts is a byte array in proj1_graphics.asm
			// it's a list of where each block color's palette entries start
			int flags = block_palette_starts[block_type - 1];
			
			// col*2 because each block is 2 columns wide
			display_set_tile(col * 2,     row, BLOCK_TILE,     flags);
			display_set_tile(col * 2 + 1, row, BLOCK_TILE + 1, flags);
		} else {
			// empty block - we still have to draw
			// something to make old blocks disappear!
			display_set_tile(col * 2,     row, EMPTY_TILE, 0);
			display_set_tile(col * 2 + 1, row, EMPTY_TILE, 0);
		}
	}
}

Your goal is the image on the right.

Completing this successfully means you have a 20% on the project.

The paddle

The paddle is what represents the player. It’s controlled with the mouse/trackpad.

I’m not going to tell you exactly what functions to do this stuff in. Go look at the call graph and look at the stubbed out functions and Use Your Brain.

Go forth and do it.

When done properly, it should look and work like the video to the right. Importantly:

Completing this successfully means you have a 40% on the project.

A useful tool: draw_hud and drawing text

draw_hud is a blank function I gave you. HUD stands for “heads-up display” and is the term used in game programming to refer to all the stuff drawn on the screen that shows you information about like, how many lives your player has, how many coins they have, that kinda thing.

There ended up not really being any use for the HUD in this game, buuuuut I left the function there for you to put “debug prints.” But instead of printing to the console, you can draw text to the screen, too.

Just to try it out, go put the equivalent of this in draw_hud:

display_draw_int_sprites(1, 1, paddle_x);

Then run the game, and now you should see a readout of the paddle’s X position in the top-left of the screen. (if you see 268507972 there, use lw instead of la aaaaaaaaaaaaaaAAAAAAAAAAAA)

You don’t have to keep that around. I was just having you try it out. Delete it if it’s not useful for you. But yeah. You can put “debug prints” there to diagnose issues more easily than printing them out to the console.

The two functions you can use are:

The ball, basic behaviors

The ball can be in one of two states (held in ball_state, what a surprise):

Start with STATE_ON_PADDLE first. In this state,

Then to draw the ball, there’s just 1 sprite, drawn at (ball_x - BALL_HALFWIDTH) / SCALE, (ball_y - BALL_HALFHEIGHT) / SCALE, with BALL_TILE and BALL_FLAGS. EZ.

At this point, the ball should now appear sitting directly on top of the middle of the paddle, and move with the paddle as you move it. Like this image.

Next, you need to be able to launch the ball. This is done by clicking the mouse.

That should be it. Now, when you click the mouse/trackpad, the ball should start moving up-right off the paddle. Go look at the video at the top of this page for an example.

But it will very quickly move offscreen and disappear. That’s because you aren’t checking for collision. Let’s do that next.

Ball collision with walls and paddle

After the code that adds ball_vx to ball_x but before the code that adds ball_vy to ball_y, you need to check for horizontal ball collision. In my solution I called it ball_check_lr (LR for “left-right”) but you can call it whatever you want. ball_collide_horiz or ball_collision_sideways or whatever

That function is going to get more complex with time, but for now it needs to:

Now it should bounce off the side wall, but… it still goes off the top of the screen. So, you need another collision function for vertical collision (ball_check_ud in my code). To be clear, in your ball’s STATE_MOVING code it’ll be something like:

	ball_x += ball_vx;
	ball_check_lr(); // or whatever you name it
	ball_y += ball_vy;
	ball_check_ud(); // ditto

The ordering of the above steps is crucial and you cannot e.g. put the two checks after updating both ball_x and ball_y. Ask me how I know 😅

In the vertical collision function:

And with that, it should now:

Last, it needs to collide with the paddle so that it doesn’t always fall into the abyss. In the vertical collision function, if it’s neither of those two things you checked for already, then you need to check for paddle collision. This is long-winded but conceptually simple.

The way I engineered it works like this:

if(ball_y is off top of screen) {
    ball_bounce_y();
} else if(ball_y is off bottom of screen) {
    kill_ball();
} else if(ball_check_paddle()) { // <-------- this!
    ball_bounce_y(); // you'll revisit this..
}

My ball_check_paddle function abstracts out the huge ugly five-part condition to check and just returns a 0 (didn’t hit) or 1 (did hit the paddle). I really recommend you do the same.

If any of these five conditions are true, then the ball is not hitting the paddle:

Because of that, it might be easiest to structure this function like:

    # set return value to 0
    li v0, 0
    
    # check the 5 conditions here, go to _not_hitting for all of them
    
    # got through the 5 conditions, return 1
    li v0, 1
_not_hitting:

This is a little tricky! Good luck!

To make it easier to see and diagnose issues, I gave you a “frame-by-frame” mode, the debug_do_framemode function called from main. The way it works is like this:

This way, if the ball is doing something weird/stupid with the paddle, you can wait until it’s almost hitting the paddle, hit R, then tap F until you can see what/where it is where it behaves incorrectly.

Completing this successfully means you have a 65% on the project. It should behave like this (and notice, it can miss my paddle! You don’t want it to ALWAYS bounce when it reaches PADDLE_Y!)

Breaking blocks

This is a big part of the project! It’s kinda tough! Breaking things up into smaller more manageable pieces is super important! Looking at my solution, these functions are involved:

I think it might be easier for you to build this from bottom-up, so let’s start with get_block. It takes pixel coordinates (a0 = x, a1 = y) as arguments and gets the block that occupies those coordinates. It returns two values:

This is a lot simpler than it sounds.

  1. Convert the pixel coords to row/column by dividing X by BLOCK_W and Y by BLOCK_H
  2. Convert row/column to index by doing (row * BLOCK_COLS) + col
  3. If that index is >= N_BLOCKS (the size of the array),
    • return BLOCK_EMPTY in v0 and -1 in v1
  4. Else,
    • return blocks[index] in v0 and index in v1

You can test this by putting some code in draw_hud like this pseudocode:

	// that is, s0 = v0 and s1 = v1 after calling it
	s0, s1 = get_block(display_mouse_x, display_mouse_y)
	display_draw_int_sprites(1, 1, s0)
	display_draw_int_sprites(1, 10, s1)

Now you can hover your mouse over blocks to see if it’s working - the top number is the block type (0 for empty, 1 for red etc) and the bottom number is its index in the array (0-7 on the top row, 8-15 on the next row etc. until 79 on the bottom-right block and -1 anywhere below it).

Next let’s work on destroy_block and check_all_blocks_destroyed.

You can test these by putting some more code in draw_hud after the code above:

if(s1 >= 0) { // s1 is index that get_block returned
	if(user is pressing D) {
		destroy_block(s1);
	}
}

Now hover your mouse over a block and press D to destroy it. Destroy them all, and the game should end!

But that’s kinda cheating, huh…

So to make the ball destroy blocks at this point, it’s pretty straightforward. Let’s start with the left/right case and I’ll leave it to you to do the up/down case.

In my ball_check_lr (horizontal ball collision function), after checking for the walls, the next case is something like…

ball_get_block_lr(); // returns 2 values
if(v0 != BLOCK_EMPTY) {
	destroy_block(v1);
	ball_bounce_x(); // boing
}

See, super simple. But that’s because ball_get_block_lr abstracts away the ugly stuff, which is like:

if(ball is moving left) { // check X velocity for this
	a0 = ball_x - BALL_HALFWIDTH; 
} else {
	a0 = ball_x + BALL_HALFWIDTH - 100;	// trust me on the - 100
}

get_block(a0 / SCALE, ball_y / SCALE); // its return values will be returned

That is - if the ball is moving left, we check a point on the left side of the ball for a block; otherwise, we check a point on the right side of the ball for a block. That block’s type and index will be returned in v0 and v1 to be checked by the caller.

Try it out. The ball should be able to destroy blocks when hitting them from the side… or kinda passing through them… weird.

Finally, you have to do the same thing for vertical collision (adding code to ball_check_ud and creating ball_get_block_ud), except:

With that implemented, congrats, you now have a fully-functional (if slightly boring) version of Breakout, and an 85%! But you’re not done if you want to get a 100%.

“Angled” paddle surface

idk what else to call this

Right now, the paddle behaves as a perfectly flat surface and the ball bounces off it like a block which makes for some really boring gameplay, as after you launch the ball, you have no control over its path.

To give the player some control, we will make it so the top of the paddle behaves a bit like a dome shape - if the ball hits the middle, it will bounce almost straight up, and if it hits closer to the ends, it will bounce off at an increasingly steep angle. (Go look at the video at the top of the page for what I mean. It’s easier to show than to describe.)

Doing this requires some…. math……..

First, in your ball’s vertical collision function (e.g. ball_check_ud), in the part where you check for the paddle and bounce it on the Y? Instead of just bouncing it on the Y, call a new function, called like ball_bounce_paddle.

ball_bounce_paddle is gonna:

  1. restore the ball’s old y position (ball_y = ball_old_y)
  2. compute the absolute delta between the ball’s X and the paddle’s X:
    • Δx = abs(ball_x - paddle_x)
    • MIPS has an abs instruction for this!
  3. that Δx is in the range [0, PADDLE_HALFWIDTH]. We have to remap it to an angle [0, 75], in a slightly funny way:
    • first multiply it by 75
    • then divide by PADDLE_HALFWIDTH
      • (your intuition might be to divide then multiply, but these are ints. if we did the division first, we’d get 0.)
  4. pass that angle as the argument to the sin_cos function
    • the sine is returned in v0 and the cosine in v1
    • they are “x10000” fixed-point numbers - that is, they have 4 decimal places instead of just 2
  5. multiply the returned vector by (14142, -14142)
    • (this is (√2, -√2) in x10000 fixed-point)
    • just multiply v0 by 14142 and v1 by -14142
  6. divide both components of that vector by 1000000 (1 million)
    • why? in the last step, we multiplied numbers with 4 decimal places, which gave us numbers with 8!
    • so dividing by 1000000 - 106 - will bring us back to just 2 decimal places
  7. if the ball’s X is less than the paddle’s X, negate the X component of the vector
    • this “undoes” the abs from earlier
    • if you fail to do this, the ball will always bounce to the right, no matter where on the paddle it hits.
  8. set that computed vector as the ball’s velocity vector.

WHEW. That’s……… it. That’s all you need to do.

Assuming it works right, you’re done! And I’m done too, done writing these instructions! Thank god!

Submitting

Like labs 3 and 4, the gradescope won’t be able to test your program automatically. Unlike labs 3 and 4, it’ll be up long before the due date.