feat: collect four open engines in full

emulators/cdogs.yml

@@ -13,124 +13,227 @@ verification: existence
 
 notes: |
   Top-down shooter engine, open-source remake of the DOS C-Dogs by Ronny Wester.
-  Ships every asset it needs in-tree: data/, graphics/, missions/, music/,
-  sounds/, dogfights/, doc/, wiki/ (about 100 MB).
+  The repository ships every asset the engine reads: data/, graphics/,
+  missions/, dogfights/, music/, sounds/ and doc/.
 
-  The data root is baked into the binary via -DCDOGS_DATA_DIR (CMakeLists.txt
-  option). Batocera sets it to /userdata/roms/cdogs/; the Linux source default
-  is cdogs-data. GetDataFilePath() in src/cdogs/utils.c:392 either returns an
-  absolute override as-is, or joins the current working directory with
-  CDOGS_DATA_DIR plus the requested relative path.
+  The data root is baked into the binary through -DCDOGS_DATA_DIR. The
+  source default is "../" ("./" on GCW0), CMakeLists.txt:141-147; Batocera
+  sets it to /userdata/roms/cdogs/. GetDataFilePath(), src/cdogs/utils.c:392,
+  returns an absolute request as it is, and otherwise joins CDOGS_DATA_DIR
+  (under the working directory when it is relative) with the requested path.
 
-  Top-level sub-trees the game pulls files from (every path is relative to
-  CDOGS_DATA_DIR, resolved through GetDataFilePath):
-    data/: ammo.json, bullets.json, guns.json, pickups.json,
-      map_objects.json, character_classes.json, particles.json,
-      gamecontrollerdb.txt, prefixes.txt (configuration data)
-    graphics/: sprites, font, icons; grafx.c:92 (cdogs_icon.bmp),
-      grafx.c:156 (font.png + font.json)
-    missions/: single-player campaigns, mission packs (JSON)
-    music/: menu, briefing, game, end, lose, victory tracks
-      (music.c:45-50 LoadMusic calls)
-    sounds/: sfx wavs
-    dogfights/: deathmatch arenas
+  Paths below are written under cdogs/, which stands for that data root.
 
-  All open-source content (GPL-2.0). No separate BIOS or retail data required.
+  What the engine reads there:
+    data/: the JSON class definitions and name lists loaded by main(),
+      src/cdogs.c:226-245, and the two controller databases,
+      src/cdogs/joystick.c:43-54
+    data/.wolf3d/: campaign templates used when a Wolfenstein 3D, Spear of
+      Destiny or Super 3D Noah's Ark installation is found,
+      src/cdogs/map_wolf.c:50
+    graphics/: every .png, walked by PicManagerLoad,
+      src/cdogs/pic_manager.c:247-254, plus the font and the window icon
+    missions/ and dogfights/: campaigns, src/cdogs/campaigns.c:203-211
+    music/: six track directories, src/cdogs/music.c:45-50
+    sounds/: samples, src/cdogs.c:213
+    doc/CREDITS: src/credits.c:47
 
 files:
   - name: "ammo.json"
-    path: "data/ammo.json"
+    path: "cdogs/data/ammo.json"
     category: game_data
     description: "Ammo type definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/ammo.c (AmmoLoadJSON reads data/ammo.json)"
+    source_ref: "src/cdogs.c:228, src/cdogs/ammo.c:77-84"
 
   - name: "bullets.json"
-    path: "data/bullets.json"
+    path: "cdogs/data/bullets.json"
     category: game_data
     description: "Bullet behaviour definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/weapon_class.c (BulletsLoadJSON)"
+    source_ref: "src/cdogs.c:230-232, src/cdogs/weapon_class.c:739-746"
 
   - name: "guns.json"
-    path: "data/guns.json"
+    path: "cdogs/data/guns.json"
     category: game_data
     description: "Weapon definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/weapon_class.c"
+    source_ref: "src/cdogs.c:230-232, src/cdogs/weapon_class.c:757-763"
 
   - name: "character_classes.json"
-    path: "data/character_classes.json"
+    path: "cdogs/data/character_classes.json"
     category: game_data
     description: "Character class definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/character_class.c"
+    source_ref: "src/cdogs.c:234-235, src/cdogs/character_class.c:353-360"
 
   - name: "map_objects.json"
-    path: "data/map_objects.json"
+    path: "cdogs/data/map_objects.json"
     category: game_data
     description: "Interactive map object definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/map_object.c"
+    source_ref: "src/cdogs.c:244-245, src/cdogs/map_object.c:231-238"
 
   - name: "particles.json"
-    path: "data/particles.json"
+    path: "cdogs/data/particles.json"
     category: game_data
     description: "Particle effect definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/particle.c"
+    source_ref: "src/cdogs.c:226, src/cdogs/particle.c:61-64"
 
   - name: "pickups.json"
-    path: "data/pickups.json"
+    path: "cdogs/data/pickups.json"
     category: game_data
     description: "Pickup item definitions"
     required: true
     bundled: true
-    source_ref: "src/cdogs/pickup_class.c"
+    source_ref: "src/cdogs.c:241-242, src/cdogs/pickup_class.c:246-252"
 
   - name: "prefixes.txt"
-    path: "data/prefixes.txt"
+    path: "cdogs/data/prefixes.txt"
     category: game_data
     description: "Random name generation prefixes"
     required: true
     bundled: true
