Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/retired64/sm64coopdx_launcher/llms.txt

Use this file to discover all available pages before exploring further.

This guide takes you from a fresh clone to an in-game session of SM64 Coop Deluxe. The only prerequisites are a working installation of coopdx-rs and a copy of the SM64 US ROM and the sm64coopdx game binary.
1
Build the launcher
2
git clone https://github.com/retired64/sm64coopdx_launcher
cd sm64coopdx_launcher
cargo build --release
3
The compiled binary is placed at target/release/sm64coopdx-launcher. You can run it from there or copy it anywhere on your PATH.
4
Place your SM64 US ROM
5
The launcher validates your ROM by MD5 checksum (20b854b239203baf6c961b850a4a51a2) before every launch. Place the ROM file in one of these locations — the launcher scans them in order and uses the first valid file it finds:
6
  • The same directory as the sm64coopdx game binary.
  • ~/.local/share/sm64coopdx/ (the shared save/data directory).
  • The path specified in ~/.config/sm64coopdx/launcher.toml under [game].rom_path.
  • Any ~/sm64coopdx_Linux-*/ release directory in your home folder.
    • 7
    The launcher copies a validated ROM to ~/.local/share/sm64coopdx/baserom.us.z64 automatically on first launch, so subsequent runs are instant.
    8
    Only the Super Mario 64 (USA) ROM with MD5 20b854b239203baf6c961b850a4a51a2 is accepted. Other regions or patched versions will fail validation and the launcher will display a red error message instead of starting the game.
    9
    Install launcher assets
    10
    The launcher requires its sprites, sounds, music, and font to be present in ~/.local/share/sm64coopdx/assets/.
    11
    mkdir -p ~/.local/share/sm64coopdx/assets
cp -r assets/* ~/.local/share/sm64coopdx/assets/
    12
    Run the launcher
    13
    ./target/release/sm64coopdx-launcher
    14
    To point the launcher at a specific game binary without editing any config file, pass --game-path:
    15
    ./target/release/sm64coopdx-launcher --game-path /path/to/sm64coopdx
    16
    Or set the SM64COOPDX_PATH environment variable for a session-scoped override (see Game path resolution below):
    17
    export SM64COOPDX_PATH="/path/to/sm64coopdx"
./target/release/sm64coopdx-launcher
    18
    Press Enter to launch the game
    19
    On the main screen, press Enter (or the gamepad A button) to start the launch sequence:
    20
  • The screen fades to black over 1.5 seconds.
  • The launcher validates that lang/English.ini exists next to the game binary and that the save path is writable.
  • A valid ROM is located, validated by MD5, and copied to ~/.local/share/sm64coopdx/baserom.us.z64 if not already present.
  • The game process is spawned with a clean environment (see below), all active mod/network/profile flags, and the save path set to ~/.local/share/sm64coopdx/.
  • The launcher returns to the main screen and monitors the game process; when the game exits, background music resumes at normal volume.
    • 21
    If anything fails (binary not found, ROM missing, language file absent, save path not writable), the launcher displays a descriptive red error message on-screen. Check ~/.local/share/sm64coopdx/game_stderr.log for the game’s own output.

    ​
    Game path resolution

    The launcher uses a strict five-tier priority system to locate the sm64coopdx binary. Each tier is tried in order; if the path doesn’t point to an existing file, the next tier is tried automatically.
    PrioritySourceExample
    1 (highest)--game-path CLI flag./sm64coopdx-launcher --game-path /opt/sm64/sm64coopdx
    2SM64COOPDX_PATH env varexport SM64COOPDX_PATH=/opt/sm64/sm64coopdx
    3Active profile → profile.json → game_path field~/.local/share/sm64coopdx/profiles/<name>/profile.json
    4launcher.toml → [game].path~/.config/sm64coopdx/launcher.toml
    5 (default)Automatic directory search<launcher_dir>/../games/mario64/sm64coopdx, <launcher_dir>/sm64coopdx, <launcher_dir>/../sm64coopdx, ~/sm64coopdx_Linux-*/sm64coopdx
    All resolved paths are canonicalized to absolute form (symlinks resolved) so that the game’s working directory is set correctly at spawn time.

    ​
    Quick override: environment variable

    The SM64COOPDX_PATH variable is the fastest way to point the launcher at a specific binary without touching any file: 
    export SM64COOPDX_PATH="$HOME/sm64coopdx_Linux-1.5.1-autoUpdater/sm64coopdx"
