From aed958ccd1f64ce2429ce7f06a5e0efa7c3a0f61 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Thu, 22 Oct 2026 06:19:13 +0200 Subject: [PATCH] docs: document the game data filter --- scripts/generate_readme.py | 3 +++ scripts/generate_site.py | 5 ++++- wiki/advanced-usage.md | 33 +++++++++++++++++++++++++++++++++ wiki/testing-guide.md | 4 ++-- wiki/tools.md | 11 ++++++++++- wiki/verification-modes.md | 5 +++++ 6 files changed, 57 insertions(+), 4 deletions(-) diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index fd2ffd86..b0cd1e7a 100644 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -617,6 +617,9 @@ def generate_readme(db: dict, platforms_dir: str) -> str: "python scripts/generate_pack.py --platform retroarch --region us,eu,jp", "python scripts/generate_pack.py --platform retroarch --region us --one-per-slot", "", + "# Firmware only: the game data a list or a core names is left out, each file named", + "python scripts/generate_pack.py --platform emuelec --no-game-data", + "", "# List available emulators and systems", "python scripts/generate_pack.py --list-emulators", "python scripts/generate_pack.py --list-systems", diff --git a/scripts/generate_site.py b/scripts/generate_site.py index fb08e885..8060ca1f 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -5318,7 +5318,10 @@ everything or to choose systems, cores and regions, and `--system`, `--core`, [installer reference](wiki/installer.md#choosing-what-to-install)). From a clone of the repository, `python scripts/generate_pack.py --platform retroarch --region us` builds the same narrowing as a pack and `--required-only` the bare -minimum each core needs to start, and `--help` lists every way to build your own. +minimum each core needs to start. `--no-game-data`, for the pack and the +installer alike, keeps the firmware and leaves out the files a game reads +([details](wiki/advanced-usage.md#firmware-without-game-data)), and `--help` +lists every way to build your own. --- diff --git a/wiki/advanced-usage.md b/wiki/advanced-usage.md index f9374e5e..2780d730 100644 --- a/wiki/advanced-usage.md +++ b/wiki/advanced-usage.md @@ -235,6 +235,39 @@ visible. Variants compose with `--split`, `--target` and `--manifest`. +## Firmware without game data + +The firmware an emulator needs comes first. A platform list can also name the +files a game reads (EmuELEC lists the Doom WADs), and a core profile marks the +data of the games it runs `category: game_data`: MAME's software lists, the +RPG Maker run-time packages, a game engine's own files. `--no-game-data` +leaves both out and keeps the firmware: + +```bash +python scripts/generate_pack.py --platform emuelec --no-game-data +python scripts/generate_pack.py --platform emuelec --no-game-data --verify-packs +python scripts/verify.py --platform emuelec --no-game-data +``` + +A platform entry is game data when the only cores of the platform that read it +read it as game data (see [Verification modes](verification-modes.md) for how +entries are categorized). An entry that some core reads as firmware stays. +The build names every file it left out and why: the platform's entries with +the cores that read them as game data, then each core with the game data +files its profile declares. + +The pack is named `EmuELEC_4.8_NoGameData_BIOS_Pack.zip` and its README says +it was narrowed. `verify.py --no-game-data` reports on the same file set, and +`--verify-packs --no-game-data` checks the pack against it. The flag composes +with `--region`, `--target`, `--required-only`, `--source`, `--one-per-slot`, +`--split`, `--system` and `--manifest` +(`install/emuelec_nogamedata.json`). It needs `--platform` or `--all` and is +refused with `--emulator`, `--system` alone, `--from-md5` and +`--all-variants`: game data is categorized against a platform's list and the +cores it runs. The installer's `--no-game-data` makes the same cut from the +full manifest, where each game data file carries `"category": "game_data"`. + + ## Hardware target filtering ### What targets are diff --git a/wiki/testing-guide.md b/wiki/testing-guide.md index 61aeecdf..4861e474 100644 --- a/wiki/testing-guide.md +++ b/wiki/testing-guide.md @@ -39,8 +39,8 @@ Every module in `tests/`, by the area it guards. |------|----------|---------| | Core regression suites | synthetic | `test_e2e`, `test_audit_regressions`, `test_tool_messages` | | File resolution and identity | synthetic + collection | `test_adler32_resolution`, `test_agnostic_scan`, `test_agnostic_scan_mode`, `test_agnostic_scope`, `test_agnostic_substitute`, `test_archive_choice`, `test_bios_companions`, `test_bundled_identity`, `test_casefold_cache`, `test_db_aliases`, `test_declared_names`, `test_derivations`, `test_directory_entries`, `test_extra_identity`, `test_foreign_tree`, `test_foreign_tree_names`, `test_frontend_digest`, `test_game_data_homonyms`, `test_hashing`, `test_identity`, `test_md5_pack_context`, `test_name_tiebreak`, `test_nec_filing`, `test_owner_resolution`, `test_path_suffix`, `test_resolution_evidence`, `test_sega_filing`, `test_shipped_content`, `test_twin_declarations`, `test_validated_choice`, `test_variant_choice`, `test_variant_identity`, `test_zipped_member` | -| Verification, cross-reference and profile checks | synthetic + profiles | `test_case_insensitive_platforms`, `test_checks_have_values`, `test_core_file_fills_declaration`, `test_core_size_refusal`, `test_cross_reference_sources`, `test_crypto_aes`, `test_crypto_unique_data`, `test_crypto_verify`, `test_file_consumers`, `test_fileless_audit`, `test_flycast_layout`, `test_gap_settlement`, `test_hidden_extras`, `test_launcher_aliases`, `test_launcher_layer`, `test_native_mode`, `test_no_case_collisions`, `test_path_conflict_status`, `test_path_null_copies`, `test_profile_checks`, `test_profile_repositories`, `test_romm_hash_rule`, `test_shared_groups`, `test_standalone_links`, `test_standalone_mode`, `test_undeclared_dedup`, `test_unplaced_extras`, `test_validation_scope`, `test_verify_all_dir`, `test_verify_emulator_evidence`, `test_verify_listing`, `test_verify_pack_choice`, `test_verify_release_asset` | -| Packs and manifests | synthetic + real packs | `test_artifact_lock`, `test_atomic_artifacts`, `test_batocera_cores`, `test_deterministic_zip`, `test_emulator_pack_counts`, `test_finalize_pack_names`, `test_large_file_cache`, `test_libretro_layout`, `test_manifest_entry`, `test_minui_platform`, `test_pack_conformance_dirs`, `test_pack_core_extras`, `test_pack_counts`, `test_pack_destinations`, `test_pack_failures`, `test_pack_file_names`, `test_pack_grouping`, `test_pack_integrity`, `test_pack_member_identity`, `test_pack_readme`, `test_platform_inheritance`, `test_platform_keys`, `test_required_only_archives`, `test_required_only_twins`, `test_split_extras`, `test_split_names`, `test_split_pack`, `test_system_pack_extras`, `test_system_pack_parity`, `test_torrentzip`, `test_which_pack` | +| Verification, cross-reference and profile checks | synthetic + profiles | `test_case_insensitive_platforms`, `test_checks_have_values`, `test_core_file_fills_declaration`, `test_core_size_refusal`, `test_cross_reference_sources`, `test_entry_categories`, `test_crypto_aes`, `test_crypto_unique_data`, `test_crypto_verify`, `test_file_consumers`, `test_fileless_audit`, `test_flycast_layout`, `test_gap_settlement`, `test_hidden_extras`, `test_launcher_aliases`, `test_launcher_layer`, `test_native_mode`, `test_no_case_collisions`, `test_path_conflict_status`, `test_path_null_copies`, `test_profile_checks`, `test_profile_repositories`, `test_romm_hash_rule`, `test_shared_groups`, `test_standalone_links`, `test_standalone_mode`, `test_undeclared_dedup`, `test_unplaced_extras`, `test_validation_scope`, `test_verify_all_dir`, `test_verify_emulator_evidence`, `test_verify_listing`, `test_verify_pack_choice`, `test_verify_release_asset` | +| Packs and manifests | synthetic + real packs | `test_artifact_lock`, `test_atomic_artifacts`, `test_batocera_cores`, `test_deterministic_zip`, `test_emulator_pack_counts`, `test_finalize_pack_names`, `test_large_file_cache`, `test_libretro_layout`, `test_manifest_entry`, `test_minui_platform`, `test_no_game_data`, `test_pack_conformance_dirs`, `test_pack_core_extras`, `test_pack_counts`, `test_pack_destinations`, `test_pack_failures`, `test_pack_file_names`, `test_pack_grouping`, `test_pack_integrity`, `test_pack_member_identity`, `test_pack_readme`, `test_platform_inheritance`, `test_platform_keys`, `test_required_only_archives`, `test_required_only_twins`, `test_split_extras`, `test_split_names`, `test_split_pack`, `test_system_pack_extras`, `test_system_pack_parity`, `test_torrentzip`, `test_which_pack` | | Slots and regions | synthetic + profiles | `test_region`, `test_region_agnostic_scan`, `test_region_groups`, `test_region_held`, `test_region_platform_index`, `test_region_required_only`, `test_slot`, `test_slots`, `test_slots_shipped_file` | | Hardware targets and systems | synthetic + target files | `test_extract_targets`, `test_lakka_targets`, `test_libretro_slugs`, `test_system_ids`, `test_system_selection`, `test_target_names`, `test_target_scrapers`, `test_target_systems`, `test_target_verify` | | Installer and downloads | loopback server | `test_check_release`, `test_download`, `test_install`, `test_install_cores`, `test_install_experience`, `test_install_selection` | diff --git a/wiki/tools.md b/wiki/tools.md index 29478e40..ce21306b 100644 --- a/wiki/tools.md +++ b/wiki/tools.md @@ -125,6 +125,7 @@ python scripts/verify.py --system atari-lynx # single system python scripts/verify.py --platform batocera --system psx # one system of a platform pack python scripts/verify.py --platform retroarch --target switch # filter by hardware python scripts/verify.py --platform recalbox --region us # regional priority list +python scripts/verify.py --platform emuelec --no-game-data # the firmware-only pack, game data named python scripts/verify.py --all --destinations tmp/paths.json # also write the paths each pack holds python scripts/verify.py --all --offline # a release asset the cache lacks counts missing, as in an offline build python scripts/verify.py --list-emulators # list all emulators @@ -153,7 +154,9 @@ Verification modes per platform: Full details and severity mapping: [verification modes](verification-modes.md). `--region` narrows the report to the file set a regional pack would carry, and a mode that cannot apply it refuses it rather than ignoring it: see -[region filtering](advanced-usage.md#region-filtering). +[region filtering](advanced-usage.md#region-filtering). `--no-game-data` narrows +it to the pack built with the same flag and names what it left out. It needs +`--platform` or `--all`. `--db`, `--platforms-dir` and `--emulators-dir` point the run at another database or source tree, which is how the tests drive it against fixtures. @@ -173,6 +176,7 @@ python scripts/generate_pack.py --system atari-lynx python scripts/generate_pack.py --platform retroarch --system sony-playstation python scripts/generate_pack.py --platform batocera --system psx python scripts/generate_pack.py --platform batocera --required-only +python scripts/generate_pack.py --platform emuelec --no-game-data python scripts/generate_pack.py --platform retroarch --split python scripts/generate_pack.py --platform retroarch --split --group-by manufacturer @@ -232,6 +236,11 @@ own verification mode ([discrepancy detection](verification-modes.md#discrepancy takes our ids only. - `--required-only`: exclude optional files and the data directories declared `required: false`, keep only required +- `--no-game-data`: firmware only. Leaves out the platform's entries + categorized game data and the cores' `category: game_data` files, and names + each one. Tags the pack `_NoGameData`. `verify.py --no-game-data` and + `--verify-packs --no-game-data` check the same file set + ([details](advanced-usage.md#firmware-without-game-data)) - `--split`: generate one ZIP per system instead of one big pack - `--split --group-by manufacturer`: group split packs by manufacturer (Sony, Nintendo, Sega...) - `--from-md5`: look up a hash in the database, or build a custom pack with diff --git a/wiki/verification-modes.md b/wiki/verification-modes.md index e81e3091..f888698d 100644 --- a/wiki/verification-modes.md +++ b/wiki/verification-modes.md @@ -299,6 +299,11 @@ pack errors. A core the platform names that has no profile yet makes nothing unr The same goes for a system none of the examined cores emulates: in both cases the absence of a reader proves nothing. +The same category filters: `--no-game-data` builds, verifies and installs the +firmware without the game data, and the install manifest marks each game data +file `"category": "game_data"` +([details](advanced-usage.md#firmware-without-game-data)). + ## File resolution chain