ConfigurationConfiguration

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#

• Click the gear button at the far right of the top bar to open the Quick Settings panel.
• Press F1 once to toggle Quick Settings, which holds the visual-effect toggles, the theme picker, the mini music player, and an About block showing your installed version.
• Press F1 twice quickly, or click Open Full Settings, to open the full Settings window.
• Press Escape to close whichever settings surface is open.

The full Settings window is organized into tabs: Library, Manual Import, ScummVM Import, Steam Import, Platform Defaults, Emulators, RetroArch, Metadata, Appearance, Custom Theme, Music, Guide, and License.

Note: The full Settings window is mouse and keyboard only. If you open it while navigating with a controller, it shows a prompt to switch to mouse navigation. Press B to close it.

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:

The following settings are stored in the database:

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:

Library Settings#

ROM Directories#

Add folders containing your game files in Settings > Library. Click Add Folder and pick a directory. RetroVoid scans these directories recursively (following symlinks) to build your library.

Each folder row gives you four controls:

• A platform dropdown, which starts on Auto-detect platform. Choosing a platform forces every game found in that folder onto it, which is the reliable option for shared disc formats.
• A pencil button (Change folder location) that repoints the folder at a new path while keeping its platform assignment.
• A Scan button that scans only that folder.
• A trash button that removes the folder from the list. Games already imported from it stay in your library.

Scan Library at the bottom scans every configured folder, and reports Found, Added, and Updated counts when it finishes.

When Auto-scan on Launch is on (the default), RetroVoid re-scans your library folders each time it starts and shows a toast listing how many games were added and on which platforms.

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.

Library scans never fetch metadata on their own. You always trigger it, either per game or in bulk.

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.

1. Go to the Twitch Developer Console and log in with your Twitch account (create one if needed, it's free).
2. Click Register Your Application.
3. Fill in the form:
   • Name: anything you like (e.g., "RetroVoid")
   • OAuth Redirect URLs: enter http://localhost
   • Category: select Application Integration
4. Click Create.
5. Find your new application in the list and click Manage.
6. Your Client ID is displayed on this page.
7. 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

1. Open Settings > Metadata.
2. Enter your Client ID and Client Secret in the IGDB API Credentials section.
3. Click Validate & Save. A green Valid credentials message confirms they work.

Once configured, RetroVoid can fetch metadata for your games.

Using Metadata Scraping

There are three ways to fetch metadata:

• Per game, automatic: in a game's detail view, click Auto-fetch Metadata from IGDB. RetroVoid searches for the best match based on the game's title and platform.
• Per game, manual: click Search IGDB (pick manually) to choose the correct match from a list of results with cover art previews. Search Different Name lets you retry with a different title, which also searches across all platforms.
• In bulk: in Settings > Metadata, click Scrape All Games. Leave Only scrape games without existing metadata checked to skip games you've already filled in. Progress is logged per game, keeps running while you browse, and can be stopped with Cancel.

Requests are throttled automatically so bulk scraping stays within IGDB's rate limit.

Image Quality

Settings > Metadata also sets the default image quality for downloads, separately for Cover Art and Media & Screenshots:

Higher tiers fall back to lower ones when IGDB doesn't have that variant. Bulk scraping uses these defaults; single-game fetches ask you each time with an Image Quality prompt.

What Metadata Is Fetched

Steam Integration#

RetroVoid can import your installed Steam games and sync play data. Importing works without credentials; play time and last played need a Steam Web API Key and your Steam ID.

Getting Your Steam Web API Key

1. Go to the Steam Web API Key registration page.
2. Log in with your Steam account.
3. Enter a domain name (anything works, e.g., localhost).
4. 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:

1. Go to your Steam Community profile in a browser.
2. If your URL looks like steamcommunity.com/id/yourname, visit steamid.io and paste your profile URL to look up your 64-bit ID.
3. If your URL already looks like steamcommunity.com/profiles/76561198XXXXXXXX, that number is your 64-bit Steam ID.

Entering Your Steam Credentials

1. Open Settings > Steam Import.
2. Enter your Steam API Key.
3. Select your account from the dropdown or enter your Steam ID (64-bit) manually.
4. 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

• Library Import: click Scan Library to list your installed Steam games, tick the ones you want, and click Import. Imported games launch through the steam:// protocol.
• Play Time: total play time synced from your Steam account.
• Last Played: the more recent of your Steam account's record and your local Steam client's own record, so sessions started outside RetroVoid still show up.
• Update Steam Data: refreshes play time and last played for games you've already imported.

Two launch-time options sit at the top of the tab:

• Auto-Import Installed Games (default off): imports newly installed Steam games automatically when RetroVoid starts.
• Import Reminder (default on): shows a notification on launch counting installed Steam games that aren't in your library yet. It is disabled while auto-import is on.

Display Settings#

Theme Selection#

Switch between the five built-in themes in Settings > Appearance or the Quick Settings panel, or build 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
• Terminal: terminal green accents, Matrix/Fallout style, CRT effects
• Purple Passion: rich purple accents, CRT effects, phosphor glow, holographic shaders

A sixth card, Custom, applies your own theme. See Themes & Customization for the editor.

Theme changes apply instantly.

Visual Effect Toggles#

Independently toggle these effects in Settings > Appearance (the first four are also in Quick Settings):

• Post-Processing: chromatic aberration, noise, vignette, and CRT effects (available for all themes)
• Particles: floating particle effects in the background (toggle hidden for the Minimal theme)
• 3D Grid: neon grid in the background (toggle hidden for the Minimal theme)
• 3D Background: 3D scene in Grid and List views (toggle hidden for the Minimal theme)
• Pause 3D When in Background: stops 3D rendering while RetroVoid isn't the active window, which also freezes animated cover art. Minimizing always pauses, whatever this is set to. On by default.

3D Quality#

Five quality tiers control the rendering resolution. The section appears only while 3D Background is enabled:

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.