Managing Your LibraryManaging Your Library

Organize your ROMs, playlists, and game collection in RetroVoid.

Your library is the heart of RetroVoid. This guide covers everything from adding games to organizing them into playlists.

Adding ROM Directories#

RetroVoid builds your library by scanning directories you specify. To add a new ROM directory:

1. Open Settings (press F1 twice).
2. Add your game folder paths to the library folders list.
3. RetroVoid will scan the directories and import any recognized game files.

Scanning is recursive by default. All subfolders are included, and symlinks are followed.

Recommended: When adding a ROM directory, assign a platform manually to the folder during import. While RetroVoid can auto-detect many systems, consoles like PlayStation, PlayStation 2, Saturn, Sega CD, and others share common file types such as .iso and .cue/.bin. Manually assigning a platform removes the guesswork and ensures every game is categorized correctly from the start.

Supported File Types#

RetroVoid recognizes a wide range of ROM and disc image formats. Platform detection is based on file extension, with folder name hints as a fallback.

Nintendo#

Sony#

Sega#

Atari#

Other Platforms#

Shared extensions: When a file extension is shared across platforms (e.g., .iso, .chd), RetroVoid uses priority ordering: PS2 > PS1 > GameCube > Wii > Xbox > Xbox 360 > Dreamcast > Saturn > 3DO. Folder name hints can override this.

How Library Scanning Works#

RetroVoid uses a multi-phase scanning process:

Phase 1: Special Format Detection#

Before scanning individual files, RetroVoid looks for directory-based game formats:

• PS3: Detects PS3_DISC.SFB in game directories
• PS4: Detects eboot.bin directly in game folders
• Wii U (Loadiine): Detects meta/meta.xml with a code/ folder present

Phase 2: ROM File Collection#

Recursively walks all configured library folders. Files are matched to platforms by extension. Certain files are filtered out:

• macOS AppleDouble files (._*)
• neogeo.zip (BIOS file)
• .bin files that are paired with a .cue or .gdi file (part of a disc image)

Phase 3: Multi-Disc Detection#

RetroVoid automatically detects multi-disc games by recognizing patterns like (Disc 1), (Disk 1), (CD1), - Disc 1, _disc1, etc. When a multi-disc set is detected (2+ discs), RetroVoid auto-generates an .m3u playlist file so you can launch the game as a single entry.

Phase 4: Game Import#

Each discovered game gets a UUID, a cleaned title (derived from the filename), and is added to the database. Duplicate ROM paths are rejected.

Manual Import#

Some platforms can't be detected by file extension alone. For these, use the manual import feature:

1. Select a platform from the dropdown.
2. Browse for the game file.
3. Edit the game title (auto-filled from the filename).
4. Click Add Game.

PS3 Note: When manually importing PS3 games, point to the installed EBOOT.BIN file, not the .pkg file.

ScummVM Import#

ScummVM games use Game IDs instead of file paths:

1. Choose ScummVM as the platform.
2. Enter the Game ID (e.g., monkey, tentacle, samnmax).
3. Enter the display title.

The Game ID is stored internally and passed to ScummVM at launch via scummvm [game-id].

Metadata#

RetroVoid fetches game metadata from IGDB (Internet Game Database via Twitch OAuth2). For each game, it retrieves:

• Name and summary
• Cover art: high-resolution (528x748) with fallback to standard (264x374)
• Screenshots: up to 5 per game
• Release date, genres, developer, and publisher

Search Strategy#

IGDB matching uses a multi-step approach:

1. Case-insensitive name search
2. Fuzzy matching for alternate spellings
3. Results ranked by: exact match → starts with → contains → shorter names → earlier releases

If auto-matching returns the wrong game, use the Search Different Name option to search for the correct title manually.

Views#

RetroVoid offers three views for browsing your library:

Grid View#

The default view. Games are displayed as a responsive grid of cover art tiles with a 3:4 aspect ratio. Features include:

• Configurable card size (120–280px) via a slider in the toolbar
• Platform logo overlay on each card
• Hover effects
• Bulk selection with Shift+Click

List View#

A table layout with sortable columns: title, platform, playtime, last played, and release date. Click any column header to sort.

Holographic Shelf View#

A 3D shelving display with games arranged on neon-lit platforms. Features include:

• Horizontal scrolling per shelf
• Platform logos
• Parallax tilt effect
• Drag and rubberband physics
• Virtualization for large libraries (400+ games)
• Configurable quality (5 tiers)

Playlists#

Playlists let you group games however you like. Games can belong to multiple playlists.

Creating a Playlist#

1. Click the + button in the sidebar under the playlists section.
2. Type a name for your playlist inline.
3. Add games via the right-click context menu or the playlist picker.

Managing Playlists#

• Rename or delete playlists via right-click context menu on the playlist name.
• Add/remove games through the Playlist Picker modal (accessible from a game's context menu or detail view).
• The first game in a playlist is used as the playlist's cover image.

Playtime Tracking#

RetroVoid automatically tracks your play sessions:

• A session starts when you launch a game and ends when the emulator process exits.
• Sessions shorter than 5 seconds are filtered out (quick closes or errors).
• Each game's total playtime accumulates across all sessions.
• Last played timestamp is updated on each launch.
• Playtime is visible in List View and in game details.

Note: Playtime tracking is not persisted if the app is force-closed shortly after starting an active session.

Steam Playtime#

Steam games launched via URL protocol may not accurately report when the game closes, which can affect RetroVoid's built-in session tracking. However, if you enter your Steam Account Web API Key in Settings, RetroVoid will use the Steam API to sync Last Played Date and Playtime data directly from your Steam account, providing accurate tracking regardless of how the game was launched.

Game Context Menu#

Right-click any game to access:

• Play: launch the game
• Favorite: toggle the game as a favorite
• Playlist: add or remove from playlists
• Cover Art: change the game's cover image
• Edit Metadata: modify title, description, etc.
• Change Platform: reassign the game's platform
• Delete: remove the game from your library

Deleting a game removes its cover art, screenshots, user media, playlist entries, play sessions, and database record. Your ROM file is not affected.