Note that this project is currently in development. Features are still missing, stuff is still being build.

What does this project try to do? (ELI5)

This project tries to emulate the Nintendo GameBoy and Nintendo GameBoy Color game system hardware accurately so that games for these game systems can be played on hardware that is natively not able to do so.

How do I build this software locally?

Currently the codebase can only be build on a Windows machine with Microsoft Visual Studio installed. If these requirements are met, simply run the build_msvc_cl.bat or build_msvc_clang inside the win32 directory - This should spawn a cl.exe or clang.exe instance which will compile the project and output the executible. In case you want to build a debug version, pass the argument debug to the build scripts.

Note: You don't necesseraly have to have Visual Studio installed - it's enough if either cl.exe or clang.exe are part of your PATH environment variable (for build_msvc_cl.bat and build_msvc_clang.bat respectively). Additionally, the linker has to be able to resolve os library and c stdlib calls.

How do I navigate the codebase?

The win32 entry point WinMain() and interface is located in the k15_win32_gb_emulator.cpp file. All Nintendo GameBoy hardware emulation code can be found in k15_gb_emulator.h with the main entry point being runGBEmulatorForCycles().

Can I run this emulator locally?

Yes, prebuild release can be found here Input is supported via keyboard and xinput gamepads.

Input on keyboard:

• arrow keys - digi pad
• return - start
• space - select
• a - a
• b - b

input on xinput pad:

• digi pad - digi pad
• x,a - a
• y,b - b

What do I have to do to port this to platform X?

Inside k15_win32_gb_emulator.cpp you can find the Win32 platform layer for orientation. Basically, all you have to do is create an emulator instance by first providing the API with a block of memory. The required memory size can be calculated by calling calculateGBEmulatorMemoryRequirementsInBytes().

An emulator instance can be created by calling createGBEmulatorInstance() (this function will take the aforemention memory block). Each emulator instance is independent from one another (goal would be link cable multiplayer using multiple instances in a single process)

After an emulator instance could be created, load a game rom using loadGBEmulatorRom() (this rom data should be provided as a memory blob either by mapping the rom file or by copying the rom file content to a memory buffer).

Now, call runGBEmulatorForCycles() each frame and check the return value for the flag K15_GB_VBLANK_EVENT_FLAG (indicating, that the GameBoy frame has finished). By calling getGBEmulatorFrameBuffer() you can get a pointer to the framebuffer data (attention: the pixel format is still in gameboy format - 2bpp. To convert to RGB8 call convertGBFrameBufferToRGB8Buffer()).

To set the joystick state of the emulator instance, call setGBEmulatorJoypadState() (this function is thread-safe so that input code can high frequently poll asynchronously for smaller input lag).

State loading/saving can be done using calculateGBEmulatorStateSizeInBytes(), storeGBEmulatorState() and loadGBEmulatorState(). For an example of how to use the API please take a look at k15_win32_gb_emulator.cpp, specificially the loadStateInSlot() and saveStateInSlot() functions.

Current State and Goals

• Emulate correct frame timings independend of monitor refresh rate
• implement proper pixel fifo emulation
• implement custom apu emulation
• pass mooneye-gb test roms
  • acceptance
    • timer
    • instr
    • interrupts
    • oam_dma
    • bits
    • ppu
  • emulator-only
    • mbc1
    • mbc2
    • mbc3
    • mbc5
  • misc
    • bits
    • ppu
• pass blarggs test roms
  • instr_timing
  • cpu_instrs
  • interrupt_time
  • mem_timing
• Implement Nintendo GameBoy Color features

Currently the emulator is purely run on the CPU, meaning that the Nintendo GameBoy CPU as well as the PPU are being emulated purely on the host CPU. The final image from the emulator will be blit to the screen by the GPU to utilize programmable scaling options and filters.