{"id":16012563,"url":"https://github.com/aksiksi/gbc","last_synced_at":"2025-03-16T07:32:19.176Z","repository":{"id":50517899,"uuid":"323416256","full_name":"aksiksi/gbc","owner":"aksiksi","description":"A Gameboy Color (GBC) emulator written in Rust.","archived":false,"fork":false,"pushed_at":"2024-10-19T00:58:14.000Z","size":11531,"stargazers_count":40,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-15T01:26:47.464Z","etag":null,"topics":["emulation","emulator","gameboy-color","gbc","rust","sdl2","wasm"],"latest_commit_sha":null,"homepage":"https://aksiksi.github.io/gbc","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aksiksi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2020-12-21T18:24:54.000Z","updated_at":"2025-01-04T15:50:14.000Z","dependencies_parsed_at":"2024-10-22T20:23:07.017Z","dependency_job_id":null,"html_url":"https://github.com/aksiksi/gbc","commit_stats":{"total_commits":232,"total_committers":2,"mean_commits":116.0,"dds":"0.017241379310344862","last_synced_commit":"4df8de52c55155f6ec138e2145def71154743499"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aksiksi%2Fgbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aksiksi%2Fgbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aksiksi%2Fgbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aksiksi%2Fgbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aksiksi","download_url":"https://codeload.github.com/aksiksi/gbc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806046,"owners_count":20350775,"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":["emulation","emulator","gameboy-color","gbc","rust","sdl2","wasm"],"created_at":"2024-10-08T14:04:03.385Z","updated_at":"2025-03-16T07:32:17.927Z","avatar_url":"https://github.com/aksiksi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gbc\n\n![Rust](https://github.com/aksiksi/gbc/workflows/Rust/badge.svg)\n\nA Gameboy Color (GBC) emulator written in Rust. This is intended as a learning project. \n\n![donkey_kong_country](https://user-images.githubusercontent.com/916621/106340437-ca4b0600-6267-11eb-818a-961c4f499110.gif)\n\n## Quick Start\n\n### 1. Download\n\nVisit the [Releases](https://github.com/aksiksi/gbc/releases) page and download the latest version for your OS.\n\n### 2. Run\n\nRun a ROM:\n\n```\ngbcemu run [path_to_rom]\n```\n\nRun with `-h` to view all flags and options.\n\n### 3. Play\n\nControls:\n\n* Arrows for direction keys\n* `S`: A button\n* `A`: B button\n* `X`: start button\n* `Z`: select button\n\nEmulator GUI keys:\n\n* `K`: save emulator state\n* `L`: load emulator state\n* `;`: reset the emulator\n* `O`: draw basic tile outline (toggle)\n* `P`: pause (toggle)\n* `]`: Fast-forward (while held)\n* `=`: Increase emulation speed by 1x\n* `-`: Decrease emulation speed by 1x\n* `0`: Reset emulation speed to 1x\n\nNote: these are replaced with buttons in the WASM version.\n\n## Games Tested\n\n- [x] Dr. Mario (DMG, no ROM banking)\n- [x] Tetris World (DMG, no ROM banking)\n- [x] Kirby's Dream Land (DMG, MBC1)\n- [x] Tetris World DX (GBC, MBC1)\n- [x] Super Mario Bros. Deluxe (GBC, MBC5)\n- [x] Pokemon Yellow (GBC, MBC5)\n- [x] Donkey Kong Country (GBC, MBC5)\n- [x] Dragon Warrior Monsters (GBC, MBC5)\n- [x] The Legend of Zelda: Link's Awakening DX (GBC, MBC5)\n- [ ] Pokemon Gold (GBC, MBC3+RTC)\n    - Hits glitch after intro (#3)\n- [ ] Shantae (GBC, MBC5)\n    - Not working, stuck on blue screen\n\n## Details\n\n### Project Structure\n\nThe emulator is divided into three crates:\n\n1. `lib`: main library for emulating a Gameboy\n2. `emu`: emulator frontend GUI written using SDL2 (runs on macOS, Windows, and Linux)\n3. `emu-wasm`: `lib` compiled to WASM and running on a [`Canvas2D`](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) in JS\n\n### Tests\n\nThere are two types of tests:\n\n1. Functional tests: verify the basic functions of the CPU and peripherals\n2. Integration tests: run existing test ROMs and ensure that they pass\n\nThese tests run on every commit to the repo.\n\n### Building\n\nDue to the SDL dependency, you have to install some dependencies before you can build the emulator. Note that SDL is automatically built as part of the Rust-SDL2 build script, but the script needs a few tools:\n\n1. CMake\n2. C compiler (MSVC, GCC, Clang)\n\nSince we statically link against `libsdl` on all platforms to avoid having to ship the DLL with the emulator, you do not need to install SDL for the build.\n\n#### Windows\n\n1. Install the VSC++ build tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/\n2. Install `rustup` (this also installs `rustc` and `cargo`): https://www.rust-lang.org/tools/install\n3. Install CMake: https://cmake.org/download/\n4. `cargo build`\n\nThe full build in release mode (including SDL) on a 10 core Windows VM takes ~1 min.\n\n### Debugger\n\nThe emulator comes with a simple GDB-like debugger CLI. Note that the debugger is not included by default.\n\nTo build the emulator with debugger support:\n\n```\ncargo build --manifest-path emu/Cargo.toml --features debug\n```\n\nAs soon as you run the emulator, it will jump into the REPL. The following commands are available:\n\n* `n`: Step to the next instruction.\n    * `n \u003cnum\u003e`: Skip the next `num` instructions.\n* `info [r]egs`: Dump all registers.\n* `p \u003caddr\u003e`: Print the byte at the specified memory address.\n* `b \u003caddr\u003e`: Set a breakpoint on an instruction address. Note that you can have multiple active breakpoints.\n* `info [b]reak`: List all breakpoints that have been set.\n* `disable \u003cindex\u003e`: Disable the breakpoint with the given index.\n* `d \u003cindex\u003e`: Delete the breakpoint with the given address.\n* `r`: Continue running the emulator until the next breakpoint is hit.\n* `[l]ist`: Disassemble the next five instructions, starting from the current one.\n    * `[l]ist \u003ccount\u003e`: Disassemble the next `count` instructions, starting from the current one.\n* `[h]ist`: Dump the last five *executed* instructions.\n    * `[h]ist \u003ccount\u003e`: Dump the last `count` *executed* instructions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faksiksi%2Fgbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faksiksi%2Fgbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faksiksi%2Fgbc/lists"}