{"id":13838413,"url":"https://github.com/Rodrigodd/gameroy","last_synced_at":"2025-07-10T21:32:49.407Z","repository":{"id":39092954,"uuid":"446933335","full_name":"Rodrigodd/gameroy","owner":"Rodrigodd","description":"A Game Boy emulator, disassembler and debugger, written in Rust","archived":false,"fork":false,"pushed_at":"2024-11-20T01:44:47.000Z","size":2397,"stargazers_count":273,"open_issues_count":3,"forks_count":6,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-20T02:25:41.609Z","etag":null,"topics":["emulator","gameboy","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rodrigodd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-01-11T18:17:51.000Z","updated_at":"2024-11-19T22:46:36.000Z","dependencies_parsed_at":"2024-02-12T02:45:12.092Z","dependency_job_id":null,"html_url":"https://github.com/Rodrigodd/gameroy","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rodrigodd%2Fgameroy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rodrigodd%2Fgameroy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rodrigodd%2Fgameroy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rodrigodd%2Fgameroy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rodrigodd","download_url":"https://codeload.github.com/Rodrigodd/gameroy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225657461,"owners_count":17503557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["emulator","gameboy","rust"],"created_at":"2024-08-04T15:01:56.014Z","updated_at":"2024-11-21T01:31:02.911Z","avatar_url":"https://github.com/Rodrigodd.png","language":"Rust","funding_links":[],"categories":["Handheld game console emulators","Rust","Nintendo Game Boy/Game Boy Color"],"sub_categories":["Nintendo Handhelds"],"readme":"# GameRoy\n\nAn emulator and debugger for the Nintendo Game Boy, written in Rust.\n\n\u003cp float=\"left\" align=\"middle\"\u003e\n  \u003cimg alt=\"Debugging Kirby\" align=\"middle\" src=\"assets/screenshot.png\" width=\"65%\" /\u003e\n  \u003cimg alt=\"Playing Zelda on Mobile\" align=\"middle\" src=\"assets/mobile_screenshot.png\" width=\"20%\" /\u003e\n\u003c/p\u003e\n\n## Features\n\n- Support for DMG (only).\n- High accuracy (see [Test suite](#test-suite) below)\n- Accurate clock frequency: don't sync over frames or sound, but the clock frequency itself.\n- Battery saves support.\n- Save and load states.\n- Time travel backwards in time (Rewind)\n- Graphical interface for listing roms in a folder.\n- Debugger with a graphical interface:\n  - Views for disassembly, registers, video RAM, etc...\n  - Statically (or while running) trace a rom for executable memory ranges.\n  - Add breakpoints at read, write, jump or execution of memory addresses.\n  - Watch addresses.\n  - Step code backwards.\n\n## Building and Running\n\nYou can find pre compiled binaries in the [Releases page](https://github.com/Rodrigodd/gameroy/releases).\n\nFor building this project, you need [the Rust toolchain](https://www.rust-lang.org/tools/install)\ninstalled (whihc includes `cargo`). Then follow the instructions for each\nplatform.\n\nThis project optionally depends on [cargo-about](https://github.com/EmbarkStudios/cargo-about)\n(0.5.1) for generating a list of licenses. You can install it using cargo:\n\n```shell\ncargo install cargo-about\n```\n\n### Windows and Linux\n\nCompiling and running for native, i.e, Windows and Linux (other platforms are\nuntested), only needs cargo:\n\n```shell\ncargo run --release -p gameroy-native\n```\n\n### WebAssembly\n\nYou can also build for WebAssembly, and run the emulator on the web. Using\n[web-pack](https://rustwasm.github.io/wasm-pack/), run the following command:\n\n```shell\ncd wasm\nwasm-pack build --target web\n```\n\nAfter that, open a web server that serves [`wasm/index.html`](wasm/index.html).\n\nFor example, you can use python's `http.server` module:\n\n```\ncd wasm\npython -m http.server\n```\n\nAnd access `localhost:8000` in a web browser.\n\n### Android\n\nTo build for android, you need to have [Anroid NDK](https://developer.android.com/ndk) installed.\n\nGameRoy uses [Gradle to build the android port](https://developer.android.com/studio/build/building-cmdline).\nTo build and install the .apk in a device:\n\n```shell\ncd android\n./gradlew installDebug # or `gradlew installDebug`, on Windows\n```\n\nTo see the logs:\n\n```shell\nadb logcat *:S gameroy:V RustStdoutStderr:V\n```\n\n(The project uses\n[rust-android-gradle](https://github.com/mozilla/rust-android-gradle) for\nbuilding the rust code for android.)\n\n## Config\n\nGameRoy uses a file named `gameroy.toml`, located in the same folder as the executable.\nThe default [`gameroy.toml`](gameroy.toml) file comes documented.\n\n### Controls\n\nThe default keymap is:\n- `left`: Left Arrow\n- `right`: Right Arrow\n- `up`: Up Arrow\n- `down`: Down Arrow\n- `A`: A\n- `B`: S\n- `select`: Backspace\n- `start`: Return\n\n## Debugger\n\nBy pressing `F12` you can open/close the debug panel. There you can see a view\nto the disassembled code, a view to the PPU memory and state, the CPU\nregisters, etc. At the bottom there is a text field for command input.\n\n### Debugger commands\n\n- `step` (`F8`): execute 1 opcode.\n- `stepback` (`F7`): reverse by 1 opcode.\n- `run` (`F9`): continue to run.\n- `run for \u003cclock_count\u003e`: run for the given number of cycles.\n- `run until \u003cclock_count\u003e`: run until the total clock count reach the given value.\n- `runto \u003caddress\u003e`: run until reaching the address.\n- `watch \u003caddress\u003e`: add a memory address to the watch list, where its value will be displayed.\n- `break \u003cflags\u003e \u003caddress\u003e`: add a breakpoint to a memory address. Flags is a continuous\n   string containing at least one of the following letters:\n  - `x`: break immediately before executing an opcode in the address.\n  - `j`: break immediately before jumping to the address.\n  - `r`: break immediately before reading the address\n  - `w`: break immediately before writing to the address\n- `reset`: restarts the Game Boy.\n- `dump \u003cpath\u003e`: write the current disassembled code to a file. This disassembly is not\n  complete nor is in a known format.\n\nPressing `Enter` with the text field empty will run a step.\n\n#### Examples\n\n- `break rw ff45`: break immediately before reading or writing to the LYC register. \n- `break x 0048`: break immediately before executing the STAT Interrupt handler.\n- `watch ff05`: watch the value of the TIMA register. \n\n## Test suite\n\nAll test roms used were obtained from [c-sp/gameboy-test-roms v.51](https://github.com/c-sp/gameboy-test-roms/releases/tag/v5.1),\nbut the emulator was only run against the tests listed below.\n\nTo run all tests, download and extract the suite to `gameroy\\core\\tests\\gameboy-test-roms`,\nthen go to the project root and run the command:\n\n```shell\ncargo test -p gameroy-core\n```\n\n### Blargg's tests\n                             \n| Test           | GameRoy |\n|----------------|---------|\n| cgb sound      | N/A\\*   |\n| cpu instrs     | :+1:    |\n| dmg sound      | :+1:    |\n| instr timing   | :+1:    |\n| interrupt time | N/A\\*   |\n| mem timing     | :+1:    |\n| mem timing 2   | :+1:    |\n| oam bug        | :x:     |\n\n\\* need GBC support. GameRoy only supports DMG.\n\n### Mooneye Test Suite\n\nOnly tests that were expected to pass on DMG were tested.\n\n| Test                  | GameRoy |\n|-----------------------|---------|\n| acceptance\\bits       | :+1:    |\n| acceptance\\instr      | :+1:    |\n| acceptance\\interrupts | :+1:    |\n| acceptance\\oam_dma    | :+1:    |\n| acceptance\\ppu        | :+1:    |\n| acceptance\\serial     | :+1:    |\n| acceptance\\timer      | :+1:    |\n| acceptance\\           | :+1:    |\n| emulator_only\\mbc1    | :+1:    |\n| emulator_only\\mbc2    | :+1:    |\n| emulator_only\\mbc5    | :+1:    |\n| manual-only\\          | :+1:    |\n| other                 | N/A\\*   |\n\n\\* Not tested.\n\n### Mealybug Tearoom tests\n\n| Test | GameRoy |\n|------|---------|\n| ppu  | 15/25   |\n| mbc  | 0/1     |\n| dma  | N/A\\*   |\n\n\\* CGB only\n\n### DMG Acid 2\n\n:+1:\n\n### Age\n\n1/7\\*\n\n\\* Only tests that passed on SameBoy were tested.\n\n### Same suite\n\n0/3\\*\n\n\\* Only tests that passed on SameBoy were tested. Was not sure which tests should pass on DMG.\n\n## Resources To Be Thankful For\n\n- [The Ultimate Game Boy Talk (33c3)](https://www.youtube.com/watch?v=HyzD8pNlpwI): great overview of\n  the Game Boy and various of it components, including the ppu fifo.\n- [Game Boy:tm: CPU Manual](http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf): used for implement most\n  if not all of the opcodes.\n- [gb-opcodes](https://gbdev.io/gb-opcodes/optables/): used for opcode reference, and the JSON format\n  was very helpful for generating lookup tables and switch cases.\n- [Game Boy Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf): used for\n  implementing precise memory access timing of instructions.\n- [Pan Docs](https://gbdev.io/pandocs/): used for overall reference.\n- [GBEDG](https://hacktixme.ga/GBEDG/): used for the implementation of the\n  timer, and the initial implementation of the PPU.\n- [NightShade's Blog](https://nightshade256.github.io/2021/03/27/gb-sound-emulation.html#fnref:2) and\n  [gbdev.gg8.se](https://gbdev.gg8.se/wiki/articles/Gameboy_sound_hardware): used for most of the\n  implementation of the sound controller.\n- [Same Boys source code](https://github.com/LIJI32/SameBoy): great help for\n  the last details of the sound controller, and without it I would never manage\n  to implement a cycle accurate PPU.\n- And maybe more that I don't remember now.\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or\n   http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or\n   http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRodrigodd%2Fgameroy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRodrigodd%2Fgameroy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRodrigodd%2Fgameroy/lists"}