Library scanning

retroBITE builds your library from the folders on disk. Each console you add has its own folder inside your library, and a scan reads every file in it that the console accepts, groups the files into games and queues them for identification.

A scan only reads. It never moves, renames, copies or deletes your files.

Folder layout

Your library is the folder set by GAMES_PATH (see Configuration). Each console gets its own folder inside it, named after the console's slug by default, such as games/ps2 or games/snes. You can point a console at another folder inside the library instead, such as roms/playstation, when you add or manage it. Folders outside the library cannot be chosen: change GAMES_PATH instead.

Layouts

How files are arranged inside a console's folder is up to you. Each console has a layout that tells retroBITE where the games are and which folders to skip. Pick one with Change layout on the Consoles page, to match the loader, frontend or emulator you play that console on.

Layout	Arrangement	Offered for
However it already is	Every folder is read, nothing is skipped, and file names are taken as they are. The default.	Every console
Game folders	One folder per game: a cue sheet with its tracks, or a playlist and its discs. The folder name is the game's title.	CD-based consoles, such as PlayStation, Saturn and Mega-CD
Open PS2 Loader	Games in DVD/ and CD/, with OPL's ART/, CFG/, VMC/ and THM/ folders beside them, which are never read as games.	PlayStation 2
RetroArch	Games loose in the folder, with RetroArch's thumbnail folders beside them, which are never read as games.	PlayStation 2

Changing the layout never moves or renames anything. Folders the new layout needs are created if they are missing, and the next scan reads the folder the new way. To rearrange existing files, move them yourself, on the disk or over the network share. The console's toolbox can then fill in what the layout expects, such as .m3u playlists for multi-disc games or Open PS2 Loader's configs and artwork.

How each layout arranges a console's folder, with a PlayStation game for the first two and a PlayStation 2 game for the last two:

However it already is

psx/
├─ Final Fantasy VII (USA).m3u
├─ Final Fantasy VII (USA) (Disc 1).cue
├─ Final Fantasy VII (USA) (Disc 1).bin
└─ ...

Game folders

psx/
└─ Final Fantasy VII (USA)/
   ├─ Final Fantasy VII (USA).m3u
   ├─ Final Fantasy VII (USA) (Disc 1).cue
   ├─ Final Fantasy VII (USA) (Disc 1).bin
   └─ ...

Open PS2 Loader

ps2/
├─ DVD/
│  └─ SLUS_203.12.Silent Hill 2.iso
├─ CD/
├─ ART/
│  ├─ SLUS_203.12_COV.png
│  └─ SLUS_203.12_ICO.png
├─ CFG/
│  └─ SLUS_203.12.cfg
├─ VMC/
└─ THM/

RetroArch

ps2/
├─ Silent Hill 2 (USA).chd
└─ media/
   ├─ Named_Boxarts/
   │  └─ Silent Hill 2 (USA).png
   ├─ Named_Snaps/
   └─ Named_Titles/

With Open PS2 Loader, only files directly in DVD/ and CD/ are games, as OPL itself reads them. The toolbox writes the artwork and configs, and can add or remove the serial prefix on file names.

Supported extensions

Each console accepts its own list of file extensions. Files with any other extension are skipped, as are a few known non-game files, such as Open PS2 Loader's games.bin. Some examples from the catalog:

Console	Folder	Extensions
Super Nintendo	snes/	.smc .sfc .fig .swc .bs .gd3 .gd7 .dx2 .bsx .zip .7z
Nintendo 64	n64/	.z64 .n64 .v64 .rom .ndd .zip .7z
Game Boy Advance	gba/	.gba .agb .mb .zip .7z
Sony PlayStation	psx/	.cue .bin .img .iso .chd .mdf .pbp .toc .cbn .ccd .ecm .vcd .m3u
PlayStation 2	ps2/	.iso .bin .cue .img .mdf .nrg .chd .cso .zso
GameCube	gc/	.iso .gcm .ciso .gcz .nkit.iso .rvz .wia .m3u
Wii	wii/	.iso .wbfs .wad .dol .gcm .gcz .ciso .rvz .wia .m3u

How files become games

A scan works through the folder in three passes, so that multi-file games are recognized as one game:

1. Playlists (.m3u) and every disc they name become one game.
2. Cue sheets not claimed by a playlist become one game each, together with the tracks they name.
3. Everything else with an accepted extension becomes a game of its own.

A four-disc PlayStation game with a playlist, four cue sheets and four tracks is one game, not nine. Grouping the files before anything is looked up also keeps lookups against your ScreenScraper allowance to a minimum.

Until a game is identified it is shown with a title read from its file name. No-Intro and Redump names give the best placeholders and match most reliably, but renamed files usually still match by checksum.

After a scan

When a scan finishes, retroBITE:

• queues every new game for identification against ScreenScraper,
• updates the file and game counts on the console cards,
• updates the storage figures on the dashboard.

Files copied into the library over SMB or FTP show up in the counts within 15 minutes, but only become games once the console is scanned.

Missing files

Files that were in the library before but are gone from the disk are marked missing. They are not deleted from the library, so a drive that is briefly unmounted does not wipe your metadata.

To protect against exactly that, a scan refuses to run when the console's folder does not exist or is empty, and reports why instead of marking every game missing. Check that the drive or network mount is connected, then scan again.

Games whose files are all gone can be cleaned up from Settings → Library: run Prune now, or turn on the nightly prune.

Rescanning

Scan a console with Scan folder on its shelf or on the Consoles page. Scans run in the background, and the page updates live as they finish. retroBITE also rescans a console on its own after a conversion or a toolbox job changes its files.

You can also scan from the command line, for one console or for every console in the library:

Docker Compose

docker compose exec -u www-data retrobite-web php artisan retrobite:scan ps2
docker compose exec -u www-data retrobite-web php artisan retrobite:scan

./retrobite

./retrobite artisan retrobite:scan ps2
./retrobite artisan retrobite:scan

Add --queue to hand the scan to the background queue instead of waiting for it.