amjad50/mizu

Mizu is an accurate Gameboy emulator built in Rust

Emulating The original gameboy (DMG) and gameboy color hardware

Mizu

.

Features

  • .
  • Passing most hardware tests (see TESTING.md).
  • Bettery save support.
  • Control SRAM save file and ability to disable SRAM save.
  • Accurate RTC emulation for MBC3 mapper.
  • Accurate APU emulation with 48KHz audio.
  • SFML gui front-end.
  • Robust testing framework for continous testing.
  • Easily change emulation speed.
  • Functional mappers:
    • NoMapper
    • MBC1
    • MBC2
    • MBC3
    • MBC5
  • Printer emulation
  • Save states

Controls

The SFML front-end provide these keyboard bindings:

Gameboy

Key Gameboy
J B
K A
U Select
I Start
W Up
S Down
A Left
D Right

Extra

Key Function
Enter A+B+Select+Start*
+ Increase 5 to FPS**
- Recude 5 from FPS**
P Open Printer
(NUM1~NUM0) Save state
Shift + (NUM1~NUM0) Load state
C Output All audio channels (default)
V Output Pulse1 audio channel only
B Output Pulse2 audio channel only
N Output Wave audio channel only
M Output Noise audio channel only

* I made this because in Zelda: Link's awakening you need to press all of these buttons on the same frame to bring the save menu, which is annoying.

** FPS here is not the same with normal games FPS, where low FPS just makes the game laggy, here FPS control the emulation speed. Normally it will run on 60 FPS. If the user set FPS to 30 it will emulate in half the speed, this include audio, and CPU emulation.

Printer window keys

Key Function
C Clear current image buffer
S Save image buffer to file

Printer

Gameboy Printer is a serial device that can be connected to the gameboy and used by some cartridges to print images. Popular cartidges that uses it are:

  • Gameboy Camera.
  • Zelda: Link's Awakening DX (to print images from the album).
  • Pokemon (several versions) (to print pokemon info from the Pokedex).

The printer can be opened by pressing the P key.

The printer emulation allows to save the printed images into disk. The window will only show 160x144 pixels, but the image is scrollable.

Save states

Save state is a very useful features emulators should have, it allows to save the state of the whole emulator at any point in time and be loaded any time later. mizu's save states files are saved in these folders:

Linux:   /home/<user>/.local/share/mizu/saved_states
Windows: C:\Users\<user>\AppData\Local\Amjad50\Mizu\data\saved_states
macOS:   /Users/<user>/Library/Application Support/Amjad50.Mizu/saved_states

The structure of the save file is at version 2:

Offset Size Field
0x00 4 MAGIC: "MST\xee" (4D 53 54 EE)
0x04 8 save state file version
0x0C 32 cartridge sha256 hash
0x2C variable zstd default level compressed saved state

There is no migrations between file versions (except from 1 to 2), that means that a file saved from a past version of the emulator will not be able to be loaded in a future version of the emulator. (If any suggestions on how we can achieve this, you are welcome to open a PR).

The hash is used to make sure that we are loading for the same game.

The zstd compression appeared in version 2, that is the reason we can load version s by loading with decompression. The compressed content, is the content we get by using the save_state library.

Building and Installation

For installing or building mizu we would use cargo.

Building

If you want to use the development version of mizu you can build the project yourself. After downloading/cloning the repository, it can be build with:

$ cargo build

With release option:

$ cargo build --release

Installing

If you want to use the latest stable version from crates.io:

$ cargo install mizu

Yet another gameboy emulator?

Why 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.

References

General Gameboy

  • Pandocs (of course)
  • Gameboy manual
  • GameBoy complete techincal reference
  • The cycle accurate gameboy docs
  • Mooneye accurate emulator, includes great tests

CPU instructions

  • Opcode table
  • Simple opcodes explaination

Debugging and testing

  • blargg gameboy tests
  • BGB emulator
  • GB test roms
  • DMG ACID PPU test
  • Mealybug PPU stress tear tests
Versions

Find the latest versions by id

v1.0.0 - May 27, 2022

Improvements to the public API of mizu-core, now its easier to use this library with your custom integration.

v0.2.0 - May 17, 2021

New major updates, featuring save_states and notifications in the UI

v0.1.1 - Feb 07, 2021

Mizu is a gameboy emulator with a goal of making it a very accurate emulator. Mizu can emulate both original gameboy (DMG) and gameboy color hardware (command line --dmg option to pick DMG).

The GUI front for Mizu is SFML. So you would need to install them if you are using linux from your package manager.

Note: frame limiting in emulation is important, I'm using SFML's frame limiting. On linux it is very accurate and stays on 60FPS all the time, but on windows it jumps a bit. Sound might be popping a bit on windows.

Information - Updated Jul 10, 2022

Stars: 15
Forks: 2
Issues: 0

Repositories & Extras

RGB (Rust Game Boy) is a simple emulator for the original game boy and the...

RGB (Rust Game Boy) is a simple emulator for the original game boy and the color game boy

RGB (Rust Game Boy) is a simple emulator for the original game boy and the...

A Gameboy emulator written in Rust

Can launch and play simple games

A Gameboy emulator written in Rust

An open source Gameboy emulator written in Rust that can use a command line interface...

An open source Gameboy emulator written in Rust that can use a command line interface as a screen and input device

An open source Gameboy emulator written in Rust that can use a command line interface...

Frosty is a GameBoy emulator written in rust

You can also hold TAB to enable turbo, which will disable the frame limiter

Frosty is a GameBoy emulator written in rust

Rust GameBoy Advanced Emulator

Building this project on linux requires cmake and gtk3

Rust GameBoy Advanced Emulator

A Rust GameBoy emulator!

TetrisZelda: Link's Awakening

A Rust GameBoy emulator!

Yet another GameBoy emulator in Rust

This is my attempt to write a GameBoy emulator in Rust, to add to the pile of existing ones

Yet another GameBoy emulator in Rust

Game Boy Emulator in Rust

To load a ROM in the emulator specify the path to the ROM file as an argument

Game Boy Emulator in Rust
Facebook Instagram Twitter GitHub Dribbble
Privacy