Configuration API

Overview

The Configuration API allows you to programmatically configure all aspects of the Hydra emulator, including CPU backend, GPU renderer, audio settings, and paths. Configuration is managed through a singleton instance accessed via Config::GetInstance() in C++ or through the C API functions prefixed with hydra_config_.

Accessing Configuration

C++ API

#include "common/config.hpp"

auto& config = hydra::Config::GetInstance();
config.GetCpuBackend() = hydra::CpuBackend::Dynarmic;
config.Serialize(); // Save changes to disk

C API

uint32_t* backend = hydra_config_get_cpu_backend();
*backend = HYDRA_CPU_BACKEND_DYNARMIC;
hydra_config_serialize();

Configuration Functions

hydra_config_serialize

Saves the current configuration to disk.

void hydra_config_serialize();

Configuration is saved to {app_data_path}/config.toml.

hydra_config_deserialize

Loads configuration from disk.

void hydra_config_deserialize();

If no configuration file exists, default values are loaded.

hydra_config_get_app_data_path

Gets the application data directory path.

hydra_string hydra_config_get_app_data_path();

return

hydra_string

Path to the application data directory

Backend Configuration

CPU Backend

The CPU backend determines which ARM64 CPU emulation engine to use.

HydraCpuBackend Enum

typedef enum : uint32_t {
    HYDRA_CPU_BACKEND_INVALID = 0,
    HYDRA_CPU_BACKEND_APPLE_HYPERVISOR,
    HYDRA_CPU_BACKEND_DYNARMIC,
} HydraCpuBackend;

HYDRA_CPU_BACKEND_INVALID

Invalid/unset backend

HYDRA_CPU_BACKEND_APPLE_HYPERVISOR

Apple’s Hypervisor.framework for native ARM64 execution (macOS/iOS only)

HYDRA_CPU_BACKEND_DYNARMIC

Dynarmic JIT compiler (cross-platform)

hydra_config_get_cpu_backend

Gets a pointer to the CPU backend setting.

uint32_t* hydra_config_get_cpu_backend();

return

uint32_t*

Pointer to the CPU backend setting (HydraCpuBackend enum value)

Example:

uint32_t* cpu_backend = hydra_config_get_cpu_backend();
if (*cpu_backend == HYDRA_CPU_BACKEND_INVALID) {
    // Set to Dynarmic if not configured
    *cpu_backend = HYDRA_CPU_BACKEND_DYNARMIC;
    hydra_config_serialize();
}

GPU Renderer

The GPU renderer determines which graphics API to use.

HydraGpuRenderer Enum

typedef enum : uint32_t {
    HYDRA_GPU_RENDERER_INVALID = 0,
    HYDRA_GPU_RENDERER_METAL,
} HydraGpuRenderer;

HYDRA_GPU_RENDERER_INVALID

Invalid/unset renderer

HYDRA_GPU_RENDERER_METAL

Metal graphics API (macOS/iOS only)

Currently, only Metal is supported. Future versions may add Vulkan support.

hydra_config_get_gpu_renderer

Gets a pointer to the GPU renderer setting.

uint32_t* hydra_config_get_gpu_renderer();

return

uint32_t*

Pointer to the GPU renderer setting (HydraGpuRenderer enum value)

Shader Backend

The shader backend determines how Nintendo Switch shaders are compiled.

HydraShaderBackend Enum

typedef enum : uint32_t {
    HYDRA_SHADER_BACKEND_INVALID = 0,
    HYDRA_SHADER_BACKEND_MSL,
    HYDRA_SHADER_BACKEND_AIR,
} HydraShaderBackend;

HYDRA_SHADER_BACKEND_INVALID

Invalid/unset shader backend

HYDRA_SHADER_BACKEND_MSL

Metal Shading Language - shaders compiled at runtime

HYDRA_SHADER_BACKEND_AIR

Apple Intermediate Representation - pre-compiled shaders for better performance

AIR provides better performance but requires shader pre-compilation. MSL is more flexible but has higher runtime overhead.

hydra_config_get_shader_backend

Gets a pointer to the shader backend setting.

uint32_t* hydra_config_get_shader_backend();