-    source_ref: "src/cdogs/character.c"
+    source_ref: "src/prep.c:324-327, src/namegen.c:44-59"
+    note: "LoadFile reads the stream without checking that fopen succeeded."
+
+  - name: "suffixes.txt"
+    path: "cdogs/data/suffixes.txt"
+    category: game_data
+    description: "Random name generation suffixes"
+    required: true
+    bundled: true
+    source_ref: "src/prep.c:325-327, src/namegen.c:44-59"
+    note: "LoadFile reads the stream without checking that fopen succeeded."
+
+  - name: "suffixnames.txt"
+    path: "cdogs/data/suffixnames.txt"
+    category: game_data
+    description: "Random name generation name suffixes"
+    required: true
+    bundled: true
+    source_ref: "src/prep.c:326-327, src/namegen.c:44-59"
+    note: "LoadFile reads the stream without checking that fopen succeeded."
 
   - name: "gamecontrollerdb.txt"
-    path: "data/gamecontrollerdb.txt"
+    path: "cdogs/data/gamecontrollerdb.txt"
     category: game_data
     description: "SDL gamecontroller mapping database"
     required: false
     bundled: true
-    source_ref: "src/cdogs/joystick.c:43"
-    unsourceable: "ships inside the engine package; a same-named file of another program must not stand in"
+    source_ref: "src/cdogs/joystick.c:43-48"
+    note: "A load failure is logged and the built-in SDL mappings stay in use."
+
+  - name: "gamecontrollerbuttondb.txt"
+    path: "cdogs/data/gamecontrollerbuttondb.txt"
+    category: game_data
+    description: "Controller button names and colours"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs/joystick.c:49-54"
+    note: "A load failure is logged."
+
+  - name: ".wolf3d/"
+    type: directory
+    path: "cdogs/data/.wolf3d/"
+    category: game_data
+    description: "Campaign templates for Wolfenstein 3D, Spear of Destiny and Super 3D Noah's Ark"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs/map_wolf.c:50, src/cdogs/map_wolf.c:110-134, src/cdogs/map_wolf.c:781-793"
+    note: >
+      Read only when the game data of one of these titles is found in a
+      Steam or GOG installation.
+
+  - name: "graphics/"
+    type: directory
+    path: "cdogs/graphics/"
+    category: game_data
+    description: "Sprites, tiles, HUD and character body definitions"
+    required: true
+    bundled: true
+    source_ref: "src/cdogs.c:189, src/cdogs/pic_manager.c:181-254, src/cdogs/draw/char_sprites.c:55-115"
+    note: >
+      PicManagerLoad walks the directory and loads every .png.
+      CharSpriteClassesLoadDir reads data.json from each directory of
+      graphics/chars/bodies/.
 
   - name: "font.png"
-    path: "graphics/font.png"
+    path: "cdogs/graphics/font.png"
     category: game_data
     description: "Main bitmap font"
     required: true
     bundled: true
-    source_ref: "src/cdogs/grafx.c:156 (FontLoadFromJSON)"
+    source_ref: "src/cdogs.c:186, src/cdogs/grafx.c:156, src/cdogs/font.c:54-60"
 
   - name: "font.json"
-    path: "graphics/font.json"
+    path: "cdogs/graphics/font.json"
     category: game_data
     description: "Main bitmap font layout"
     required: true
     bundled: true
-    source_ref: "src/cdogs/grafx.c:156"
+    source_ref: "src/cdogs.c:186, src/cdogs/grafx.c:156, src/cdogs/font_utils.c:35-41"
 
   - name: "cdogs_icon.bmp"
-    path: "graphics/cdogs_icon.bmp"
+    path: "cdogs/graphics/cdogs_icon.bmp"
     category: game_data
     description: "Window icon"
     required: false
     bundled: true
-    source_ref: "src/cdogs/grafx.c:92"
+    source_ref: "src/cdogs/grafx.c:92-93"
+
+  - name: "missions/"
+    type: directory
+    path: "cdogs/missions/"
+    category: game_data
+    description: "Campaigns"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs/sys_config.h.cmake:38, src/cdogs/campaigns.c:203-206, src/cdogs/campaigns.c:257-298"
+    note: >
+      Every entry of the directory is tried as a campaign and subdirectories
+      are walked. Quick play needs none.
+
+  - name: "dogfights/"
+    type: directory
+    path: "cdogs/dogfights/"
+    category: game_data
+    description: "Dogfight arenas"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs/sys_config.h.cmake:39, src/cdogs/campaigns.c:208-211"
+
+  - name: "music/"
+    type: directory
+    path: "cdogs/music/"
+    category: game_data
+    description: "Music tracks: menu, briefing, game, end, lose, victory"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs/music.c:45-50, src/cdogs/music.c:52-64"
+    note: "Every file of each of the six directories is loaded as a track."
+
+  - name: "sounds/"
+    type: directory
+    path: "cdogs/sounds/"
+    category: game_data
+    description: "Sound effects"
+    required: false
+    bundled: true
+    source_ref: "src/cdogs.c:213, src/cdogs/sounds.c:187-198, src/cdogs/sounds.c:199-244"
+    note: "SoundLoadDir walks the directory and loads every .ogg, .wav and .mp3."
+
+  - name: "CREDITS"
+    path: "cdogs/doc/CREDITS"
+    category: game_data
+    description: "Credits shown in the main menu"
+    required: false
+    bundled: true
+    source_ref: "src/credits.c:47-53"

emulators/fallout2-ce.yml

@@ -60,4 +60,11 @@ files:
     category: game_data
     required: false
     description: "High Resolution Patch resource archive, loaded when present"
