Technical Background

You will create this game using the MIPS assembly language taught in class and the MARS. However, there area few concepts that we will need to cover in more depth here to prepare you for the project: displaying pixels, taking keyboard input and system calls (syscall).

Displaying Pixels Using a Framebuffer

To display things on the screen, we will use a framebuffer: an area in memory shown as a 2D    array of “units”,where each “unit” is a small box of pixels of a single colour. Figure 1on the right  shows a framebuffer of width 10 and height 8 units.

Units arestored as an array in memory: every 4-  byte word in that array is mapped to a single on- screen “unit”. This is known as a framebuffer, because the buffer (the region of memory) controls what is shown on the display. The address of this frame buffer array is the base address of the display. The unit at the top-left corner of the bitmap is located at the base address, followed by the rest of the top row in the subsequent locations in memory. This is followed by the units of the second row, the third row and so on (referred to as row major order).

•   Set the dimensions of the overall display: in the example above the framebuffer is of size 32x32 units, since we configured the bitmap display to have width and height of 256 pixels, and units   of 8x8 pixels. Make sure the sizes match your assembly code.

•   Tell MARS the base address for the framebuffer in hexadecimal. In screenshot above, this is memory location 0x10008000 in the screenshot. This means that the unit in the top-left corner is at address 0x10008000, the first unit in the second row is at address 0x10008080 and the unit in the bottom right corner is at address 0x10008ffc .

• Remember to click “Connect to MIPS” so that the tool connects to the simulated CPU.

Tip: We recommend using 0x10008000 as the base address for your framebuffer, but only if your framebuffer has 8192 cells or fewer, which is enough for 128x64 or 64x128 (if you want a larger framebuffer, ask us on Piazza; you’ll have to add avariable at the beginning of the .data section). When using the Bitmap Display, make sure to change the “base location of display” field. If you set it to the default value (static data) provided by the Bitmap Display dialog, this will refer to the " .data" section of memory and may cause the display data you write to overlap with instructions that define your program, leading to unexpected bugs.

Bitmap Display Starter Code

To get you started, the code below provides a short demo, painting three units at different locations with different colours. Understand this demo and make it work in MARS.

