{"id":13436724,"url":"https://github.com/Gekkio/mooneye-gb","last_synced_at":"2025-03-18T21:30:57.847Z","repository":{"id":24779057,"uuid":"28192577","full_name":"Gekkio/mooneye-gb","owner":"Gekkio","description":"A Game Boy research project and emulator written in Rust","archived":false,"fork":false,"pushed_at":"2023-03-16T03:58:55.000Z","size":1948,"stargazers_count":897,"open_issues_count":43,"forks_count":56,"subscribers_count":30,"default_branch":"master","last_synced_at":"2024-10-27T20:20:55.462Z","etag":null,"topics":["emulator","game-boy","gameboy","gameboy-emulator","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gekkio.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"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":"2014-12-18T16:56:06.000Z","updated_at":"2024-10-27T00:19:08.000Z","dependencies_parsed_at":"2024-06-20T18:45:00.232Z","dependency_job_id":null,"html_url":"https://github.com/Gekkio/mooneye-gb","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gekkio%2Fmooneye-gb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gekkio%2Fmooneye-gb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gekkio%2Fmooneye-gb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gekkio%2Fmooneye-gb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gekkio","download_url":"https://codeload.github.com/Gekkio/mooneye-gb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244310453,"owners_count":20432545,"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","game-boy","gameboy","gameboy-emulator","rust"],"created_at":"2024-07-31T03:00:51.601Z","updated_at":"2025-03-18T21:30:53.798Z","avatar_url":"https://github.com/Gekkio.png","language":"Rust","funding_links":[],"categories":["Applications","Rust","Software Development","应用程序 Applications","Applications written in Rust","应用 Applications","应用","软件开发"],"sub_categories":["Emulators","模拟器 Emulators","仿真器","模拟器"],"readme":"# Mooneye GB\n\nMooneye GB is a Game Boy research project and emulator written in Rust.\n\n[![Build Status](https://github.com/Gekkio/mooneye-gb/workflows/ci/badge.svg)](https://github.com/Gekkio/mooneye-gb/actions)\n\nThe main goals of this project are accuracy and documentation. Some existing\nemulators are very accurate (Gambatte, BGB \u003e= 1.5) but are not documented very\nclearly, so they are not that good references for emulator developers. I want\nthis project to document as clearly as possible *why* certain behaviour is\nemulated in a certain way. This also means writing a lot of test ROMs to figure\nout corner cases and precise behaviour on real hardware.\n\nFor documentation about known behaviour, see [Game Boy: Complete Technical Reference](https://github.com/Gekkio/gb-ctr)\n\n*Looking for the mooneye-gb test ROMs?* They are now part of [Mooneye Test Suite](https://github.com/Gekkio/mooneye-test-suite/).\n\nNon-goals:\n\n* CGB (Game Boy Color) support. It would be nice, but I want to make the normal\n  Game Boy support extremely robust first.\n* A debugger\n* A good user interface. Building native UIs with Rust is a bit painful at the\n  moment.\n\n**Warning**:\n\n* Project is WIP\n* Doesn't work properly without a boot ROM\n* The emulator is lagging behind hardware research. I don't want to spend time\n  making short-lived and probably incorrect fixes to the emulator if I'm not\n  sure about the hardware behaviour.\n\n## Performance\n\n**Always compile in release mode if you care about performance!**\n\nOn a i7-3770K desktop machine I can usually run ROMs with 2000 - 4000% speed.\nWithout optimizations the speed drops to 150 - 200%, which is still fine for\ndevelopment purposes.\n\nRaspberry Pi with X11 desktop works but is too slow because there is no OpenGL\nacceleration.\n\nThe emulator is runnable on Android, but cross-compiling and packaging is a\nhuge pain and touch controls would have to be implemented, so I'm not\nsupporting Android at the moment.\n\n## Running the emulator\n\nRequirements:\n\n* Rust 1.26\n* SDL2 development libraries for your platform must be installed\n\n### GUI\n\n1. `cargo run --release`\n2. Follow the instructions\n\n### Command-line\n1. Acquire a Game Boy bootrom, and put it to `$HOME/.local/share/mooneye-gb/bootroms/dmg_boot.bin`\n2. `cargo build --release`\n3. `cargo run --release -- PATH_TO_GAMEBOY_ROM`\n\nOn Windows, also download an SDL2 package containing SDL2.dll, and put it to\n`target/debug` and `target/release`.\n\n### Game Boy keys\n\n| Game Boy | Key        |\n| -------- | ---------- |\n| Dpad     | Arrow keys |\n| A        | Z          |\n| B        | X          |\n| Start    | Return     |\n| Select   | Backspace  |\n\n### Other keys\n\n| Function                   | Key       |\n| -------------------------- | --------- |\n| Fast forward               | Shift     |\n| Toggle performance overlay | F2        |\n\n## Test suite\n\n### Blargg's tests\n\n| Test              | mooneye-gb |\n| ----------------- | ---------- |\n| cpu instrs        | :+1:       |\n| dmg sound 2       | :x:        |\n| instr timing      | :+1:       |\n| mem timing 2      | :+1:       |\n| oam bug 2         | :x:        |\n| cgb sound 2       |            |\n\nNotes:\n\n* cpu_instrs fails on MGB/SGB2 hardware and emulators emulating them correctly.\n  The ROM incorrectly detects the device as CGB, and attempts to perform a CPU\n  speed change which causes a freeze (STOP instruction with joypad disabled)\n* dmg_sound-2 test #10 can fail randomly on real hardware and seems to depend\n  on non-deterministic behaviour.\n* oam_bug-2 fails on all CGB, AGB, and AGS devices\n* cgb_sound-2 test #03 fails on CPU CGB, CPU CGB A, and CPU CGB B\n\n### Mooneye GB acceptance tests\n\n| Test                    | mooneye-gb |\n| ----------------------- | ---------- |\n| add sp e timing         | :+1:       |\n| boot div dmg0           | :x:        |\n| boot div dmgABCmgb      | :x:        |\n| boot div S              | :x:        |\n| boot div2 S             | :x:        |\n| boot hwio dmg0          | :x:        |\n| boot hwio dmgABCmgb     | :x:        |\n| boot hwio S             | :+1:       |\n| boot regs dmg0          | :+1:       |\n| boot regs dmgABC        | :+1:       |\n| boot regs mgb           | :+1:       |\n| boot regs sgb           | :+1:       |\n| boot regs sgb2          | :+1:       |\n| call timing             | :+1:       |\n| call timing2            | :+1:       |\n| call cc_timing          | :+1:       |\n| call cc_timing2         | :+1:       |\n| di timing GS            | :+1:       |\n| div timing              | :+1:       |\n| ei sequence             | :+1:       |\n| ei timing               | :+1:       |\n| halt ime0 ei            | :+1:       |\n| halt ime0 nointr_timing | :+1:       |\n| halt ime1 timing        | :+1:       |\n| halt ime1 timing2 GS    | :+1:       |\n| if ie registers         | :+1:       |\n| intr timing             | :+1:       |\n| jp timing               | :+1:       |\n| jp cc timing            | :+1:       |\n| ld hl sp e timing       | :+1:       |\n| oam dma_restart         | :+1:       |\n| oam dma start           | :+1:       |\n| oam dma timing          | :+1:       |\n| pop timing              | :+1:       |\n| push timing             | :+1:       |\n| rapid di ei             | :+1:       |\n| ret timing              | :+1:       |\n| ret cc timing           | :+1:       |\n| reti timing             | :+1:       |\n| reti intr timing        | :+1:       |\n| rst timing              | :+1:       |\n\n#### Bits (unusable bits in memory and registers)\n\n| Test           | mooneye-gb |\n| -------------- | ---------- |\n| mem oam        | :+1:       |\n| reg f          | :+1:       |\n| unused_hwio GS | :+1:       |\n\n#### Instructions\n\n| Test                        | mooneye-gb |\n| --------------------------- | ---------- |\n| daa                         | :+1:       |\n\n#### Interrupt handling\n\n| Test                        | mooneye-gb |\n| --------------------------- | ---------- |\n| ie push                     | :+1:       |\n\n#### OAM DMA\n\n| Test                        | mooneye-gb |\n| --------------------------- | ---------- |\n| basic                       | :+1:       |\n| reg_read                    | :+1:       |\n| sources GS                  | :+1:       |\n\n#### PPU\n\n| Test                        | mooneye-gb |\n| --------------------------- | ---------- |\n| hblank ly scx timing GS     | :+1:       |\n| intr 1 2 timing GS          | :+1:       |\n| intr 2 0 timing             | :+1:       |\n| intr 2 mode0 timing         | :+1:       |\n| intr 2 mode3 timing         | :+1:       |\n| intr 2 oam ok timing        | :+1:       |\n| intr 2 mode0 timing sprites | :x:        |\n| lcdon timing GS             | :x:        |\n| lcdon write timing GS       | :x:        |\n| stat irq blocking           | :x:        |\n| stat lyc onoff              | :x:        |\n| vblank stat intr GS         | :+1:       |\n\n#### Serial\n\n| Test                        | mooneye-gb |\n| --------------------------- | ---------- |\n| boot sclk align dmgABCmgb   | :x:        |\n\n#### Timer\n\n| Test                 | mooneye-gb |\n| -------------------- | ---------- |\n| div write            | :+1:       |\n| rapid toggle         | :+1:       |\n| tim00 div trigger    | :+1:       |\n| tim00                | :+1:       |\n| tim01 div trigger    | :+1:       |\n| tim01                | :+1:       |\n| tim10 div trigger    | :+1:       |\n| tim10                | :+1:       |\n| tim11 div trigger    | :+1:       |\n| tim11                | :+1:       |\n| tima reload          | :+1:       |\n| tima write reloading | :+1:       |\n| tma write reloading  | :+1:       |\n\n### Mooneye GB emulator-only tests\n\n#### MBC1\n\n| Test              | mooneye-gb |\n| ----------------- | ---------- |\n| bits bank1        | :+1:       |\n| bits bank2        | :+1:       |\n| bits mode         | :+1:       |\n| bits ramg         | :+1:       |\n| rom 512kb         | :+1:       |\n| rom 1Mb           | :+1:       |\n| rom 2Mb           | :+1:       |\n| rom 4Mb           | :+1:       |\n| rom 8Mb           | :+1:       |\n| rom 16Mb          | :+1:       |\n| ram 64kb          | :+1:       |\n| ram 256kb         | :+1:       |\n| multicart rom 8Mb | :+1:       |\n\n#### MBC2\n\n| Test              | mooneye-gb |\n| ----------------- | ---------- |\n| bits ramg         | :+1:       |\n| bits romb         | :+1:       |\n| bits unused       | :+1:       |\n| rom 512kb         | :+1:       |\n| rom 1Mb           | :+1:       |\n| rom 2Mb           | :+1:       |\n| ram               | :+1:       |\n\n#### MBC5\n\n| Test              | mooneye-gb |\n| ----------------- | ---------- |\n| rom 512kb         | :+1:       |\n| rom 1Mb           | :+1:       |\n| rom 2Mb           | :+1:       |\n| rom 4Mb           | :+1:       |\n| rom 8Mb           | :+1:       |\n| rom 16Mb          | :+1:       |\n| rom 32Mb          | :+1:       |\n| rom 64Mb          | :+1:       |\n\n### Mooneye GB manual tests\n\n| Test            | mooneye-gb |\n| --------------- | ---------- |\n| sprite priority | :+1:       |\n\n### Mooneye GB misc tests\n\n| Test              | mooneye-gb |\n| ---------------   | ---------- |\n| boot div A        |            |\n| boot div cgb0     |            |\n| boot div cgbABCDE |            |\n| boot hwio C       |            |\n| boot regs A       |            |\n| boot regs cgb     |            |\n\n#### Bits\n\n| Test          | mooneye-gb |\n| ------------- | ---------- |\n| unused hwio C |            |\n\n#### PPU\n\n| Test               | mooneye-gb |\n| ------------------ | ---------- |\n| vblank stat intr C |            |\n\n# License and copyright\n\nMooneye GB is licensed under GPLv3+.\nCopyright (C) 2014-2020 Joonas Javanainen \u003cjoonas.javanainen@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGekkio%2Fmooneye-gb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGekkio%2Fmooneye-gb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGekkio%2Fmooneye-gb/lists"}