-    source_ref: "src/game.cc:1380-1382"
+    source_ref: "src/game.cc:1380-1382, src/interface.cc:2488, src/interface.cc:2540-2543"
+    note: >
+      Opened as one more database over master.dat, with no check of its
+      content. The engine loads art\intrface\HR_IFACE_<width>.FRM, the
+      widened interface bar, and HR_IFACELFT<n>.frm and HR_IFACERHT<n>.frm,
+      the side panels, which this archive provides. Several builds circulate
+      under the same name and the code cannot tell them apart. BGforgeNet
+      f2_res v0.6 carries hr_iface_800.frm and both pairs of side panels.

emulators/hcl.yml

@@ -16,73 +16,81 @@ notes: |
   Castle Labyrinth. ptitSeb's SDL/SDL2/SDL3 fork is used by batocera (the
   package batocera/ports/hcl pins HCL_VERSION to this commit).
 
-  The engine opens every data file from a relative "data/" prefix hard-coded
-  in the sources:
-    - qda.c:19, strcpy(fullPath, "data/") before appending qda chunk names
-    - hero.c:202, fopen("data/save.tmp", "rb")
-    - sdl2/audio.c:30, strcpy(buff, "data/") before midi/wav loads
-    - sdl2/graphics.c, sdl3/graphics.c: fopen("data/bmp.qda", "rb")
-    - game.h:184, savename macro = "data/save.tmp"
+  The SDL builds open every data file from a relative "data/" prefix
+  hard-coded in the sources:
+    - src/qda.c:19, strcpy(fullPath, "data/") before the archive name
+    - src/sdl2/graphics.c:223, fopen("data/bmp.qda", "rb")
+    - src/text.c:79, "data/" before en.dat or jp.dat
+    - src/game.c:1195 and src/game.c:1290, "data/map/" and "data/obj/"
+    - src/sdl2/audio.c:30 and src/sdl2/audio.c:40, "data/" before the
+      music and sound names
+    - src/game.h:184, savename macro = "data/save.tmp"
   Save files are rewritten in that same relative data/ tree, so the game must
-  be launched from a working directory that contains data/ (batocera copies
-  the shipped data/ beside the binary).
+  be launched from a working directory that contains data/.
 
-  The 31 MB data/ tree is shipped in the source repository and is open content.
-  Nothing else is required.
+  Paths below are written under hcl/, which stands for that working
+  directory. The data/ tree is shipped in the source repository.
 
 files:
   - name: "bmp.qda"
-    path: "data/bmp.qda"
+    path: "hcl/data/bmp.qda"
     category: game_data
     description: "Packed graphics (QDA archive of all bitmaps)"
     required: true
     bundled: true
-    source_ref: "src/sdl2/graphics.c:229 (fopen \"data/bmp.qda\" rb)"
+    source_ref: "src/qda.c:19-28, src/sdl2/graphics.c:223"
 
   - name: "en.dat"
-    path: "data/en.dat"
+    path: "hcl/data/en.dat"
     category: game_data
     description: "English localization"
     required: true
     bundled: true
-    source_ref: "src/text.c (loaded via data/ prefix)"
+    source_ref: "src/text.c:79-93"
 
   - name: "jp.dat"
-    path: "data/jp.dat"
+    path: "hcl/data/jp.dat"
     category: game_data
     description: "Japanese localization"
     required: true
     bundled: true
-    source_ref: "src/text.c"
+    source_ref: "src/text.c:79-93"
 
-  - name: "map"
-    path: "data/map"
+  - name: "map/"
+    type: directory
+    path: "hcl/data/map/"
     category: game_data
-    description: "Level maps directory (060 .map files)"
+    description: "Room tile maps, <nnn>.map and the background layer <nnn>a.map"
     required: true
     bundled: true
-    source_ref: "src/stagedata.c (loads data/map/<nnn>.map)"
+    source_ref: "src/game.c:1195-1209"
 
-  - name: "obj"
-    path: "data/obj"
+  - name: "obj/"
+    type: directory
+    path: "hcl/data/obj/"
     category: game_data
-    description: "Per-stage object definitions directory"
+    description: "Per-room object definitions, <nnn>.dat"
     required: true
     bundled: true
-    source_ref: "src/stagedata.c (loads data/obj/<nnn>.dat)"
+    source_ref: "src/game.c:1290-1306"
 
-  - name: "midi"
-    path: "data/midi"
+  - name: "midi/"
+    type: directory
+    path: "hcl/data/midi/"
     category: game_data
-    description: "Music files (.mid + .ogg companions)"
+    description: "Music, each track as .mid and .ogg"
     required: false
     bundled: true
-    source_ref: "src/sdl2/audio.c:30 (data/ prefix for midi loads)"
+    source_ref: "src/sdl2/audio.c:25-34, src/game.c:48-56, src/game.c:473-474"
+    note: >
+      PHL_LoadMusic appends .ogg or .mid according to the music type option.
+      A track that fails to load is not played.
 
-  - name: "wav"
-    path: "data/wav"
+  - name: "wav/"
+    type: directory
+    path: "hcl/data/wav/"
     category: game_data
     description: "Sound effect samples"
     required: false
     bundled: true
-    source_ref: "src/sdl2/audio.c (data/wav/<name>.wav)"
+    source_ref: "src/sdl2/audio.c:37-42, src/game.c:428-470"

emulators/hurrican.yml

@@ -25,6 +25,8 @@ notes: |
       from --pathsave or -PS, else XDG_DATA_HOME and XDG_CONFIG_HOME on
       builds with USE_HOME_DIR, else "." (Hurrican/src/Main.cpp:370-385).
 
