An emulator, assembler, and disassembler for the Sega Game Gear
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.
Ben Kurtovic e8fe5e4797 Implement some missing graphics features (fixes #4) il y a 2 ans
docs Smaller image. il y a 3 ans
roms Initial commit il y a 5 ans
scripts Fix a couple assembler bugs involving obscure instructions. il y a 3 ans
src Implement some missing graphics features (fixes #4) il y a 2 ans
tests Fix assembler bug involving extended immediates. il y a 3 ans
.gitignore Add support for saved game files for cart RAM (fixes #3) il y a 2 ans
LICENSE Add support for saved game files for cart RAM (fixes #3) il y a 2 ans CLI: have -s be --save instead of --scale; use -x for --scale. il y a 2 ans
crater.c Refactor: pass the entire Config object to the emulator. il y a 3 ans
makefile Refactor debug logging as distinct from dev build; add tracing. il y a 3 ans


crater is an emulator for the Sega Game Gear, with an included Z80 assembler/disassembler, written in C.

Tails Adventure (1995)


While the internet is full of emulators for retro game systems, writing one is nevertheless a fun learning project.

crater is named after 31 Crateris, a star that was – for a short time in 1974 – misidentified as a moon of Mercury. Mercury was Sega’s codename for the Game Gear during development.


Only OS X and Linux are tested. You’ll need a modern compiler that supports C11 (clang preferred) and SDL 2. Using Homebrew, you can brew install sdl2; using apt, you can apt-get install libsdl2-dev.

Run make to create ./crater. To build the development version with debug symbols and no optimizations, run make DEBUG=1, which creates ./crater-dev.

crater has a number of test cases. Run the entire suite with make test; individual components can be tested by doing make test-{component}, where {component} is one of cpu, vdp, psg, asm, dis, or integrate.


Running ./crater without arguments will display a list of ROM images located in the roms/ directory, and then ask the user to pick one, or enter their own ROM path. You can provide a path directly with ./crater path/to/rom.

Add or symlink ROMs to roms/ at your leisure. Note that they must end in .gg or .bin to be auto-detected.

Add --fullscreen (-f) to enable fullscreen mode, or --scale <n> (-x <n>) to scale the game screen by an integer factor in windowed mode (this only sets the starting configuration; the window should be resizeable).

By default, crater will save cartridge RAM (“battery saves”; these are distinct from save states, which are not yet supported) to a file named <rom>.sav, where <rom> is the path to the ROM file. You can set a custom save location with --save <path> (-s <path>) or disable saving entirely with --no-save.

Add --debug (-g) to show logging information while running. Pass it twice (-gg) to show more detailed logs, including an emulator trace.

./crater -h gives (fairly basic) command-line usage, and ./crater -v gives the current version.

Key mapping

Custom key mappings are not supported. There are two primary configurations I like:

  • Return/Esc for Start; WASD for D-pad; . for 1/left trigger; / for 2/right trigger

  • Return/Esc for Start; arrow keys for D-pad; Z for 1/left trigger; X for 2/right trigger

You can switch between them freely.


crater has built-in support for converting Z80 assembly into ROM images, as well as attempting the reverse process (i.e., disassembling).

--assemble <input> [<output>] (-a) converts source code into a .gg binary that can be run by crater. --disassemble <input> [<output>] (-d) executes the opposite operation. If no output file is given, crater will use the name of the input file, with the extension replaced with .gg for -a and .asm for -d. By default, this will never overwrite the original filename; pass --overwrite (-r) to let crater do so.


The emulator is almost fully functional, lacking only audio support, a few uncommon CPU instructions, and some advanced graphics features. Most games are playable with only minor bugs. Future goals include full save states and a more sophisticated debugging mode.

The assembler is complete. Future goals include more documentation, macros, and additional directives.

The disassembler works, but can’t differentiate between code and data yet, so it’s not very useful.

The testing infrasture is limited. The assembler has decent coverage, other components minimal.


Special thanks to SMS Power!’s excellent development section, which has been invaluable in figuring out many of the Game Gear’s details, including ROM header structure and the memory mapping system. Various source code comments reference their pages.

Also thanks to Thomas Scherrer’s Z80 website for many useful resources about the Game Gear’s CPU, including info about undocumented opcodes and flags. Finally, credit goes to ClrHome for their helpful Z80 instruction table.