Goal

In this project, we hope you can use RISC-V programming to implement a game using Longan Nano board.

You have two options: Either you implement a Retro Snake game, or implement your own game if you want - except a pong game (the default game from last year).

Also, we will only provide the basic framework as in the Lab 11 starter - we expect that you should be capable of doing a project from scratch. Of course, the library functions are attached.

Getting started

Make sure you read through the entire webpage before starting the project.

You will be using gitlab to collaborate with your group partner. Autolab will use the files from gitlab. Make sure that you have access to gitlab. In the group CS110_Projects you should have access to your project 4 repository. Also, in the group CS110, you should have access to the p4_framework.

Hardware and Software setup

Refer to Lab 11 for details. The following is a quick navigator:

• Software setup
• Hardware setup

Obtain your files

1. Clone your Project 4 repository from GitLab.
2. In the repository add a remote repo that contains the framework files:
   git remote add framework https://autolab.sist.shanghaitech.edu.cn/gitlab/cs110_21s/p4-framework.git
3. Go and fetch the files:
   git fetch framework
4. Now merge those files with your master branch:
   git merge framework/master
5. The rest of the git commands work as usual.

Files

The framework contains the following files:

.
├── LICENSE
├── Makefile
├── README.md
├── dfu-util
├── include
│   ├── README
│   ├── fatfs
│   │   ├── diskio.h
│   │   ├── ff.h
│   │   ├── ffconf.h
│   │   └── tf_card.h
│   ├── gd32v_pjt_include.h
│   ├── gd32vf103_libopt.h
│   ├── lcd
│   │   ├── bmp.h
│   │   ├── lcd.h
│   │   └── oledfont.h
│   ├── systick.h
│   └── utils.h
├── platformio.ini
└── src
    ├── assembly
    │   └── example.S
    ├── fatfs
    │   ├── 00history.txt
    │   ├── 00readme.txt
    │   ├── ff.c
    │   ├── ffsystem.c
    │   ├── ffunicode.c
    │   └── tf_card.c
    ├── lcd
    │   └── lcd.c
    ├── main.c
    ├── systick.c
    └── utils.c

Please read src/utils.c, src/assembly/example.S, src/systick.c and src/lcd/lcd.c carefully. They contain helper functions and/or infomation that may not be mentioned in this webpage.

Retro Snake Game Introduction

The player controls a dot, square, or object on a bordered plane. As it moves forward, it leaves a trail behind, resembling a moving snake. In some games, the end of the trail is in a fixed position, so the snake continually gets longer as it moves. In another common scheme, the snake has a specific length, so there is a moving tail a fixed number of units away from the head. The player loses when the snake runs into the screen border, a trail, other obstacle, or itself.

There is an online demo here. For details, please refer to this link.

Here we provide a demo of Retro Snake game in Longan Nano for your reference. The 4 images shows a start menu, a help menu, a game play and a score board respectively. A video demo is shown below for your further understanding.

Requirements

Coding

We expect you to program something in RISC-V on a real machine - So we require that:

• You implement at least 3 RISC-V functions, and the total LoC is larger than 300 (comments excluded).
• For tidiness, please put all the assembly functions (.S files) in src/assembly. No other files or directories should appear in that folder.
• For assembly code: You need to have comments not less than 40% of the total lines of RISC-V code you wrote. A comment is defined by a sentence followed by #. Comments have to be meaningful and in English.
  • Actually, riscv-nuclei-elf-as allows you to write comments by using // and /* ... */; but we don't want you to do this for tidiness. Those comments will not count.
• The project can be successfully compiled via PlatformIO.

Game

There is no solid restriction for the Retro Snake game - the details of the game are up to you.

However, we're saying "Retro Snake Game" here - we expect that, if you want to implement a Retro Snake, at least your game should look like Retro Snake. We want your Retro Snake game to "look good" - Otherwise your score will be deducted.

The above has shown a online demo Retro Snake game and a implemented one in Longan Nano. Your Retro Snake game should more or less look like that. Here are a few basic requirements for a nice-looking Retro Snake game:

• The snake should be controled by at least 2 buttons, a turn left button and a turn right button.
• You need to design at least 2 kinds of food for your snake: one can lengthen the snake, while the other shorten the snake.
• The snake dies when it hits the wall, hits itself (or eat some poison food you design).
• When the snake dies, display a score board (which shows the length of the snake).
• You are required to implement at least a game play and a score board.

Hints

• Pick a proper data structure for your snake.
• When implementing RISC-V functions, recall the calling conventions that you've learned - which registers should be saved by th caller and which by the callee?
• Think twice before you write something - it is not convenient to debug on this board. We recommend you write a framework first, and add functionalities one by one.
• If you want to make use of advanced features of the board, here is a bunch of links that will help you:
  • Official document
  • Official download site (contains documents, specifications, HDK, SDK, etc)
  • Official example project (bad apple)
• If you face problems that can't be solved by your group, feel free to come to TAs' office hour for help.

Grading Policy

If you did not pass the check on Autolab, you will get zero score.

We will grade your project based on the latest commit that passed the Autolab check. You'll get 80% of score if you implemented a Retro Snake that works (can correctly respond to the button input, no matter ugly or not); you'll get the rest 20% if we think that your Retro Snake game is a nice-looking one.

Submission

Submit changes to your remote GitLab repo by running the following commands in your local repo folder:

$ git commit -a
$ git push origin master:master

How to Autolab

Similar to previous projects, upload your autolab.txt to Autolab to submit your project.

Submission Time Announcement

The last time of your submission to the git repo will count towards your submission time - also with respect to slip days. So do not commit to this git after the due date, unless you want to use slip days or are OK with getting fewer points.

Collaborative Coding and Frequent Pushing

You have to work at this project as a team. We invite you to use all of the features of gitlab for your project, for example branches, issues, wiki, milestones, etc.

We require you to push very frequently to gitlab. In your commits we want to see how the code evolved. We do NOT want to see the working code suddenly appear - this will make us suspicious.

We also require that all group members do substantial contributions to the project. This also means that one group member should not finish the project all by himself, but distribute the work among all group members!

At the end of Project 4 we will interview all group members and discuss their contributions, to see if we need to modify the score for certain group members.