✨ Learning by doing: Exploring the fundamentals of emulation with a minimalist Game Boy™ project. 🎮
CameBoy—a raw dive into retro computing. This Game Boy™ emulator, built in C99, isn't about bells or whistles. It's a hands-on experiment pieced together from a patchwork of online insights, designed to reveal the bare mechanics behind this classic handheld. Here, every line of code tries to be a lesson in minimalism, without unnecessary clutter.
Important
This project is built purely for learning and experimenting. We aren’t connected to Nintendo® in any way. Also, this repository doesn’t include any illegal BIOS nor ROMs, nor do we support using them—the end user are responsible for making sure to use legally obtained softwares.
📸 Screenshots
|
instr_timing.gb 🟥 |
mem_timing.gb 🟨 |
| cpu_instrs.gb 🟩 |
bgbtest.gb 🟩 |
- C99 Compiler (GCC 9+/Clang 12+)
- CMake (3.26+)
- SDL2 (2.32.0+ for frontend)
- SDL2_ttf (2.24.0+ for frontend)
- ROM file (Game Boy .gb format)
Note
External dependencies (SDL2, SDL2_ttf, ccache) can be managed by CPM.cmake.
See /CameBoy/CMakeLists.txt file.
# Clone repository
git clone https://github.com/SOHNE/CameBoy.git
cd CameBoy
# Configure build (default Release mode)
mkdir build && cd build
cmake ../CameBoy -DCMAKE_BUILD_TYPE=Release
# Compile
cmake --build . --config Release
# Optional: Enable debug features
cmake .. -DCC_DEBUG=ON -DUSE_SANITIZERS=ONCameBoy --help
Usage: CameBoy [options]
A Game Boy™ emulator using CameCore and SDL2.
-h, --help show this help message and exit
-d, --debug Enable debug logging
-c, --cartridge=<str> Path to the cartridge file
Example: CameBoy --debug --cartridge /path/to/legal_rom.gbWarning
Needs to improve and correct this Architecture Overview.
┌───────────────────────────────────────┐ ┌──────────────────────────────┐
│ CameCore │ │ CameBoy │
│ (Game Boy Core Library) │ │ (Standalone Frontend) │
├───────────────┬───────────────────────┤ ├───────────────┬──────────────┤
│ Core │ Utils │ │ Application │ SDL2 │
│ (Emu Context) │ (Logging/IO) │◀──────┤ Loop │ (Rendering/ │
├───────────────┴───┬───────────────────┤ │ │ Input) │
│ CPU │ Bus │ └───────┬───────┴───────┬──────┘
│ ┌───────┐ │ (Memory │ │ │
│ │Fetch ├──────▶│ Mapper) │ └───────┬───────┘
│ │Decode │ ├────────┬──────────┤ │
│ │Execute│ │ Cart │ PPU │ ┌───────▼───────┐
│ └───────┘ │ │ │ │ Platform │
│ (SM83 Emulation) │ │ │ │ Integration │
│ │ │ │ └───────────────┘
└───────────────────┴────────┴──────────┘
┌───────────────────────┐
│ Future Improvements │
│ (Planned Components) │
├────────────┬──────────┤
│ APU │ Timer │
│ (Audio │ (System │
│ System) │ Timing) │
└────────────┴──────────┘
Key Components:
CameCore Library:
- Core: Emulator state management (Init/Step/Run)
- CPU: Full SM83 implementation with instruction pipeline
- Bus: Memory bus controller with proper banking
- Cart: ROM loading/validation with MBC support
- Utils: Logging system and file I/O operations
CameBoy Standalone:
- Application Loop: Ties core emulation to platform
- SDL Integration: Handles video output and input
- Platform Layer: Build system and dependency management
Data Flow:
Cartridge → Cart → Bus ↔ CPU ↔ Core
│
SDL Events ← Bus ↔ Core → SDL Rendering
Memory Map Implementation:
0000-FFFF Address Space
├─ ROM Banks (Cart)
├─ VRAM (Bus)
├─ WRAM (Bus)
├─ OAM (Bus)
└─ I/O Registers (Bus)
Instruction Pipeline:
PC → Fetch → Decode → Execute → Cycle Counting
▲ │ │
└────────┴─────────┘ (Flags/Reg Updates)
The CONTRIBUTING guidelines should help in getting you started on how to contribute to this project.
A sincere thank you to the individuals, communities, and resources that brought this project to life:
- Game Boy Pan Docs: The definitive technical reference for Game Boy architecture and programming, which served as the backbone of this emulator's development.
- Console Architecture Guide by Rodrigo Copetti: An invaluable overview of the Game Boy's hardware internals and system design.
- Gekkio's Research: For sharing meticulous hardware tests, reverse-engineering insights, and technical documentation.
- The Ultimate Game Boy Talk: An educational deep-dive into emulator development fundamentals by Michael Steil.
- Game Boy Emulator Development YouTube Series: A hands-on, step-by-step guide to building a functional emulator by Rocky D. Pulley.
- Game Boy Test ROMs by c-sp: A comprehensive suite of test ROMs essential for validating emulator accuracy and performance.
This project stands on the shoulders of the passionate gbdev.io community – thank you for preserving and sharing Game Boy knowledge for future generations.
CameCore and CameBoy are licensed under zlib/libpng license, an OSI-certified and BSD-like license. Check LICENSE for details.