GameboyGo

GameboyGo

About The Project

GameboyGo is a cross-platform Nintendo Gameboy emulator written in Go. This emulator aims for instruction accuracy and leverages Ebiten for handling 2D graphics and keyboard input. I developed GameboyGo as a hobby to learn the basics of low-level emulation development to re-create the nostalgic experience of playing classic Nintendo games.

(back to top)

Built With

• 
• Ebiten

(back to top)

Getting Started

Prerequisites

1. Install Go (Golang):

   • Make sure you have Go installed on your machine. If you don't have Go installed, you can download and install it from the official Go website.

   • Verify the installation by opening your terminal and running:

     go version
     

2. Install Git:

   • Ensure you have Git installed to clone the repository. You can download and install Git from the official Git website.

   • Verify the installation by opening your terminal and running:

     git --version
     

3. Install a C Compiler (required only for macOS and Linux):

   • Ensure you have a C compiler installed on your machine since Ebiten uses both Go and C. You can follow a guide from the official Ebiten website to download and install a C compiler.

   • Verify the installation by opening your terminal and running depending on your C compiler:

     gcc --version
     

     or

     clang --version
     

Installation

1. Clone the repository

   git clone https://github.com/BeralaWoolies/GameboyGo.git <Repo-Directory>
   

2. Navigate into the cloned repository

   cd <Repo-Directory>
   

3. Build the emulator by running:

   go build -o GameboyGo ./cmd/main/main.go
   

   • If building on Windows Subsystem for Linux (WSL) then instead run:

     GOOS=windows go build -o GameboyGo ./cmd/main/main.go
     

(back to top)

Usage

Simplest way to run the emulator:

./GameboyGo -rom <rom-name.gb>

To run the emulator with a user-provided boot rom:

./GameboyGo -rom <rom-name.gb> -bootrom <boot-rom.bin>

All options:

    -rom
        must specify a .gb or .gbc rom
    -bootrom
        optionally specify a boot rom to play
    -stats
        optionally enable fps and emu speed tracking
    -d
        optionally enable debug mode
    -cpuprofile
        write cpu profile to `file`
    -memprofile
        write memory profile to `file`

Controls

Saving

If the loaded rom supports battery backed saves, a <rom-name>.sav (e.g pokemon-gold.sav) file containing the cartridge RAM dump is created under the directory ./saves/. The emulator maps <rom-name>.sav into main memory during runtime allowing all RAM writes to be flushed into the .sav file eventually.

(back to top)

Testing

CPU

GameboyGo passes all individual Blargg's cpu instruction test roms.

PPU

GameboyGo passes dmg-acid2.gb which tests for correct sprite, background and window rendering. It also tests for correct LCD scrolling, palettes, sprite priority and sprite flipping.

Memory Bank Controllers

GameboyGo passes all tests in ./tests/mbc1 (except for multicart_rom_8Mb.gb) and ./tests/mbc3.

(back to top)

Contributing

Any contributions are greatly appreciated and welcomed! GameboyGo still has various small bugs that can appear in games so don't hesitate to play around and experiment with the project.

Please feel free to open any pull requests to this project by:

1. Forking the repository.
2. Creating your feature branch (git checkout -b feature/yourFeature).
3. Committing your changes (git commit -m 'Add some yourFeature').
4. Pushing to the branch (git push origin feature/yourFeature).
5. Opening a pull request.

(back to top)

Features

• CPU
  • All 512 CPU instructions
• PPU
  • Sprite rendering
  • Background rendering
  • Window rendering
  • LCD scrolling
  • Palettes
  • OAM transfer
• APU
• DMA
• Interrupts
  • VBLANK interrupts
  • Joypad interrupts
  • Timer interrupts
  • STAT interrupts
  • Serial interrupts
• Joypad Input
• Battery backed saves
• Serial Data Transfer (stubbed)
• Memory Bank Controllers
  • MBC1
  • MBC3
    • RTC (Real Time Clock) implementation
  • MBC5

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Resources

Interested in writing a Gameboy emulator or just emulation development in general? Feel free to draw inspiration from this repo and also check out these amazing resources that helped me build GameboyGo.

• The Nintendo Gameboy is notorious for many edge cases and obscure behaviour. I highly recommend checking out the Emulator Development Discord server if you are unsure about how to emulate certain parts of the Gameboy.
• https://github.com/Humpheh/goboy/tree/master - another great Gameboy emulator written in Go to use for reference
• https://gbdev.io/pandocs/single.html - in-depth Gameboy documentation
• https://github.com/AntonioND/giibiiadvance/blob/master/docs/TCAGBD.pdf - in-depth Gameboy documentation
• https://gbdev.io/gb-opcodes/optables/ - CPU opcode table
• https://blog.tigris.fr/category/emulator/ - great for understanding the Gameboy functionality
• https://emudev.de/gameboy-emulator/overview/ - great for understanding the Gameboy functionality and emulation in general
• https://axleos.com/writing-axles-gameboy-emulator/ - great for understanding the boot rom
• https://hacktix.github.io/GBEDG/ - great for understanding the Gameboy PPU (specifically the pixel FIFO)

(back to top)