Gecko

A cross-platform GameCube/Wii emulator and debugger written in Rust.

Gecko 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:

• GameCube
• Wii

Note: 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.

Gecko is developed with homebrew development and reverse engineering in mind, but also aims to provide a faithful and playable experience!

• PowerPC JIT (Cranelift)
• DSP JIT (Cranelift)
• GX vertex decode JIT (Cranelift)
• Starlet HLE
• IPL skip patches for NTSC and PAL
• wgpu based renderer backend
  • Supports all major platforms
• wesl based specialized shader compiler
• JIT and shader cache
• Frame pacing
• Modular audio backend, defaults to cpal
  • Supports mixing audio sinks
  • Supports dumping to .wav files
• MCP server
• Lua scripting system for runtime introspection
• A beautiful yet advanced egui-based debugging UI
• Symbol parsing from ELFs and IDA Pro databases
• RenderDoc captures with all sorts of debug markers
• ISO and RVZ support; also supports either packed as a ZIP
• Included multitool, supports:
  • IPL decode/encode
  • DVD filesystem extraction
  • Disassembler for PPC and DSP
• Various built-in diagnostics for JIT and GX
• Support for web browser
  • incl. debugging capabilities

There is currently no way to save games for GameCube. Wii save games are supported naturally via NAND.

Prebuilt releases (including debug builds) can be downloaded here. GameCube and Wii require system files to use the emulator, please refer to the "Required Files" chapter. Minimal commands to launch a game:

# Launch a GameCube game
./tinyapp --ipl IPL.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --skip-ipl --dvd YourGame.rvz

# Launch a Wii game
./tinyapp --dsp dsp_rom.bin --coef dsp_coef.bin --dvd YourGame.rvz

Keybindings are currently hardcoded into tinyapp and debugger!

Wiimote:

Nunchuk:

This is a table of the main projects. Refer to crates/ to find out about all available projects.

git submodule init && git submodule update

cargo build -p multitool --release                               # multitool
cargo build -p tinyapp --release                                 # main application
cargo build -p debugger --release                                # debugger
wasm-pack build crates/web --target web --out-dir pkg --release  # web version

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.

Features 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, so the underlying flag of the same name is what actually toggles the behavior. For exact build invocations refer to the GitHub CI actions file.

debugger always builds with gecko/hooks, gecko/audio-wav-dump, image/symbols (ELF/IDA symbol parsing), and the full scripting crate enabled.

Gecko does not ship any system files.

• IPL (NTSC and PAL tested)
• DSP IROM
• DSP coefficient ROM

If you only have an encoded IPL, decode it first with multitool:

multitool ipl --action decode private/IPL.bin private/IPL.decoded.bin

NAND filesystem dump from Dolphin or a real Wii. Place it under ./fs/ or point GECKO_FS_ROOT at the directory:

GECKO_FS_ROOT=/path/to/dolphin-nand tinyapp --dvd wii_game.rvz

NAND must likely be NTSC. Reference SHA-256 hashes (these are the files the project is developed against):

Example invocations:

multitool ipl --action decode ipl.encoded.bin ipl.decoded.bin
multitool dvd --extract game.rvz
tinyapp --dol homebrew.dol  # may also require a DSP depending on the DOL
tinyapp --dvd game.iso --ipl ipl.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --skip-ipl
debugger --dvd game.rvz --ipl ipl.decoded.bin --dsp dsp_rom.bin --coef dsp_coef.bin --script example.lua

The CLI options are largely the same across the sub projects (such as the debugger). For more options, see --help.

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

Gecko is being developed alongside other amazing emulators that shaped how Gecko came to be. Without them, Gecko wouldn't exist!

• lazuli by vxpm
• solstice by hazelwiss
• beanwii by zayd

Besides these "sister projects", Dolphin has also been a major contributor in many ways.