{"id":31655537,"url":"https://github.com/otaleghani/zigboy","last_synced_at":"2025-10-07T13:15:23.922Z","repository":{"id":311906253,"uuid":"1045533112","full_name":"otaleghani/zigboy","owner":"otaleghani","description":"A Gameboy (DMG) emulator written in Zig and SDL3. Currently supports ROM-only and MBC1 cartridges.","archived":false,"fork":false,"pushed_at":"2025-08-27T10:38:30.000Z","size":630,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-27T19:54:34.598Z","etag":null,"topics":["emulator","gameboy","gameboy-emulator","retro-gaming","sdl3","system-programming","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/otaleghani.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,"zenodo":null}},"created_at":"2025-08-27T10:22:43.000Z","updated_at":"2025-08-27T10:27:11.000Z","dependencies_parsed_at":"2025-08-27T19:54:38.110Z","dependency_job_id":"c38fa068-22a2-42e2-9949-efa012eb7ca4","html_url":"https://github.com/otaleghani/zigboy","commit_stats":null,"previous_names":["otaleghani/zigboy"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/otaleghani/zigboy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaleghani%2Fzigboy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaleghani%2Fzigboy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaleghani%2Fzigboy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaleghani%2Fzigboy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/otaleghani","download_url":"https://codeload.github.com/otaleghani/zigboy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otaleghani%2Fzigboy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278780091,"owners_count":26044499,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["emulator","gameboy","gameboy-emulator","retro-gaming","sdl3","system-programming","zig"],"created_at":"2025-10-07T13:15:22.417Z","updated_at":"2025-10-07T13:15:23.914Z","avatar_url":"https://github.com/otaleghani.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zigboy\nZigboy is a Gameboy (DMG) emulator written in Zig. It uses the SDL3 library for windowing, input, and audio. It currently supports ROM-only and MBC1 cartridges.\n\n### Screenshots\n\nHere is a gallery of the emulator in action, running a few classic titles.\n\n---\n\n#### Super Mario Land\n\n| | | |\n| :---: | :---: | :---: |\n| ![Super Mario Land 1](screenshots/super-mario-land-01.gif) | ![Super Mario Land 2](screenshots/super-mario-land-02.gif) | ![Super Mario Land 3](screenshots/super-mario-land-03.gif) |\n| ![Super Mario Land Animation 1](screenshots/super-mario-land-anim-01.gif) | ![Super Mario Land Animation 2](screenshots/super-mario-land-anim-02.gif) | |\n\n---\n\n#### Tetris\n\n| | | |\n| :---: | :---: | :---: | \n| ![Tetris 1](screenshots/tetris-01.gif) | ![Tetris 2](screenshots/tetris-02.gif) | ![Tetris Animation 1](screenshots/tetris-anim-01.gif) |\n\n---\n\n#### The Legend of Zelda: Link's Awakening\n\n| | | |\n| :---: | :---: | :---: |\n| ![Zelda 1](screenshots/zelda-01.gif) | ![Zelda 2](screenshots/zelda-02.gif) | ![Zelda 3](screenshots/zelda-03.gif) |\n| ![Zelda Animation 1](screenshots/zelda-anim-01.gif) | ![Zelda Animation 2](screenshots/zelda-anim-02.gif) | ![Zelda Animation 3](screenshots/zelda-anim-03.gif) |\n| ![Zelda Animation 4](screenshots/zelda-anim-04.gif) | | |\n\n\n## Features\n\n- *CPU*: Implements the full SM83 (Gameboy-variant Z80) instruction set.\n- *PPU (Picture Processing Unit)*: Renders graphics for many classic titles. Handles background tiles, window rendering, and sprites.\n- *APU (Audio Processing Unit)*: A basic implementation of the Gameboy's sound hardware is included but is currently buggy and impacts performance. It can be disabled at build time.\n- *Cartridge Support*:\n    - ROM-only cartridges.\n    - MBC1 (Memory Bank Controller 1) for games with larger ROMs and RAM.\n- *Debugging*: Includes optional flags for printing CPU state and generating logs compatible with the [Gameboy Doctor](https://robertheaton.com/gameboy-doctor/) debugging tool.\n\n## Usage\n\n### Prerequisites\nInstall [Zig](https://ziglang.org/) (version 0.14.1) and [SDL3](https://libsdl.org/). If you are using NixOs you could just use the `flake.nix` to install dependencies.\n``` bash\ngit clone https://github.com/otaleghani/zigboy\ncd zigboy\nnix develop\n```\n\n### Build\n``` bash\n# Standard build (APU disabled):\nzig build\n\n# Build with the (buggy) APU enabled:\nzig build -Denable_apu=true\n\n# Build with CPU debug logging for diagnostics:\nzig build -Denable_cpu_debug=true\n\n# Build with Gameboy Doctor compatible logging:\nzig build -Denable_cpu_debug_gbd=true\n```\n\n### Run\n``` bash \n# Run the emulator with a path to a Gameboy ROM file:\n./zig-out/bin/zigboy path/to/your/rom.gb\n```\n\n### Controls\n\nThe emulator uses the keyboard for input. The default key mappings are:\n\n| Keyboard Key | Gameboy Button |\n| :----------- | :------------- |\n| W, A, S, D   | D-Pad (Up, Left, Down, Right) |\n| Z            | A Button       |\n| X            | B Button       |\n| Enter        | Start Button   |\n| P            | Select Button  |\n| Escape       | Quit Emulator  |\n\n### Compatibility\n\nThe emulator is still in an early stage of development. While the goal is broad compatibility, rigorous testing has been focused on a core set of titles.\n\n**Confirmed Playable:**\n* *Tetris*\n* *The Legend of Zelda: Link's Awakening*\n* *Super Mario Land*\n\nAttempting to run other ROMs, especially those using more complex mappers or hitting obscure hardware edge cases, may result in graphical glitches, freezes, or a panic. There are still many bugs to solve, and stability with a wider range of games is a top priority for future development.\n\n## References\n\nThis project would not have been possible without the extensive documentation created by the retro-development community. Key resources used during development include:\n\n- [Pan Docs](https://gbdev.io/pandocs/): The single most comprehensive hardware reference for the Gameboy.\n- [Game Boy: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf): In-depth details on instruction timing and hardware quirks.\n- [Game Boy CPU Instruction Set](https://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html): Instruction set of the CPU (LR35902)\n- [Blargg's GB Test ROMs](https://github.com/retrio/gb-test-roms): A suite of test ROMs used to verify emulator accuracy.\n\n## Current status\nThis project is a work-in-progress. While many games are playable, there are known issues:\n\n- APU Bugs: The audio implementation has timing and synchronization problems, leading to incorrect sound output.\n- Performance: With the APU enabled, the frame rate drops to 40-50 FPS due to inefficiencies in the current implementation.\n- Test ROMs: Some of Blargg's hardware test ROMs still fail, indicating inaccuracies in CPU timing or CPU/PPU synchronization.\n\n## Future Improvements\n\n- Fix APU: Debug and rewrite the APU for accuracy and performance.\n- Pass Test ROMs: Work towards passing all of Blargg's test ROMs for higher accuracy.\n- More Mappers: Add support for MBC2, MBC3, and MBC5 to increase game compatibility.\n- UI/UX: Implement features like save states, controller remapping, and display scaling options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotaleghani%2Fzigboy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fotaleghani%2Fzigboy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotaleghani%2Fzigboy/lists"}