Gameboy Advance emulator.


Alt text


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).

In this section we are writing some basic guidelines to organize better this project.


You can open an issue to ask any question about everything related to the project. Someone will answer to you as soon as possible.

🔨 Feature

These kind of issues should be used to manage the project. So only mantainers can open a new feature issue. If you would like to take a task on your own, ask for it and someone will assign it to you.

🐞 Bugs

Open an issue if you find a bug. Try to describe as best as possibile the use case in which the bug appears.


Share with us your ideas about how the project could evolve.

↩️ PR

Pull Requests have to be linked to an issue. You need to describe as best as you can what you have done.

Keep in mind that in this early stage some kind of stuff could be a mess: we are still organizing ourselves.


We are using many resources. You can find them on our Discord Server.

  • CPSR: Add tests for `sign_flag` and `overflow_flag`

    CPSR: Add tests for `sign_flag` and `overflow_flag`

    I wrote a test for 0xAAAA representation and another for 0xAAAAAAAA representation. All those made with 0xAAAA fail and those with 0xAAAAAAAA.

    P.N. I used the hex notation for the condition to make the error more explicit. I will convert it to binary.

    Signed-off-by: Federico Bruzzone [email protected]

    opened by FedericoBruzzone 9
  • Palette visualizer

    Palette visualizer

    Closes #89

    I also added a feature "debug" to put random values in the palette_ram. In can be useful to use this features also to some hard coded test for the render process.

    To run clementine in debug mode you just need to run the command: just debug *rom_path/rom.gba*

    opened by gallottino 7
  • cartridge_headers: Add all cartridge headers

    cartridge_headers: Add all cartridge headers

    All the cartridge header implementations have been added to the file. (#17)

    Keep in mind: 1. BIOS must be able to overwrite the boot_mode header, as defined in the extract_boot_mode function comments; 2. BIOS must be able to overwrite the slave_id_number header, as defined in the extract_slave_id_number function comments; 3. If the GBA has been booted by using Joybus transfer mode, we have to put our initialization procedure directly at joybus_mode_entry_point address, or redirect to the actual boot procedure by depositing a "B " opcode in the space used by joybus_mode_entry_point.

    opened by FedericoBruzzone 7
  • Convert HEX values to BIN - Inconsistency in the format of numbers

    Convert HEX values to BIN - Inconsistency in the format of numbers

    Many values are written in hexadecimal format (like 0x0B_00_00_00), and a few others in binary format (like 0b1110_1010_0000_0000_0000_0000_0111_1111). It would be useful to standardize all values in binary, for readability reasons.

    However, I think it is better to close #33 first because it would allow the removal of many values.

    good first issue 
    opened by AlessandroGrassi99 6
  • Refactor of the Cartridge struct

    Refactor of the Cartridge struct

    CartridgeHeader is now in the "Cartridge" file along with the "Cartridge" struct, which is respondible to take raw data and turn it in header fields and ROM (most of the fields are missing at the moment)

    Cartridge takes the ROM data under the "rom" field in a reference counted ptr, so the type inside the ARM7TDMI implementation of the CPU was modified

    opened by simo498 6
  • Add new logger

    Add new logger

    • Logger: Add new logger for clementine
    • Everywhere: Use logger in the code with a special arg --log-on-file

    Basically the feature is because I would love to analyze the data and istruction post-run of a specific ROM, since now we have enough instruction running but we don't know where are bugs :). This allow us to log on stdout as befor of log on a file saved under /tmp/clementine-{utc::now()}.log with a special arg like ./clementine --log-on-file my_game.gba.

    We need to check this path on windows platform.

    opened by guerinoni 5
  • Add GUI tools for Clementine

    Add GUI tools for Clementine

    Now it is possible use some kind of graphic debug tools in the UI. You can easily add new ones and edit existing ones.

    N.B. I also refactored all the structure of our workspace

    opened by gallottino 5
  • Small fixes in thumb/bx

    Small fixes in thumb/bx

    • CpuState was using the inverted logic
    • BX was not reading the value from Rn
    • Added instruction decode for THUMB mode
    • Setting lsb in PC to 0 before fetching
    opened by AlessioC31 4
  • API: Add `clear` function to `bitwise`

    API: Add `clear` function to `bitwise`

    Closes #49

    These function complete the bitwise file.

    • The first one allow us to clean (set to 0) all bits from msg to idx;
    • The second one allow us to clean (set to 0) all bits from idx to 0

    Signed-off-by: Federico Bruzzone [email protected]

    opened by FedericoBruzzone 4
  • ARM: Add check before advancing `PC`

    ARM: Add check before advancing `PC`

    After executing an instruction that modifies PC, it should not be advanced by 4.

    I've added that functions that implement instructions should return a bool representing whether PC should be increased after its execution.

    I don't know if this is the best solution, maybe we could use an Option<u32> containing the new PC (returned from the instruction function) if Some or execute advance_program_counter if None. We can discuss it here :)

    Tests are broken since they were written taking into account the fact that PC is always increased, when we decide which way to take I can fix the tests

    opened by AlessioC31 3
  • Adding `LCDRegisters` mapping to `InternalMemory`

    Adding `LCDRegisters` mapping to `InternalMemory`

    This PR adds LCDRegisters memory region to InternalMemory. It serves as preparation to implement the ppu (hopefully :D).

    Structs IORegister and LCDRegisters have been written to model these registers.

    Unit tests have been added to InternalMemory.

    Added get_byte and set_byte in Bits trait to selectively read/write a specific byte from an u32.

    opened by AlessioC31 3
  • Add UI for disassembler

    Add UI for disassembler

    This is a start to a migration on how code is structured in order to have displayed the asm code in one point passing arg for every instruction while decoding. Screenshot 2022-12-28 at 00 25 28

    opened by guerinoni 1
  • Add render in BG_MODE_4

    Add render in BG_MODE_4

    Documented here: BG_MODE_4

    In this PR I also added a macro to simplify lock syntax:

    acquire_lock!(lock_var, acquired => { you can use acquired here } );

    It was usefull because sometime we have to acquire a lock only in the needed scopes. In this way it is more cleaner to use a mutex more times in the same flow.

    For example assume you have two function fn_1(), fn_2()

    fn_1() {
      // it needs a lock
      let acquired_var = self.lock_var.lock().unwrap();
    fn_2() {
      // it needs a lock
      let acquired_var = self.lock_var.lock().unwrap();

    if you call fn_1() a deadlock occurs.

    with this macro you can do this without problems:

    fn_1() {
      // it needs a lock
      acquire_lock!(self.lock_var, var => { var.do_something(); });

    With just test_mode_4 path/rom.gba you can check the correct behavior with the help of PaletteVisualizer.

    opened by gallottino 0
  • UI: Add `MemoryInspector`

    UI: Add `MemoryInspector`

    Added a new UiTool to read values from memory.

    I don't like very much how it is implemented but it was the only way (or at least the only one I found) to make it work since we have Gba<T: Cpu> and Cpu trait didn't have any method to access memory and memory is stored into an Rc<RefCell<>>.

    Please tell me if you think it could be implemented in a better way (maybe without returning Ref? But I think it's needed since InternalMemory is managed by a RefCell).

    It's very simple because I want to use it to debug an issue we may have in the instruction implementations. In the future, we could show a matrix with all the values and so on but for now I think this does the job.

    opened by AlessioC31 4
  • PR CI: Add check on rebase

    PR CI: Add check on rebase

    We currently have checks (fmt, test, lint) on PR branches. It would be useful to execute the same set of checks on the "potential" new main branch (PR branch rebased to current main).

    This is useful because the PR branch may be not rebased to the main, thus merging the PR could result in broken tests.

    opened by AlessioC31 2
  • Docker support

    Docker support

    Clementine could be run within a Docker container. It should be created a proper Dockerfile, documentation and some github action to build and push the container into a public registry when a PR is merged.

    opened by mastrogiovanni 0
A Gameboy Emulator in Rust

RBoy A Gameboy Color Emulator written in Rust Implemented CPU All instructions correct All timings correct Double speed mode GPU Normal mode Color mod

Mathijs van de Nes 512 Dec 23, 2022
Full featured Cross-platform GameBoy emulator by Rust. Forever boys!.

Gameboy Full featured Cross-platform GameBoy emulator. Forever boys!. You can start a game with the following command, here with a built-in game "Boxe

Mohanson 1.2k Jan 2, 2023
GameBoy emulator.

yobemag GameBoy emulator. WIP for now :) General knowledge ROM This is the read-only memory, it's also called "cartridge" and holds the data of the ga

Federico Guerinoni 4 Aug 31, 2022
Cycle-accurate Gameboy Color emulator in Rust

Description Currently intended only for personal research, this is a WIP cycle-accurate GB/C emulator written in Rust. Building If you wish to build f

Luke Stadem 3 May 5, 2022
Nes-emulator - A NES emulator made to learn the Rust programming language

nes-emulator Building $ rustc --version rustc 1.32.0 (9fda7c223 2019-01-16) $ cargo --version cargo 1.32.0 (8610973aa 2019-01-02) $ cargo build --rel

Michael Burge 225 Dec 23, 2022
Commodore 64 emulator written in Rust

Rust64 - a C64 emulator written in Rust This is my attempt to study the Rust programming language and have fun at the same time. The goal is to presen

Krzysztof Kondrak 214 Dec 27, 2022
A Flash Player emulator written in Rust

website | demo | nightly builds | wiki Ruffle Ruffle is an Adobe Flash Player emulator written in the Rust programming language. Ruffle targets both t

Ruffle 11.2k Jan 8, 2023
A Game Boy research project and emulator written in Rust

Mooneye GB Mooneye GB is a Game Boy research project and emulator written in Rust. The main goals of this project are accuracy and documentation. Some

Joonas Javanainen 802 Dec 28, 2022
RGB (Rust Game Boy) is a simple emulator for the original game boy

RGB RGB (Rust Game Boy) is a simple emulator for the original game boy and the color game boy. Warning: This no longer compiles in the latest versions

Niven Achenjang 18 Dec 2, 2022
NES emulator written in Rust to learn Rust

OxideNES A NES emulator in Rust. CPU should be accurate, PPU is mostly accurate, timing between the 2 is off for some corner cases and hardware qui

null 37 Nov 7, 2022
An NES emulator written in Rust

Pinky Pinky is an NES emulator written in Rust completely from scratch based only on publicly available documentation. You can run it in your Web brow

Koute 709 Dec 23, 2022
NES emulator written in Rust

sprocketnes is an emulator for the Nintendo Entertainment System written in the Rust programming language. Its purpose is to serve as a technology dem

Patrick Walton 725 Dec 27, 2022
NES emulator in rust

NES emulator in Rust plastic is a NES emulator built from scratch using Rust. This is a personal project for fun and to experience emulating hardware

Amjad Alsharafi 27 Dec 15, 2022
ZX Spectrum emulator written in Rust

rustzx ZX Spectrum emulator which I writing in rust. I develop this project just for fun and for learning the basics of computer architecture. License

Vladislav Nikonov 162 Dec 27, 2022
R.A.Z.E. A ZX Spectrum Emulator

R.A.Z.E. A ZX Spectrum emulator This project is part of a friendly competition to build an emulator using Rust and WebAssembly. Check the live version

Rodrigo Rivas Costa 37 Nov 25, 2022
Rustual Boy - A Virtual Boy emulator.

Rustual Boy Description Rustual Boy is a Virtual Boy emulator. It can be used to play existing Virtual Boy games, as well as be a helpful development/

null 224 Nov 9, 2022
Intel 8080 cpu emulator by Rust

i8080 i8080 is a emulator for Intel 8080 cpu. 8080 Programmers Manual 8080 opcodes [dependencies] i8080 = { git = ""

Mohanson 83 Dec 27, 2022
TestSuite4 is a framework designed to simplify development and testing of TON Contracts. It includes light-weight emulator of blockchain making it easy to develop contracts.

TestSuite4 0.1.2 TestSuite4 is a framework designed to simplify development and testing of TON Contracts. It contains lightweight blockchain emulator

TON Labs 26 Feb 3, 2022
Learn emulator and programming languages, target chip8, nes, gbc, gba ...

[WIP]learn emulator go-chip8 go run main.go source https://githu

早晨海风 4 Apr 30, 2021