Launcher

First run

Open the launcher and add your ROM.

  1. Install a launcher release from the Launcher releases page.
  2. Open Z3R Launcher.
  3. Press Upload SFC and select your compatible, legally dumped USA .sfc ROM.
  4. After the ROM is stored, Upload SFC changes to Open SFC Folder and Repos becomes available.

You can also place the ROM in a project root as zelda3.sfc. The launcher does not download or include a ROM.

Detected Builds

The home screen lists Z3R folders found by the launcher.

Environment

Checks Git, Python, venv, SDL2, build tools, ROM, assets, and the executable.

Activity

Shows command output and setup messages from launcher actions.

Repos

Add or clone a Z3R repo.

  1. Press Repos.
  2. Use Scan Paths to add a folder that already contains one or more Z3R folders.
  3. Use Clone, choose a Clone destination, then press Clone Z3R for the default repo.
  4. To clone a fork, paste its GitHub URL and press Clone Custom.
  5. Close the dialog and press the refresh button if the new project does not appear right away.

If the home screen says No Z3R folders found, add a scan path that contains a Z3R folder or clone one from the Repos dialog.

Project setup

Use Environment for the selected project.

  1. On the home screen, choose a project under Detected Builds.
  2. Press Environment.
  3. Press Run Checks.
  4. Use Manual install beside any missing dependency that the launcher cannot install for you.
  5. Follow Setup Path: Create venv, Install dependencies, then the correct build button for your platform.

Build assets extracts from zelda3.sfc, creates zelda3_assets.dat, and builds the executable. Required checks must pass before the build buttons can finish successfully. If a project card shows Patch Makefile or Patch SLN, run that patch before building that project.

Build buttons

Pick the button that matches your platform.

Platform Before building Launcher button
Linux Install Make, a C/C++ toolchain, Python venv support, and SDL2 development files. Build assets
macOS Install Xcode Command Line Tools and SDL2 development files. Build assets
Windows with Visual Studio Install Visual Studio Build Tools with Desktop development with C++. Build assets Visual Studio
Windows with TCC Use the TCC route when you want the lightweight compiler path. Build assets TCC

Windows launcher releases bundle portable Git, Python, TCC, and SDL2. MSBuild is still required for the Visual Studio route.

Play and settings

Return home when setup is done.

Play

Play is enabled when the selected project has assets and a built executable.

Controls

Use Controls to edit keyboard and gamepad bindings written to zelda3.ini.

Features

Use Features for INI toggles, MSU, Link sprites, shaders, and related asset pickers.

Sprite and shader setup is handled from Features. Use Clone sprites or Clone shaders, choose an item, then press Use sprite or Use shader. See Link sprites for manual sprite setup.

Randomizer

Use the Randomizer screen after project setup.

  1. Press Randomizer on a detected project.
  2. Press Extract assets to create editable YAML/config files and the vanilla masterlist.
  3. Set Seed, exclusions, Include small keys, Include big chests, and No spoiler log as needed.
  4. Use Preview randomization to inspect a result without writing YAML/config changes.
  5. Use Randomize YAML/configs, then Build randomized assets.

Use Restore vanilla YAML before rerolling if you want to return to the saved vanilla masterlist.

Build launcher

Only build the launcher from source if you are developing it.

Shared requirements are Git, Rust with Cargo, Rust 1.77.2 or newer, and Tauri CLI 2.

cargo install tauri-cli --version "^2"
cd launcher
cargo tauri build

Build output is written under launcher/src-tauri/target/release/bundle/.

Windows release toolkit

The Windows setup exe bundles portable Git, Python, TCC, and SDL2 from launcher/src-tauri/bundled-tools/windows/. MSBuild is still required for Build assets Visual Studio. 

powershell.exe -ExecutionPolicy Bypass -File ./scripts/prepare-windows-toolkit.ps1
powershell.exe -ExecutionPolicy Bypass -File ./scripts/verify-windows-toolkit.ps1
cargo tauri build