| Mode | Name | Size | |
|---|---|---|---|
| -rw-r--r-- | .gitignore | 57 | logstatsplainblame |
| -rw-r--r-- | Makefile | 513 | logstatsplainblame |
| -rw-r--r-- | README.md | 2754 | logstatsplainblame |
| d--------- | src | 475 | logstatsplain |
gbc — a Game Boy Color emulator in C, rendered to the terminal
A from-scratch Game Boy / Game Boy Color emulator written in plain C11. It
renders graphics directly to the terminal using 24-bit (truecolor) ANSI escape
codes and the Unicode upper-half-block trick (▀): each character cell packs
two vertical pixels (foreground = top pixel, background = bottom pixel),
giving a 160×144 GB screen in 160×72 terminal cells.
Build & run
make
./build/gbc path/to/rom.gb # interactive
./build/gbc rom.gb --test 30 # headless: run 30s, log serial (test roms)
./build/gbc rom.gb --shot 60 out.ppm # run 60 frames, dump a PPM screenshot
Requires a truecolor-capable terminal (COLORTERM=truecolor) at least
160 columns wide.
Controls
| Key | Button |
|---|---|
| arrows / WASD | D-pad |
z / j |
A |
x / k |
B |
| enter | Start |
| space | Select |
q / Ctrl-C |
Quit |
Since terminals don't report key-release, buttons are held for a few frames after each keypress (relying on the terminal's key-repeat for sustained holds).
Architecture
| File | Responsibility |
|---|---|
types.h |
fixed-width integer typedefs |
cart.c |
ROM loading, header parsing, MBC1/2/3/5, battery saves |
gb.c |
system bus / memory map, joypad, OAM-DMA, HDMA/GDMA, reset |
cpu.c |
Sharp SM83 core (full opcode set, cycle-accurate accesses) |
timer.c |
DIV/TIMA/TMA/TAC with falling-edge accuracy |
ppu.c |
LCD controller, scanline renderer (BG/window/sprites), CGB |
render.c |
terminal truecolor output + raw-mode keyboard input |
main.c |
argument parsing, frame loop, timing, screenshot/test modes |
Emulation status
Passing:
- blargg
cpu_instrs— all 11 sub-tests - blargg
instr_timing - blargg
mem_timing— all 3 - dmg-acid2 — PPU test renders correctly
- cgb-acid2 — CGB PPU test renders correctly
Implemented:
- Full SM83 CPU incl. HALT bug, EI delay, interrupt dispatch
- Accurate timer edge behavior
- PPU modes 0–3, STAT/LYC/VBlank interrupts, window line counter
- CGB: double VRAM banks, BG/OBJ color palettes, tile attributes, master priority, WRAM banking, double-speed (KEY1), HDMA/GDMA
- MBC1/2/3/5 with RAM banking and battery
.savfiles
Not yet implemented:
- APU (audio) — registers are stubbed
- MBC3 RTC advancement
- Sub-instruction PPU FIFO timing edge cases
License
For educational use. Test ROMs are downloaded separately and not included.