Configuration API

Configure Hydra emulator settings programmatically

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 · 0

Invalid/unset backend

HYDRA_CPU_BACKEND_APPLE_HYPERVISOR · 1

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

HYDRA_CPU_BACKEND_DYNARMIC · 2

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 · 0

Invalid/unset renderer

HYDRA_GPU_RENDERER_METAL · 1

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 · 0

Invalid/unset shader backend

HYDRA_SHADER_BACKEND_MSL · 1

Metal Shading Language - shaders compiled at runtime

HYDRA_SHADER_BACKEND_AIR · 2

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 · 0

Invalid/unset audio backend

HYDRA_AUDIO_BACKEND_NULL · 1

No audio output (silent mode)

HYDRA_AUDIO_BACKEND_CUBEB · 2

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 · 1

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

HYDRA_RESOLUTION_720P · 2

1280x720 resolution

HYDRA_RESOLUTION_1080P · 3

1920x1080 resolution

HYDRA_RESOLUTION_1440P · 4

2560x1440 resolution

HYDRA_RESOLUTION_2160P · 5

3840x2160 resolution (4K)

HYDRA_RESOLUTION_4320P · 6

7680x4320 resolution (8K)

HYDRA_RESOLUTION_AUTO_EXACT · 7

Match exact native resolution without scaling

HYDRA_RESOLUTION_CUSTOM · 8

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.