Game Library

How the game library works from a user perspective: browsing systems, managing ROMs, and keeping your library up to date.

Systems Grid#

The main library view shows all known systems as cards, each with the system display name, manufacturer, game count, and total size. Systems with no ROMs appear dimmed.

Tap a system to view its games.

Game List#

Each system page shows its ROMs with:

• Box art thumbnails for every game that has images available
• Search within the system (debounced so it doesn’t lag while typing)
• Random Game within the current system
• Infinite scroll with fast pagination (100 games per page)
• ROM details – filename, file size (Mbit/Kbit for cartridge systems, MB/GB for disc-based), file format badge
• Consistent game cards – the same card layout (box art, badges, favorite toggle) is used across all views: ROM lists, search results, developer pages, series siblings, and recommendations

Per-Game Actions#

Each game supports:

• Favorite toggle – add or remove from favorites
• Inline rename – rename the ROM file (with extension protection to prevent breaking file associations)
• Delete with confirmation – shows file count and total size before deleting

Smart multi-file management: Delete handles related files together – M3U + disc files, CUE + BIN, ScummVM data directories, SBI companions. Rename is restricted for formats where renaming would break the game (CUE sheets, ScummVM, binary-referenced M3U playlists).

Multi-Disc Handling (M3U)#

Games that span multiple discs (common for PlayStation, Sega CD, etc.) are handled automatically:

• When an M3U playlist exists, individual disc files are hidden from the game list
• Sizes from all disc files are aggregated into the playlist entry
• M3U playlists are auto-generated at scan time for multi-part games (Side A/B, Disk 1 of N)

From a user perspective, a 3-disc game appears as a single entry with the combined size.

Arcade Display Names#

Arcade ROMs use internal codenames (e.g., sf2.zip). The app automatically shows human-readable titles (“Street Fighter II”) for arcade entries across MAME, FBNeo, and Flycast (Naomi/Atomiswave). Entries from the source metadata are retained, including gambling, slot machine, computer, handheld, and electromechanical categories, so ROMs from full MAME sets can still be identified.

Favorites#

Favorites let you build a personal shortlist of the games you care about most. Star any game from its card or detail page and it appears in a dedicated Favorites section — a curated view of your collection that cuts through the noise of thousands of ROMs.

The favorites page shows a featured card for your most recent favorite, a recently added horizontal scroll, and per-system cards summarizing your favorites across systems. You can switch between a flat list and grouped views at any time. Games are sorted by date added (newest first) across all views.

Organizing Favorites#

As your favorites grow, the organize feature helps you make sense of them. Choose one or two grouping criteria — developer, genre, system, player count, rating, or alphabetical — and your favorites are sorted into subfolders automatically. For example, grouping by genre and then by system creates folders like “Action > Mega Drive” and “RPG > PlayStation”.

Before applying, a preview shows exactly how your favorites will be grouped so you can adjust criteria without committing. Organized views are persistent — they stay until you change or clear them.

Managing Favorites#

• Add/remove from any game card or the game detail page
• Remove confirmation – tapping the star shows “Remove?” before acting, so you don’t accidentally lose a favorite
• Recursive unfavorite – removing a favorite from within an organized subfolder unfavorites the game and removes it from the view immediately

Favorites-Based Recommendations#

The favorites page includes personalized recommendations based on what you’ve favorited:

• “Because You Love [Game]” – discovers similar games by matching genre and developer
• “More from [Series]” – surfaces unfavorited series siblings across all your favorites

Recents#

Recently played games are tracked automatically when you launch a game from the app. The home page shows:

• Last Played hero card with the most recently launched game
• Recently Played horizontal scroll of recent games

Region Preference#

Set your preferred ROM region (USA, Europe, Japan, World) in Settings. This affects:

• Sort order – preferred region variants appear first in game lists
• Search scoring – preferred region gets a boost in search results
• Recommendation dedup – when multiple region variants exist, the preferred one is shown

A secondary region preference is also supported for a two-tier sort: Primary > Secondary > World > others.

Automatic Library Updates#

On local storage (SD, USB, NVMe), the app watches the roms/ directory for changes. New, modified, or deleted ROMs are detected automatically – no manual refresh needed. Changes are debounced (3 seconds) to handle bulk file copies smoothly. Removing an entire system folder also propagates: cached rows for that system are dropped to match disk.

On NFS storage, automatic live detection is not possible (inotify does not work across network mounts). Startup and manual rescans reconcile every visible system, including ROMs stored in subfolders, so ROMs added while the device was off are picked up on the next boot. Use the “Rescan Game Library” button in the metadata page when you want to refresh immediately. NFS rescans treat a missing top-level system folder as ambiguous (could be a transient mount blip) and preserve the cached rows; only successful walks replace state.

For cartridge systems with No-Intro CRC data, normal startup scans, manual rescans, and local watcher rescans reuse cached CRC identity when the file still has the same recorded size. This keeps common rescans fast on large ROM sets and NFS shares without dropping hash-based identification. Manual “Rebuild Game Library” is the full verification path: it ignores the CRC cache and recomputes hashes for hash-eligible ROM files. Hybrid folders such as Sega 32X only hash cartridge-shaped entries; CD/image/playlist entries are skipped.

When ROM matching continues after a scan or rebuild, Replay Control shows a “Matching ROMs” progress banner. Library browsing stays available, but starting another rescan or rebuild is blocked until matching finishes. If you add, rename, or delete ROMs while a scan, rebuild, or matching pass is running, run Rescan again afterwards so the library reflects the final files on disk.

Startup Behavior#

On first launch, normal startup, or after a rebuild, the app scans all visible system directories to index your ROMs and catch offline changes. During this process:

• The server responds immediately with a banner showing the active phase, such as scanning the library, enriching metadata, rebuilding the thumbnail index, or matching ROMs
• Pages are fully usable while scanning runs in the background
• Startup still checks subfolders, but systems that have not changed since the last complete scan are skipped after the file check, so restarts are faster on stable libraries
• If no storage is connected, a waiting page is shown until storage becomes available
• Interrupted scans are repaired automatically by the next startup scan
• If the configured storage changes or becomes unavailable during a long scan, the in-flight scan is cancelled before the next system write so stale results are not saved to the wrong storage database

For architecture details on the cache tiers, scan pipeline, and enrichment process, see the Architecture section.