Skip to main content
This guide will help you go from a fresh Hydra installation to running your first Nintendo Switch game.

​
Prerequisites

Before starting, make sure you have:
Hydra installed on your Mac (Installation Guide)
A Nintendo Switch game file (NRO, NCA, or NX format)
System firmware files (required for official games) (Firmware Guide)
Game patches (recommended for official games) from hydra-patches

​
Loading Your First Game

1

Launch Hydra

Open the Hydra application from your Applications folder or the build output directory.On first launch, Hydra will create its configuration directory at:
~/Library/Application Support/Hydra/
If you built from source with -DFRONTEND=SwiftUI, you’ll see a native macOS interface. Otherwise, you’ll see the SDL3 interface.
2

Configure Firmware (For Official Games)

If you’re running an official game (NCA format), you need to configure firmware files first:
  1. Open the config file: 
    open ~/Library/Application\ Support/Hydra/config.toml
  2. Set the firmware path: 
    [System]
firmware_path = "/path/to/decrypted/firmware"
  3. Apply game patches from hydra-patches to prevent crashes
Firmware files must be decrypted. Use switch-extract-macos to extract and decrypt firmware from your Switch.
3

Load and Run Your Game

There are two ways to load a game:Option 1: SDL3 Frontend
  • Use the file menu or drag-and-drop your game file onto the window
  • The game will start automatically
Option 2: SwiftUI Frontend
  • Click “Load Game” in the interface
  • Navigate to your game file
  • Select the file and click “Open”
For NRO files (homebrew), no firmware is required. These will run immediately.

​
Supported File Formats

Hydra supports the following Nintendo Switch game formats:
FormatTypeFirmware RequiredNotes
NROHomebrew executableNoRuns immediately, no setup needed
NCANintendo Content ArchiveYesOfficial game format, requires firmware and patches
NXPackaged gameYesConvert NSP to NX with herakles
NSONintendo Shared ObjectNoShared libraries and modules
NSP files are not directly supported. Convert them first:

​
Configuring Game Paths

You can configure default game paths in the config file for easier access:
config.toml
[System]
# Path to your game library directory
game_path = "/Users/yourname/Games/Switch"

# Path to firmware files (for official games)
firmware_path = "/Users/yourname/Switch/Firmware"

# Path to save data
sd_card_path = "~/Library/Application Support/Hydra/sdcard"
These paths are defined in src/common/config.cpp:170.

​
Default Controls

Hydra comes with a default keyboard mapping for Switch buttons:

​
Keyboard Controls

Switch ButtonKeyboard KeyFunction
AZConfirm
BXBack/Cancel
XAAction
YSAction
LQLeft bumper
RWRight bumper
ZL1Left trigger
ZR2Right trigger
PlusReturnStart/Menu
MinusBackspaceSelect
D-PadArrow KeysNavigation
Left StickWASDMovement
Right StickIJKLCamera
Controller support is available through Apple’s GameController framework. Most PlayStation, Xbox, and Nintendo Pro Controllers work out of the box.
For detailed control configuration, see the Controls Guide.

​
Performance Settings

To get the best performance, configure these settings based on your Mac:
Recommended Settings (config.toml):
[CPU]
cpu_backend = "apple_hypervisor"  # Best performance on Apple Silicon

[Graphics]
gpu_renderer = "metal"
shader_backend = "air"  # Pre-compiled shaders for faster loading
display_resolution = "1080p"  # Or higher if your Mac supports it

[Audio]
audio_backend = "cubeb"
Apple Hypervisor provides near-native ARM64 performance on Apple Silicon Macs.
See the Configuration Guide for all available options.

​
Running Official Games

To run official Nintendo Switch games (NCA format):
1

Obtain Firmware Files

Extract and decrypt firmware files from your Nintendo Switch using switch-extract-macos.Required firmware files include:
  • Fonts (FontStandard, FontNintendoExtension)
  • Time zone data (TimeZoneBinary)
  • Avatar images (AvatarImage)
See the Firmware Guide for details.
2

Install Game Patches

Download patches from hydra-patches to prevent crashes in official games.Follow the installation guide in that repository to apply patches correctly.
3

Load the Game

With firmware configured and patches installed, load your NCA file through Hydra’s interface.
First launch may take longer as shaders compile. Subsequent launches will be faster.

​
First Launch Checklist

When running a game for the first time:
Firmware configured - Set firmware_path in config.toml (for official games)
Patches installed - Download from hydra-patches
File format supported - NRO, NCA, or NX (convert NSP if needed)
Sufficient RAM - Close other applications to free memory
Latest Hydra version - Check releases

​
Troubleshooting Common Issues

Possible solutions:
  1. Verify file format: Ensure you’re using NRO, NCA, or NX format (not NSP)
  2. Check firmware: Official games require firmware files configured in config.toml
  3. Install patches: Download from hydra-patches
  4. Check logs: Look at logs in ~/Library/Application Support/Hydra/log.txt
# View recent errors
tail -n 50 ~/Library/Application\ Support/Hydra/log.txt
Try these optimizations:
  1. Lower resolution: Change display_resolution to "720p" in config.toml
  2. Use recommended CPU backend: "apple_hypervisor" on Apple Silicon, "dynarmic" on Intel
  3. Close other applications: Free up RAM and CPU resources
  4. Check Activity Monitor: Ensure Hydra has sufficient resources
See the Configuration Guide for performance tuning options.
Debugging steps:
  1. Test keyboard controls: Use the default keyboard mapping first
  2. Connect controller before launch: Plug in gamepad before opening Hydra
  3. Check controller compatibility: PlayStation, Xbox, and Nintendo Pro Controllers are supported
  4. Review control configuration: See Controls Guide
Test with arrow keys and Z/X buttons first to verify basic input works.
Solutions:
  1. Verify audio backend: Set audio_backend = "cubeb" in config.toml
  2. Check system volume: Ensure macOS volume is not muted
  3. Select correct output device: Check Sound settings in System Preferences
  4. Try restarting: Close and reopen Hydra
See the Audio Features documentation for advanced settings.
For more detailed troubleshooting, see the Troubleshooting Guide.

​
Checking Logs

If you encounter issues, check the log file for error messages: 
# View the full log file
open -e ~/Library/Application\ Support/Hydra/log.txt

# Or tail the last 100 lines
tail -n 100 ~/Library/Application\ Support/Hydra/log.txt
Log file location is defined in src/common/config.cpp:62.

​
Enable Debug Logging

For more detailed logs, enable debug mode in config.toml: 
[Debug]
log_level = "debug"  # Options: "off", "error", "warn", "info", "debug"
log_to_file = true
log_to_stdout = true
Debug options are defined in src/common/config.cpp:218-225.

​
Next Steps

Now that you have Hydra running:

Configuration

Fine-tune CPU, GPU, and system settings

Controls

Configure keyboard and controller inputs

Running Games

Learn advanced game loading and management

Troubleshooting

Fix issues and optimize performance
Need help? Join the Discord server or check the FAQ for common questions.

Build docs developers (and LLMs) love

Get started for freeTalk to us