Skip to content

armgit / gecko

Public Imported from GitHub
0

A GameCube/Wii emulator and debugger written in Rust.

clean up for master

Layledf074e9c5e06
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 1f7ce97..291a6fa 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -17,9 +17,15 @@ jobs:
- os: ubuntu-latest
target: x86_64-unknown-linux-gnu
suffix: linux-x86_64
+ dbg_suffix: linux-dbg-x86_64
- os: windows-latest
target: x86_64-pc-windows-msvc
suffix: windows-x86_64
+ dbg_suffix: windows-dbg-x86_64
+ - os: macos-latest
+ target: aarch64-apple-darwin
+ suffix: macos-arm64
+ dbg_suffix: macos-dbg-arm64
runs-on: ${{ matrix.os }}
@@ -46,7 +52,7 @@ jobs:
- name: Patch chipi dispatch strategy
shell: bash
- run: sed -i 's/strategy fn_ptr_lut/strategy jump_table/g' crates/gecko/*.bindings.chipi
+ run: perl -pi -e 's/strategy fn_ptr_lut/strategy jump_table/g' crates/gecko/*.bindings.chipi
- name: Install Linux dependencies
if: runner.os == 'Linux'
@@ -54,33 +60,56 @@ jobs:
sudo apt-get update
sudo apt-get install -y libwayland-dev libxkbcommon-dev libx11-dev libxi-dev libxrandr-dev libxcursor-dev
- - name: Build tinyapp
+ - name: Build tinyapp (release)
run: cargo build --release --package tinyapp --target ${{ matrix.target }}
- - name: Build debugger
+ - name: Build debugger (release)
run: cargo build --release --package debugger --target ${{ matrix.target }}
- - name: Build multitool
+ - name: Build multitool (release)
run: cargo build --release --package multitool --target ${{ matrix.target }}
- - name: Package artifacts (Linux)
- if: runner.os == 'Linux'
+ - name: Build binaries (dev profile, with tracing output)
+ run: cargo build --profile dev --target ${{ matrix.target }} -p tinyapp -p debugger -p multitool
+
+ - name: Package artifacts (Unix)
+ if: runner.os != 'Windows'
run: |
- mkdir -p staging artifacts
- cp target/${{ matrix.target }}/release/tinyapp staging/
- cp target/${{ matrix.target }}/release/debugger staging/
- cp target/${{ matrix.target }}/release/multitool staging/
- cd staging && zip ../artifacts/gecko-${{ matrix.suffix }}.zip tinyapp debugger multitool
+ mkdir -p artifacts
+
+ mkdir -p staging-rel
+ cp target/${{ matrix.target }}/release/tinyapp staging-rel/
+ cp target/${{ matrix.target }}/release/debugger staging-rel/
+ cp target/${{ matrix.target }}/release/multitool staging-rel/
+ cp LICENSE README.md staging-rel/
+ (cd staging-rel && zip ../artifacts/gecko-${{ matrix.suffix }}.zip tinyapp debugger multitool LICENSE README.md)
+
+ mkdir -p staging-dbg
+ cp target/${{ matrix.target }}/debug/tinyapp staging-dbg/
+ cp target/${{ matrix.target }}/debug/debugger staging-dbg/
+ cp target/${{ matrix.target }}/debug/multitool staging-dbg/
+ cp LICENSE README.md staging-dbg/
+ (cd staging-dbg && zip ../artifacts/gecko-${{ matrix.dbg_suffix }}.zip tinyapp debugger multitool LICENSE README.md)
- name: Package artifacts (Windows)
if: runner.os == 'Windows'
shell: bash
run: |
- mkdir -p staging artifacts
- cp target/${{ matrix.target }}/release/tinyapp.exe staging/
- cp target/${{ matrix.target }}/release/debugger.exe staging/
- cp target/${{ matrix.target }}/release/multitool.exe staging/
- cd staging && 7z a ../artifacts/gecko-${{ matrix.suffix }}.zip tinyapp.exe debugger.exe multitool.exe
+ mkdir -p artifacts
+
+ mkdir -p staging-rel
+ cp target/${{ matrix.target }}/release/tinyapp.exe staging-rel/
+ cp target/${{ matrix.target }}/release/debugger.exe staging-rel/
+ cp target/${{ matrix.target }}/release/multitool.exe staging-rel/
+ cp LICENSE README.md staging-rel/
+ (cd staging-rel && 7z a ../artifacts/gecko-${{ matrix.suffix }}.zip tinyapp.exe debugger.exe multitool.exe LICENSE README.md)
+
+ mkdir -p staging-dbg
+ cp target/${{ matrix.target }}/debug/tinyapp.exe staging-dbg/
+ cp target/${{ matrix.target }}/debug/debugger.exe staging-dbg/
+ cp target/${{ matrix.target }}/debug/multitool.exe staging-dbg/
+ cp LICENSE README.md staging-dbg/
+ (cd staging-dbg && 7z a ../artifacts/gecko-${{ matrix.dbg_suffix }}.zip tinyapp.exe debugger.exe multitool.exe LICENSE README.md)
- uses: actions/upload-artifact@v4
with:
diff --git a/README.md b/README.md
index 31fe20b..f65435b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
# Gecko
-A WIP GameCube/Wii emulator and debugger written in Rust.
+A cross-platform GameCube/Wii emulator and debugger written in Rust.
<img src="images/ffcccb.png" width="50%">
@@ -17,6 +17,7 @@ Gecko is still in development. Support may vary, while many games work perfectly
- PowerPC interpreter
- DSP LLE interpreter
+- Starlet HLE
- IPL skip patches for NTSC and PAL
- `wgpu` based renderer backend
- `wesl` based shader compiler
@@ -25,13 +26,21 @@ Gecko is still in development. Support may vary, while many games work perfectly
- 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
- [Support for web browser](https://gecko.layle.dev)
- [incl. debugging capabilities](https://gecko.layle.dev/dbg)
-- Terrible idle skipping :^)
+
+WIP features:
+- IPL HLE backed by [solstice](https://codeberg.org/hazelwiss/solstice)
+- Idle skipping
Gecko currently does **not** implement sound and does **not** support Wii controls.
## Projects
+This is a table of the main projects. Refer to `crates/` to find out about all available projects.
| Crate | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
@@ -43,21 +52,69 @@ Gecko currently does **not** implement sound and does **not** support Wii contro
## Building
```sh
-cargo build -p multitool --release # multi-tool
+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
```
-Certain features require certain feature flags such as `scripting` and `scripting-mut-traps`, however, the debugger has them all enabled (except `renderdoc-capture`).
-For more information refer to the GitHub CI actions file. PGO optimized compilation is supported, refer to the `Justfile`.
+> 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
+
+| Flag | Crates | Description |
+| ------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
+| `hooks` | `tinyapp` (off), `debugger` (on) | Lua scripting and hooks |
+| `hooks-mut-traps` | `tinyapp` (off), `debugger` (off) | Let hooks re-register themselves at runtime |
+| `idle-skip` | `tinyapp` (off), `debugger` (off) | Skip idle PPC polling loops |
+| `efb-writeback` | `tinyapp` (off), `debugger` (off) | EFB-to-texture writeback (needed by some games) |
+| `renderdoc-capture` | `debugger` (off) | RenderDoc captures with debug markers, triggered by F10 |
+| `debug` | `web` (off, on for [`/dbg`](https://gecko.layle.dev/dbg)) | Bundle the in-browser debugger UI |
+
+For exact build invocations refer to the GitHub CI actions file. PGO optimized compilation is supported, refer to the `Justfile`.
+
+## Required files
+
+Gecko does not ship any system files.
+
+### GameCube
+- IPL (NTSC and PAL tested)
+- DSP IROM (may not be required if running homebrew DOLs)
+
+If you only have an encoded IPL, decode it first with multitool:
+
+```sh
+multitool ipl --action decode private/IPL.bin private/IPL.decoded.bin
+```
+
+### Wii
+NAND filesystem dump from Dolphin. Place it under `./fs/` or point `GECKO_FS_ROOT` at the directory:
+
+```sh
+GECKO_FS_ROOT=/path/to/dolphin-nand tinyapp --dvd wii_game.rvz
+```
+
+Reference SHA-256 hashes (these are the files the project is developed against):
+
+| File | SHA-256 |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `IPL.bin` (NTSC, encoded) | `7228bd8f0171008e71c48788eef5e0fd5abce8ef85f1d00327c6f3368113d2a5` |
+| `IPL.decoded.bin` (NTSC) | `31e9aa82d972a423d9b7ea7bdbdcff0aff86c3ed953600ca841fe24f3f577051` |
+| `PAL_IPL.bin` (PAL, encoded) | `a5fd3ab0ed3d63ad365990cbf522f9f175e01d3b37e5f30a8e5a103cbbc749fd` |
+| `PAL_IPL.decoded.bin` (PAL) | `011b66ce68d8dcb4f37460fcb322215bcda7df79072aeca22fdc690499deabac` |
+| `dsp_rom.bin` | `49d987ee1eab29a157425b82d54516957a81e1bac247c8834e494642605c3e8c` |
## Usage
+Example invocations:
```sh
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
+tinyapp --dvd game.iso --ipl ipl.decoded.bin --dsp dsp_rom.bin --skip-ipl
+debugger --dvd game.rvz --ipl ipl.decoded.bin --dsp dsp_rom.bin --script example.lua
```
The CLI options are largely the same across the sub projects (such as the debugger). For more options, see `--help`.
diff --git a/crates/debugger/src/main.rs b/crates/debugger/src/main.rs
index 760dec8..7090c0c 100644
--- a/crates/debugger/src/main.rs
+++ b/crates/debugger/src/main.rs
@@ -129,7 +129,7 @@ impl ApplicationHandler for App {
event_loop
.create_window(
Window::default_attributes()
- .with_title("Gecko")
+ .with_title("Gecko Debugger")
.with_inner_size(winit::dpi::PhysicalSize::new(initial_size.0, initial_size.1)),
)
.unwrap(),
@@ -223,7 +223,10 @@ impl ApplicationHandler for App {
}
#[derive(Parser)]
-#[command(about = "GameCube/Wii debugger")]
+#[command(
+ about = "GameCube/Wii debugger",
+ after_help = "Repository: https://github.com/ioncodes/gecko"
+)]
struct Args {
/// Path to the DOL file (GameCube homebrew by default)
#[arg(long)]
diff --git a/crates/multitool/src/cli.rs b/crates/multitool/src/cli.rs
index d61ee02..b25a44b 100644
--- a/crates/multitool/src/cli.rs
+++ b/crates/multitool/src/cli.rs
@@ -59,7 +59,11 @@ pub enum Command {
}
#[derive(Parser)]
-#[command(about = "GameCube/Wii multi-tool", long_about = None)]
+#[command(
+ about = "GameCube/Wii multitool",
+ long_about = None,
+ after_help = "Repository: https://github.com/ioncodes/gecko",
+)]
pub struct Args {
#[command(subcommand)]
pub command: Command,
diff --git a/crates/tinyapp/Cargo.toml b/crates/tinyapp/Cargo.toml
index 432cb23..1d02ad3 100644
--- a/crates/tinyapp/Cargo.toml
+++ b/crates/tinyapp/Cargo.toml
@@ -5,8 +5,8 @@ edition = "2024"
[features]
idle-skip = ["gecko/idle-skip"]
-scripting = ["gecko/hooks", "dep:scripting"]
-scripting-mut-traps = ["scripting", "gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]
+hooks = ["gecko/hooks", "dep:scripting"]
+hooks-mut-traps = ["hooks", "gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]
efb-writeback = ["backend-wgpu/efb-writeback", "gecko/efb-writeback"]
[dependencies]
diff --git a/crates/tinyapp/src/app.rs b/crates/tinyapp/src/app.rs
index 4f9a4dd..477c688 100644
--- a/crates/tinyapp/src/app.rs
+++ b/crates/tinyapp/src/app.rs
@@ -239,7 +239,7 @@ impl ApplicationHandler for App {
event_loop
.create_window(
Window::default_attributes()
- .with_title("Gecko")
+ .with_title("Tiny Gecko")
.with_inner_size(winit::dpi::PhysicalSize::new(initial_size.0, initial_size.1)),
)
.unwrap(),
diff --git a/crates/tinyapp/src/main.rs b/crates/tinyapp/src/main.rs
index ebdcde5..b47e8dc 100644
--- a/crates/tinyapp/src/main.rs
+++ b/crates/tinyapp/src/main.rs
@@ -14,7 +14,10 @@ use winit::event_loop::EventLoop;
use winit::keyboard::KeyCode;
#[derive(Parser)]
-#[command(about = "GameCube/Wii emulator")]
+#[command(
+ about = "GameCube/Wii emulator",
+ after_help = "Repository: https://github.com/ioncodes/gecko"
+)]
struct Args {
/// Path to the DOL file (GameCube homebrew by default)
#[arg(long)]
@@ -50,7 +53,7 @@ struct Args {
dsp: Option<String>,
/// Path to a Lua script for scripting hooks
- #[cfg(feature = "scripting")]
+ #[cfg(feature = "hooks")]
#[arg(long)]
script: Option<String>,
@@ -123,7 +126,7 @@ fn main() {
if dvd.header().is_wii() {
println!("Detected Wii disc, booting via apploader HLE");
let builder = Wii::apploader_hle(dvd);
- #[cfg(feature = "scripting")]
+ #[cfg(feature = "hooks")]
let builder = if let Some(ref path) = args.script {
let host = scripting::LuaHost::from_file(path).expect("failed to load script");
builder.lua_host(Box::new(host))
@@ -150,7 +153,7 @@ fn configure<const SYSTEM: SystemId>(emulator: &mut System<SYSTEM>, args: &Args)
emulator.dsp.load_irom(&dsp_data);
}
- #[cfg(feature = "scripting")]
+ #[cfg(feature = "hooks")]
if let Some(ref path) = args.script {
// Already attached for Wii apploader HLE; only attach here for other
// boot paths.
diff --git a/crates/tinytracer/Cargo.toml b/crates/tinytracer/Cargo.toml
index e2500c9..c27a0ce 100644
--- a/crates/tinytracer/Cargo.toml
+++ b/crates/tinytracer/Cargo.toml
@@ -5,8 +5,8 @@ edition = "2024"
[features]
idle-skip = ["gecko/idle-skip"]
-scripting = ["gecko/hooks", "dep:scripting"]
-scripting-mut-traps = ["scripting", "gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]
+hooks = ["gecko/hooks", "dep:scripting"]
+hooks-mut-traps = ["hooks", "gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]
[dependencies]
gecko = { path = "../gecko" }
diff --git a/crates/tinytracer/src/main.rs b/crates/tinytracer/src/main.rs
index 45e073b..07294c5 100644
--- a/crates/tinytracer/src/main.rs
+++ b/crates/tinytracer/src/main.rs
@@ -73,7 +73,7 @@ struct Args {
dsp: Option<String>,
/// Path to a Lua script for scripting hooks
- #[cfg(feature = "scripting")]
+ #[cfg(feature = "hooks")]
#[arg(long)]
script: Option<String>,
}
@@ -116,7 +116,7 @@ fn main() {
emulator.dsp.load_irom(&dsp_data);
}
- #[cfg(feature = "scripting")]
+ #[cfg(feature = "hooks")]
if let Some(path) = &args.script {
let host = scripting::LuaHost::from_file(path).expect("failed to load script");
emulator.set_hook_host(Box::new(host));