{"id":23002614,"url":"https://github.com/amjad50/mizu","last_synced_at":"2025-07-22T13:35:06.468Z","repository":{"id":39678888,"uuid":"314881886","full_name":"Amjad50/mizu","owner":"Amjad50","description":"Gameboy emulator in Rust","archived":false,"fork":false,"pushed_at":"2024-03-15T18:28:06.000Z","size":2024,"stargazers_count":32,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-03T03:47:51.905Z","etag":null,"topics":["emulator","game-boy","gameboy","gameboy-emulator","hacktoberfest","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/Amjad50.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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-11-21T18:53:01.000Z","updated_at":"2024-11-01T19:51:48.000Z","dependencies_parsed_at":"2024-12-15T07:11:52.207Z","dependency_job_id":null,"html_url":"https://github.com/Amjad50/mizu","commit_stats":{"total_commits":326,"total_committers":3,"mean_commits":"108.66666666666667","dds":"0.018404907975460127","last_synced_commit":"396d6b12b9703a00ddc0d3f1f335003be5b5f645"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Amjad50/mizu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2Fmizu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2Fmizu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2Fmizu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2Fmizu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Amjad50","download_url":"https://codeload.github.com/Amjad50/mizu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2Fmizu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266506252,"owners_count":23940021,"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-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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","game-boy","gameboy","gameboy-emulator","hacktoberfest","rust"],"created_at":"2024-12-15T07:11:45.627Z","updated_at":"2025-07-22T13:35:06.435Z","avatar_url":"https://github.com/Amjad50.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mizu\n[![Build status](https://github.com/Amjad50/mizu/workflows/Rust/badge.svg)](https://github.com/Amjad50/mizu/actions?query=workflow%3ARust)\n[![codecov](https://codecov.io/gh/Amjad50/mizu/branch/master/graph/badge.svg)](https://codecov.io/gh/Amjad50/mizu)\n[![crate.io](https://img.shields.io/crates/v/mizu)](https://crates.io/crates/mizu)\n[![dependency status](https://deps.rs/repo/github/Amjad50/mizu/status.svg)](https://deps.rs/repo/github/Amjad50/mizu)\n\nMizu is an accurate Gameboy emulator built in Rust.\n\n\n## Features\n- Emulating The original gameboy (DMG) and gameboy color hardware.\n- Passing most hardware tests (see [TESTING.md](./TESTING.md)).\n- Bettery save support.\n- Control SRAM save file and ability to disable SRAM save.\n- Accurate RTC emulation for MBC3 mapper.\n- Accurate APU emulation with 48KHz audio.\n- SFML gui front-end.\n- Robust testing framework for continous testing.\n- Easily change emulation speed.\n- Functional mappers:\n    - NoMapper\n    - MBC1\n    - MBC2\n    - MBC3\n    - MBC5\n- Printer emulation\n- Save states\n\n# Controls\nThe SFML front-end provide these keyboard bindings:\n\n## Gameboy\n\n| Key | Gameboy |\n| --- | ------- |\n| J   | B       |\n| K   | A       |\n| U   | Select  |\n| I   | Start   |\n| W   | Up      |\n| S   | Down    |\n| A   | Left    |\n| D   | Right   |\n\n## Extra\n\n| Key                 | Function                              |\n| ------------------- | ------------------------------------- |\n| Enter               | A+B+Select+Start\\*                    |\n| +                   | Increase 5 to FPS\\*\\*                 |\n| -                   | Recude 5 from FPS\\*\\*                 |\n| P                   | Open Printer                          |\n| (NUM1~NUM0)         | Save state                            |\n| Shift + (NUM1~NUM0) | Load state                            |\n| C                   | Output `All` audio channels (default) |\n| V                   | Output `Pulse1` audio channel only    |\n| B                   | Output `Pulse2` audio channel only    |\n| N                   | Output `Wave` audio channel only      |\n| M                   | Output `Noise` audio channel only     |\n\n\u003e \\* I made this because in `Zelda: Link's awakening` you need to press\n\u003e all of these buttons on the same frame to bring the save menu, which is annoying.\n\n\u003e \\*\\* FPS here is not the same with normal games FPS, where low FPS just makes the game\n\u003e laggy, here FPS control the emulation speed. Normally it will run on `60` FPS.\n\u003e If the user set FPS to `30` it will emulate in half the speed, this include audio,\n\u003e and CPU emulation.\n\n## Printer window keys\n\n| Key   | Function                   |\n| ----- | -------------------------- |\n| C     | Clear current image buffer |\n| S     | Save image buffer to file  |\n\n# Printer\nGameboy Printer is a serial device that can be connected to the gameboy and\nused by some cartridges to print images. Popular cartidges that uses it are:\n- Gameboy Camera.\n- Zelda: Link's Awakening DX (to print images from the album).\n- Pokemon (several versions) (to print pokemon info from the Pokedex).\n\nThe printer can be opened by pressing the `P` key.\n\nThe printer emulation allows to save the printed images into disk. The window\nwill only show `160x144` pixels, but the image is scrollable.\n\n# Save states\nSave state is a very useful features emulators should have, it allows\nto save the state of the whole emulator at any point in time and be loaded\nany time later. `mizu`'s save states files are saved in these folders:\n```txt\nLinux:   /home/\u003cuser\u003e/.local/share/mizu/saved_states\nWindows: C:\\Users\\\u003cuser\u003e\\AppData\\Local\\Amjad50\\Mizu\\data\\saved_states\nmacOS:   /Users/\u003cuser\u003e/Library/Application Support/Amjad50.Mizu/saved_states\n```\nThe structure of the save file is at version `2`:\n| Offset | Size      | Field                                       |\n| ------ | --------- |-------------------------------------------- |\n| 0x00   | 4         | MAGIC: `\"MST\\xee\"` `(4D 53 54 EE)`          |\n| 0x04   | 8         | save state file version                     |\n| 0x0C   | 32        | cartridge `sha256` hash                     |\n| 0x2C   | variable  | `zstd` default level compressed saved state |\n\nThere is no migrations between file versions (except from `1` to `2`), that means\nthat a file saved from a past version of the emulator will not be able to be loaded\nin a future version of the emulator.\n(If any suggestions on how we can achieve this, you are welcome to open a PR).\n\nThe `hash` is used to make sure that we are loading for the same game.\n\nThe `zstd` compression appeared in version `2`, that is the reason we can load version `s`\nby loading with decompression. The compressed content, is the content we get\nby using the [`save_state`](./save_state) library.\n\n# Building and Installation\nFor installing or building `mizu` we would use `cargo`.\n\n## Building\nIf you want to use the development version of `mizu` you can build the project\nyourself. After downloading/cloning the repository, it can be build with:\n```\n$ cargo build\n```\nWith release option:\n```\n$ cargo build --release\n```\n\n## Installing\nIf you want to use the latest stable version from `crates.io`:\n```\n$ cargo install mizu\n```\n\n\n# Yet another gameboy emulator?\nWhy not?. it is fun and educational, but even though I'm planning to make it as accurate as I can. If you want to see cool emulators, check my previous work [Plastic].\n\n# References\n### General Gameboy\n- [Pandocs (of course)](https://gbdev.io/pandocs/)\n- [Gameboy manual](http://www.codeslinger.co.uk/pages/projects/gameboy/files/GB.pdf)\n- [GameBoy complete techincal reference](https://gekkio.fi/files/gb-docs/gbctr.pdf)\n- [The cycle accurate gameboy docs](https://github.com/AntonioND/giibiiadvance/blob/master/docs/TCAGBD.pdf)\n- [Mooneye accurate emulator, includes great tests](https://github.com/Gekkio/mooneye-gb)\n### CPU instructions\n- [Opcode table](https://gbdev.io/gb-opcodes//optables/dark)\n- [Simple opcodes explaination](http://gameboy.mongenel.com/dmg/opcodes.html)\n### Debugging and testing\n- [blargg gameboy tests](https://gbdev.gg8.se/files/roms/blargg-gb-tests/)\n- [BGB emulator](https://bgb.bircd.org/)\n- [GB test roms](https://github.com/retrio/gb-test-roms)\n- [DMG ACID PPU test](https://github.com/mattcurrie/dmg-acid2)\n- [Mealybug PPU stress tear tests](https://github.com/mattcurrie/mealybug-tearoom-tests)\n\n\n[Plastic]: https://github.com/Amjad50/plastic\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famjad50%2Fmizu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famjad50%2Fmizu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famjad50%2Fmizu/lists"}