Clementine - A collaborative approach to GBA emulation

Welcome to the first ripsters' project. Our goal is to understand how GameBoy Advance works and to create a modern emulator written in Rust (if you want to collaborate but you can't code in Rust take a look here).

Everything is work in progress. We will update this document a lot of times in this stage.

Collaborative Guidelines

We love collaborating with others, so feel free to interact with us however you want. First of all, we strongly suggest you to enter in our Discord channel where you can find all of us (here).

Contributing doc

Resources

Build and quick start

• clone the repository :)
• we are using just and not make then if you want take the benefit of this install it cargo install just

Tip: Run just to see all the available commands

# quick check all is working on you machine
just build
just test

# run a .gba file (debug build)
just run ~/Desktop/my_game.gba

Requirements

Before running the emulator, you need:

1. GBA BIOS file: A file named gba_bios.bin (16KB) placed in the directory where you run the emulator. This is the GBA boot ROM and is required for the emulator to function.

   Note: The BIOS path is currently hardcoded to gba_bios.bin in the current working directory.

2. A GBA ROM file: Any .gba ROM file you want to run.

Running the Emulator

Using Just Commands

| Command | Description | |---------|-------------| | just run <rom> | Run ROM in debug mode | | just run-release <rom> | Run ROM in release mode (better performance) | | just run-log <rom> | Run in debug mode with logging to file | | just run-release-log <rom> | Run in release mode with logging to file |

Examples:

# Run a game in debug mode
just run ~/roms/pokemon_emerald.gba

# Run with better performance (recommended for playing)
just run-release ~/roms/pokemon_emerald.gba

# Run with logging enabled (logs saved to temp directory)
just run-log ~/roms/pokemon_emerald.gba

Logging

When --log-to-file is passed, logs are written to clementine.log in your system's temp directory. The path is printed at startup.

Features

• ARM7TDMI CPU — ARM and Thumb instruction sets
• LCD rendering — Backgrounds (modes 0–5), sprites, windowing, color blending effects (alpha, brightness)
• Input — Keyboard-mapped GBA buttons
• Save/Load state — Versioned save states with integrity checks (ROM/BIOS excluded from serialization)
• Speed control — Adjustable emulation speed multiplier
• Pokemon tools — Party viewer, wild encounter patching (see below)

Pokemon Debugger

A built-in tool for Gen 3 Pokemon games (accessible from the sidebar). Supported games:

| Game | Region | ROM Code | |------|--------|----------| | Pokemon FireRed | US | BPRE | | Pokemon LeafGreen | US | BPGE | | Pokemon Emerald | US | BPEE | | Pokemon Ruby | US | AXVE | | Pokemon Sapphire | US | AXPE |

Party tab - View your party Pokemon (species, level, stats, moves, held items). The game version is auto-detected from the ROM header.

Wild tab - Force all wild grass encounters to a specific Pokemon species and level. Search/select any of the 386 Pokemon by name, set a level, and click "Patch All Encounters". This patches the ROM encounter tables in memory (not on disk), so it resets when the emulator restarts.

UI Tools

The emulator includes several debug tools accessible via the sidebar:

• Gba Display - Main game display (3x scale)
• Cpu Handler - Run/Pause/Step controls and breakpoints
• Cpu Registers - View ARM7TDMI register values
• Disassembler - Real-time disassembly of executed instructions
• Save Game - Save/Load state with version validation
• Pokemon Debugger - Party viewer and wild encounter cheats

Development

| Command | Description | |---------|-------------| | just build | Build the entire project | | just test | Run all tests across the workspace | | just lint | Run clippy with strict configuration | | just fmt | Format all code | | just check-fmt | Check formatting without modifying | | just clean | Clean build directory | | just doc | Generate and open documentation |

Documentation

The codebase is documented with Rust doc comments explaining how each component works. This is useful for understanding the GBA hardware and for contributors.

# Generate and open documentation in your browser
just doc

Architecture

The emulator uses a multi-threaded architecture:

• UI Thread: Runs the egui/eframe GUI at ~60fps
• CPU Thread: Runs the GBA emulation independently

Communication between threads uses lock-free SPSC (single-producer, single-consumer) channels for commands (UI -> CPU) and events (CPU -> UI).

Tests ROM

All tests + implementation are based on jsmolka/gba-tests.git + documentation in Wiki and online resources.

• [x] Thumb rom
• [x] ARM rom
• [x] Memory rom
• [x] Bios rom