return

uint32_t*

Pointer to the shader backend setting (HydraShaderBackend enum value)

Audio Backend

The audio backend determines which audio output system to use.

HydraAudioBackend Enum

typedef enum : uint32_t {
    HYDRA_AUDIO_BACKEND_INVALID = 0,
    HYDRA_AUDIO_BACKEND_NULL,
    HYDRA_AUDIO_BACKEND_CUBEB,
} HydraAudioBackend;

HYDRA_AUDIO_BACKEND_INVALID

Invalid/unset audio backend

HYDRA_AUDIO_BACKEND_NULL

No audio output (silent mode)

HYDRA_AUDIO_BACKEND_CUBEB

Cubeb cross-platform audio library

hydra_config_get_audio_backend

Gets a pointer to the audio backend setting.

uint32_t* hydra_config_get_audio_backend();

return

uint32_t*

Pointer to the audio backend setting (HydraAudioBackend enum value)

Display Configuration

Resolution

The display resolution setting controls the output resolution of the emulator.

HydraResolution Enum

typedef enum : uint32_t {
    HYDRA_RESOLUTION_INVALID = 0,
    HYDRA_RESOLUTION_AUTO,
    HYDRA_RESOLUTION_720P,
    HYDRA_RESOLUTION_1080P,
    HYDRA_RESOLUTION_1440P,
    HYDRA_RESOLUTION_2160P,
    HYDRA_RESOLUTION_4320P,
    HYDRA_RESOLUTION_AUTO_EXACT,
    HYDRA_RESOLUTION_CUSTOM,
} HydraResolution;

HYDRA_RESOLUTION_AUTO

Automatically scale to native Switch resolution (720p docked, variable handheld)

HYDRA_RESOLUTION_720P

1280x720 resolution

HYDRA_RESOLUTION_1080P

1920x1080 resolution

HYDRA_RESOLUTION_1440P

2560x1440 resolution

HYDRA_RESOLUTION_2160P

3840x2160 resolution (4K)

HYDRA_RESOLUTION_4320P

7680x4320 resolution (8K)

HYDRA_RESOLUTION_AUTO_EXACT

Match exact native resolution without scaling

HYDRA_RESOLUTION_CUSTOM

Use custom resolution specified by hydra_config_get_custom_display_resolution()

hydra_config_get_display_resolution

Gets a pointer to the display resolution setting.

uint32_t* hydra_config_get_display_resolution();

return

uint32_t*

Pointer to the display resolution setting (HydraResolution enum value)

hydra_config_get_custom_display_resolution

Gets a pointer to the custom resolution setting.

hydra_uint2* hydra_config_get_custom_display_resolution();

return

hydra_uint2*

Pointer to custom resolution (width x, height y). Only used when display_resolution is HYDRA_RESOLUTION_CUSTOM.

Example:

// Set custom 2560x1440 resolution
uint32_t* resolution = hydra_config_get_display_resolution();
*resolution = HYDRA_RESOLUTION_CUSTOM;

hydra_uint2* custom_res = hydra_config_get_custom_display_resolution();
custom_res->x = 2560;
custom_res->y = 1440;

hydra_config_serialize();

Path Configuration

Firmware Path

hydra_config_get_firmware_path

Gets the firmware directory path.

hydra_string hydra_config_get_firmware_path();

return

hydra_string

Path to the Nintendo Switch firmware directory

hydra_config_set_firmware_path

Sets the firmware directory path.

void hydra_config_set_firmware_path(hydra_string value);

value

hydra_string

required

Path to the firmware directory

SD Card Path

hydra_config_get_sd_card_path

Gets the virtual SD card directory path.

hydra_string hydra_config_get_sd_card_path();

return

hydra_string

Path to the virtual SD card directory (default: {app_data}/sdmc)

hydra_config_set_sd_card_path

Sets the virtual SD card directory path.

void hydra_config_set_sd_card_path(hydra_string value);

value

hydra_string

required

Path to the SD card directory

Save Path

hydra_config_get_save_path

Gets the save data directory path.

hydra_string hydra_config_get_save_path();

return

hydra_string