+  Paths below are written under hurrican/, which stands for g_storage_ext.
+
   Files read under g_storage_ext:
     lang/*.lng: Hurrican/src/Main.cpp:496-515, Hurrican/src/Texts.cpp:65
     data/textures/: Hurrican/src/DX8Texture.cpp:204-211
@@ -40,8 +42,9 @@ notes: |
   for levels, textures, custom.lng and levellist.dat.
 
 files:
-  - name: "lang"
-    path: "lang"
+  - name: "lang/"
+    type: directory
+    path: "hurrican/lang/"
     category: game_data
     description: "Language files (.lng)"
     required: true
@@ -51,8 +54,9 @@ files:
       GameInit lists the .lng files of lang/, then of the working directory,
       and aborts when it finds none.
 
-  - name: "textures"
-    path: "data/textures"
+  - name: "textures/"
+    type: directory
+    path: "hurrican/data/textures/"
     category: game_data
     description: "Textures (sprites, backgrounds, fonts)"
     required: true
@@ -62,16 +66,18 @@ files:
       An optional scalefactors.txt in the same directory is read by
       ReadScaleFactorsFiles (Hurrican/src/DX8Texture.cpp:162-168).
 
-  - name: "levels"
-    path: "data/levels"
+  - name: "levels/"
+    type: directory
+    path: "hurrican/data/levels/"
     category: game_data
     description: "Level files and levellist.dat"
     required: true
     bundled: true
     source_ref: "Hurrican/src/Tileengine.cpp:330-336, Hurrican/src/Texts.cpp:127-133"
 
-  - name: "shaders"
-    path: "data/shaders"
+  - name: "shaders/"
+    type: directory
+    path: "hurrican/data/shaders/"
     category: game_data
     description: "GLSL shader sources, one subdirectory per GLSL version"
     required: true
@@ -81,16 +87,18 @@ files:
       Loaded by the GL2 and GL3 renderers (GL2 is the build default); a GL1
       build compiles this block out.
 
-  - name: "music"
-    path: "data/music"
+  - name: "music/"
+    type: directory
+    path: "hurrican/data/music/"
     category: game_data
     description: "Music tracks"
     required: true
     bundled: true
     source_ref: "Hurrican/src/DX8Sound.cpp:314-320"
 
-  - name: "sfx"
-    path: "data/sfx"
+  - name: "sfx/"
+    type: directory
+    path: "hurrican/data/sfx/"
     category: game_data
     description: "Sound effect samples"
     required: true
@@ -98,10 +106,10 @@ files:
     source_ref: "Hurrican/src/DX8Sound.cpp:580-586"
 
   - name: "gamecontrollerdb.txt"
-    path: "data/gamecontrollerdb.txt"
+    path: "hurrican/data/gamecontrollerdb.txt"
     category: game_data
     description: "SDL game controller mapping database"
     required: false
     bundled: true
-    source_ref: "Hurrican/src/DX8Input.cpp:97-99"
-    unsourceable: "ships inside the engine package; a same-named file of another program must not stand in"
+    source_ref: "Hurrican/src/DX8Input.cpp:97-102"
+    note: "Passed to SDL_GameControllerAddMappingsFromFile; the result is only logged."

emulators/ikemen.yml

@@ -16,9 +16,10 @@ notes: |
   .def, .air, .cmd, .cns, .sff and .snd files of M.U.G.E.N. content, plus its
   own .zss state files.
 
-  Every path below is relative to the working directory. The file names come
-  from the embedded default configuration, src/resources/defaultConfig.ini,
-  which save/config.ini overrides (src/main.go:189-195).
+  Every file is read relative to the working directory; paths below are
+  written under ikemen/, which stands for it. The file names come from the
+  embedded default configuration, src/resources/defaultConfig.ini, which
+  save/config.ini overrides (src/main.go:189-195).
 
   The repository ships:
     data/: common animations, commands, constants and state files
@@ -28,17 +29,25 @@ notes: |
     font/: debug.def with Open Sans, and the default-3x5 bitmap fonts
 
   The default configuration also names files the repository does not hold:
-  the motif data/ikemen1/system.def, the effects pack data/gofx/gofx.def and
-  the stage stages/stage0-720.def. Release packages copy chars, data, font,
-  sound, stages and video from the Ikemen-GO-Screenpack repository next to
-  the engine (.github/workflows/releases.yml:585-593).
+  the motif data/ikemen1/system.def, the effects pack data/gofx/gofx.def, the
+  stage stages/stage0-720.def and external/gamecontrollerdb.txt. Release
+  packages copy chars, data, font, sound, stages and video from the
+  Ikemen-GO-Screenpack repository next to the engine
+  (.github/workflows/releases.yml:585-593) and download the controller
+  database (.github/workflows/releases.yml:610-612).
+
+  A definition file names the files it loads. Each name is searched beside
+  the definition, beside the motif, in the working directory and in data/
+  (src/common.go:641), fonts also in font/ and videos in video/. The motif
+  names its music under sound/, which release packages ship empty.
 
   Characters and stages are found under chars/ and stages/
   (src/system.go:5364, src/system.go:5590).
 
 files:
-  - name: "script"
-    path: "external/script"
+  - name: "script/"
+    type: directory
+    path: "ikemen/external/script/"
     category: game_data
     description: "Lua scripts: main.lua and the modules it requires"
     required: true
@@ -49,7 +58,7 @@ files:
       requires debug, start, options and menu from the same directory.
 
   - name: "IkemenCylia_256.png"
-    path: "external/icons/IkemenCylia_256.png"
+    path: "ikemen/external/icons/IkemenCylia_256.png"
     category: game_data
     description: "Window icon, 256 px"
     required: true
@@ -57,7 +66,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:141, src/system.go:527-538"
 
   - name: "IkemenCylia_96.png"
-    path: "external/icons/IkemenCylia_96.png"
+    path: "ikemen/external/icons/IkemenCylia_96.png"
     category: game_data
     description: "Window icon, 96 px"
     required: true
@@ -65,15 +74,16 @@ files:
     source_ref: "src/resources/defaultConfig.ini:141, src/system.go:527-538"
 
   - name: "IkemenCylia_48.png"
-    path: "external/icons/IkemenCylia_48.png"
+    path: "ikemen/external/icons/IkemenCylia_48.png"
     category: game_data
     description: "Window icon, 48 px"
     required: true
     bundled: true
     source_ref: "src/resources/defaultConfig.ini:141, src/system.go:527-538"
 
-  - name: "shaders"
-    path: "external/shaders"
+  - name: "shaders/"
+    type: directory
+    path: "ikemen/external/shaders/"
     category: game_data
     description: "Post-processing shaders offered in the options menu"
     required: false
@@ -81,7 +91,7 @@ files:
     source_ref: "external/script/options.lua:1646, src/system.go:457-470"
 
   - name: "common.air"
-    path: "data/common.air"
+    path: "ikemen/data/common.air"
     category: game_data
     description: "Common animations merged into every character"
     required: true
@@ -89,7 +99,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:12, src/char.go:4676-4689"
 
   - name: "common.cmd"
-    path: "data/common.cmd"
+    path: "ikemen/data/common.cmd"
     category: game_data
     description: "Common commands appended to every character's command file"
     required: true
@@ -97,7 +107,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:14, src/compiler.go:8367-8380"
 
   - name: "common.const"
-    path: "data/common.const"
+    path: "ikemen/data/common.const"
     category: game_data
     description: "Common constants"
     required: true
@@ -105,7 +115,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:16, src/char.go:4338-4355"
 
   - name: "functions.zss"
-    path: "data/functions.zss"
+    path: "ikemen/data/functions.zss"
     category: game_data
     description: "Common states: shared ZSS functions"
     required: true
@@ -113,7 +123,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "action.zss"
-    path: "data/action.zss"
+    path: "ikemen/data/action.zss"
     category: game_data
     description: "Common states: actions"
     required: true
@@ -121,7 +131,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "demo.zss"
-    path: "data/demo.zss"
+    path: "ikemen/data/demo.zss"
     category: game_data
     description: "Common states: demo mode"
     required: true
@@ -129,7 +139,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "dizzy.zss"
-    path: "data/dizzy.zss"
+    path: "ikemen/data/dizzy.zss"
     category: game_data
     description: "Common states: dizzy"
     required: true
@@ -137,7 +147,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "guardbreak.zss"
-    path: "data/guardbreak.zss"
+    path: "ikemen/data/guardbreak.zss"
     category: game_data
     description: "Common states: guard break"
     required: true
@@ -145,7 +155,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "score.zss"
-    path: "data/score.zss"
+    path: "ikemen/data/score.zss"
     category: game_data
     description: "Common states: score"
     required: true
@@ -153,7 +163,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "system.zss"
-    path: "data/system.zss"
+    path: "ikemen/data/system.zss"
     category: game_data
     description: "Common states: system"
     required: true
@@ -161,7 +171,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "tag.zss"
-    path: "data/tag.zss"
+    path: "ikemen/data/tag.zss"
     category: game_data
     description: "Common states: tag team"
     required: true
@@ -169,7 +179,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "training.zss"
-    path: "data/training.zss"
+    path: "ikemen/data/training.zss"
     category: game_data
     description: "Common states: training mode"
     required: true
@@ -177,7 +187,7 @@ files:
     source_ref: "src/resources/defaultConfig.ini:18, src/compiler.go:8545-8552"
 
   - name: "common1.cns.zss"
-    path: "data/common1.cns.zss"
+    path: "ikemen/data/common1.cns.zss"
     category: game_data
     description: "ZSS replacement for the common1.cns state file"
     required: true
@@ -189,7 +199,7 @@ files:
       asking for common1.cns gets data/common1.cns.zss.
 
   - name: "debug.def"
-    path: "font/debug.def"
+    path: "ikemen/font/debug.def"
     category: game_data
     description: "Debug overlay font definition"
     required: true
@@ -198,7 +208,7 @@ files:
     note: "loadDebugFont raises a Lua error when the font cannot be loaded."
 
   - name: "OpenSans-Bold.ttf"
-    path: "font/Open_Sans/OpenSans-Bold.ttf"
+    path: "ikemen/font/Open_Sans/OpenSans-Bold.ttf"
     category: game_data
     description: "TrueType face named by debug.def"
     required: true
@@ -209,7 +219,7 @@ files:
       font directories; the engine panics when that fails too.
 
   - name: "default-3x5.def"
-    path: "font/default-3x5.def"
+    path: "ikemen/font/default-3x5.def"
     category: game_data
     description: "Default motif font (font1)"
     required: false
@@ -218,7 +228,7 @@ files:
     note: "A motif font that fails to load is logged and replaced by an empty font."
 
   - name: "default-3x5.sff"
-    path: "font/default-3x5.sff"
+    path: "ikemen/font/default-3x5.sff"
     category: game_data
     description: "Glyph sprites named by default-3x5.def"
     required: false
@@ -227,7 +237,7 @@ files:
     note: "LoadFntSff panics when default-3x5.def is loaded and this file is missing."
 
   - name: "system.def"
-    path: "data/ikemen1/system.def"
+    path: "ikemen/data/ikemen1/system.def"
     category: game_data
     description: "Default motif definition"
     required: true
@@ -239,7 +249,7 @@ files:
       when the definition cannot be read. -r selects another motif.
 
   - name: "gofx.def"
-    path: "data/gofx/gofx.def"
+    path: "ikemen/data/gofx/gofx.def"
     category: game_data
     description: "Common effects pack"
     required: true
@@ -249,22 +259,158 @@ files:
       Held by the Ikemen-GO-Screenpack repository and copied into release
       packages. A load failure puts the match loader in its error state.
 
-  - name: "chars"
-    path: "chars"
+  - name: "gofx/"
+    type: directory
+    path: "ikemen/data/gofx/"
+    category: game_data
+    description: "Sprites, animations and sounds named by gofx.def"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:162-193"
+    note: "loadFightFx returns an error when the sff, air or snd file it names fails to load."
+
+  - name: "ikemen1/"
+    type: directory
+    path: "ikemen/data/ikemen1/"
+    category: game_data
+    description: "Default motif: sprites, logo and credits storyboards, fonts"
+    required: false
+    bundled: true
+    source_ref: "src/motif.go:72-85, src/motif.go:2475-2487, src/motif.go:2594-2621, src/storyboard.go:561-620"
+    note: >
+      Files named by system.def and searched beside it first. A sprite file
+      or font that fails to load is logged and replaced by an empty one.
+
+  - name: "select.def"
+    path: "ikemen/data/select.def"
+    category: game_data
+    description: "Character and stage selection list"
+    required: true
+    bundled: true
+    source_ref: "src/motif.go:81, external/script/main.lua:1522, external/script/main.lua:43-50"
+    note: "main.lua reads the file at startup and raises an error when it cannot be opened."
+
+  - name: "fight.def"
+    path: "ikemen/data/fight.def"
+    category: game_data
+    description: "Fight screen definition"
+    required: true
+    bundled: true
+    source_ref: "src/motif.go:82, src/fightscreen.go:6005-6027, src/fightscreen.go:4792-4800, src/script.go:4233-4236, external/script/main.lua:1188"
+    note: "main.lua calls loadFightScreen at startup, which raises a Lua error on a load failure."
+
+  - name: "fight.sff"
+    path: "ikemen/data/fight.sff"
+    category: game_data
+    description: "Fight screen sprites"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:4916-4926"
+    note: "Named by the sff key of fight.def; a load failure fails loadFightScreen."
+
+  - name: "fight.snd"
+    path: "ikemen/data/fight.snd"
+    category: game_data
+    description: "Fight screen sounds"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:4927-4937"
+    note: "Named by the snd key of fight.def; a load failure fails loadFightScreen."
+
+  - name: "fightfx.sff"
+    path: "ikemen/data/fightfx.sff"
+    category: game_data
+    description: "Common effect sprites"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:4938-4948"
+    note: "Named by the fightfx.sff key of fight.def; a load failure fails loadFightScreen."
+
+  - name: "fightfx.air"
+    path: "ikemen/data/fightfx.air"
+    category: game_data
+    description: "Common effect animations"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:4949-4959"
+    note: "Named by the fightfx.air key of fight.def; a load failure fails loadFightScreen."
+
+  - name: "common.snd"
+    path: "ikemen/data/common.snd"
+    category: game_data
+    description: "Common effect sounds"
+    required: true
+    bundled: true
+    source_ref: "src/fightscreen.go:4960-4966"
+    note: "Named by the common.snd key of fight.def; a load failure fails loadFightScreen."
+
+  - name: "system.snd"
+    path: "ikemen/data/system.snd"
+    category: game_data
+    description: "Motif sounds"
+    required: false
+    bundled: true
+    source_ref: "src/resources/defaultMotif.ini:69, src/motif.go:73, src/motif.go:2578-2590"
+    note: "Named by the snd key of the motif. A load failure is logged and an empty sound set is used."
+
+  - name: "glyphs.sff"
+    path: "ikemen/data/glyphs.sff"
+    category: game_data
+    description: "Button glyph sprites for the movelist"
+    required: false
+    bundled: true
+    source_ref: "src/resources/defaultMotif.ini:97, src/motif.go:84, src/motif.go:2490-2503"
+    note: "A load failure is logged and an empty sprite set is used."
+
+  - name: "font/"
+    type: directory
+    path: "ikemen/font/"
+    category: game_data
+    description: "Fonts named by the motif, the fight screen and storyboards"
+    required: false
+    bundled: true
+    source_ref: "src/motif.go:64, src/motif.go:2594-2621, src/fightscreen.go:5017, src/storyboard.go:620, src/font.go:413"
+    note: "font/ is the default directory of every font lookup."
+
+  - name: "video/"
+    type: directory
+    path: "ikemen/video/"
+    category: game_data
+    description: "Videos played by the logo and credits storyboards"
+    required: false
+    bundled: true
+    source_ref: "src/stage.go:204-212"
+    note: >
+      A background element of type video names its file in path; video/ is
+      the default directory of the lookup.
+
+  - name: "gamecontrollerdb.txt"
+    path: "ikemen/external/gamecontrollerdb.txt"
+    category: game_data
+    description: "SDL game controller mapping database"
+    required: false
+    bundled: true
+    source_ref: "src/resources/defaultConfig.ini:153, src/system.go:444-445, src/input_sdl.go:261-271"
+    note: "A read failure is logged."
+
+  - name: "chars/"
+    type: directory
+    path: "ikemen/chars/"
     category: game_data
     description: "Character directory"
     required: false
     source_ref: "src/system.go:5364, src/script.go:3190-3191"
     note: >
-      User supplied. A character path that does not resolve as given is
-      searched under chars/.
+      A character path that does not resolve as given is searched under
+      chars/. Release packages ship the Kung Fu Man characters.
 
-  - name: "stages"
-    path: "stages"
+  - name: "stages/"
+    type: directory
+    path: "ikemen/stages/"
     category: game_data
     description: "Stage directory"
     required: false
     source_ref: "src/system.go:5590, src/resources/defaultConfig.ini:178, external/script/main.lua:1770-1774"
     note: >
-      User supplied. Debug.StartStage defaults to stages/stage0-720.def, the
-      stage added when select.def lists none.
+      Debug.StartStage defaults to stages/stage0-720.def, the stage added
+      when select.def lists none.

emulators/openjkdf2.yml

@@ -28,6 +28,16 @@ notes: |
     aGobDirectories[4]   gamedata\resource (CD overlay), mounted by
                          jkRes_LoadCd (src/Main/jkRes.c:130-131)
 
+  The asset root is the working directory when it holds resource/jk_.cd,
+  else the per-user data directory, whose last component is openjkdf2,
+  openjkmots or opendroidworks (src/Main/InstallHelper.c:97,
+  src/Main/InstallHelper.c:239-270). Paths below are written under that
+  component.
+
+  jkRes_LoadNew mounts every .gob (.goo in Mysteries of the Sith mode) of
+  resource/ (src/Main/jkRes.c:287-300) and jkEpisode lists every one of
+  episode/ (src/Main/jkEpisode.c:106).
+
   Required-asset lists are declared in src/Main/InstallHelper.c and
   checked by InstallHelper_CheckInstalled / AttemptInstallFromExisting;
   a missing entry aborts installation (src/Main/InstallHelper.c:748-756,
@@ -45,7 +55,7 @@ files:
   # ================================================================
 
   - name: "JK1.gob"
-    path: "episode/JK1.gob"
+    path: "openjkdf2/episode/JK1.gob"
     system: dark-forces-ii
     category: game_data
     required: true
@@ -53,7 +63,7 @@ files:
     note: "Single-player episode data."
 
   - name: "JK1CTF.gob"
-    path: "episode/JK1CTF.gob"
+    path: "openjkdf2/episode/JK1CTF.gob"
     system: dark-forces-ii
     category: game_data
     required: true
@@ -61,7 +71,7 @@ files:
     note: "Multiplayer CTF episode."
 
   - name: "JK1MP.gob"
-    path: "episode/JK1MP.gob"
+    path: "openjkdf2/episode/JK1MP.gob"
     system: dark-forces-ii
     category: game_data
     required: true
@@ -69,7 +79,7 @@ files:
     note: "Multiplayer deathmatch episode. Default -episode value in Main.c:120."
 
   - name: "Res1hi.gob"
-    path: "resource/Res1hi.gob"
+    path: "openjkdf2/resource/Res1hi.gob"
     system: dark-forces-ii
     category: game_data
     required: true
@@ -77,7 +87,7 @@ files:
     note: "High-resolution textures and sprites."
 
   - name: "Res2.gob"
-    path: "resource/Res2.gob"
+    path: "openjkdf2/resource/Res2.gob"
     system: dark-forces-ii
     category: game_data
     required: true
@@ -85,15 +95,43 @@ files:
     note: "Shared engine resources: sounds, 3DOs, materials."
 
   - name: "jk_.cd"
-    path: "resource/jk_.cd"
+    path: "openjkdf2/resource/jk_.cd"
     system: dark-forces-ii
     category: game_data
     required: true
-    source_ref: "src/Main/InstallHelper.c:39 (aRequiredAssets), src/Main/jkRes.c:234"
-    note: "CD key marker read by jkRes_ReadKeyFromFile."
+    source_ref: "src/Main/InstallHelper.c:39 (aRequiredAssets), src/Main/InstallHelper.c:764-769, src/Main/InstallHelper.c:1334-1336, src/engine_config.h:263"
+    note: |
+      4-byte marker. The install helper writes JKRES_MAGIC_1 into it once the
+      assets are copied, 0x699232C4 for this game. At startup a missing
+      marker sends the engine to the required-asset check.
+
+  - name: "jk1demo.gob"
+    path: "openjkdf2/episode/jk1demo.gob"
+    system: dark-forces-ii
+    category: game_data
+    required: false
+    source_ref: "src/Main/InstallHelper.c:654, src/Main/InstallHelper.c:841"
+    note: "Single-player episode of the demo, copied by the install helper when present."
+
+  - name: "jk1mpdem.gob"
+    path: "openjkdf2/episode/jk1mpdem.gob"
+    aliases: ["jk1mpdemo.gob"]
+    system: dark-forces-ii
+    category: game_data
+    required: false
+    source_ref: "src/Main/InstallHelper.c:655-656, src/Main/InstallHelper.c:842-843"
+    note: "Multiplayer episode of the demo. The install helper copies it under either name."
+
+  - name: "res1demo.gob"
+    path: "openjkdf2/resource/res1demo.gob"
+    system: dark-forces-ii
+    category: game_data
+    required: false
+    source_ref: "src/Main/InstallHelper.c:657, src/Main/InstallHelper.c:844"
+    note: "Resources of the demo, copied by the install helper when present."
 
   - name: "Res1low.gob"
-    path: "resource/Res1low.gob"
+    path: "openjkdf2/resource/Res1low.gob"
     system: dark-forces-ii
     category: game_data
     required: false
@@ -115,7 +153,7 @@ files:
   # ================================================================
 
   - name: "JKM.goo"
-    path: "episode/JKM.goo"
+    path: "openjkmots/episode/JKM.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
@@ -123,28 +161,28 @@ files:
     note: "Main MoTS single-player episode."
 
   - name: "JKM_KFY.goo"
-    path: "episode/JKM_KFY.goo"
+    path: "openjkmots/episode/JKM_KFY.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
     source_ref: "src/Main/InstallHelper.c:45 (aRequiredAssetsMots)"
 
   - name: "JKM_MP.goo"
-    path: "episode/JKM_MP.goo"
+    path: "openjkmots/episode/JKM_MP.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
     source_ref: "src/Main/InstallHelper.c:46 (aRequiredAssetsMots)"
 
   - name: "JKM_SABER.goo"
-    path: "episode/JKM_SABER.goo"
+    path: "openjkmots/episode/JKM_SABER.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
     source_ref: "src/Main/InstallHelper.c:47 (aRequiredAssetsMots)"
 
   - name: "Jkmres.goo"
-    path: "resource/Jkmres.goo"
+    path: "openjkmots/resource/Jkmres.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
@@ -152,13 +190,24 @@ files:
     note: "Shared MoTS engine resources."
 
   - name: "JKMsndLO.goo"
-    path: "resource/JKMsndLO.goo"
+    path: "openjkmots/resource/JKMsndLO.goo"
     system: mysteries-of-the-sith
     category: game_data
     required: true
     source_ref: "src/Main/InstallHelper.c:50 (aRequiredAssetsMots)"
     note: "Low-quality sound bank (MININSTALL/JKMSNDLO.GOO on the CD)."
 
+  - name: "jk_.cd"
+    path: "openjkmots/resource/jk_.cd"
+    system: mysteries-of-the-sith
+    category: game_data
+    required: true
+    source_ref: "src/Main/InstallHelper.c:51 (aRequiredAssetsMots), src/Main/InstallHelper.c:1318-1320, src/Main/jkRes.c:232-235, src/engine_config.h:267-270"
+    note: |
+      4-byte marker holding 0x3B426929. InstallHelper_SetCwd reads it at
+      startup and enables Mysteries of the Sith mode when it finds that
+      value.
+
   - name: "JKM.EXE"
     system: mysteries-of-the-sith
     category: game_data

emulators/sonic3-air.yml

@@ -42,11 +42,18 @@ notes: |
   (enginedata.bin, gamedata.bin, audiodata.bin, audioremaster.bin). Three
   are required and part of the release; audioremaster.bin is optional and
   downloaded on demand from https://sonic3air.org/download/audioremaster.bin
-  (126 MB) when the user enables the remastered soundtrack.
+  when the user enables the remastered soundtrack.
   ref: Oxygen/sonic3air/oxygenproject.json:32-38,
        Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:115-118,
        Oxygen/sonic3air/source/sonic3air/audio/RemasteredMusicDownload.cpp:48-62
 
+  Each package is opened from the game data directory, data/ under the
+  install directory, then from data/ under the app-data directory, where
+  the downloader saves audioremaster.bin. Package paths below are written
+  under sonic3-air/, which stands for either root.
+  ref: Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:643-651,
+       Oxygen/oxygenengine/source/oxygen/application/Configuration.cpp:288-289
+
   Only one RomInfo is declared (S3K_Steam). The engine does not support
   on-the-fly Sonic 3 + Sonic & Knuckles lock-on concatenation at run time;
   the user must supply the 4 MiB combined ROM (as distributed with Sega
@@ -69,13 +76,53 @@ files:
       accepts a user-picked .bin via the native file-selection dialog that
       satisfies the same post-modification check.
 
+  - name: "enginedata.bin"
+    path: "sonic3-air/data/enginedata.bin"
+    category: game_data
+    system: sonic3-air
+    required: true
+    bundled: true
+    source_ref: "Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:115, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:603-617, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:643-651"
+    note: |
+      Oxygen Engine data package. A required package that cannot be opened
+      closes the application, unless the data is present unpacked
+      (data/images/icon.png exists). The engine then checks for
+      oxygen_icon.png in the engine data and stops when it is absent
+      (EngineMain.cpp:584-593).
+
+  - name: "gamedata.bin"
+    path: "sonic3-air/data/gamedata.bin"
+    category: game_data
+    system: sonic3-air
+    required: true
+    bundled: true
+    source_ref: "Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:116, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:603-617, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:643-651"
+    note: |
+      Game data package. A required package that cannot be opened closes
+      the application, unless the data is present unpacked
+      (data/images/icon.png exists).
+
+  - name: "audiodata.bin"
+    path: "sonic3-air/data/audiodata.bin"
+    category: game_data
+    system: sonic3-air
+    required: true
+    bundled: true
+    source_ref: "Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:117, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:603-617, Oxygen/oxygenengine/source/oxygen/engine/EngineMain.cpp:643-651"
+    note: |
+      Audio data package. A required package that cannot be opened closes
+      the application, unless the data is present unpacked
+      (data/images/icon.png exists).
+
   - name: "audioremaster.bin"
+    path: "sonic3-air/data/audioremaster.bin"
     category: game_data
     system: sonic3-air
     required: false
-    source_ref: "Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:118 (mDataPackages, Required=false), Oxygen/sonic3air/source/sonic3air/audio/RemasteredMusicDownload.cpp:48-62"
+    source_ref: "Oxygen/sonic3air/source/sonic3air/EngineDelegate.cpp:118 (mDataPackages, Required=false), Oxygen/sonic3air/source/sonic3air/audio/RemasteredMusicDownload.cpp:45-62"
     note: |
-      Remastered soundtrack package (approx 126 MB). Downloaded on demand
-      from https://sonic3air.org/download/audioremaster.bin and reloaded
+      Remastered soundtrack package (131677405 bytes). Downloaded on demand
+      from https://sonic3air.org/download/audioremaster.bin, saved as
+      data/audioremaster.bin under the app-data directory and reloaded
       via EngineMain::reloadFilePackage. Absent at first launch; the
       engine falls back to the emulated FM soundtrack.