gade

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #golang #go #docker #macos #windows #awesome #awesome-list #security #openai #mcp

(★ 32)

A Game Boy emulation library in Ada

gade Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![CI](https://github.com/ellamosi/gade/actions/workflows/ci.yml/badge.svg)](https://github.com/ellamosi/gade/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/ellamosi/gade/badge.svg?branch=main)](https://coveralls.io/github/ellamosi/gade?branch=main)
[![Ada 2022](https://img.shields.io/static/v1?label=&message=2022&color=153261&labelColor=555&logo=ada&logoColor=white&logoSize=auto)](https://ada-lang.io/)
[![Alire](https://img.shields.io/endpoint?url=https://alire.ada.dev/badges/gade.json)](https://alire.ada.dev/crates/gade.html)
[![Mentioned in Awesome Ada](https://awesome.re/mentioned-badge.svg)](https://github.com/ohenley/awesome-ada)

# Gade
A Game Boy emulation library in Ada

This is a proof of concept for an interpreting emulator developed in Ada. It's meant to test the language's suitability for a project of this kind, the performance of generated code, and cross-language interaction. It's not meant to be the go-to emulator for simply playing Game Boy games.

## Background
This project started as an homage to [my university's Computer Architecture department](https://www.ac.upc.edu/en?set_language=en). I thoroughly enjoyed their courses, in which I went from not knowing binary to fully understanding how a modern CPU works, all the way down to the logic-gate level. This inspired me to write an emulator, and while looking for a balance between simplicity, size, and software-catalog popularity, I set my sights on the venerable Game Boy.

Why Ada? I learned to program in Ada, and I always felt that it was a more reliable candidate for native code compilation than the likes of C. The precise and platform-independent representation clauses the language offers, which allow precise definition of memory-mapped hardware, were also a factor in the decision. Also, while such emulators exist in plenty of other languages, I suspect this is the first one written in Ada.

## Library Architecture
`gade` is the emulator core library. It can be consumed by different front ends and by the test harness used by integration tests.

Today, the main consumers are:
- [`gade-sdl`](https://github.com/ellamosi/gade-sdl): sibling SDL front end project.
- [`gade-testd`](tests/harness/): command-driven harness binary used by `pytest` integration tests.

The architecture is intentionally set up so new front ends can be added without changing emulator core behavior (for example, a native macOS Swift front end via Objective-C bindings).

```mermaid
flowchart LR
 A[gade Ada emulator core library]

subgraph Frontends["Front ends / hosts"]
 B[gade-sdl Easily portable SDL2 app]
 C[gade-testd Test harness process]
 D[Possible alternate frontends such as Swift MacOS app via Objective-C bindings]
 H[libgade_cpp_interface_check C++ interface compilation check]
 end

subgraph CPP["C++ interface layer"]
 G[gade-interfaces-c Ada C ABI bridge]
 I[libgade.hpp C++ wrapper API]
 end

subgraph Testing["Automated test layer"]
      F[pytest integration tests]
    end

B --> A
    C --> A
    H --> I
    D --> I
    I --> G
    G --> A
    F -->|line protocol| C
```

## Build
From `gade/`, using [Alire](https://alire.ada.dev/), you can build the library with:

```sh
alr build
```

For information on how to build and run the tests, see the [tests README](tests/README.md).

### Formatting

Install [`gnatformat`](https://github.com/AdaCore/gnatformat) with `alr install gnatformat`.

Ada sources can be formatted locally with:

```sh
./scripts/format-ada.sh
```

To run the same Ada format check before each commit, install
[`pre-commit`](https://pre-commit.com/) with:

```sh
python3 -m pip install -r requirements-dev.txt
pre-commit install
```

The hook formats only staged Ada files. The checked-in
`./scripts/check-ada-format.sh` script still performs the full project-level
check used by CI. The pre-commit hook formats staged Ada files in place, so if
it rewrites files you should `git add` them and re-run the commit.

### Scenario Variables
`gade` exposes three GPR scenario variables through `alire.toml`:

- `GADE_BUILD_MODE`: `debug` enables safety/debug checks; `release` enables optimized runtime settings
- `GADE_LIBRARY_TYPE`: `relocatable` for shared builds, `static` for static linking, `static-pic` for static PIC artifacts
- `GADE_COVERAGE`: `false` | `true` (enables `--coverage` instrumentation)

## State of affairs

### What works
- Full CPU emulation (Passes Blargg's CPU instruction tests)
- Plain, MBC1, MBC2, MBC3 cartridge types with saves and MBC3 RTC support
- Joypad
- Timer
- Background Layer
- Window Layer
- Sprites
- Mid scanline rendering
- Audio

### Next steps
- Performance optimizations (GPU rendering)
- Performance optimizations (CPU interpretation/Interrupt handling)
- Support for more cartridge types

gade

gade Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

gade

gade Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README