{"id":15662153,"url":"https://github.com/earwig/crater","last_synced_at":"2026-03-01T12:31:41.194Z","repository":{"id":18438525,"uuid":"21626498","full_name":"earwig/crater","owner":"earwig","description":"An emulator, assembler, and disassembler for the Sega Game Gear","archived":false,"fork":false,"pushed_at":"2019-12-04T21:48:59.000Z","size":470,"stargazers_count":21,"open_issues_count":3,"forks_count":3,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-05-05T23:07:36.795Z","etag":null,"topics":["assembler","c","disassembler","emulator","game-gear-emulator","sega-game-gear","z80"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/earwig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-08T19:20:22.000Z","updated_at":"2025-04-03T20:19:07.000Z","dependencies_parsed_at":"2022-09-02T07:01:56.083Z","dependency_job_id":null,"html_url":"https://github.com/earwig/crater","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/earwig/crater","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earwig%2Fcrater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earwig%2Fcrater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earwig%2Fcrater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earwig%2Fcrater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/earwig","download_url":"https://codeload.github.com/earwig/crater/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earwig%2Fcrater/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T11:43:06.159Z","status":"ssl_error","status_checked_at":"2026-03-01T11:43:03.887Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembler","c","disassembler","emulator","game-gear-emulator","sega-game-gear","z80"],"created_at":"2024-10-03T13:30:25.619Z","updated_at":"2026-03-01T12:31:36.183Z","avatar_url":"https://github.com/earwig.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"crater\n======\n\n**crater** is an emulator for the [Sega Game Gear][game gear], with an included\n[Z80][z80] assembler/disassembler, written in C.\n\n\u003cimg src=\"/docs/tailsadventure.png?raw=true\" title=\"Tails Adventure (1995)\" alt=\"Tails Adventure (1995)\" width=\"320px\"\u003e\n\n[game gear]: https://en.wikipedia.org/wiki/Sega_Game_Gear\n[z80]: https://en.wikipedia.org/wiki/Zilog_Z80\n\nWhy?\n----\n\nWhile the internet is full of emulators for retro game systems, writing one is\nnevertheless a fun learning project.\n\ncrater is named after [31 Crateris][crateris], a star that was – for a short\ntime in 1974 – misidentified as [a moon of Mercury][moon]. Mercury was Sega's\ncodename for the Game Gear during development.\n\n[crateris]: http://www.astrostudio.org/xhip.php?hip=58587\n[moon]: https://en.wikipedia.org/wiki/Mercury%27s_moon\n\nInstalling\n----------\n\nOnly OS X and Linux are tested. You'll need a modern compiler that supports C11\n([clang][clang] preferred) and [SDL 2][sdl2]. Using Homebrew, you can\n`brew install sdl2`; using apt, you can `apt-get install libsdl2-dev`.\n\nRun `make` to create `./crater`. To build the development version with debug\nsymbols and no optimizations, run `make DEBUG=1`, which creates `./crater-dev`.\n\ncrater has a number of test cases. Run the entire suite with `make test`;\nindividual components can be tested by doing `make test-{component}`, where\n`{component}` is one of `cpu`, `vdp`, `psg`, `asm`, `dis`, or `integrate`.\n\n[clang]: http://clang.llvm.org/\n[sdl2]: https://www.libsdl.org/\n\nUsage\n-----\n\nRunning `./crater` without arguments will display a list of ROM images located\nin the `roms/` directory, and then ask the user to pick one, or enter their own\nROM path. You can provide a path directly with `./crater path/to/rom`.\n\nAdd or symlink ROMs to `roms/` at your leisure. Note that they must end in\n`.gg` or `.bin` to be auto-detected.\n\nAdd `--fullscreen` (`-f`) to enable fullscreen mode, or `--scale \u003cn\u003e`\n(`-x \u003cn\u003e`) to scale the game screen by an integer factor in windowed mode (this\nonly sets the starting configuration; the window should be resizeable).\n\nFor games that support it, crater will save cartridge RAM (\"battery saves\";\nthese are distinct from save states, which are not yet supported) to a file\nnamed `\u003crom\u003e.sav`, where `\u003crom\u003e` is the path to the ROM file. You can set a\ncustom save location with `--save \u003cpath\u003e` (`-s \u003cpath\u003e`) or disable saving\nentirely with `--no-save`.\n\nAdd `--debug` (`-g`) to show logging information while running. Pass it twice\n(`-gg`) to show more detailed logs, including an emulator trace.\n\ncrater tries to reproduce the Game Gear's native display resolution, which had\na pixel aspect ratio (PAR) of [8:7][par]; this means the pixels were slightly\nwider than square, unlike modern LCD displays with a 1:1 PAR. Add `--square`\n(`-q`) to force square pixels.\n\n`./crater -h` gives (fairly basic) command-line usage, and `./crater -v` gives\nthe current version.\n\n[par]: https://pineight.com/mw/index.php?title=Dot_clock_rates\n\n### Input\n\ncrater supports keyboard and joystick/controller input.\n\nFor keyboards, custom mappings are not yet supported. There are two primary\nconfigurations I like:\n\n- `Return`/`Esc` for `Start`; `WASD` for D-pad; `J` for `1`/left trigger;\n  `K` for `2`/right trigger\n\n- `Return`/`Esc` for `Start`; arrow keys for D-pad; `Z` for `1`/left trigger;\n  `X` for `2`/right trigger\n\nYou can switch between them freely.\n\nFor controllers, crater uses SDL controller mappings. Many common controllers\nare supported out of the box, but you may define your own mappings by creating\na file named `gamecontrollerdb.txt` in the working directory. For more info,\nsee [this community mapping database][gcdb].\n\n[gcdb]: https://github.com/gabomdq/SDL_GameControllerDB\n\n### Assembler/Disassembler\n\ncrater has built-in support for converting Z80 assembly into ROM images, as\nwell as attempting the reverse process (i.e., disassembling).\n\n`--assemble \u003cinput\u003e [\u003coutput\u003e]` (`-a`) converts source code into a `.gg` binary\nthat can be run by crater. `--disassemble \u003cinput\u003e [\u003coutput\u003e]` (`-d`) executes\nthe opposite operation. If no output file is given, crater will use the name of\nthe input file, with the extension replaced with `.gg` for `-a` and `.asm` for\n`-d`. By default, this will never overwrite the original filename; pass\n`--overwrite` (`-r`) to let crater do so.\n\nStatus\n------\n\nThe emulator is almost fully functional, lacking only audio support, a few\nuncommon CPU instructions, and some advanced graphics features. Most games are\nplayable with only minor bugs. Future goals include full save states and a more\nsophisticated debugging mode.\n\nThe assembler is complete. Future goals include more documentation, macros, and\nadditional directives.\n\nThe disassembler works, but can't differentiate between code and data yet, so\nit's not very useful.\n\nThe testing infrastructure is limited. The assembler has decent coverage, other\ncomponents minimal.\n\nCredits\n-------\n\nSpecial thanks to [SMS Power!][sms_power]'s excellent [development][sms_dev]\nsection, which has been invaluable in figuring out many of the Game Gear's\ndetails, including ROM header structure and the memory mapping system. Various\nsource code comments reference their pages.\n\nAlso thanks to [Thomas Scherrer's Z80 website][scherrer] for many useful\nresources about the Game Gear's CPU, including info about\n[undocumented opcodes][undoc_ops] and [flags][undoc_flags]. Finally, credit\ngoes to [ClrHome][clrhome] for their helpful Z80 [instruction table][clrtab].\n\n[sms_power]: http://www.smspower.org/\n[sms_dev]: http://www.smspower.org/Development/Index\n[scherrer]: http://z80.info/\n[undoc_ops]: http://www.z80.info/z80undoc.htm\n[undoc_flags]: http://z80.info/z80sflag.htm\n[clrhome]: http://clrhome.org/\n[clrtab]: http://clrhome.org/table/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearwig%2Fcrater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fearwig%2Fcrater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearwig%2Fcrater/lists"}