Path to the save data directory (default: {app_data}/save)

hydra_config_set_save_path

Sets the save data directory path.

void hydra_config_set_save_path(hydra_string value);

value

hydra_string

required

Path to the save data directory

Sysmodules Path

hydra_config_get_sysmodules_path

Gets the system modules directory path.

hydra_string hydra_config_get_sysmodules_path();

return

hydra_string

Path to the sysmodules directory (default: {app_data}/sysmodules)

hydra_config_set_sysmodules_path

Sets the system modules directory path.

void hydra_config_set_sysmodules_path(hydra_string value);

value

hydra_string

required

Path to the sysmodules directory

Game and Plugin Configuration

hydra_config_get_game_paths

Gets the list of game library paths.

void* hydra_config_get_game_paths();

return

void*

Pointer to a string list containing game library paths

Example:

void* game_paths = hydra_config_get_game_paths();
uint32_t count = hydra_string_list_get_count(game_paths);

for (uint32_t i = 0; i < count; i++) {
    hydra_string path = hydra_string_list_get(game_paths, i);
    // Process each game path
}

hydra_config_get_loader_plugins

Gets the list of loader plugins.

void* hydra_config_get_loader_plugins();

return

void*

Pointer to a loader plugin list

hydra_config_get_patch_paths

Gets the list of patch directories.

void* hydra_config_get_patch_paths();

return

void*

Pointer to a string list containing patch directory paths

System Configuration

hydra_config_get_user_id

Gets the active user ID.

hydra_u128* hydra_config_get_user_id();

return

hydra_u128*

Pointer to the 128-bit user ID

hydra_config_get_handheld_mode

Gets the handheld mode setting.

bool* hydra_config_get_handheld_mode();

return

bool*

Pointer to handheld mode flag. true for handheld mode, false for docked mode.

Example:

bool* handheld = hydra_config_get_handheld_mode();
*handheld = false; // Switch to docked mode
hydra_config_serialize();

Debugging Configuration

Logging

hydra_config_get_log_output

Gets the log output destination.

uint32_t* hydra_config_get_log_output();

return

uint32_t*

Pointer to log output setting (HydraLogOutput enum)

typedef enum : uint32_t {
    HYDRA_LOG_OUTPUT_INVALID = 0,
    HYDRA_LOG_OUTPUT_NONE,
    HYDRA_LOG_OUTPUT_STD_OUT,
    HYDRA_LOG_OUTPUT_FILE,
} HydraLogOutput;

hydra_config_get_log_fs_access

Gets the filesystem access logging flag.

bool* hydra_config_get_log_fs_access();

return

bool*

Pointer to flag controlling filesystem access logging

hydra_config_get_debug_logging

Gets the debug logging flag.

bool* hydra_config_get_debug_logging();

return

bool*

Pointer to flag enabling verbose debug logging

GDB Server

hydra_config_get_gdb_enabled

Gets the GDB server enabled flag.

bool* hydra_config_get_gdb_enabled();

return

bool*

Pointer to flag enabling the GDB remote debugging server

hydra_config_get_gdb_port

Gets the GDB server port.

uint16_t* hydra_config_get_gdb_port();

return

uint16_t*

Pointer to GDB server port number (default: 1234)

hydra_config_get_gdb_wait_for_client

Gets the GDB wait for client flag.

bool* hydra_config_get_gdb_wait_for_client();

return

bool*

Pointer to flag that makes emulator wait for GDB client connection before starting

Example:

// Enable GDB debugging on port 5555
bool* gdb_enabled = hydra_config_get_gdb_enabled();
*gdb_enabled = true;

uint16_t* gdb_port = hydra_config_get_gdb_port();
*gdb_port = 5555;

bool* wait_for_client = hydra_config_get_gdb_wait_for_client();
*wait_for_client = true;

hydra_config_serialize();

C++ Config Class

The C++ API provides a more convenient interface through the Config class:

namespace hydra {

class Config {
public:
    static Config& GetInstance();
    
    void LoadDefaults();
    void Serialize();
    void Deserialize();
    void Log();
    
