{"id":50316354,"url":"https://github.com/ioncodes/gecko","last_synced_at":"2026-06-07T03:07:35.637Z","repository":{"id":358975947,"uuid":"1201567738","full_name":"ioncodes/gecko","owner":"ioncodes","description":"A GameCube/Wii emulator and debugger written in Rust.","archived":false,"fork":false,"pushed_at":"2026-05-28T21:27:43.000Z","size":30113,"stargazers_count":225,"open_issues_count":8,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-05-29T00:22:07.668Z","etag":null,"topics":["emulation","emulator","gamecube","wii"],"latest_commit_sha":null,"homepage":"https://emu.layle.dev","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/ioncodes.png","metadata":{"files":{"readme":"README.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T21:16:03.000Z","updated_at":"2026-05-28T14:22:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ioncodes/gecko","commit_stats":null,"previous_names":["ioncodes/gecko"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/ioncodes/gecko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncodes%2Fgecko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncodes%2Fgecko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncodes%2Fgecko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncodes%2Fgecko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioncodes","download_url":"https://codeload.github.com/ioncodes/gecko/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncodes%2Fgecko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33803753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"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":["emulation","emulator","gamecube","wii"],"created_at":"2026-05-29T00:03:04.735Z","updated_at":"2026-06-02T03:04:37.423Z","avatar_url":"https://github.com/ioncodes.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Gecko\n\nA cross-platform GameCube/Wii emulator and debugger written in Rust.\n\n\u003cimg src=\"images/ffcccb.png\" width=\"50%\"\u003e\n\n\u003cimg src=\"images/wario.png\" width=\"30%\"\u003e \u003cimg src=\"images/sunshine.png\" width=\"30%\"\u003e \u003cimg src=\"images/windwaker.png\" width=\"30%\"\u003e\n\u003cimg src=\"images/luigi.png\" width=\"30%\"\u003e \u003cimg src=\"images/re4.png\" width=\"30%\"\u003e \u003cimg src=\"images/debugger.png\" width=\"30%\"\u003e\n\n\u003c/div\u003e\n\n## Status\n\nGecko is still in development. While many games work well, most will likely have varying degrees of visual glitches or will be outright broken. Refer to the screenshot databases to gauge compatiblity:\n- [GameCube](https://emu.layle.dev/gecko-gc/4ad1a63/)\n- [Wii](https://emu.layle.dev/gecko-wii/4ad1a63/)\n\nNote: Only NTSC games are tracked. The screenshot service makes a best effort attempt to enter games by pressing random buttons. Just because a game doesn't go ingame, doesn't mean it actually doesn't.\n\n## Features\n\nGecko is developed with homebrew development and reverse engineering in mind, but also aims to provide a faithful and playable experience!\n\n- PowerPC JIT (Cranelift)\n- DSP JIT (Cranelift)\n- GX vertex decode JIT (Cranelift)\n- Starlet HLE\n- IPL skip patches for NTSC and PAL\n- `wgpu` based renderer backend\n  - Supports all major platforms\n- `wesl` based specialized shader compiler\n- JIT and shader cache\n- Frame pacing\n- Modular audio backend, defaults to `cpal`\n  - Supports mixing audio sinks\n  - Supports dumping to .wav files\n- MCP server\n- Lua scripting system for runtime introspection\n- A beautiful yet advanced egui-based debugging UI\n- Symbol parsing from ELFs and IDA Pro databases\n- IDA Pro loaders for DOL and Apploader\n- RenderDoc captures with all sorts of debug markers\n- ISO and RVZ support; also supports either packed as a ZIP\n- Included multitool, supports:\n  - IPL decode/encode\n  - DVD filesystem extraction\n  - Disassembler for PPC and DSP\n- Various built-in diagnostics for JIT and GX\n- [Support for web browser](https://gecko.layle.dev)\n  - [incl. debugging capabilities](https://gecko.layle.dev/dbg)\n\nThere is currently **no way to save games** for GameCube. Wii save games are supported naturally via NAND.\n\n## Usage\nPrebuilt releases (including debug builds) can be downloaded [here](https://github.com/ioncodes/gecko/releases). GameCube and Wii require system files to use the emulator, please refer to the [\"Required Files\"](https://github.com/ioncodes/gecko#required-files) chapter. Minimal commands to launch a game:\n\n```sh\n# Launch a GameCube game\n./tinyapp --ipl IPL.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --skip-ipl --dvd YourGame.rvz\n\n# Launch a Wii game\n./tinyapp --dsp dsp_rom.bin --coef dsp_coef.bin --dvd YourGame.rvz\n```\n\nA more modern and friendly experience is provided via `gecko` ([short preview on YouTube](https://www.youtube.com/watch?v=wg62ie71JP0)):\n\n![launcher](images/launcher.png)\n\nIt scans the configured GameCube and Wii folders for `.iso`, `.rvz` and `.zip` files. Double-clicking on a row opens a dedicated player window for that game. The decoded GameCube IPL and DSP files are expected to be inside the `system` folder and **must** be named exactly as follows:\n\n```\n\u003cgecko exe dir\u003e/\n  config.toml                # settings\n  cache/library.bin          # cached library\n  system/                    # system file folder (!)\n    IPL.bin                  # GameCube only\n    dsp_rom.bin              # GameCube and Wii\n    dsp_coef.bin             # GameCube and Wii\n  fs/                        # Wii only (NAND from Dolphin or real console)\n```\n\n### Controls\n\nKeybindings are currently hardcoded!\n\n#### GameCube\n\n| Key             | Action                     |\n| --------------- | -------------------------- |\n| Arrow keys      | Main stick                 |\n| `I` `K` `J` `L` | D-pad (up/down/left/right) |\n| `X`             | A                          |\n| `Z`             | B                          |\n| `C`             | X                          |\n| `V`             | Y                          |\n| `Enter`         | Start                      |\n| `A`             | L                          |\n| `S`             | R                          |\n| `D`             | Z                          |\n\n#### Wii\n\nWiimote:\n\n| Input          | Action         |\n| -------------- | -------------- |\n| Mouse movement | IR pointer     |\n| Left mouse     | A              |\n| Right mouse    | B              |\n| Arrow keys     | D-pad          |\n| `1`            | 1              |\n| `2`            | 2              |\n| `Home`         | Home           |\n| `-`            | Minus          |\n| `=`            | Plus           |\n| `Left Shift`   | Shake (motion) |\n\nNunchuk:\n\n| Key             | Action       |\n| --------------- | ------------ |\n| `W` `S` `A` `D` | Analog stick |\n| `Q`             | Z            |\n| `E`             | C            |\n\n#### Global\n\n| Key     | Action                                                             |\n| ------- | ------------------------------------------------------------------ |\n| `Space` | Start emulation from the splash screen (`--wait` flag)             |\n| `F10`   | Trigger a RenderDoc capture (requires `renderdoc-capture` feature) |\n| `F11`   | Screenshot the full window                                         |\n| `F12`   | Screenshot the emulated framebuffer only                           |\n\n## Projects\nThis is a table of the main projects. Refer to `crates/` to find out about all available projects.\n\n| Crate       | Description                                                                                                                     |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `app`       | End-user library browser (binary name `gecko`): iced-based game list, double-click to play, per-game player window                |\n| `tinyapp`   | Lightweight emulator application with an egui/wgpu GUI, optional Lua scripting                                                  |\n| `debugger`  | Interactive GUI debugger built on egui with rendering support, hooks and scripting capabilities                                 |\n| `web`       | WebAssembly build of the emulator for browser deployment via wasm-bindgen, with optional debug UI                               |\n| `multitool` | CLI utility for analyzing, disassembling and extracting GC/Wii binaries/images (DOL, IPL, ISO/RVZ) with support for PPC and DSP |\n\n## Building\n\n```sh\ngit submodule init \u0026\u0026 git submodule update\n\ncargo build -p multitool --release                               # multitool\ncargo build -p tinyapp --release                                 # tinyapp\ncargo build -p gecko-app --release                               # library shell (binary: gecko)\ncargo build -p debugger --release                                # debugger\nwasm-pack build crates/web --target web --out-dir pkg --release  # web version\n```\n\n\u003e Release builds compile out all tracing output (the `gecko` crate pins `tracing` with `release_max_level_off`), so `--release` binaries are silent. Build with `--profile dev` if you want log messages.\n\n### Features\n\nFeatures below are listed based on the frontend crate that supports them. Most of them are simply forwarded into the core `gecko` and `backend-wgpu` crates,\nso the underlying flag of the same name is what actually toggles the behavior. For exact build invocations refer to the GitHub CI actions file.\n\n#### `tinyapp`\n\n| Flag                  | Default | Description                                                                                                     |\n| --------------------- | :-----: | --------------------------------------------------------------------------------------------------------------- |\n| `fps-counter`         |   on    | Emulator-core driven FPS counter (forwards `gecko/fps-counter`).                                                |\n| `scripting`           |   off   | Enables Lua scripting support and the `--script` CLI option (pulls in `gecko/hooks` + the `scripting` crate).   |\n| `scripting-mut-traps` |   off   | Implies `scripting`: lets scripted hooks re-register themselves at runtime (`gecko/hooks-mut-traps`).           |\n| `audio-wav-dump`      |   off   | Forwards `gecko/audio-wav-dump`: write all emulated audio to a `.wav` sink while running.                       |\n| `renderdoc-capture`   |   off   | Forwards `backend-wgpu/renderdoc-capture`: load the RenderDoc in-app API and emit debug markers.                |\n| `jit-stats`           |   off   | Forwards `gecko/jit-stats`: per-block PPC JIT stats, block-frequency CSV dumps and more.                        |\n| `gx-stats`            |   off   | Forwards `gecko/gx-stats`: GX submission and draw-call counters surfaced by the core.                           |\n| `profile`             |   off   | Forwards `gecko/profile`: in-process profiler (Windows-only kernel IP sampler).                                 |\n| `hotpath`             |   off   | Compiles `hotpath::measure` instrumentation into the core and the wgpu backend; reports on shutdown.            |\n| `hotpath-alloc`       |   off   | Implies `hotpath`: swaps the global allocator for a counting allocator that attributes allocs to hot functions. |\n| `hotpath-cpu`         |   off   | Implies `hotpath`: samples CPU time per measured function via `hotpath/hotpath-cpu`.                            |\n| `hotpath-tui`         |   off   | Implies `hotpath`: renders the live `hotpath` TUI instead of dumping a report on exit.                          |\n\n#### `debugger`\n\n`debugger` always builds with `gecko/hooks`, `gecko/audio-wav-dump`, `image/symbols` (ELF/IDA symbol parsing), and the full `scripting` crate enabled.\n\n| Flag                  | Default | Description                                                                                                       |\n| --------------------- | :-----: | ----------------------------------------------------------------------------------------------------------------- |\n| `scripting-mut-traps` |   off   | Same as in `tinyapp`: re-registerable scripted hooks (`gecko/hooks-mut-traps` + `scripting/hooks-mut-traps`).     |\n| `renderdoc-capture`   |   off   | Forwards `backend-wgpu/renderdoc-capture`. With this enabled, F10 triggers a RenderDoc capture of the next frame. |\n\n#### `gecko`\n\n| Flag                  | Default | Description                                                                                                            |\n| --------------------- | :-----: | ---------------------------------------------------------------------------------------------------------------------- |\n| `jit`                 |   on    | Cranelift-backed JIT for Gekko, DSP, and GX vertex decode. Without it the core falls back to interpreters.             |\n| `hooks`               |   off   | Memory/instruction trap hook surface used by `scripting`, the `debugger`, and tooling like `dsptestrunner`.            |\n| `hooks-mut-traps`     |   off   | Implies `hooks`: allows hooks to mutate trap state.                                                                    |\n| `audio-wav-dump`      |   off   | Compiles the `hound`-backed `.wav` audio sink.                                                                         |\n| `fps-counter`         |   off   | Compiles the core FPS counter for more accurate measurements.                                                          |\n| `jit-stats`           |   off   | Implies `jit`: per-block JIT hit counts, idle-skip stats, CSV dumps (pulls in `backtrace`).                            |\n| `gx-stats`            |   off   | GX command-processor / BP / XF submission counters.                                                                    |\n| `vtx-jit-validate`    |   off   | Implies `jit` + `gx-stats`. Runs both the GX vertex JIT and interpreter for every draw and reports drift between them. |\n| `profile`             |   off   | Per-block PPC/DSP heatmap profiler; on Windows it also enables a kernel-IP sampler via `windows-sys`.                  |\n| `rendersink-blackbox` |   off   | Wraps `EmptyRenderSink::exec` in `std::hint::black_box`. Useful for benchmarking.                                      |\n| `hotpath`             |   off   | Compiles `hotpath::measure` instrumentation across the core hot loops.                                                 |\n\n#### `backend-wgpu`\n\n| Flag                | Default | Description                                                                        |\n| ------------------- | :-----: | ---------------------------------------------------------------------------------- |\n| `renderdoc-capture` |   off   | Pulls in the `renderdoc` crate and enables the in-app capture API + debug markers. |\n| `hotpath`           |   off   | Instruments the wgpu sink (incl. crossbeam channels) for `hotpath` reporting.      |\n\n#### `web`\n\n| Flag    | Default | Description                                                                                                                              |\n| ------- | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| `debug` |   off   | Bundles the in-browser debugger UI (pulls in `dbglib` and `egui-phosphor`). Enabled for the [`/dbg`](https://gecko.layle.dev/dbg) build. |\n\n#### `tinybench`\n\n| Flag        | Default | Description                                                                                       |\n| ----------- | :-----: | ------------------------------------------------------------------------------------------------- |\n| _(default)_ |    —    | Forwards `gecko/rendersink-blackbox` so the renderless benchmark loop doesn't get optimized away. |\n| `jit-stats` |   off   | Forwards `gecko/jit-stats` for benchmarking.                                                      |\n\n## Required files\n\nGecko does not ship any system files.\n\n### GameCube\n- IPL (NTSC and PAL tested)\n- DSP IROM\n- DSP coefficient ROM\n\nIf you only have an encoded IPL, decode it first with multitool:\n\n```sh\nmultitool ipl --action decode private/IPL.bin private/IPL.decoded.bin\n```\n\n### Wii\nNAND filesystem dump from Dolphin or a real Wii. Place it under `./fs/` or point `GECKO_FS_ROOT` at the directory:\n\n```sh\nGECKO_FS_ROOT=/path/to/dolphin-nand tinyapp --dvd wii_game.rvz\n```\n\nNAND must likely be NTSC.\nReference SHA-256 hashes (these are the files the project is developed against):\n\n| File                         | SHA-256                                                            |\n| ---------------------------- | ------------------------------------------------------------------ |\n| `IPL.bin` (NTSC, encoded)    | `7228bd8f0171008e71c48788eef5e0fd5abce8ef85f1d00327c6f3368113d2a5` |\n| `IPL.decoded.bin` (NTSC)     | `31e9aa82d972a423d9b7ea7bdbdcff0aff86c3ed953600ca841fe24f3f577051` |\n| `PAL_IPL.bin` (PAL, encoded) | `a5fd3ab0ed3d63ad365990cbf522f9f175e01d3b37e5f30a8e5a103cbbc749fd` |\n| `PAL_IPL.decoded.bin` (PAL)  | `011b66ce68d8dcb4f37460fcb322215bcda7df79072aeca22fdc690499deabac` |\n| `dsp_rom.bin`                | `49d987ee1eab29a157425b82d54516957a81e1bac247c8834e494642605c3e8c` |\n| `dsp_coef.bin`               | `d7741279c2e8ec5c5fb318f8fbdd6de6bf583520d288e836a5383233a4238179` |\n\n## Usage\nExample invocations:\n\n```sh\nmultitool ipl --action decode ipl.encoded.bin ipl.decoded.bin\nmultitool dvd --extract game.rvz\ntinyapp --dol homebrew.dol  # may also require a DSP depending on the DOL\ntinyapp --dvd game.iso --ipl ipl.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --skip-ipl\ndebugger --dvd game.rvz --ipl ipl.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --script example.lua\n```\n\nThe CLI options are largely the same across the sub projects (such as the debugger). For more options, see `--help`.\n\n## Why?\nWhy do we get a new Wii emulator? Well, it all started a few years ago. I wanted to do something nostalgic and as a kid I spent countless hour in this one Wii game called *Final Fantasy Crystal Chronicals: The Crystal Bearers*. It wasn't a well received game but I loved it so much, I chose my online persona \"Layle\" after the main protagonist. I figured it would be cool to spend some years learning about emulation development with the goal to eventually run the game in my own emulator!\n\n## Sister Projects\nGecko is being developed alongside other amazing emulators that shaped how Gecko came to be. Without them, Gecko wouldn't exist!\n\n- [lazuli](https://github.com/vxpm/lazuli) by vxpm\n- [solstice](https://codeberg.org/hazelwiss/solstice) by hazelwiss\n- [beanwii](https://github.com/zaydlang/beanwii) by zayd\n\nBesides these \"sister projects\", [Dolphin](https://github.com/dolphin-emu/dolphin) has also been a major contributor in many ways.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncodes%2Fgecko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioncodes%2Fgecko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncodes%2Fgecko/lists"}