ECE243 Final Project: Doudizhu on DE1-SoC

ECE243 Computer Organization (W26)

Authors

• Emma Le
• Peng Yang (Jonathan) Deng

Overview

This project brings Doudizhu (斗地主), a three-player Chinese card game, onto the DE1-SoC FPGA board. The final board-facing build supports the full main gameplay loop: startup screen, bidding, turn-based play, round resolution, audio feedback, and a persistent scoreboard across rounds.

The repository is split into two major parts:

• libdoudizhu/: a portable C11 game engine that handles rules, move classification, bidding, scoring, and bot play
• src/: the DE1-SoC integration layer, including VGA rendering, PS/2 keyboard input, audio, timers, and the board entry point

Features

• portable Doudizhu rules engine packaged as a reusable library
• bot opponents supplied by the libdoudizhu submodule
• board-side VGA UI for the full gameplay loop
• PS/2 keyboard-driven interaction model
• audio feedback tied to major game events
• isolated unit / demo targets for individual hardware subsystems

Gameplay Flow On Board

The board executable in src/main.c follows this loop:

1. Show the help screen and wait for Enter
2. Deal a new round and sort the human player's hand
3. Run bidding until a landlord is chosen
4. Run the main play phase with one human player and two bots
5. Apply round scoring and show the round-finish screen
6. Wait for Enter, then start the next round while keeping cumulative scores

Controls

The keyboard driver currently supports:

• Left / A: move left
• Right / D: move right
• Up / Down / W / S: toggle card selection
• Enter: confirm bid, play selected cards, pass, or continue from splash / results screens

During bidding, left and right cycle through available bid options and Enter confirms the current selection. During play, selecting no cards and pressing Enter submits a pass.

Screenshots

Startup / Help Screen

Startup screen shown before gameplay begins. This is the first screen players see on the DE1-SoC display.

Bidding Screen

Bidding screen shown before gameplay beings. This is where the player and bots bid for control of the landlord.

Main Gameplay Screen

Main in-game board state showing the player's hand, opponent HUD, centre play area, and current round status.

Round Result Screen

End-of-round results screen showing the winner and updated running scores before the next round starts.

Repository Layout

Path	Purpose
README.md	Top-level project overview
CMakeLists.txt	Root build configuration
riscv32-toolchain.cmake	DE1-SoC RISC-V cross-compilation setup
rvgcc-toolchain.cmake	Alternate RISC-V cross-compilation setup
libdoudizhu/	Portable Doudizhu rules engine and bot library
src/io/	DE1-SoC hardware interface modules
src/units/	Board-side and host-side unit / demo targets
src/other/	Shared addresses and helper utilities
src/main.c	Main board-side gameplay loop

Build Requirements

To build this project, you need:

• CMake 3.3 or newer
• Ninja or Unix Makefiles
• a C11-compatible compiler

For DE1-SoC builds, you also need the RISC-V toolchain referenced by riscv32-toolchain.cmake.

Before building, initialize the game-engine submodule if needed:

git submodule update --init --recursive

Building On Linux

Debug Build

mkdir cmake-build-debug-linux
cd cmake-build-debug-linux
cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja ..
cmake --build .

Release Build

mkdir cmake-build-release-linux
cd cmake-build-release-linux
cmake -DCMAKE_BUILD_TYPE=Release -G Ninja ..
cmake --build .

Building For The DE1-SoC RISC-V Target

mkdir cmake-build-riscv
cd cmake-build-riscv

# Ninja
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../riscv32-toolchain.cmake -G Ninja ..
cmake --build .

# Or Unix Makefiles
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../riscv32-toolchain.cmake -G "Unix Makefiles" ..
cmake --build .

When cross-compiling, the board-facing targets are emitted as .elf files. The main game target is FinalProject.elf.

Running Targets

To actually run the game, you must use the DE1-SoC RISC-V build, specifically with the riscv32-toolchain.cmake setup.

# After building, the target FinalProject.elf should be in your directory
# Rename the binary to output.elf - the Makefile looks for this.
mv FinalProject.elf output.elf

# In one powershell terminal, run the following:
./gmake DE1-SOC
./gmake gdb_server

# Afterwards, run the following in a second terminal:
./gmake gdb_client

# Use the continue command to start execution
c

Running Tests

Game Logic Tests

The core rules and bot tests live in libdoudizhu and can be run from a Linux build directory:

cd cmake-build-debug-linux
cmake --build . --target all
ctest

Relevant test binaries include:

• test_moves
• test_game
• test_bot
• test_eval

If bot tuning is enabled with -DDOUDIZHU_TUNING=ON, the project also builds test_selfplay.

Board / IO Targets

The board-facing hardware tests live in src/units and should be built with the RISC-V toolchain, then run on the DE1-SoC or in Cpulator.

cd cmake-build-riscv
cmake --build . --target all

Relevant targets include:

• AudioTest.elf
• DisplayTest.elf
• KeyboardTest.elf
• TimerTest.elf
• MainTest.elf

Host-Side Utility / Logic Tests

These host-side targets are useful for validating non-board-specific behavior:

• FontTest
• DisplayLogicTest
• HexDispTest