An emulator, assembler, and disassembler for the Sega Game Gear
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 4.6 KiB

10 years ago
10 years ago
10 years ago
8 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123
  1. crater
  2. ======
  3. **crater** is an emulator for the [Sega Game Gear][game gear], with an included
  4. [Z80][z80] assembler/disassembler, written in C.
  5. <img src="/docs/tailsadventure.png?raw=true" title="Tails Adventure (1995)" alt="Tails Adventure (1995)" width="320px">
  6. [game gear]: https://en.wikipedia.org/wiki/Sega_Game_Gear
  7. [z80]: https://en.wikipedia.org/wiki/Zilog_Z80
  8. Why?
  9. ----
  10. While the internet is full of emulators for retro game systems, writing one is
  11. nevertheless a fun learning project.
  12. crater is named after [31 Crateris][crateris], a star that was – for a short
  13. time in 1974 – misidentified as [a moon of Mercury][moon]. Mercury was Sega's
  14. codename for the Game Gear during development.
  15. [crateris]: http://www.astrostudio.org/xhip.php?hip=58587
  16. [moon]: https://en.wikipedia.org/wiki/Mercury%27s_moon
  17. Installing
  18. ----------
  19. Only OS X and Linux are tested. You'll need a modern compiler that supports C11
  20. ([clang][clang] preferred) and [SDL 2][sdl2]. Using Homebrew, you can
  21. `brew install sdl2`; using apt, you can `apt-get install libsdl2-dev`.
  22. Run `make` to create `./crater`. To build the development version with debug
  23. symbols and no optimizations, run `make DEBUG=1`, which creates `./crater-dev`.
  24. crater has a number of test cases. Run the entire suite with `make test`;
  25. individual components can be tested by doing `make test-{component}`, where
  26. `{component}` is one of `cpu`, `vdp`, `psg`, `asm`, `dis`, or `integrate`.
  27. [clang]: http://clang.llvm.org/
  28. [sdl2]: https://www.libsdl.org/
  29. Usage
  30. -----
  31. Running `./crater` without arguments will display a list of ROM images located
  32. in the `roms/` directory, and then ask the user to pick one, or enter their own
  33. ROM path. You can provide a path directly with `./crater path/to/rom`.
  34. Add or symlink ROMs to `roms/` at your leisure. Note that they must end in
  35. `.gg` or `.bin` to be auto-detected.
  36. Add `--fullscreen` (`-f`) to enable fullscreen mode, or `--scale <n>`
  37. (`-s <n>`) to scale the game screen by an integer factor in windowed mode (this
  38. only sets the starting configuration; the window should be resizeable).
  39. Add `--debug` (`-g`) to show logging information while running. Pass it twice
  40. (`-gg`) to show more detailed logs, including an emulator trace.
  41. `./crater -h` gives (fairly basic) command-line usage, and `./crater -v` gives
  42. the current version.
  43. ### Key mapping
  44. Custom key mappings are not supported. There are two primary configurations I
  45. like:
  46. - `Return`/`Esc` for `Start`; `WASD` for D-pad; `.` for `1`/left trigger;
  47. `/` for `2`/right trigger
  48. - `Return`/`Esc` for `Start`; arrow keys for D-pad; `Z` for `1`/left trigger;
  49. `X` for `2`/right trigger
  50. You can switch between them freely.
  51. ### Assembler/Disassembler
  52. crater has built-in support for converting Z80 assembly into ROM images, as
  53. well as attempting the reverse process (i.e., disassembling).
  54. `--assemble <input> [<output>]` (`-a`) converts source code into a `.gg` binary
  55. that can be run by crater. `--disassemble <input> [<output>]` (`-d`) executes
  56. the opposite operation. If no output file is given, crater will use the name of
  57. the input file, with the extension replaced with `.gg` for `-a` and `.asm` for
  58. `-d`. By default, this will never overwrite the original filename; pass
  59. `--overwrite` (`-r`) to let crater do so.
  60. Status
  61. ------
  62. The emulator is almost fully functional, lacking only audio support, a few
  63. uncommon CPU instructions, and some advanced graphics features. Most games are
  64. playable with only minor bugs. Future goals include save states and a more
  65. sophisticated debugging mode.
  66. The assembler is complete. Future goals include more documentation, macros, and
  67. additional directives.
  68. The disassembler works, but can't differentiate between code and data yet, so
  69. it's not very useful.
  70. The testing infrasture is limited. The assembler has decent coverage, other
  71. components minimal.
  72. Credits
  73. -------
  74. Special thanks to [SMS Power!][sms_power]'s excellent [development][sms_dev]
  75. section, which has been invaluable in figuring out many of the Game Gear's
  76. details, including ROM header structure and the memory mapping system. Various
  77. source code comments reference their pages.
  78. Also thanks to [Thomas Scherrer's Z80 website][scherrer] for many useful
  79. resources about the Game Gear's CPU, including info about
  80. [undocumented opcodes][undoc_ops] and [flags][undoc_flags]. Finally, credit
  81. goes to [ClrHome][clrhome] for their helpful Z80 [instruction table][clrtab].
  82. [sms_power]: http://www.smspower.org/
  83. [sms_dev]: http://www.smspower.org/Development/Index
  84. [scherrer]: http://z80.info/
  85. [undoc_ops]: http://www.z80.info/z80undoc.htm
  86. [undoc_flags]: http://z80.info/z80sflag.htm
  87. [clrhome]: http://clrhome.org/
  88. [clrtab]: http://clrhome.org/table/