Organising ROMs

A games library is one console and one or more folders. Credenza walks those folders, picks up the files that belong to that console, and files each one as a game. This page covers how to lay the files out so they come through cleanly, and how to get box art and details for them.

One library per console

Create a library for each console you have games for, at Settings → Server → Libraries: set Type to Games, pick the System, and add the folders. The system decides which file extensions the scan collects — the full list is in the consoles table.

Because each library only collects its own console’s extensions, you can keep your ROMs however suits you:

/srv/roms/
├── nes/
│   ├── Super Mario Bros. 3 (USA).nes
│   └── The Legend of Zelda (USA).zip
├── snes/
│   ├── Chrono Trigger (USA).sfc
│   └── Super Metroid (Japan, USA).7z
└── gba/
    └── Metroid Fusion (USA).gba

Point an NES library at /srv/roms/nes, a SNES library at /srv/roms/snes, and so on — one folder per console is the layout that always works.

If your files aren’t zipped, you can also point several libraries at one mixed folder: the NES library takes only the .nes files, the SNES library only the .sfc files, and so on. Archives are the exception. A .zip, .7z or .rar doesn’t say which console it is for, so every games library that can see it picks it up — keep archives in a folder that only one console’s library scans.

Subfolders are scanned too, so grouping games into folders by genre, series or anything else is fine. Hidden files and folders — names starting with a dot — are skipped.

After adding the library, press Scan now on its row. New files are picked up on the next scan, whether you start it by hand or on a schedule; see Scanning.

How file names become titles

Before any metadata source is asked, the scan names each game after its file:

• Anything in round or square brackets is removed — region tags like (USA) or (Europe), revision tags like (Rev 1), and dump tags like [!].
• Underscores and dots become spaces.
• A leading “The”, “A” or “An” is moved to the end for sorting, so The Legend of Zelda sorts under L.

So Super_Mario_World_(USA)_[!].sfc shows up as Super Mario World until a metadata source supplies the proper title.

Several copies of the same game

Files whose names are the same once the bracketed tags are removed become one game with several files. Tetris (World).gb and Tetris (Japan).gb in the same library are one Tetris, not two.

When a game has more than one file, Play runs the largest one. To make it run a particular copy, either keep only that file in the library’s folders, or — as an administrator — open the game’s page and use Unlink on the copies you don’t want in its Files list. Unlinking leaves the file on disk; it just stops counting as part of the game, and Relink puts it back.

If two genuinely different games end up merged because their names only differ inside brackets, rename one of the files so the part outside the brackets differs.

Zipped ROMs

Every games library also accepts .zip, .7z and .rar archives. Nothing is extracted to disk: the server sends the archive as it is, and the emulator unpacks it in the browser.

• Put one game in each archive. The emulator boots the first file inside the archive that belongs to the console, and that is also the file the metadata lookup uses.
• Keep each console’s archives in its own folder. Any games library that scans a folder picks up every archive in it, because an archive’s name says nothing about the console. An archive of SNES games that a Game Boy Advance library finds still appears on that library’s shelf, but holds nothing its emulator can run; Credenza logs a warning and can only look it up by name.
• Password-protected archives can’t be played, because the emulator can’t open them.

Other archive formats, such as .tar, are not picked up at all, because the emulator could not open them.

Multi-disc games

Every console Credenza supports today is cartridge-based, so there are no disc images or multi-disc games to organise.

Setting up ScreenScraper and IGDB

Box art, release year, publisher, developer, player count, rating, genres and a synopsis come from two sources. You can use either, both, or neither — games still scan and play without them, with a generated cover.

Source	How it identifies a game	What you need
ScreenScraper	By the ROM’s checksum, so clean dumps from known sets are recognised whatever the file is called, and it can tell hacks and bad dumps apart	Nothing to start with. Your own free screenscraper.fr account is optional and raises the daily quota
IGDB	By title, so it wants files named after the games	A Twitch application’s client id and secret; no daily quota

Both are set up at Settings → Server → Metadata, in the Games section.

ScreenScraper

Credenza comes with its own ScreenScraper developer account, so ScreenScraper works without any setup of your own.

1. Tick the ScreenScraper checkbox to switch it on, and press Save.
2. Optionally register at screenscraper.fr — it’s free — and add your ScreenScraper username and ScreenScraper password. It is worth doing: requests then count against your own daily quota, ScreenScraper reserves most of its capacity for signed-in accounts, and contributing to ScreenScraper raises your limits.

Once ScreenScraper is on, the panel under it shows your account’s limits and how many requests you’ve used today. Press Check account to refresh it. The daily quota resets at midnight, Paris time. When it runs out, Credenza stops asking ScreenScraper until then; to pick up games that went unmatched in the meantime, choose Refresh metadata on the library afterwards.

If you have a ScreenScraper developer account of your own, enter it under Use a developer account of your own and Credenza uses it instead.

IGDB

IGDB signs in through Twitch.

1. Register an application at dev.twitch.tv/console/apps. Any Twitch account can do this.
2. Paste its Twitch client id, and the Twitch client secret you get from New Secret on the application.
3. Tick the IGDB checkbox and press Save.

Which source wins

A source can only be switched on once its credentials are filled in (ScreenScraper’s come with Credenza). With both on, use the arrows beside each to rank them. Sources are asked in that order and the first one that has a game keeps it — its box art, its details and its rating. Nothing is mixed from the two.

Changing the order, or switching a source on or off, doesn’t re-match games already matched. To apply it to what’s already there, open the library’s menu at Settings → Server → Libraries and choose Refresh metadata.

Ratings keep each source’s own scale — ScreenScraper scores out of 20, IGDB out of 100 — and the game’s page always shows which, such as “16/20”.

Correcting a game

If a game was matched to the wrong title, or not matched at all, someone allowed to correct metadata can fix it by hand.

• Wrong match: open the ⋮ menu on the game’s tile or its page and choose Fix match….
• No match: games nobody could identify wait under Needs matching in an administrator’s sidebar, on the Games tab. An unmatched game’s page also shows Fix match… prominently. A dump that is in no checksum set will never be identified by a rescan, so naming it by hand is the way forward.

The picker searches every source you have switched on, not just the top-ranked one, and lets you type your own search. Once you choose a result, that game is only ever matched against the source you picked, so a higher-ranked source can’t quietly replace your choice later.

Refresh metadata on the same menu re-fetches one game’s details, and Edit details… lets you override its title or other fields yourself. See Fixing matches and Editing details for the full picture.