From 7722e96f5aafeb8a54a879895bb84d51b80d5f6c Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Thu, 5 Nov 2026 12:06:17 +0100 Subject: [PATCH] docs: describe each core without other profiles Notes compared a core with another profile of this directory (unlike beetle_pce, unlike the other engines in this directory), which means nothing once a profile is read alone, and shouted NOT, ALL and MUST. The facts stay, the comparisons and capitals go. Comparisons with a core's own upstream remain. --- emulators/corsixth.yml | 2 +- emulators/doukutsu_rs.yml | 2 +- emulators/frodo.yml | 2 +- emulators/fuse.yml | 6 +++--- emulators/idtech4a++.yml | 3 +-- emulators/ioquake3.yml | 2 +- emulators/mame2009.yml | 3 +-- emulators/mednafen_pce_fast.yml | 4 ++-- emulators/minivmac.yml | 2 +- emulators/opentyrian.yml | 6 +++--- emulators/parallel_n64.yml | 3 +-- emulators/pokemini.yml | 2 +- emulators/rvvm.yml | 2 +- emulators/scummvm.yml | 4 ++-- emulators/sdlpop.yml | 5 ++--- emulators/splitwolf.yml | 2 +- emulators/stonesoup.yml | 2 +- emulators/vice.yml | 2 +- emulators/vice_x64.yml | 2 +- emulators/vice_x64sc.yml | 2 +- emulators/x64sdl.yml | 5 ++--- tests/test_audit_regressions.py | 23 +++++++++++++++++++++++ 22 files changed, 52 insertions(+), 34 deletions(-) diff --git a/emulators/corsixth.yml b/emulators/corsixth.yml index e5a4f5009..019755a9d 100644 --- a/emulators/corsixth.yml +++ b/emulators/corsixth.yml @@ -28,7 +28,7 @@ notes: | paths (:1473-1491) looking for a folder that passes App:isThemeHospitalPath, which demands three subdirectories named data, levels and qdata (:1435-1447). - 2. Once a candidate is accepted, three sentinel files MUST exist + 2. Once a candidate is accepted, three sentinel files must exist (:1523-1525): DATA/VBlk-0.tab LEVELS/Level.L1 diff --git a/emulators/doukutsu_rs.yml b/emulators/doukutsu_rs.yml index 149a5172c..868ac3cc5 100644 --- a/emulators/doukutsu_rs.yml +++ b/emulators/doukutsu_rs.yml @@ -21,7 +21,7 @@ systems: # (Doukutsu Monogatari) engine in Rust, ported to libretro by Dr. Glaucous. # It plays the original freeware Cave Story and Cave Story+ (Steam/Switch). # -# The core does NOT use RetroArch's system directory for any BIOS or firmware. +# The core does not use RetroArch's system directory for any BIOS or firmware. # get_system_directory() is defined in libretro.rs:1255 but never called by # the core (the import is commented out in core.rs:28). # diff --git a/emulators/frodo.yml b/emulators/frodo.yml index 6390fb90b..708fdd18c 100644 --- a/emulators/frodo.yml +++ b/emulators/frodo.yml @@ -35,7 +35,7 @@ notes: | 3. "Char ROM" (4096 bytes, CHAR_ROM_SIZE 0x1000) -> TheC64->Char 4. "1541 ROM" (16384 bytes, DRIVE_ROM_SIZE 0x4000) -> TheC64->ROM1541 - The core does NOT construct paths relative to retro_system_directory for + The core does not construct paths relative to retro_system_directory for ROM loading. The system directory variable is fetched in retro_init() but only used for the save directory fallback, not for ROM path construction. DATADIR defaults to "" (empty string) when not defined by the build diff --git a/emulators/fuse.yml b/emulators/fuse.yml index ec567ca64..7e426b0d8 100644 --- a/emulators/fuse.yml +++ b/emulators/fuse.yml @@ -28,7 +28,7 @@ notes: | {system_dir}/fuse/{rom_filename} (src/compat/file.c:160-175). Embedded ROMs cover 48K-family, 128K, +2, +3, +3e, SE, TC2048, TC2068. - Pentagon, Scorpion, and peripheral ROMs are NOT embedded and must be + Pentagon, Scorpion, and peripheral ROMs are not embedded and must be placed in {system_dir}/fuse/ by the user. Default ROM filenames are set in fuse/settings.c:209-260. Each machine @@ -244,7 +244,7 @@ files: note: "Timex TC2068 ROM 1 (EXROM). Also used for TS2068. Embedded in core." source_ref: "fuse/settings.c:262, fuse/settings.c:264, fuse/machines/tc2068.c:141" - # -- External ROMs (NOT embedded, must be in {system_dir}/fuse/) -- + # -- External ROMs (not embedded, must be in {system_dir}/fuse/) -- # Pentagon family - name: "fuse/128p-0.rom" @@ -441,7 +441,7 @@ platform_details: plus3-0/1/2/3.rom, plus3e-0/1/2/3.rom, se-0.rom, se-1.rom, tc2048.rom, tc2068-0.rom, tc2068-1.rom. disciple.rom, plusd.rom, speccyboot-1.4.rom are present in the repo - fuse/roms/ directory but NOT in mem_entries[], so they are loaded + fuse/roms/ directory but not in mem_entries[], so they are loaded from the filesystem only. machine_rom_map: diff --git a/emulators/idtech4a++.yml b/emulators/idtech4a++.yml index 25130e05c..6e329f943 100644 --- a/emulators/idtech4a++.yml +++ b/emulators/idtech4a++.yml @@ -289,8 +289,7 @@ files: directory (Q3E/src/main/jni/ecwolf/src/wl_main.cpp:1294-1307). Failing to open it ends the process with "Could not open ecwolf.pk3!". It holds the IWADINFO rules that identify which Wolfenstein data set is present, the palettes and the actor definitions. This build - reads it from disk after extraction, unlike the libretro core which - compiles it in. + reads it from disk after extraction. source_ref: "Q3E/src/main/jni/ecwolf/src/version.h:12, Q3E/src/main/jni/ecwolf/src/wl_iwad.cpp:604, Q3E/src/main/java/com/n0n3m4/q3e/Q3EPatchResourceManager.java:186-195" - name: glprogs.pk4 diff --git a/emulators/ioquake3.yml b/emulators/ioquake3.yml index 58020f253..2521fbca3 100644 --- a/emulators/ioquake3.yml +++ b/emulators/ioquake3.yml @@ -24,7 +24,7 @@ notes: | Loaded paks are matched against hardcoded unsigned 32-bit checksums (code/qcommon/files.c:178-198: pak_checksums[], missionpak_checksums[]). - These are NOT MD5 / SHA1 / CRC32 of the file. They are id's own custom + These are not MD5 / SHA1 / CRC32 of the file. They are id's own custom pak checksum (sum of each lump CRC, see FS_LoadZipFile). A mismatch prints "WARNING: baseq3/pak0.pk3 is present but its checksum (%u) is not correct" (code/qcommon/files.c:3574) and keeps running: the loader diff --git a/emulators/mame2009.yml b/emulators/mame2009.yml index e6d3dfe33..6e25454d4 100644 --- a/emulators/mame2009.yml +++ b/emulators/mame2009.yml @@ -52,8 +52,7 @@ notes: | Artwork in system_dir/mame2009/artwork/. INI config files in system_dir/mame2009/ini/. - No hiscore.dat, history.dat, or mameinfo.dat support (unlike - mame2000/mame2003). The hiscore path is disabled in the libretro + No hiscore.dat, history.dat, or mameinfo.dat support. The hiscore path is disabled in the libretro wrapper. 48 BIOS root sets. ROM naming follows MAME 0.135 conventions. diff --git a/emulators/mednafen_pce_fast.yml b/emulators/mednafen_pce_fast.yml index 91e2e0acc..147765b30 100644 --- a/emulators/mednafen_pce_fast.yml +++ b/emulators/mednafen_pce_fast.yml @@ -16,10 +16,10 @@ systems: [nec-pc-engine] verification: existence notes: > Fork of Mednafen's pce_fast module (speed-optimized, no SuperGrafx support). - Separate codebase from beetle_pce (mednafen/pce_fast/ vs mednafen/pce/). + Built from mednafen/pce_fast/. BIOS loaded via HuCLoadCD() at CD-ROM load time. Core option "pce_fast_cdbios" selects which card image to use (default: System Card 3). - No Games Express auto-detection (unlike beetle_pce), so the user must select manually. + Does not detect Games Express: the card is chosen by the pce_fast_cdbios option. No hash or size validation on BIOS load. Upstream pce_fast module only has a single pce_fast.cdbios string setting: the 6-option dropdown is a libretro addition. diff --git a/emulators/minivmac.yml b/emulators/minivmac.yml index 4922ccf27..b629249c8 100644 --- a/emulators/minivmac.yml +++ b/emulators/minivmac.yml @@ -26,7 +26,7 @@ systems: [macintosh-ii] # 5. app parent directory # 6. current directory -# The libretro port does NOT call ROM_IsValid() (unlike upstream backends), +# The libretro port does not call ROM_IsValid() (unlike upstream backends), # so no checksum validation occurs. ROM_Init() patches the Mac's own boot # ROM check (DisableRomCheck = 1, ROMEMDEV.c:279). diff --git a/emulators/opentyrian.yml b/emulators/opentyrian.yml index 2790b9f8c..9077cefd7 100644 --- a/emulators/opentyrian.yml +++ b/emulators/opentyrian.yml @@ -17,7 +17,7 @@ verification: existence notes: | OpenTyrian is a source port of the DOS vertical scrolling shooter Tyrian, ported to libretro. It loads the Tyrian 2.1 freeware game data directly. - Tyrian 1.x, 2.0, and Tyrian 2000 data files are NOT compatible. + Tyrian 1.x, 2.0, and Tyrian 2000 data files are not compatible. The core's .info file sets supports_no_game = true. The core locates the data directory by probing for tyrian1.lvl in several paths (file.c:33-58): @@ -245,9 +245,9 @@ files: # which maps to shapes{char}.dat at tyrian2.c:3079. # The shipped set is ), W, X, Y, Z. lvlmast.c:128-131 writes } for the # Episode 4 tileset, which no distributed file matches. - # Note: shapeFile[34] in lvlmast.c is a DIFFERENT mechanism: + # Note: shapeFile[34] in lvlmast.c is a different mechanism: # it maps indices to characters for newsh?.shp (enemy sprites), - # NOT for shapes?.dat (level tilesets). + # not for shapes?.dat (level tilesets). # ----------------------------------------------------------- - name: "shapes).dat" category: game_data diff --git a/emulators/parallel_n64.yml b/emulators/parallel_n64.yml index d103fdc28..cbb04c42d 100644 --- a/emulators/parallel_n64.yml +++ b/emulators/parallel_n64.yml @@ -35,5 +35,4 @@ notes: divergence_note: > Fork of mupen64plus-core with significant divergence. Includes legacy GPU plugins (Glide64, glN64, Rice, angrylion) and ParaLLEl-RDP/RSP. - Uses flat path 64DD_IPL.bin unlike mupen64plus-next which uses - Mupen64plus/IPL.n64 subdirectory. + Reads 64DD_IPL.bin at the root of the system folder. diff --git a/emulators/pokemini.yml b/emulators/pokemini.yml index aad109124..76efaa28c 100644 --- a/emulators/pokemini.yml +++ b/emulators/pokemini.yml @@ -54,7 +54,7 @@ notes: | wrapper hardcodes it to 0 (always prefer real BIOS when available). FreeBIOS (freebios/freebios.min) is 4096 bytes, a clean-room - reimplementation. It is NOT the official Nintendo Pokemon Mini BIOS. + reimplementation. files: - name: "bios.min" diff --git a/emulators/rvvm.yml b/emulators/rvvm.yml index 21184b7be..21fa36c02 100644 --- a/emulators/rvvm.yml +++ b/emulators/rvvm.yml @@ -18,7 +18,7 @@ systems: [riscv] # loads a .rvvm plain-text config file specifying bootrom, kernel, nvme drives, # memory, CPU mode, cmdline, and framebuffer resolution. # -# The core does NOT use the RetroArch system directory. All firmware paths are +# The core does not use the RetroArch system directory. All firmware paths are # specified in the .rvvm config file and resolved relative to its directory. # The core chdir()s to the .rvvm file's parent before initializing the VM. # diff --git a/emulators/scummvm.yml b/emulators/scummvm.yml index f8241807d..08fa6d172 100644 --- a/emulators/scummvm.yml +++ b/emulators/scummvm.yml @@ -34,7 +34,7 @@ systems: [scummvm] # # MT-32/CM-32L ROM files go in scummvm/extra/ and are loaded by # audio/softsynth/mt32.cpp. The core tries CM-32L first, then MT-32. -# These are NOT bundled (proprietary). Everything else is open-source +# These are not bundled (proprietary). Everything else is open-source # data shipped with ScummVM releases. # ----- scummvm.ini (config, auto-created) ----- @@ -566,7 +566,7 @@ files: # Grim Fandango, Escape from Monkey Island, Myst III, The Longest # Journey (Stark), Wintermute 3D, Freescape, HPL1 (Penumbra), # Playground3D test engine. Listed in dists/scummvm.rc. - # Individual shader files are NOT listed here since they are + # Individual shader files are not listed here since they are # bundled in shaders.dat for the theme path and as individual # files in the extra/shaders/ directory. The build bundles them # automatically via backends/platform/libretro/scripts/bundle_datafiles.sh. diff --git a/emulators/sdlpop.yml b/emulators/sdlpop.yml index 822451fb9..22f2f9af6 100644 --- a/emulators/sdlpop.yml +++ b/emulators/sdlpop.yml @@ -18,9 +18,8 @@ verification: existence notes: | SDLPoP is NagyD's open-source port of the DOS Prince of Persia (1989), rebuilt from the leaked Jordan Mechner source and refined through - years of community reverse engineering. Unlike the other engines in - this directory, SDLPoP ships with ALL game data in-tree, so no retail - data file is required or useful. + years of community reverse engineering. SDLPoP ships all game data in + its tree, so no retail data file is needed. open_dat() (src/seg009.c:438) reads an archive named FOO.DAT if present, otherwise falls back to a loose folder data/FOO/ containing diff --git a/emulators/splitwolf.yml b/emulators/splitwolf.yml index e5e3d699b..4defdb895 100644 --- a/emulators/splitwolf.yml +++ b/emulators/splitwolf.yml @@ -31,7 +31,7 @@ notes: | the shareware build, wl6 then wl3 then wl1 for the full ones, sdm for the Spear demo, sod or sd1 after --mission 0 or 1 for Spear of Destiny, sd2 or sd3 after --mission 2 or 3 for the mission pack build - (wl_main.cpp:2015-2040). Unlike Wolf4SDL, every Spear build reads its + (wl_main.cpp:2015-2040). Every Spear build reads its graphics and audio files under the sod extension (wl_menu.cpp:5341-5342) and only vswap, maphead and gamemaps under the mission extension, so the mission packs need the original game beside them. diff --git a/emulators/stonesoup.yml b/emulators/stonesoup.yml index 2d4a86ce5..9d03cf32c 100644 --- a/emulators/stonesoup.yml +++ b/emulators/stonesoup.yml @@ -26,7 +26,7 @@ notes: | Game data loaded at runtime from dat/ tree via datafile_path(). ref: crawl-ref/source/files.cc:375-458 (_get_base_dirs() + datafile_path()) No DATA_DIR_PATH defined in Makefile.libretro, so it falls back to SysEnv.crawl_dir. - Data is NOT compiled into the binary. + Data is not compiled into the binary. dat/ tree contents (532 files, 16 MB): - dat/tiles/*.png (floor, wall, feat, player, main, gui, icons) (crawl-ref/source/tiletex.cc:89-97) diff --git a/emulators/vice.yml b/emulators/vice.yml index 891baeef5..f85f64fc1 100644 --- a/emulators/vice.yml +++ b/emulators/vice.yml @@ -36,7 +36,7 @@ notes: | separate libretro core. All standard ROMs (kernal, basic, chargen, drive DOS, editor) are embedded - in the core binary via USE_EMBEDDED. External ROM files are NOT required + in the core binary via USE_EMBEDDED. External ROM files are not required for normal operation. The embedded ROMs are compiled from vice/data// and ship with every build. diff --git a/emulators/vice_x64.yml b/emulators/vice_x64.yml index efec76790..1196c653c 100644 --- a/emulators/vice_x64.yml +++ b/emulators/vice_x64.yml @@ -20,7 +20,7 @@ notes: > plus all drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001, 2031, 2040, 3040, 4040, 9000) and VIC-II palettes. Embedded ROM check in sysfile_load takes priority over filesystem. Kernal Rev 1 (901227-01) and - Rev 2 (901227-02) are NOT embedded: selecting C64 OLD NTSC or C64 OLD PAL model + Rev 2 (901227-02) are not embedded: selecting C64 OLD NTSC or C64 OLD PAL model requires them on the filesystem in system/vice/C64/. JiffyDOS requires True Drive Emulation enabled and a 1541/1571/1581 drive type. SX-64 models use a separate JiffyDOS kernal (JiffyDOS_SX-64.bin) not declared in the .info. diff --git a/emulators/vice_x64sc.yml b/emulators/vice_x64sc.yml index 705f53536..0a9d1ed11 100644 --- a/emulators/vice_x64sc.yml +++ b/emulators/vice_x64sc.yml @@ -21,7 +21,7 @@ notes: > plus all drive ROMs (1540, 1541, 1541-II, 1551, 1570, 1571, 1571CR, 1581, 1001, 2031, 2040, 3040, 4040, 9000) and VIC-II palettes. Embedded ROM check in sysfile_load takes priority over filesystem. Kernal Rev 1 (901227-01) and - Rev 2 (901227-02) are NOT embedded: selecting C64 OLD NTSC or C64 OLD PAL model + Rev 2 (901227-02) are not embedded: selecting C64 OLD NTSC or C64 OLD PAL model requires them on the filesystem in system/vice/C64/. JiffyDOS requires True Drive Emulation enabled and a 1541/1571/1581 drive type. SX-64 models use a separate JiffyDOS kernal (JiffyDOS_SX-64.bin) not declared in the .info. diff --git a/emulators/x64sdl.yml b/emulators/x64sdl.yml index e09b38ab8..bf9a3031c 100644 --- a/emulators/x64sdl.yml +++ b/emulators/x64sdl.yml @@ -15,9 +15,8 @@ cores: [x64sdl] systems: [commodore-c64] notes: > Old port of VICE 3.1 using an SDL-to-libretro shim (r-type/sdlvice-libretro). - Separate codebase from the newer vice-libretro port. Marked experimental and - superseded. Unlike the newer port, this core does NOT embed system ROMs: all ROMs - must be on disk in /data/C64/ and /data/DRIVES/. + Marked experimental and superseded. This core embeds no system ROMs: all ROMs + are read from /data/C64/ and /data/DRIVES/. The .info declares firmware_count=0, while the core reads the ROMs this profile lists. No JiffyDOS support. No save states, no netplay, no cheats. diff --git a/tests/test_audit_regressions.py b/tests/test_audit_regressions.py index 39330ab7c..4e191efc2 100644 --- a/tests/test_audit_regressions.py +++ b/tests/test_audit_regressions.py @@ -6855,5 +6855,28 @@ class HiganSuperGameBoyFolderIsFree(unittest.TestCase): ) +class ProfileNotesDescribeTheCoreAlone(unittest.TestCase): + """mednafen_pce_fast, sdlpop and x64sdl described the core by what + another profile of this directory does ("unlike beetle_pce", "unlike the + other engines in this directory"), which means nothing once the profile + is read on its own, and 21 lines shouted NOT, ALL or MUST.""" + + SHOUT = re.compile(r"\b(NOT|NEVER|ONLY|MUST|ALL|DIFFERENT)\b(?! FOUND)") + + def test_no_profile_shouts_or_compares_with_another_profile(self): + names = {path.stem.casefold() for path in (ROOT / "emulators").glob("*.yml")} + names |= {name.replace("_", "-") for name in names} + found = [] + for path in sorted((ROOT / "emulators").glob("*.yml")): + text = path.read_text(encoding="utf-8") + for number, line in enumerate(text.splitlines(), 1): + if self.SHOUT.search(line): + found.append(f"{path.stem}:{number}") + for match in re.finditer(r"\bunlike (?:the )?([\w+-]+)", line, re.I): + if match.group(1).casefold() in names: + found.append(f"{path.stem}:{number}") + self.assertEqual(found, []) + + if __name__ == "__main__": unittest.main()