mirror of
https://github.com/Abdess/retroarch_system.git
synced 2026-04-15 21:32:32 -05:00
docs: add wiki pages for all audiences, fix .old.yml leak
9 new wiki pages: getting-started, faq, troubleshooting, advanced-usage, verification-modes, adding-a-platform, adding-a-scraper, testing-guide, release-process. Updated architecture.md with mermaid diagrams, tools.md with full pipeline and target/exporter sections, profiling.md with missing fields, index.md with glossary and nav links. Expanded CONTRIBUTING.md from stub to full contributor guide. Filter .old.yml from load_emulator_profiles, generate_db alias collection, and generate_readme counts. Fix BizHawk sha1 mode in tools.md, fix RetroPie path, fix export_truth.py typos.
This commit is contained in:
Abdessamad Derraz
243
wiki/troubleshooting.md
Normal file
243
wiki/troubleshooting.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Troubleshooting - RetroBIOS
|
||||
|
||||
Diagnosis guide organized by symptom. Each section describes what to check and how to fix it.
|
||||
|
||||
## Game won't start / black screen
|
||||
|
||||
Most launch failures are caused by a missing or incorrect BIOS file.
|
||||
|
||||
**Check if the BIOS exists:**
|
||||
|
||||
```bash
|
||||
python scripts/verify.py --platform retroarch --verbose
|
||||
python scripts/verify.py --system sony-playstation
|
||||
```
|
||||
|
||||
Look for `MISSING` entries in the output. A missing required BIOS means the core
|
||||
cannot start games for that system at all.
|
||||
|
||||
**Check if the hash matches:**
|
||||
|
||||
Look for `HASH_MISMATCH` in the verify output. This means the file exists but
|
||||
contains different data than expected. Common causes:
|
||||
|
||||
- Wrong region (a PAL BIOS instead of NTSC, or vice versa)
|
||||
- Wrong hardware revision (e.g. SCPH-5501 vs SCPH-1001 for PlayStation)
|
||||
- Corrupted download
|
||||
|
||||
Each system page on the site lists the expected hashes. Compare your file's
|
||||
MD5 or SHA1 against those values.
|
||||
|
||||
**Wrong region BIOS:**
|
||||
|
||||
Some cores require region-specific BIOS files. A Japanese BIOS won't boot
|
||||
North American games on cores that enforce region matching. Check the emulator
|
||||
profile for your core to see which regions are supported and which files
|
||||
correspond to each.
|
||||
|
||||
## BIOS not found by emulator
|
||||
|
||||
The file exists on disk, but the emulator reports it as missing.
|
||||
|
||||
**Wrong directory:**
|
||||
|
||||
Each platform expects BIOS files in a specific base directory:
|
||||
|
||||
- RetroArch, Lakka: `system/` inside the RetroArch directory
|
||||
- Batocera: `/userdata/bios/`
|
||||
- Recalbox: `/recalbox/share/bios/`
|
||||
- RetroPie: `~/RetroPie/BIOS/`
|
||||
|
||||
Some cores expect files in subdirectories (e.g. `dc/` for Dreamcast, `pcsx2/bios/`
|
||||
for PlayStation 2). Check the `path:` field in the emulator profile for the exact
|
||||
expected location relative to the base directory.
|
||||
|
||||
**Wrong filename:**
|
||||
|
||||
Cores match BIOS files by exact filename. If a core expects `scph5501.bin` and your
|
||||
file is named `SCPH-5501.BIN`, it won't be found on platforms that do exact name matching.
|
||||
|
||||
Check the emulator profile for the expected filename and any aliases listed under
|
||||
`aliases:`. Aliases are alternative names that the core also accepts.
|
||||
|
||||
**Case sensitivity:**
|
||||
|
||||
Linux filesystems are case-sensitive. A file named `Bios.ROM` won't match a lookup
|
||||
for `bios.rom`. Windows and macOS are case-insensitive by default, so the same
|
||||
file works there but fails on Linux.
|
||||
|
||||
Batocera's verification uses `casefold()` for case-insensitive matching, but
|
||||
the actual emulator may still require exact case. When in doubt, use the exact
|
||||
filename from the emulator profile.
|
||||
|
||||
## Hash mismatch / UNTESTED
|
||||
|
||||
`verify.py` reports `HASH_MISMATCH` or `UNTESTED` for a file.
|
||||
|
||||
**HASH_MISMATCH:**
|
||||
|
||||
The file exists and was hashed, but the computed hash doesn't match any expected
|
||||
value. This means you have a different version of the file than what the platform
|
||||
or emulator expects.
|
||||
|
||||
To find the correct version, check the system page on the site. It lists every
|
||||
known BIOS file with its expected MD5 and SHA1.
|
||||
|
||||
**UNTESTED:**
|
||||
|
||||
On existence-only platforms (RetroArch, Lakka, RetroPie), the file is present
|
||||
but its hash was not verified against a known value. The platform itself only
|
||||
checks that the file exists. The `--verbose` flag shows ground truth data from
|
||||
emulator profiles, which can confirm whether the file's hash is actually correct.
|
||||
|
||||
**The .variants/ directory:**
|
||||
|
||||
When multiple versions of the same BIOS exist (different revisions, regions, or
|
||||
dumps), the primary version lives in the main directory and alternatives live in
|
||||
`.variants/`. `verify.py` checks the primary file first, then falls back to
|
||||
variants when resolving by hash.
|
||||
|
||||
If your file matches a variant hash but not the primary, it's a valid BIOS --
|
||||
just not the preferred version. Some cores accept multiple versions.
|
||||
|
||||
## Pack is missing files
|
||||
|
||||
A generated pack doesn't contain all the files you expected.
|
||||
|
||||
**Severity levels:**
|
||||
|
||||
`verify.py` assigns a severity to each issue. Not all missing files are equally
|
||||
important:
|
||||
|
||||
| Severity | Meaning | Action needed |
|
||||
|----------|---------|---------------|
|
||||
| CRITICAL | Required file missing or hash mismatch on MD5 platforms | Must fix. Core won't function. |
|
||||
| WARNING | Optional file missing, or hash mismatch on existence platforms | Core works but with reduced functionality. |
|
||||
| INFO | Optional file missing on existence-only platforms, or HLE fallback available | Core works fine, BIOS improves accuracy. |
|
||||
| OK | File present and verified | No action needed. |
|
||||
|
||||
Focus on CRITICAL issues first. WARNING files improve the experience but aren't
|
||||
strictly necessary. INFO files are nice to have.
|
||||
|
||||
**Large files (over 50 MB):**
|
||||
|
||||
Files like PS3UPDAT.PUP, PSVUPDAT.PUP, and Switch firmware are too large for the
|
||||
git repository. They are stored as GitHub release assets under the `large-files`
|
||||
release and downloaded at build time.
|
||||
|
||||
If a pack build fails to include these, check your network connection. In offline
|
||||
mode (`--offline`), large files are only included if already cached locally in
|
||||
`.cache/large/`.
|
||||
|
||||
**Data directories:**
|
||||
|
||||
Some cores need entire directory trees rather than individual files (e.g. Dolphin's
|
||||
`Sys/` directory, PPSSPP's `assets/`). These are fetched by `refresh_data_dirs.py`
|
||||
from upstream repositories.
|
||||
|
||||
In offline mode, data directories are only included if already cached in `data/`.
|
||||
Run `python scripts/refresh_data_dirs.py` to fetch them.
|
||||
|
||||
## verify.py reports errors
|
||||
|
||||
How to read and interpret `verify.py` output.
|
||||
|
||||
**Status codes:**
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `ok` | File present, hash matches (or existence check passed) |
|
||||
| `untested` | File present, hash not confirmed (existence-only platforms) |
|
||||
| `missing` | File not found in the repository |
|
||||
| `hash_mismatch` | File found but hash doesn't match expected value |
|
||||
| `size_mismatch` | File found but size doesn't match what the emulator expects |
|
||||
|
||||
**Reading the output:**
|
||||
|
||||
Each line shows the file path, its status, and severity. In verbose mode, ground
|
||||
truth data from emulator profiles is appended, showing which cores reference the
|
||||
file and what validations they perform.
|
||||
|
||||
```
|
||||
scph5501.bin ok [OK]
|
||||
dc_boot.bin missing [CRITICAL]
|
||||
gba_bios.bin untested [WARNING]
|
||||
```
|
||||
|
||||
**Cross-reference section:**
|
||||
|
||||
After per-file results, `verify.py` prints a cross-reference report. This lists
|
||||
files that emulator cores need but that the platform YAML doesn't declare. These
|
||||
files are still included in packs automatically, but the report helps identify
|
||||
gaps in platform coverage data.
|
||||
|
||||
The cross-reference uses `resolve_platform_cores()` to determine which emulator
|
||||
profiles are relevant for each platform, then checks whether each profile's files
|
||||
appear in the platform config.
|
||||
|
||||
**Filtering output:**
|
||||
|
||||
```bash
|
||||
# By platform
|
||||
python scripts/verify.py --platform batocera
|
||||
|
||||
# By emulator core
|
||||
python scripts/verify.py --emulator beetle_psx
|
||||
|
||||
# By system
|
||||
python scripts/verify.py --system sony-playstation
|
||||
|
||||
# By hardware target
|
||||
python scripts/verify.py --platform retroarch --target switch
|
||||
|
||||
# JSON for scripted processing
|
||||
python scripts/verify.py --platform retroarch --json
|
||||
```
|
||||
|
||||
## Installation script fails
|
||||
|
||||
Problems with `install.py`, `install.sh`, or `download.sh`.
|
||||
|
||||
**Network issues:**
|
||||
|
||||
The installer downloads packs from GitHub releases. If the download fails:
|
||||
|
||||
- Check your internet connection
|
||||
- Verify that `https://github.com` is reachable
|
||||
- If behind a proxy, set `HTTPS_PROXY` in your environment
|
||||
- Try again later if GitHub is experiencing issues
|
||||
|
||||
**Permission denied:**
|
||||
|
||||
The installer needs write access to the target directory.
|
||||
|
||||
- On Linux/macOS: check directory ownership (`ls -la`) and run with appropriate
|
||||
permissions. Avoid running as root unless the target directory requires it.
|
||||
- On Windows: run PowerShell as Administrator if installing to a protected directory.
|
||||
|
||||
**Platform not detected:**
|
||||
|
||||
`install.py` auto-detects your platform by checking for known config files. If
|
||||
detection fails, specify the platform manually:
|
||||
|
||||
```bash
|
||||
python install.py --platform retroarch --dest ~/RetroArch/system/
|
||||
python install.py --platform batocera --dest /userdata/bios/
|
||||
```
|
||||
|
||||
Use `python install.py --help` to see all available platforms and options.
|
||||
|
||||
**Pack not found in release:**
|
||||
|
||||
If the installer reports that no pack exists for your platform, check available
|
||||
releases:
|
||||
|
||||
```bash
|
||||
python scripts/download.py --list
|
||||
# or
|
||||
bash scripts/download.sh --list
|
||||
```
|
||||
|
||||
Some platforms share packs (Lakka uses the RetroArch pack). The installer handles
|
||||
this mapping automatically, but if you're downloading manually, check which pack
|
||||
name corresponds to your platform.
|
||||
Reference in New Issue
Block a user