Abdessamad Derraz
123d698e43
generate_site.py writes the Starlight project in website/ and nothing else: mkdocs.yml, the MkDocs hooks, theme overrides and stylesheet go, and the wiki is written in Starlight's syntax. Both workflows set up Node with the official actions/setup-node pinned by commit, run npm ci from the committed lockfile, build with the strict link validator and check the result with validate_site.py. The search weighs a page by what it answers: Start here pages first, a system page's cards and file names before a guide citing them, deep guides, launchers, aliases and frozen copies after. Status badges, hash blocks and the export change lists leave the index. The ranking sits at the centre of a range where the 13 queries of search_gate.py all answer, in the search box itself. 839 pages, every URL and 45,611 ids match the MkDocs build. The tests read the Starlight content and syntax.
8.4 KiB
level, order
| level | order |
|---|---|
| reference | 120 |
Technical questions
Answers to "how do you know?" questions: how a file is identified, why one BIOS has several fingerprints, why some files are not BIOS, and which MAME version an arcade set belongs to. Each answer gives a real file as its example, so you can check it on the system pages. Questions asked before installing are in the FAQ.
What's a hash/checksum?
A hash is a fixed-length fingerprint computed from a file's contents. If even one byte differs, the hash changes completely. Every file in the database carries these:
| Type | Length | Example | Used for |
|---|---|---|---|
| SHA1 | 40 hex chars | 10155d8d6e6e832d8ea1571511e40dfb15fede05 |
database primary key, BizHawk, installer downloads |
| MD5 | 32 hex chars | 924e392ed05558ffdb115408c263dccf |
most platform verification |
| SHA256 | 64 hex chars | 9a1c... |
emulator profiles whose upstream publishes SHA256 |
| CRC32 | 8 hex chars | 2F468B96 |
ROM-set matching, arcade DATs |
Emulator profiles add Adler-32 where the code checks it, which is how Dolphin
checks its DSP ROMs (dsp_rom.bin and dsp_coef.bin, hashed byte-swapped).
IPL.bin is not one of them: Dolphin loads it without a hash check.
Verification uses whichever one the platform itself uses: MD5 for Batocera, RetroBat, Recalbox, EmuDeck, RetroDECK, RomM, ROCKNIX, KNULLI, AmberELEC, EmuELEC and MiSTer FPGA, SHA1 for BizHawk, and nothing at all for RetroArch, Lakka and RetroPie, which only check that the file exists.
How is a missing file ranked?
In verification output, missing required files appear as CRITICAL or WARNING depending on the platform. Missing optional files appear as WARNING or INFO.
When a core has HLE support, the verification tool lowers the severity of a missing BIOS to INFO. The file is still included in packs because the real BIOS gives better results. The full table is the severity matrix.
Why are there multiple hashes for the same file?
Two main reasons:
- Regional variants. The same filename (e.g.,
IPL.binfor GameCube) exists in different versions for USA, Europe, and Japan. Each region has a different hash. - Revision differences. Console manufacturers released updated BIOS versions over time. A PlayStation SCPH-5501 BIOS differs from a SCPH-7001.
Platforms that verify by MD5 accept specific hashes. If yours doesn't match any known hash, it may be a bad dump or an uncommon revision.
A filename is never allowed to stand in for a declared hash. When a file entry
carries a hash, resolution matches on content and reports hash_mismatch if the
only same-named copy disagrees. What happens next depends on the platform: an
MD5 or SHA1 platform would report the file as not the expected one, so the pack
omits it and says why,
while an existence platform only checks presence, so the file ships and the divergence
is reported instead.
Why are there files that aren't BIOS?
A file earns its place when an emulator loads it from disk and does not bundle it. That covers actual BIOS ROMs, console firmware, arcade BIOS sets, and also game data, such as doom.wad for the PrBoom core (category: game_data in emulators/prboom.yml) or soundfonts for EasyRPG.
This follows the platforms themselves: EmuELEC lists Diablo's diabdat.mpq in its BIOS list (platforms/emuelec.yml, destination ports/diablo/diabdat.mpq), and libretro declares such files in the firmware field of its core info. The word "BIOS" is their vocabulary for "external file the emulator needs". Files are tagged by category (bios, game_data, bios_zip) in the emulator profiles, so the distinction stays visible.
A file the emulator carries inside itself is not one of them. PrBoom compiles its engine data prboom.wad into the core from src/prboom_wad_data.h and never opens it on disk (emulators/prboom.yml, src/d_main.c:1449-1465), so no PrBoom pack needs it.
Why is a file the emulator reads not in the pack?
A pack brings what the user has to obtain. A file the emulator installs itself
(a font, a shader, a game database, a free replacement BIOS) is already on the
machine once the emulator is installed, so the pack leaves it out. This is
decided per build and per platform: the PPSSPP standalone release ships its
assets/ folder, the PPSSPP libretro core does not, so RetroArch packs carry
those files and a standalone PPSSPP pack does not. When a platform's own
package installs data beside a core (Batocera with blueMSX), that platform's
pack leaves it out too. The emulator's page marks these files as installed with
the emulator.
What's HLE?
HLE (high-level emulation) is code inside an emulator that does the BIOS's job,
so some games start without the file. Beetle PSX, for one, carries OpenBIOS for
that (emulators/beetle_psx.yml, notes). The real file still ships, because
the stand-in is not perfect: some games glitch or do not start.
A profile entry records it as hle_fallback: true. That flag does not decide
required: 13 of the 778 entries that carry it are required, among them Beetle
PSX's three region BIOS. Verification reports a missing hle_fallback file at
INFO either way.
How often are packs updated?
The platforms' own lists (libretro's System.dat, batocera-systems and the others) are read again by hand, and the difference is reviewed before it lands. A release follows when files are added or profiles change.
Are these files verified against original hardware dumps?
No. The hashes here document what
emulator code loads and accepts, read from the source. When several
revisions or regions pass, all of them are kept (.variants/ in the
repository, per-emulator pages list each one), and the pack ships the
variant satisfying the most checks, logging any conflict it cannot
resolve.
Whether a file byte-matches the original hardware ROM is a different question, answered by dump-preservation catalogs such as No-Intro, Redump, and TOSEC, not by emulator code. The collection is cross-referenced against their DATs: files matching a catalog entry carry a verified dump badge on the system pages, and catalog entries absent from the collection are tracked as acquisition targets. When the two views differ, this project follows the code, because that is what decides whether your emulator boots.
The dump provenance page has the current coverage per catalog and the full list of catalogued dumps still missing.
Which MAME version do the arcade BIOS sets match?
Arcade BIOS sets are coupled to the romset version, so there is one
profile per MAME core generation: MAME 2000 (0.37b5), MAME 2003 (0.78),
MAME 2003-Plus, MAME 2009 (0.135u4), MAME 2010 (0.139), MAME 2015
(0.160), MAME 2016 (0.174), and current MAME (0.289), each read from that
version's own source tree, because the BIOS root sets differ between
versions. Derivatives and ports carry their own profiles on top of those
generations: mamearcade, mamemess, mame2003_midway, the three
mame4droid drops, advancemame, groovymame and hbmame. Recalbox
compiles two MAME versions of its own, 0.258 and 0.278, profiled as
mame0258 and mame0278. The pack
ships the sets matching the core you run, and a generic unversioned arcade
pack cannot do that.
Why does my verification report say UNTESTED?
untested means the file exists on disk but its hash does not match the expected value. This happens on MD5 and SHA1 platforms (Batocera, Recalbox, BizHawk, ROCKNIX, MiSTer FPGA, and the rest) when the file is present but contains different data than what the platform declares.
On existence-mode platforms (RetroArch, Lakka, RetroPie, MinUI, NextUI, MyMinUI), files are never untested because the platform only checks presence, not content. Those files show as ok if present, whatever they contain.
Running verify.py --emulator <core> --verbose shows the emulator-level ground truth, which can confirm whether the file's hash matches what the source code expects. The platform report applies the same check on its own: verify.py --platform retroarch prints a DISCREPANCY line for every file the platform accepts and a profiled emulator rejects.
It reaches only as far as the profiles do. Files no profile states a value for are platform-only, and nothing can be said about their content. The footer of the platform report gives that ratio as Ground truth: N/M files have emulator validation.
:::tip[Next]
- Reference index, every reference page in one list
- For contributors: How to contribute :::