The assembly directive  .eqv defines a numeric constant which you can use instead of writing the number manually (similar to #define in C, but much more primitive) You can use it to define common useful constants such as fixed addresses, colours, number of enemies, etc.

Keyboard

This project will use the MARS Keyboard and

MMIO Simulator to take in these keyboard inputs (Tools Keyboard and MMIO Simulator). To use it when playing, make sure to click inside the lower window titled “KEYBOARD”. As with the bitmap display, remember to “Connect to MIPS” .

Note we cannot use system calls to read the keyboard input, because syscalls will block your program from executing (they are also slower).

Note the MARS simulator does not support pressing multiple keys at the sametime, which you may need to think about when implementing jumps to left and right.

...and then, to run and test your program:

4.  Run > Assemble (see the memory addresses and values, check for bugs)

5.  Run > Go (to start the run)

6.  Input the character a or  d orw or s in Keyboard area (bottom white box) in Keyboard and Display MMIO Simulator window.

Code Structure

Your code should store the location of the player character and other entities (and any other information you need) in memory or registers. We particularly recommend arrays for storing things like enemies. Make sure to determine what values you need to store and label the locations in memory where you’ll be storing them (in the  .data section)

At the beginning of your program, clear the screen and initialize the state of the game. You will then   switch to a central processing loop of the game (the “main loop”). Everyone’s main loop looks a little    different, but in general your loop will eventually need to do most if not all of the following operations (not necessarily in this order!):

•   Check for keyboard input.

•    Figure out if the player character is standing on a platform.

•    Update player location, enemies, platforms, power ups, etc.

•   Check for various collisions (e.g., between player and enemies).

•    Update other game state and end of game.

•    Erase objects from the old position on the screen.

•    Redraw objects in the new position on the screen.

At the end of each iteration, your main loop should sleep for a short time and go back to step 1.

Sleep and Display Refresh Rate

For animations, we generally need to update the display between 20 to 60 times per second (we recommend sleeping for 40ms, at least initially, which is a 25Hz update rate). When developing your game, you may find it occasionally useful to set it to a very high number to help debugging. We recommend using a constant (.eqv) to make it easy to change the wait time.

Make sure to choose your display size and frame rate pragmatically. The simulated MIPS processor isn't very fast. If you have too many pixels on the display and too high a frame rate, the processor will have trouble keeping up with the computation. If you want to have a large display and fancy graphics in your game, you might consider optimizing your way of repainting the screen so that it does incremental updates instead of redrawing the whole screen; however, that maybe quite a challenge! Moreover, sleep time can affect the speed and difficulty of your game.

Tip: Your display may flicker (blink on and off) because it takes sometime between erasing an object and redrawing it at the new position. There are all kinds of ways to prevent this, but some of them require special hardware. You can prevent flicker by carefully erasing and/or redrawing only the parts to the frame buffer that have changed but this requires some effort. We are not marking you based on the smoothness of the display, as long as the game is reasonably playable, so don’t worry about it.

See Marking below.

General Tips for Success

1.   Prototype and build in stages. Start withdrawing a square on the screen. Then animate it moving move across the screen by adjusting its position every frame and redrawing in a loop.     Then add keyboard controls for the position, and perhaps simple rules about not moving across the edges or through platforms. Then add gravity, and soon.

2. Choose storage wisely. Most of your variable will be stored in memory (.data), because you only have a few registers, and they are not going to be enough for allocating all the different variables that you'll need for keeping track of the state of the game. Use the ".data" section (static data) of your code to declare as many variables as you need. In particular, arrays are very useful. Nevertheless, it might make sense to devote a few registers to very common variables or values that you need! Calling conventions can help you there.

3. Create reusable functions for code that you reuse frequently. Instead of copy-pasting, write a function. Design the interface of your function (input arguments and return values) so that the function can be reused in a simple way.

4. …but pay attention to performance. Calling functions comes at a cost. Use functions when you need to (using the same code many times), but not when you don’t. Think about calling conventions that make sense for you and are efficient. For example, you may be able to avoid using the stack entirely!

5. Flicker and clearing the screen. It is usually best to avoid erasing and redrawing the entire screen every frame. It is a slow process and will cause lots of flickering. It is better to just erase the part you need to erase. The more time that passes between erase and redraw, the more flickering you will have.

6. Create meaningful labels. Meaningful labels for variables, functions and branch targets will make your code much easier to debug.

7. Write comments. Without proper comments, assembly programs tend to become incomprehensible spaghetti alarmingly quickly, even for the author of the program. It would be in your best interest to keep track of registers, variables, and stack pointers (if you use it) relevant to different components of your game.

8. Start small and build upwards. Don’t try to implement your whole game at once. Assembly programs are notoriously hard to debug, so add each feature one at a time and test them. Always save the previous working version before adding the next feature. Use source control (Git, SVN, etc.).

Features, Milestones, and Marking

Projects are individual. This assignment is worth 17 points. 8 will be evaluated during the checkpoint demoon the last week of classes depending on your progress, and the other 9 will be for the functionality of your final submission. To better give you a sense of progress, the project is broken down into 3 milestones as follows. For milestones 1 and 2 you need to implement all features; for milestone 3 you choose a set of features to implement.

1.   Milestone 1: basic graphics [3 marks]

A. Draw the level (platforms, ladders if you have them, etc.). Your game’s display resolution (framebuffer size) should beat least 64 units high and 64 units wide. Make   sure to include at least 3 platforms the player would be able to stand on (that could for example mean 2 floating platforms plus a floor).

B. Draw the player character: it needs to beat least 3 framebuffer units big (more is allowed).

C.   Draw at least 2 additional objects that are not platforms other than the player and the level itself (more is allowed!). These can be enemies, pickups,a mixture of both, or anything similar that makes sense. Each object needs to beat least 3 framebuffer units big (more is allowed).

2.   Milestone 2: basic controls [5 marks]

A. Player can move the player character left/right around the platform using the movement keys. Make sure the player cannot move past the edges of the screen! Optional exception: you may choose to allow the player to momentarily be above the top of the screen during a jump. You will need to account for this when drawing the player character (it should be clipped by the top of the screen, meaning drawn partially).

B. Platform collision and gravity: the player can stand on a platform but will fall down if moving off a platform. If the player falls down on another platform, they will not go through; you need to detect and handle “collision” between player and platforms. You also need to handle the case where a player falls off the edge of the screen (unless you add a “floor”). This can be handles as an “endgame” condition (see Milestone 3).

C.   Vertical movement: the player can navigate to (then move around on) at least 3 different platforms (including the one they are standing on initially). This can be done by jumping up to platforms and dropping down from them. You may choose instead alternative mechanisms such as going up and down ladders for navigation, and that’sok (see Donkey Kong example). Again, make sure the player is actually able to get to at least 3 platforms.

D. Collision with objects: the game must detect when a moving object touches the player (or viceversa). There are several ways to do this, and you don’t have to be 100% accurate as long as they are very close. You also need to handle collisions appropriately and give some feedback to the player. For example, if it’san enemy you could change the player character color to indicate the collision, and also reduce the player’s health or end the game. If it’sa pick-up, you could make it vanish and perhaps increase the score. E. Allow restarting the game at any point by pressing the p key on the keyboard.

ð In your checkpoint session, you need to demonstrate to your TA a working implementation of the first two milestones; see Basic Demo above for what that might look like. In addition, you  will need to have at least started on the other milestones.

3. Milestone 3: additional features and polish

Choose and implement enough features from the list below, each is worth some marks. Your preamble and video should list specifically what features you implemented, and you need to  demonstrate them in the video.  To get full marks on this milestone, you will need to implement features with a total of at least 9 marks (assuming you got all the marks for milestones 1 and 2). Note you cannot “make up” for missing features of previous milestones. In other words, you can only make at most 9 marks from milestone 3.

A. Health/score [2 marks]:  track and show the player’s health and/or score onscreen during the game. You must show the score on the screen during play and on the game- over screen for this to count. You can do this in many ways: a numeric score,a bar, or hearts that disappearwhen the player gets hurt. Score can be based on pick-ups, jumping on top of enemies, or any idea you may have.

B. Fail condition [1 mark]: the player should be able to fail the game, and you then show    an appropriategame overscreen. Failure could becaused by the player health dropping to zero, falling off the edge of the screen, or failing to meet a time limit – up to you. Don’t make the game too hard!

C. Win condition [1 mark]: the player can win the game and there is a“you won!” screen when the goal is achieved. For example, collecting all the floating coins, or getting a specific pick-up. It’s OK to make the game easy if you want, but try not making it so easy that you can’t demonstrate important features.

D. Moving objects [2 mark]: have the enemies/pickups move around the level. This entails continually redrawing the relevant parts of the screen with the appropriate assets. For    example, perhaps enemies patrol left and right across on the platform they are on, or object pickups hovering gently up and down, orannoying, flying batstrying to hit the player.

E. Moving platforms [2 marks]: some of the platforms might be moving around, making it more challenging for the player to reach them.

F. Disappearing platforms [1 mark]: some of the platforms disappear and reappear over time. Note this is considered similar to moving platform, so if you implement both features you will only get 2 marks. A variation of this is bubble platforms: when the player touches the bubble, the bubble pops and player gets a boost up. The bubble will reappear after sometime