CODE-DMG v1.0.0 🕹️ (GUI)

Side Note: You may be wondering why is there a "Core" version and "GUI" version. The Core version is only focused on the main emulation. The GUI version is using that core with a nice GUI, so there is no need to use the terminal. CODE-DMG is mainly focused on the Core. However the main 3 reason for the GUI version is ease of use, providing debug tools, and testing the flexibility of the Core. See "imgui" branch for source code of the GUI version.

Download

1. Download the zip for your platform.
2. Unzip the folder
3. Launch the executable
   • On MacOS, there might be a pop up saying "Apple could not verify", this is normal. Simply right click on the app, then open, then open again. You also go to System Settings, then security, then allow. You only need to do this once during the first time.
   • You may also need to enable execute permission on "Unix-like Oses"
4. You are ready to go!

Controls

• (A) = Z
• (B) = X
• [START] = [ENTER]
• [SELECT] = [RSHIFT]
• D-Pad = ArrowKeys

Usage

After launching the executable, you are ready to go. Load a ROM by File -> Open ROM. Switch to Game mode (the view without all the debug stuff) by View -> Game

Bootrom

The bootrom of the Gameboy is first program that is ran by the Gameboy which sets up register and memory value, and also performs a validity check on the rom. This better known as the Nintendo logo scrolling down when you power on a Gameboy. Optional, but it is recommended you provide the bootrom. It must be named dmg_boot.bin and be placed in root of executable for the Core version. For the GUI version, you can go to File -> Select BOOTROM However, even without a bootrom, roms will still work.

Fallback ROM

The fallback rom, fall_back.gb, is a custom ROM I made in GBZ80 assembly as a fall back rom the emulator can run. This rom purposely has invalid header data, which if provided a bootrom, can emulate what happens when you turn on a Gameboy without a game. If a bootrom is not provided, and the fall back rom is ran, then you will see a screen with a message saying "This should not be seen on a real DMG or emu with bootrom checks"

Compatibility

Pretty much every game I tried does work. Do note MBC0/ROM Only should work. MBC1, MBC3, and MBC5 should also work. I don't have a full list of games, but here is a list of games I tried:

Asteriods - Works
Donkey Kong Land - Works
Donkey Kong Land 2 - Works
Donkey Kong Land 3 - Works
Dr.Mario - Works
Dropzone - Works
Kriby's Dream Land - Works
Kriby's Dream Land 2 - Hangs on first frame due to unimplemented timer interrupt
Legend of Zelda, The Link's Awakening - Works
Pokemon Blue - Works
Pokemon Yellow - Works
Pokemon Gold - Works
Prehistorik Man - Playable, but graphical glitches in intro (requires accurate timing)
Super Mario Land - Works
Super Mario Land 2, 6 Golden Coins - Works
Tetris - Works
Tennis - Works

 __________________
|-|--------------|-|
|  ______________  |
| |  __________  | |
| | |          | | |
| |·|          | | |
| | |          | | |
| | |__________| | |
| |_____________/  |
|   _  GAMEBOY     |
| _| |_         () |
||_   _|       ()  |
|  |_|             |
|       / /   \\\ /
|________________/
Gameboy ASCII art I made myself :)

CODE-DMG v1.0.0 🕹️

Note: Only the win-x64, win-x64-selfcontained, linux-x64, and linux-x64-selfcontained were only tested.

Download

1. Download the zip for your platform. If you don't have the dotnet runtime, get the "selfcontained" version.
2. Unzip the folder
3. Open up your terminal at the download location (Can be ran with CLI only for right now) Your current working directory must be at the application location when using!
4. Optional: Place the bootrom by the executable. Bootrom file should be named dmg_boot.bin
5. Windows: CODE-DMG --dmg <string:rom>, Unix-like Oses: ./CODE-DMG --dmg <string:rom> (You may also need to enable execute permission on Unix-like Oses")
6. You are ready to go!

Controls

• (A) = Z
• (B) = X
• [START] = [ENTER]
• [SELECT] = [RSHIFT]
• D-Pad = ArrowKeys

Usage

For the most basics usage: CODE-DMG --dmg <string:rom> or ./CODE-DMG --dmg <string:rom>. Terminal should be at the location of the application as the current working directory when calling CODE-DMG. Save files are supported (experimental), a .sav file will be genarated in the same location as the ROM. This .sav file can work between emulators like BGB. Currently CODE-DMG support MBC0/ROM Only roms, as well as experimental MBC1, MBC3 (no RTC), and MB5 (no rumble).

Flags

CODE-DMG for now is only runnable through the CLI. Executing the executable directly will rely on the fall back rom. Note: these flags can be passed in any order, and in any combination.

• --dmg <string:path>, --dmg: Starts up the emulator given a rom file (Default mode. No rom given, fall back is default)
• --json <string>: Runs a CPU test for a instruction given a JSON file in test/v1
• -b <string:path>, --bootrom <string:path>: Loads custom bootrom path than default. (dmg_boot.bin is default)
• -s <int>, --scale <int>: Scale window size by factor (2 is default)
• -f, --fps: Enables FPS counter (off is default)
• -rl, --raylib-log: Enables Raylib logs (off is default)
• -p <string>, --palette <string>: Changes the 2bpp palette given name (dmg is default)
• -a, --about: Shows about
• -v, --version: Shows version number
• -h, --help: Shows help screen

Bootrom

The bootrom of the Gameboy is first program that is ran by the Gameboy which sets up register and memory value, and also performs a validity check on the rom. This better known as the Nintendo logo scrolling down when you power on a Gameboy. Optional, but it is recommended you provide the bootrom. It must be named dmg_boot.bin and be placed in root of executable. However, even without a bootrom, roms will still work.

Fallback ROM

The fallback rom, fall_back.gb, is a custom ROM I made in GBZ80 assembly as a fall back rom the emulator can run. This rom purposely has invalid header data, which if provided a bootrom, can emulate what happens when you turn on a Gameboy without a game. If a bootrom is not provided, and the fall back rom is ran, then you will see a screen with a message saying "This should not be seen on a real DMG or emu with bootrom checks"

Compatibility

Pretty much every game I tried does work. Do note MBC0/ROM Only should work. MBC1, MBC3, and MBC5 should also work. I don't have a full list of games, but here is a list of games I tried:

Asteriods - Works
Donkey Kong Land - Works
Donkey Kong Land 2 - Works
Donkey Kong Land 3 - Works
Dr.Mario - Works
Dropzone - Works
Kriby's Dream Land - Works
Kriby's Dream Land 2 - Hangs on first frame due to unimplemented timer interrupt
Legend of Zelda, The Link's Awakening - Works
Pokemon Blue - Works
Pokemon Yellow - Works
Pokemon Gold - Works
Prehistorik Man - Playable, but graphical glitches in intro (requires accurate timing)
Super Mario Land - Works
Super Mario Land 2, 6 Golden Coins - Works
Tetris - Works
Tennis - Works

 __________________
|-|--------------|-|
|  ______________  |
| |  __________  | |
| | |          | | |
| |·|          | | |
| | |          | | |
| | |__________| | |
| |_____________/  |
|   _  GAMEBOY     |
| _| |_         () |
||_   _|       ()  |
|  |_|             |
|       / /   \\\ /
|________________/
Gameboy ASCII art I made myself :)