Assignment 1: Pacman in MIPS
version: 1.0a last updated: 2023-06-27 17�45�00
You may find the Assignment 1 overview lecture to be a good starting point.
to give you experience writing MIPS assembly code
to give you experience translating C to MIPS
to give you experience with data and control structures in MIPS
Getting Started
Create a new directory for this assignment called pacman , change to this directory, and fetch the provided code by
running these commands:
$ mkdir -m 700 pacman
$ cd pacman
$ 1521 fetch pacman
If you’re not working at CSE, you can download the provided files as a zip file or a tar file.
This will add the following files into the directory:
pacman.s : a stub MIPS assembly file to complete.
pacman.c : a reference implementation of Pacman in C.
pacman_EOF.c : additional C file for testing.
input.txt : example input file.
Pacman: The Game
pacman.c is an implementation of Pacman, a classic arcade game.
An example game of Pacman can be seen to the right.
A game of Pacman takes place on a 2D grid, as the player tries to collect dots while avoiding ghosts!
Each turn, you can move up ( W ), left ( A ), down ( S ), or right ( D ). If you move onto a dot on the grid, that dot
becomes collected. Your goal is to collect all the dots. Each turn the ghosts also move, and if you run into a ghost the
game ends.
To get a feel for this game, try it out in a terminal:
$ dcc pacman_EOF.c -o pacman
$ ./pacman
https://cgi.cse.unsw.edu.au/~cs1521/23T2/assignments/ass1/provided.zip
https://cgi.cse.unsw.edu.au/~cs1521/23T2/assignments/ass1/provided.tar
https://en.wikipedia.org/wiki/Wikipedia:Stub
https://en.wikipedia.org/wiki/Pacman
$ 1521 mipsy pacman.s
Enter a non-zero number for the seed: 42
Welcome to 1521 Pacman!
The objective is to collect all the dots.
Use WASD to move.
Ghosts will move every time you move.
Touching them will end the game.
#############
#………..#
#.#########.#
#.#M#…….#
#.#####.###.#
#.#####.###.#
#.#.#…#M..#
#…..#…#.#
#############
You’ve collected 0 out of 53 dots.
Choose next move (wasd): # — CUT —
You have been provided with two files: pacman.c
and pacman_EOF.c
pacman.c is the file you should be translating into
MIPS. This implementation doesn’t handle EOF
correctly. When ^D is pressed, the program will enter
an infinite loop.
pacman_EOF.c correctly handles EOF. This has
been provided to make exploring the reference
implementation easier. You do not need to translate
this file (there are only small differences between it
and pacman.c).
You should read through pacman.c . There are comments
throughout it that should help you understand what the
program is doing — which you’ll need for the
next part of the assignment.
pacman.s: The Assignment
Your task in this assignment is to implement pacman.s in
MIPS assembly.
You have been provided with some assembly and some
helpful information in pacman.s . Read through the provided code carefully, then add MIPS assembly so it executes
exactly the same as pacman.c .
The functions get_seed and random_number has already been translated to MIPS assembly for you.
You have to implement the following functions in MIPS assembly:
print_welcome
get_direction
play_trick
get_valid_directions
check_ghost_collision
collect_dot_and_check_win
do_ghost_logic .
You must translate each function separately to MIPS assembler, following the standard calling conventions used in
lectures. When translating a function, you must not make any assumptions about the behaviour or side effects of any
other function which is called.
This assignment is split into four subsets. Later subsets will involve more complex translation.
Subset Functions Performance Weight
Subset 0 print_welcome 5%
[citation needed]
https://imgs.xkcd.com/comics/wikipedian_protester.png
Subset Functions Performance Weight
get_direction
get_valid_directions
check_ghost_collision
collect_dot_and_check_win
do_ghost_logic
Note that in print_map , the loop which iterates over ghosts does not need to be implemented until you begin
Running & Testing
To run your MIPS code, simply enter the following in your terminal:
$ 1521 mipsy pacman.s
Once you have finished your translation, to test your implementation, you can compile the provided C
implementation, run it to collect the expected output, run your assembly implementation to collect observed output,
and then compare them.
The game takes a lot of input, so it’s a good idea to write a file with the input you want to test, then pipe that into your
You have been given a file called input.txt as an example.
$ dcc pacman.c -o pacman
$ cat input.txt | ./pacman | tee c.out
$ cat input.txt | 1521 mipsy pacman.s | tee mips.out
$ diff -s c.out mips.out
Files c.out and mips.out are identical
Try this for different sequences of inputs.
You should implement all the functions from one subset before moving onto the next.
You may find the provided get_seed and random_number function implementations to be useful guidance for your
implementations including comments, label names, indentation and register usage.
Simplified C code
You are encouraged to simplify your C code to remove any loop constructs and if-else statements, and testing that
your simplified code works correctly before translating it to MIPS, in a separate file pacman.simple.c .
This file will not be marked – you do not need to submit it.
In order to allow you to ensure that your simplified code works correctly, we have provided a series of automated
You can run these tests by running the following command:
$ 1521 autotest pacman.simple
Assumptions, Clarifications, and Restrictions
Like all good programmers, you should make as few assumptions as possible.
Your submitted code must be hand-written MIPS assembly, which you yourself have written.
You may not submit code in other languages.
You may not submit compiled output.
You may not copy a solution from an online source. e.g. Github.
Your functions will be tested individually. They must exactly match the behaviour of the corresponding C function
and they must follow MIPS calling conventions.
The C code defines constants using #define . Your MIPS translation should use the corresponding provided named
constants, in the places where a #define is used in the C code. You should not use a #define constant in your
MIPS translation if it is not used in the corresponding part of the C code.
In the get_direction function, you may assume that all user input consists of either empty lines, or lines with
exactly one ASCII character. You do not need to handle end-of-file.
There will be a correctness penalty for assignments that do not follow standard MIPS calling conventions including:
Function arguments are passed in registers $a0 .. $a3 .
Function return values are passed in register $v0
Values in registers $s0 .. $s7 are preserved across function calls.
If a function changes these registers, it must restore the original value before returning.
The only registers’ values that can be relied upon across a function call are $s0 .. $s7 , $gp , $sp , and $fp .
All other registers must be assumed to be have, an undefined value after a function call, except $v0 which has
the function return value.
If you need clarification on what you can and cannot use or do for this assignment, ask in the class forum.
You are required to submit intermediate versions of your assignment. See below for details.
Change Log
Assessment
We have provided some automated tests to help you check the correctness of your translation. To run all the
provided tests, execute the following command:
$ 1521 autotest pacman
Some of these tests check only a specific function, and some test your whole program. To run run all the tests for a
specific function, pass the name of the function to autotest . For example, to run all the tests for the
print_welcome function, run the command:
$ 1521 autotest pacman print_welcome
You can also run all the autotests for a particular subset. For example, to run all the autotests for subset 0, run the
Version 1.0
(2023-06-12 12�00�00)
Initial release
Version 1.0a
(2023-06-27 17�45�00)
Updated late penalty. No change to provided code or autotests.
$ 1521 autotest pacman S0
To run the autotests which test your program as a whole, run the command:
$ 1521 autotest pacman whole_prog
To run all the subset 2 autotests for print_map (not involving ghosts):
$ 1521 autotest pacman print_map_S2
Whilst we can detect that errors have occurred, it is often substantially harder to explain what that error
The errors from 1521 autotest will be less clear and useful than in labs.
You will need to do your own debugging and analysis.
1521 autotest will not test everything. You are strongly encouraged to do your own testing.
Whilst the function autotests for subset 0, 1 and 2 check for your conformance to the MIPS calling
convention (‘strict’ autotests), the subset 3 autotests will not check whether your code follows the MIPS
calling convention. However, the marking tests will check for conformance to the MIPS calling convention.
This means that it is very important that you check yourself that your code follows the MIPS calling
convention, particularly for your subset 3 code.
Submission
When you are finished working on the assignment, you must submit your work by running give :
$ give cs1521 ass1_pacman pacman.s
You must run give before Week 5 Friday 20�00�00 to obtain the marks for this assignment. Note that this is an
individual exercise, the work you submit with give must be entirely your own.
You can run give multiple times.
Only your last submission will be marked.
If you are working at home, you may find it more convenient to upload your work via give’s web interface.
You cannot obtain marks by emailing your code to tutors or lecturers.
You can check your latest submission on CSE servers with:
$ 1521 classrun check ass1_pacman
You can check the files you have submitted here.
Manual marking will be done by your tutor, who will mark for style and readability, as described in the Assessment
section below. After your tutor has assessed your work, you can view your results here; The resulting mark will also
be available via give’s web interface.
This assignment is due Week 5 Friday 20�00�00 (2023-06-30 20�00�00).
https://cgi.cse.unsw.edu.au/~give/Student/give.php
https://cgi.cse.unsw.edu.au/~cs1521/23T2/student/
https://cgi.cse.unsw.edu.au/~cs1521/23T2/student/
https://cgi.cse.unsw.edu.au/~give/Student/sturec.php
The UNSW standard late penalty for assessment is a reduction of the maximum achievable mark (the ‘ceiling’) by 5%
per day for 5 days – this is implemented hourly for this assignment.
The maximum achievable mark for your submission will be reduced by 0.2% for each hour (or part thereof) late past
the submission deadline.
For example, if an assignment worth 96% was submitted 3 hours and 59 minutes late, it would still receive 96% – as
the ceiling would be at 99.2%, whereas if it was submitted 22 hours and 59 minutes late, it would be awarded 95.4%.
Beware – submissions 5 or more days late will receive zero marks. This again is the UNSW standard assessment
Assessment Scheme
This assignment will contribute 15 marks to your final COMP1521 mark.
80% of the marks for assignment 1 will come from the performance of your code on a large series of tests.
20% of the marks for assignment 1 will come from hand marking. These marks will be awarded on the basis of clarity,
commenting, elegance and style. In other words, you will be assessed on how easy it is for a human to read and
understand your program.
An indicative assessment scheme for performance follows.
The lecturer may vary the assessment scheme after inspecting the assignment submissions, but it is likely to be
broadly similar to the following:
100% for performance implements all behaviours perfectly,
following the spec exactly.
90% for performance implements all behaviours perfectly,
but doesn’t conform to the MIPS ABI
75% for performance implements all simple and
all moderate difficulty functions correctly.
65% for performance implements all simple and
some moderate difficulty functions correctly.
≤ 50% for performance good progress,
simple functions work correctly.
An indicative assessment scheme for style follows.
The lecturer may vary the assessment scheme after inspecting the assignment submissions, but it is likely to be
broadly similar to the following:
100% for style perfect style
90% for style great style, almost all style characteristics perfect.
80% for style good style, one or two style characteristics not well done.
70% for style good style, a few style characteristics not well done.
60% for style ok style, an attempt at most style characteristics.
≤ 50% for style an attempt at style.
An indicative style rubric follows.
The lecturer may vary the assessment scheme after inspecting the assignment submissions, but it is likely to be
broadly similar to the following:
Formatting (8/20):
Whitespace
Indentation (consistent, tabs or spaces are okay)
Line length (below 120 characters unless very exceptional)
Line breaks (using vertical whitespace to improve readability)
Documentation (12/20):
Header comment (with name, zID, description of program)
Function comments (above each function with a description)
Sensible commenting throughout the code
Descriptive label names, indicating structure
Note that the following penalties apply to your total mark for plagiarism:
assignment 1
knowingly providing your work to anyone
and it is subsequently submitted (by anyone).
submitting any other person’s work; this includes joint work.
misconduct
submitting another person’s work without their consent;
paying another person to do work for you.
Intermediate Versions of Work
You are required to submit intermediate versions of your assignment.
Every time you work on the assignment and make some progress you should copy your work to your CSE account
and submit it using the give command below. It is fine if intermediate versions do not compile or otherwise fail
submission tests. Only the final submitted version of your assignment will be marked.
Assignment Conditions
Joint work is not permitted on this assignment.
This is an individual assignment. The work you submit must be entirely your own work: submission of work even
partly written by any other person is not permitted.
Do not request help from anyone other than the teaching staff of COMP1521 — for example, in the course forum,
or in help sessions.
Do not post your assignment code to the course forum. The teaching staff can view code you have recently
submitted with give, or recently autotested.
Assignment submissions are routinely examined both automatically and manually for work written by others.
Rationale: this assignment is designed to develop the individual skills needed to produce an entire working
program. Using code written by, or taken from, other people will stop you learning these skills. Other CSE
courses focus on skills needed for working in a team.
The use of code-synthesis tools, such as GitHub Copilot, ChatGPT, Google Bard, etc. are not permitted on
this assignment.
COMP1521 23T2: Computer Systems Fundamentals is brought to you by
the School of Computer Science and Engineering
at the University of New South Wales, Sydney.
For all enquiries, please email the class account at
CRICOS Provider 00098G
Rationale: this assignment is designed to develop your understanding of basic concepts. Using synthesis tools
will stop you learning these fundamental concepts, which will significantly impact your ability to complete future
Sharing, publishing, or distributing your assignment work is not permitted.
Do not provide or show your assignment work to any other person, other than the teaching staff of COMP1521.
For example, do not message your work to friends.
Do not publish your assignment code via the Internet. For example, do not place your assignment in a public
GitHub repository.
Rationale: by publishing or sharing your work, you are facilitating other students using your work. If other
students find your assignment work and submit part or all of it as their own work, you may become involved in
an academic integrity investigation.
Sharing, publishing, or distributing your assignment work after the completion of COMP1521 is not
permitted.
For example, do not place your assignment in a public GitHub repository after this offering of COMP1521 is over.
Rationale: COMP1521 may reuse assignment themes covering similar concepts and content. If students in future
terms find your assignment work and submit part or all of it as their own work, you may become involved in an
academic integrity investigation.
Violation of any of the above conditions may result in an academic integrity investigation, with possible penalties up
to and including a mark of 0 in COMP1521, and exclusion from future studies at UNSW. For more information, read
the UNSW Student Code, or contact the course account.
https://www.cse.unsw.edu.au/
https://www.unsw.edu.au/
https://www.gs.unsw.edu.au/policy/documents/studentcodepolicy.pdf