Adding ROMs

Games live in /storage/roms, one folder per system. archr-launcher only shows a system once its folder holds at least one file with an extension that system accepts.

How the card is laid out

The image writes three partitions in an MBR table:

STORAGE is only 32 MB inside the downloaded image and grows to fill the card on first boot. On a card with room for it, the first boot instead stops STORAGE at 8 GiB and makes a fourth partition, ARCHR_ROMS (exFAT), with the rest of the card. It is mounted on /storage/roms, so the games, saves and screenshots sit on a partition that Windows, macOS and Linux read. A card too small for both (16 GB or less) keeps the single STORAGE; 32 GB or larger is recommended. ARCHR_ROOT is marked as partition type 0xDA so desktop file managers do not offer to mount it.

Three ways to copy ROMs

1. Put the card in a computer

If the card has the ARCHR_ROMS partition, it shows up as a normal drive on Windows, macOS and Linux, with a folder per system. Eject the drive before you remove the card. A card made before this layout can be converted in Settings › Storage › ROMs on the PC: the device restarts, moves the ROMs, saves and BIOS and checks each folder before removing it from the old place (about 1 minute per GB; keep it on the charger). File names that exFAT does not accept, such as names with :, are renamed during the move, and the page lists them.

Otherwise the partition you want is STORAGE, and the folder you want is roms/. Linux mounts ext4 directly. Windows and macOS do not, so you need either Linux File Systems for Windows by Paragon, WSL with --mount, or an equivalent third-party driver.

2. SSH and SCP

Quicker than moving the card around. See SSH access.

scp ~/roms/snes/*.sfc root@<device-ip>:/storage/roms/snes/

3. Samba

Samba is off by default. Turn it on in archr-launcher under Settings › Network › Network services › File sharing (Samba). The ROM share is called games-roms and points at /storage/roms:

• Windows: open Explorer and type \\archr\games-roms, or use the IP address.
• macOS: Finder, Cmd-K, smb://archr.local/games-roms.
• Linux: your file manager's "Connect to server", smb://archr.local/games-roms.

The share accepts guests with no password, so only enable it on a network you trust. More detail in Samba.

A second card

If your console has a second card slot, ArchR mounts that card at /storage/games-external. By default, the second card is listed separately. Both cards show up in Settings › Storage (System card and Second card), with the filesystem, the space used and an Eject › link for the second one.

What happens next depends on the settings in that same page:

• By default, the card's ROM folder (<card>/roms, or the card root when there is no roms/) is published as /run/archr/roms2, and archr-launcher lists it next to /storage/roms: every system reads /storage/roms/<system> and <card>/<system>, each with its own gamelist and media. When the same game is on both, the first card wins. Inserting or removing the card updates the lists within a couple of seconds.
• Unified storage (system.merged.storage=1) instead combines the two cards with mergerfs at /storage/roms. It is off by default, applies immediately when the card is mounted, and uses the existing-path/most-free-space creation policy (epmfs) to decide where new files go.
• Mount automatically (system.automount, on by default) mounts the second card when it is inserted.

System folders

The list has 125 system entries. These are the ones people ask about most:

A few folder names catch people out:

• Mega Drive appears three times, as megadrive, genesis and megadrive-japan. They are separate entries in the list with the same extensions, so pick one and put everything there.
• The same duplication exists for nes and famicom, and for snes and sfc.
• ColecoVision reads from coleco, Odyssey 2 from odyssey, SuperGrafx from sgfx, Macintosh from mac, PC-8800 from pc88 and PC-9800 from pc98.
• Atari Lynx and Atari Jaguar use the long names atarilynx and atarijaguar, not lynx and jaguar.
• WonderSwan Color has its own folder, wonderswancolor.

ScummVM, Tools and the music player use configuration folders instead of a ROM folder: ScummVM looks in /storage/.config/scummvm/games, Tools in /storage/.config/modules and the music player in /storage/.config/gmu/playlists. The image viewer uses /storage/roms/screenshots.

The full list lives on the device in /usr/share/archr/systems.cfg (a copy in /storage/.config/archr/systems.cfg takes precedence), with the exact path and extensions for every entry.

Making the launcher see new games

New files are picked up without a manual rescan: when archr-launcher starts (it starts again every time you leave a game), it compares each system folder with its cache (paths, extensions and modification times) and recounts what changed. If a game you just copied does not show yet, restart the launcher with systemctl restart archr-launcher-session over SSH.

BIOS files

Place BIOS files under /storage/roms/bios, preserving each required relative path and filename; some systems require subfolders (for example neocd/ or keropi/). ArchR ships no BIOS files, that part is on you.

To verify your BIOS files, run archr-systems over SSH:

archr-systems

It walks /storage/roms/bios, compares each file against a table of known md5 sums and prints what is missing or does not match. archr-systems --filter psx narrows it to one system, and archr-systems --createReadme prints all filenames and checksums in its BIOS reference table.

Some common ones:

bios/scph5500.bin  scph5501.bin  scph5502.bin   PlayStation
bios/disksys.rom                                Famicom Disk System
bios/gba_bios.bin                               Game Boy Advance
bios/neogeo.zip                                 Neo Geo
bios/bios_CD_E.bin  bios_CD_U.bin  bios_CD_J.bin   Sega CD
bios/dc_boot.bin  dc_flash.bin                  Dreamcast
bios/sega_101.bin  mpr-17933.bin                Saturn
bios/bios7.bin  bios9.bin  firmware.bin         Nintendo DS
bios/panafz1.bin  panafz10.bin  goldstar.bin    3DO
bios/pcfx.rom                                   PC-FX

Compressed ROMs

Most libretro cores open .zip and .7z without unpacking them first. ArchR builds zlib-ng in zlib-compat mode, so every program on the system uses it in place of stock zlib.

For disc-based systems, .chd is worth the conversion: it is smaller than .bin/.cue and lossless. There is no chdman on the console, so convert on your computer:

chdman createcd -i game.cue -o game.chd

For PSP, .cso takes roughly half the space of .iso at a small CPU cost.

Keeping two machines in sync

Syncthing can mirror a folder between the console and your PC over the network. Once enabled, open http://archr.local:8384 in a browser. It is paused automatically while a game is running, so it does not compete for CPU. See Cloud sync.

Scraping artwork

archr-launcher includes a built-in ScreenScraper client under Settings › Games › Scrape artwork, plus per-game re-scraping on the Game Details screen (Y › Details › Scrape again). See Scraping.

Permissions

/storage is mounted rw,noatime. ROM files do not need a particular owner, emulators read them with ordinary file permissions and ArchR does not rewrite ownership on the partition.

If you delete the per-system folders by accident, they are recreated at boot. The list of directories is /usr/config/system-dirs.conf and the archr-automount service applies it with systemd-tmpfiles --create.