./target/release/sm64coopdx-launcher

    ​
    Persistent configuration: launcher.toml

    For a permanent path configuration, create ~/.config/sm64coopdx/launcher.toml: 
    [game]
# Absolute path to the sm64coopdx game binary
path = "/home/user/sm64coopdx_Linux-1.5.1-autoUpdater/sm64coopdx"

# Optional: absolute path to the SM64 US ROM
# If omitted, the launcher searches common locations automatically
rom_path = "/home/user/sm64coopdx_Linux-1.5.1-autoUpdater/Super Mario 64 (USA).z64"

    ​
    Per-profile binary path

    Each profile’s ~/.local/share/sm64coopdx/profiles/<name>/profile.json can also specify a game_path. This allows different profiles to target different builds of the game (for example, a stable release and a development build): 
    {
  "playername": "MyName",
  "game_path": "/home/user/sm64coopdx_dev/sm64coopdx",
  "skip_intro": true,
  "fullscreen": false,
  "no_discord": false,
  "skip_update_check": true,
  "headless": false
}

    ​
    Keyboard controls

    KeyAction
    EnterLaunch the game / confirm selection
    TabToggle the side menu open/closed
    EscGo back / close sub-screen / exit (from main screen)
    ↑ / ↓ (or W / S)Navigate menu items and lists
    ← / →Change network mode; navigate tag chips
    FToggle fullscreen / windowed mode
    SpaceActivate selected item (e.g. set active profile)
    NNew profile (in Profile Manager)
    RRename selected profile (in Profile Manager)
    Delete (hold 1.5s)Delete selected profile (in Profile Manager)
    /Activate search (in Download Browser)
    CClear all filters (in Download Browser)
    Page Up / Page DownPrevious / next page (in Download Browser)

    ​
    Gamepad controls

    ButtonAction
    A (button 0)Confirm / launch
    B (button 1)Cancel / back
    X (button 2)Activate (set active profile)
    L1 (button 4)Previous page
    R1 (button 5)Next page
    Start (button 7)Toggle menu (Tab equivalent)
    D-PadNavigate lists and menus
    B (hold 5s)Exit the launcher
    Holding the gamepad B button for five seconds — or the keyboard K key — triggers a graceful shutdown with a progress indicator. Release before five seconds to cancel.

    ​
    Troubleshooting

    SymptomLikely causeFix
    ”Game binary not found” on main screenNo binary at any of the 5 resolution tiersSet SM64COOPDX_PATH or add [game].path to launcher.toml
    Red error: “Language file not found”lang/English.ini missing next to the binaryEnsure the full SM64 Coop DX release archive is extracted with its lang/ directory intact
    Red error: “No valid SM64 US ROM found”ROM absent or wrong MD5Place Super Mario 64 (USA).z64 (MD5: 20b854b239203baf6c961b850a4a51a2) next to the game binary
    Game freezes at “Loading ROM Assets”ROM not copied to save pathCheck that ~/.local/share/sm64coopdx/ is writable by your user
    Launcher fails at splash screenAssets missingRe-run cp -r assets/* ~/.local/share/sm64coopdx/assets/
    For detailed game-side errors, inspect the log written by the launcher: 
    cat ~/.local/share/sm64coopdx/game_stderr.log

    Build docs developers (and LLMs) love

    Get started for freeTalk to us