Configuration
Understand how RetroVoid stores and manages settings.
RetroVoid manages its settings through a combination of a SQLite database (for backend/persistent settings) and browser localStorage (for frontend/UI settings). There is no external configuration file. All settings are managed through the in-app Settings panel.
Accessing Settings
- Press F1 once to toggle the Quick Settings panel for common options.
- Press F1 twice quickly to open the full Settings window.
How Settings Are Stored
Backend Settings (SQLite Database)
Core application settings are stored in a SQLite database as key-value pairs. The database is located at:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/com.retrovoid.app/retrovoid.db |
| Windows | %APPDATA%\RetroVoid\retrovoid.db |
| Linux | ~/.config/retrovoid/retrovoid.db or ~/.local/share/retrovoid/retrovoid.db |
The following settings are stored in the database:
| Setting | Type | Default | Description |
|---|---|---|---|
auto_scan_enabled | boolean | true | Auto-scan ROM folders when the app launches |
library_folders | JSON array | [] | Paths to your ROM library folders |
playlists_expanded | boolean | true | Whether the sidebar playlist section is expanded |
launch_fullscreen | boolean | true | Start in borderless fullscreen (Windows/Linux only) |
retroarch_path | string | empty | Path to your RetroArch installation |
retroarch_cores_path | string | empty | Path to your RetroArch cores directory |
igdb_client_id | string | empty | Twitch Client ID for IGDB metadata scraping |
igdb_client_secret | string | empty | Twitch Client Secret for IGDB metadata scraping |
steam_api_key | string | empty | Steam API key for playtime/last played tracking |
steam_id | string | empty | Steam user ID for library import |
Note: You should not edit the database directly unless you know what you're doing. Use the Settings panel instead.
Frontend Settings (localStorage)
UI and display preferences are stored in localStorage (managed by Zustand with persist middleware). These include:
| Setting | Type | Default | Description |
|---|---|---|---|
theme | string | cyberpunk | Active theme (cyberpunk, minimal, retro-crt, purple-passion, retro-terminal, custom) |
enablePostProcessing | boolean | true | Bloom, chromatic aberration, noise effects |
enableParticles | boolean | true | Background particle system |
enableGrid | boolean | true | 3D grid background |
enable3DBackground | boolean | true | Full 3D background scene |
volume | number | 80 | Audio volume level |
launchInFullscreen | boolean | true | Launch in fullscreen mode |
gridCardSize | number | 180 | Grid view card size in pixels (range: 120–280) |
quality3D | string | high | 3D rendering quality tier |
Library Settings
ROM Directories
Add folders containing your game files through the Settings panel. RetroVoid scans these directories recursively (following symlinks) to build your library.
When auto_scan_enabled is on, RetroVoid re-scans your library folders each time it launches. New games are added and the library stays up to date.
Metadata (IGDB)
RetroVoid fetches game metadata from IGDB (Internet Game Database), including cover art, screenshots, descriptions, release dates, genres, developer, and publisher information. To use this feature, you need to provide your own IGDB API credentials.
Getting Your IGDB Credentials
IGDB uses Twitch's authentication system. You'll need to create a free Twitch Developer application to get a Client ID and Client Secret.
- Go to the Twitch Developer Console and log in with your Twitch account (create one if needed, it's free).
- Click Register Your Application.
- Fill in the form:
- Name: anything you like (e.g., "RetroVoid")
- OAuth Redirect URLs: enter
http://localhost - Category: select Application Integration
- Click Create.
- Find your new application in the list and click Manage.
- Your Client ID is displayed on this page.
- Click New Secret to generate your Client Secret. Copy it immediately. It won't be shown again.
Important: Keep your Client Secret private. Do not share it publicly.
Entering Your Credentials in RetroVoid
- Open Settings > Metadata.
- Enter your Client ID and Client Secret in the IGDB API Credentials section.
- Click Validate & Save. A green checkmark confirms your credentials are valid.
Once configured, RetroVoid can fetch metadata for your games.
Using Metadata Scraping
There are two ways to fetch metadata for your games:
- Automatic: from a game's detail view, click Auto-fetch Metadata from IGDB. RetroVoid will search for the best match based on the game's title and platform.
- Manual: click Search IGDB (pick manually) to search and select the correct match from a list of results with cover art previews.
You can also scrape metadata for your entire library in bulk from Settings > Metadata, which will fetch metadata for all games (or only those missing it). A 300ms delay between requests keeps you within IGDB's rate limits.
What Metadata Is Fetched
| Data | Details |
|---|---|
| Cover Art | High-resolution cover image |
| Screenshots | Up to 5 screenshots per game |
| Description | Game summary |
| Release Date | Original release date |
| Genres | Genre tags |
| Developer | Development studio |
| Publisher | Publishing company |
Steam Integration
RetroVoid can import your Steam library and sync playtime data using the Steam Web API. To enable this, you need a Steam Web API Key and your Steam ID.
Getting Your Steam Web API Key
- Go to the Steam Web API Key registration page.
- Log in with your Steam account.
- Enter a domain name (anything works, e.g.,
localhost). - Click Register and your API key will be displayed. Copy it.
Finding Your Steam ID
RetroVoid will try to auto-detect your Steam accounts from your local Steam installation. If detected, you'll see a dropdown with your account(s) listed by name and 64-bit Steam ID.
If auto-detection doesn't work, you can find your 64-bit Steam ID manually:
- Go to your Steam Community profile in a browser.
- If your URL looks like
steamcommunity.com/id/yourname, visit steamid.io and paste your profile URL to look up your 64-bit ID. - If your URL already looks like
steamcommunity.com/profiles/76561198XXXXXXXX, that number is your 64-bit Steam ID.
Entering Your Steam Credentials
- Open Settings > Steam Import.
- Select your account from the dropdown or enter your 64-bit Steam ID manually.
- Enter your Steam Web API Key.
- Click Validate & Save. This confirms your credentials and profile are accessible.
Important: Your Steam profile must be set to Public for the API to work. Check this in Steam under Profile > Edit Profile > Privacy Settings.
What Steam Integration Provides
- Playtime: total playtime synced from your Steam account
- Last Played: last played date for each game
- Library Import: import your Steam games into RetroVoid (launched via
steam://protocol)
Click Update Steam Data in the Steam Import settings to refresh playtime and last played data for your imported Steam games.
Display Settings
Theme Selection
Switch between the five built-in themes in Settings > Appearance, or create your own with the Custom Theme Editor:
- Cyberpunk: neon cyan accents, holographic effects, particles, bloom (default)
- Minimal: warm tan accents, clean aesthetic, no particles or grid
- Retro CRT: amber orange accents, CRT barrel distortion, scanlines, phosphor glow
- Purple Passion: rich purple accents, CRT effects, phosphor glow, holographic shaders
- Terminal: terminal green accents, Matrix/Fallout style, CRT effects
- Custom: build your own theme from scratch (see Themes & Customization)
Theme changes apply instantly.
Visual Effect Toggles
Independently toggle these effects in the Appearance settings:
- Post-Processing: bloom, chromatic aberration, noise (available for all themes)
- Particles: background particle system (toggle hidden for Minimal theme)
- 3D Grid: grid overlay in 3D scene (toggle hidden for Minimal theme)
- 3D Background: full 3D background scene (toggle hidden for Minimal theme)
3D Quality
Five quality tiers control the rendering resolution:
| Tier | Render Scale | Notes |
|---|---|---|
| Performance | 1x fixed | For older/integrated GPUs |
| Balanced | Up to 1.5x | Good balance |
| High (default) | Up to 2x | Recommended for most dedicated GPUs |
| Ultra | Up to 3x | High-end GPUs |
| Maximum | Native DPR | Best quality, highest GPU load |
Environment Variables
RetroVoid does not use any environment variables for configuration. All settings are managed through the in-app Settings panel.
Resetting to Defaults
To reset all settings, you can delete the app data directory for your platform (see paths above). RetroVoid will recreate the database with default values on next launch.
Warning: This deletes all settings, library metadata, playlists, and cached media. Your ROM files are not affected.