    // Getters return references for direct modification
    CpuBackend& GetCpuBackend();
    GpuRenderer& GetGpuRenderer();
    ShaderBackend& GetShaderBackend();
    Resolution& GetDisplayResolution();
    AudioBackend& GetAudioBackend();
    
    const std::string_view GetAppDataPath() const;
    const std::string_view GetLogsPath() const;
    // ... more getters
};

}

Example:

#include "common/config.hpp"

auto& config = hydra::Config::GetInstance();

// Load config from disk
config.Deserialize();

// Modify settings
config.GetCpuBackend() = hydra::CpuBackend::Dynarmic;
config.GetDisplayResolution() = hydra::Resolution::_1080p;
config.GetHandheldMode() = false;

// Save changes
config.Serialize();

// Log current configuration
config.Log();

See src/common/config.hpp for the complete implementation.

Getting Started

API Reference

​Overview

​Accessing Configuration

​C++ API

​C API

​Configuration Functions

​hydra_config_serialize

​hydra_config_deserialize

​hydra_config_get_app_data_path

​Backend Configuration

​CPU Backend

​HydraCpuBackend Enum

​hydra_config_get_cpu_backend

​GPU Renderer

​HydraGpuRenderer Enum

​hydra_config_get_gpu_renderer

​Shader Backend

​HydraShaderBackend Enum

​hydra_config_get_shader_backend

​Audio Backend

​HydraAudioBackend Enum

​hydra_config_get_audio_backend

​Display Configuration

​Resolution

​HydraResolution Enum

​hydra_config_get_display_resolution

​hydra_config_get_custom_display_resolution

​Path Configuration

​Firmware Path

​hydra_config_get_firmware_path

​hydra_config_set_firmware_path

​SD Card Path

​hydra_config_get_sd_card_path

​hydra_config_set_sd_card_path

​Save Path

​hydra_config_get_save_path

​hydra_config_set_save_path

​Sysmodules Path

​hydra_config_get_sysmodules_path

​hydra_config_set_sysmodules_path

​Game and Plugin Configuration

​hydra_config_get_game_paths

​hydra_config_get_loader_plugins

​hydra_config_get_patch_paths

​System Configuration

​hydra_config_get_user_id

​hydra_config_get_handheld_mode

​Debugging Configuration

​Logging

​hydra_config_get_log_output

​hydra_config_get_log_fs_access

​hydra_config_get_debug_logging

​GDB Server

​hydra_config_get_gdb_enabled

​hydra_config_get_gdb_port

​hydra_config_get_gdb_wait_for_client

​C++ Config Class

Build docs developers (and LLMs) love

Overview

Accessing Configuration

C++ API

C API

Configuration Functions

hydra_config_serialize

hydra_config_deserialize

hydra_config_get_app_data_path

Backend Configuration

CPU Backend

HydraCpuBackend Enum

hydra_config_get_cpu_backend

GPU Renderer

HydraGpuRenderer Enum

hydra_config_get_gpu_renderer

Shader Backend

HydraShaderBackend Enum

hydra_config_get_shader_backend

Audio Backend

HydraAudioBackend Enum

hydra_config_get_audio_backend

Display Configuration

Resolution

HydraResolution Enum

hydra_config_get_display_resolution

hydra_config_get_custom_display_resolution

Path Configuration

Firmware Path

hydra_config_get_firmware_path

hydra_config_set_firmware_path

SD Card Path

hydra_config_get_sd_card_path

hydra_config_set_sd_card_path

Save Path

hydra_config_get_save_path

hydra_config_set_save_path

Sysmodules Path

hydra_config_get_sysmodules_path

hydra_config_set_sysmodules_path

Game and Plugin Configuration

hydra_config_get_game_paths

hydra_config_get_loader_plugins

hydra_config_get_patch_paths

System Configuration

hydra_config_get_user_id

hydra_config_get_handheld_mode

Debugging Configuration

Logging

hydra_config_get_log_output

hydra_config_get_log_fs_access

hydra_config_get_debug_logging

GDB Server

hydra_config_get_gdb_enabled

hydra_config_get_gdb_port

hydra_config_get_gdb_wait_for_client

C++ Config Class