Pac-Man: architecture spec

What each module is, what crosses between them, where every bit of state lives, and the budgets (clocks per frame, memory, logic). Written for someone who will change the design or build the next game on it.

Contents

1. Requirements
2. Modules and hierarchy
3. Clock domains and crossings
4. Coordinate system and screen geometry
5. Memories and tables
6. pac_logic: state, sequencer, encodings
7. pac_draw: the pixel pipeline
8. pac_sound
9. Board I/O and the USB protocol
10. Budgets
11. Design decisions

Requirements

• The arcade Pac-Man's maze, dots, power pellets, four ghosts with the arcade's targeting and mode timing, frightened mode, eyes returning home, lives, levels with rising speed, a high score, the intro tune and effects.
• Runs on the DE10-Lite with the LCD / game-pad shield, from the library's display chain (VGA pins and LCD together).
• Playable by a person with the joystick and Start, and by the AI over USB (letters), so it can be tested without hands.
• The screen can be read back over USB (debug_link) for automatic checks.
• Fits comfortably in the MAX 10 10M50 with the debug capture buffer: under 25 % logic, under 70 % memory.
• Fully testable in simulation: a testbench renders frames and plays the game.

Modules and hierarchy

pacman_top                      board level, 25/50/100 MHz
├─ pll25 (lib)                   50 MHz in → 25, 50, 100 MHz, locked
├─ Screens_dispaly (lib)         VGA timing (pxl_x, pxl_y, sync) + LCD copy
├─ gamepad (lib) + adc IP        the shield's joystick and buttons, 50 MHz
├─ debounce (lib)                8 buttons, 5 ms steady
├─ pac_logic                     the game
│  ├─ maze_tiles  (q_tiles)      tile table, query port (walls)
│  ├─ maze_tiles  (f_tiles)      tile table, fill port (dots, power)
│  └─ dots[1024]                 inferred dual-port RAM, 2 bits
├─ pac_draw                      the picture
│  ├─ walls[61440]               inferred ROM, 2 bits ($readmemb assets/walls.bin)
│  ├─ ghost_sprite ×4            14 × 14 ghost, colour parameter
│  └─ font8x8 (lib)              8 × 8 glyphs, ASCII 0x20..0x5F
├─ pac_sound                     the buzzer
├─ seven_segment ×6 (lib)        BCD score
├─ debug_link (lib)              '?' status, 'F' frame dump; the rx stream is shared with the game's letters
└─ jtag_uart (lib)               the USB link (alt_jtag_atlantic)

pac_logic ports

Clock domains and crossings

The JTAG UART's rx_valid is a 25 MHz pulse. The game's letters are decoded in pacman_top; 's' is held in a register until the next tick so the game, which samples start only at ticks, cannot miss it.

Coordinate system and screen geometry

Memories and tables

Both big memories answer one clock after the address. The screen therefore computes the address from the next scan pixel (pxl_x + 1) and uses the answer for the current one; the wall lookup and the dot lookup both work this way, so no pixel is shifted. The testbench primes each line by starting at pxl_x = -1.

pac_logic: state, sequencer, encodings

Per-actor registers

Five actors, index 0 Pac-Man, 1 Blinky, 2 Pinky, 3 Inky, 4 Clyde: ax, ay (8-bit maze pixels), ad (2-bit direction), acc (5-bit speed accumulator, sixteenths), gst (3-bit ghost state), gfr (frightened).

Game state (gs) and its timer (gtimer, frames)

The micro-sequencer (ms)

Started by a tick in G_PLAY. One actor (a) at a time; the actor's registers are copied into working registers cx, cy, cd, cst and written back in M_DONE after every pixel step.

Longest frame: 5 actors × 2 steps × about 12 clocks + 4 + 1 ≈ 130 clocks. Vertical blank is 36,000.

Numbers that tune the game

pac_draw: the pixel pipeline

Purely combinational from (pxl_x, pxl_y) and the game's registers, plus the two memories addressed one pixel ahead. For every pixel, in priority order:

1. Ghosts (Blinky in front): ghost_sprite gives hit and a colour. The body is a 14-row bitmap with two skirt frames (frame[3]); eyes are two 4 × 5 whites shifted a pixel toward the direction with 2 × 2 pupils; frightened: blue body, a wavy mouth, white/red while flashing; EYES / ENTER: only the eyes.
2. Pac-Man: a 13-pixel disc on half-pixel centres (dx2 = 2(mx - x) + 1, dx2² + dy2² ≤ 169) minus a wedge: the pixel is in the mouth when a·sin(t) > |b|·cos(t), with (a, b) the pixel rotated into the facing direction and t the half-opening (0°, 25°, 45° by pac_mouth; 15°..180° by death_phase while dying). Products go through 12-bit wires: the compare would otherwise be done at 6 bits.
3. Text: one font8x8; the character comes from the panel tables (screen grid) or the maze messages (READY!, GAME OVER, PUSH START on tile row 17). Numbers are BCD digits with leading zeros blanked, the last two always shown.
4. Spare-life icons: small left-facing Pac-Men, one per spare life.
5. Dots (2 × 2 at the tile centre) and power pellets (a 7-pixel disc, blinking) from rb_q.
6. Walls from the ROM: blue, white while maze_white; the door pink.

pac_sound

A square wave: a 16-bit counter toggles the output when it reaches half (clocks per half period at 25 MHz, half = 25e6 / (2f)). half is chosen once per frame from the highest-priority effect still running: death (96 frames, falling with a warble), the intro tune (31 notes, {half, frames} table, 256 frames), ghost eaten (30 frames, rising), power pellet (40 frames, two low notes), dot (6 frames, two notes whose order alternates: "waka"). 'm' mutes. The output drives ARDUINO_IO[12], the shield's buzzer line.

Board I/O and the USB protocol

Budgets

Design decisions

• No frame buffer for the game. The picture is computed per pixel from a few hundred bits of state; the only memories are the static wall picture and the 2-bit dot map. Cheap, and nothing can tear.
• Sequential game update. One actor and one pixel per few clocks instead of parallel per-actor logic: a fifth of the logic, one tile-table port, and a state machine you can single-step in a waveform.
• BCD everywhere a number is shown. Score, high score and level never need a divider; the screen and the 7-segment read the same digits.
• Tables generated by Python. The maze is a 31-line text picture in make_maze.py; it writes the Verilog table, the wall picture (with the arcade's inset double lines computed from distance to open tiles) and a preview PNG. Edit the text, run the script, rebuild.
• Letters over USB. Five lines of decode in the top make the whole game testable by a machine.
• Kept out, on purpose: the fruit, the pop-up score, the demo in attract mode. They are easy additions and are listed on the overview page.