Firestaff game-data setup

Firestaff contains no game assets. Supply media from copies you own and point the launcher at the folder that contains them. The scanner identifies content by hash, so filenames and the surrounding folder layout are only suggestions.

No BIOS, firmware, System Card, operating-system ROM, or external emulator is part of the setup or is consulted by the production launcher. Game data is the complete runtime input contract.

Keep original archives and disc images intact. Firestaff can scan supported loose files, ZIP archives and disc-image containers directly; do not unpack your game collection just to make it visible to the launcher. A recognised file is a launch-data check, not a claim that every game is already playable. See the project status for that boundary.

For the exact container and record families that Firestaff currently knows, read the game-data format reference. It distinguishes decoded data from runtime-bound data and records the formats that deliberately remain opaque or closed.

Start requirements

These are the source-data roles that must be present before the launcher can admit a game. A matching name alone is never enough: the bytes must match a catalogued original edition.

For the three DAT-based games, both files are mandatory. Do not mix GRAPHICS.DAT from one release with DUNGEON.DAT from another. The launcher rejects an incomplete or mismatched pair instead of guessing a compatible version.

Optional original media

Optional means that the file is not needed to identify the basic launch data. It can still improve a presentation path, enable a language or make an original save available. Keep it with the matching edition when you have it.

Dungeon Master

TITLE/TITLE.DAT and SWOOSH/SWOOSH.DAT contain original startup and FTL presentation media. SONG.DAT supplies the original music where that edition includes it. The PC multilingual release can additionally provide DUNGEONF.DAT and DUNGEONG.DAT for French and German dungeon text; the English DUNGEON.DAT remains the base file.

For PC 3.4, Firestaff binds SONG.DAT only as the sibling of the admitted GRAPHICS.DAT source. This works for a member in a ZIP archive as well as a loose file, reads it in memory, and fails closed to silence if that exact installation has no compatible companion. It never borrows music from another data directory or extracts game data to disk.

Chaos Strikes Back

Original title, animation and utility media are optional to the data gate. Their names differ by platform and include SWOOSH, TITL.DAT, ENDA.DAT, HCSB.HTC, HCSB.DAT, ANIMATE.DAT, ANIMATE.SCR, ANIMATE.FTL, CHAOS.FTL and SWITCH.DAT. Keep campaign and utility saves such as MINI.DAT, MINIF.DAT, MINIG.DAT and CSBGAME.DAT only if you want to resume a source-supported save. They are never a substitute for the required graphics and dungeon pair.

Dungeon Master II: Skullkeep

DM2 has bounded native routes from authenticated DOS, Amiga, FM Towns and Macintosh source families. When several versions are present below one root, the launcher retains the selected edition as the sole source owner; a DOS data symlink is valid when it resolves to the verified DOS files. These routes do not yet establish complete presentation or campaign parity.

PC music is stored in the original GDAT data. FM Towns presentation media, including AUTOEXEC.BAT, TWANIM.EXP, SWOOSH, TITLE, SKULL.EXP and END, belongs with the original disc archive. Firestaff reads the MODE1/2352 disc image and animation streams in memory. The Japanese FM Towns disc is sufficient for every supported UI language: Firestaff maps its authenticated GDAT text keys to canonical gettext entries and applies the selected catalog. An optional PC English GRAPHICS.DAT may be supplied only for diagnostic cross-checking; it is never required and never replaces Towns game data.

The Amiga installer archive is read as the original in-memory LZX source. The The supported Mac retail ZIP keeps its HFS/resource-fork owner and big-endian dungeon records. Do not mix GRAPHICS.DAT and DUNGEON.DAT across editions.

The Amiga edition’s CD.DAT and SK00.MOD through SK09.MOD are its original map-music data. Keep them with the six-disk installer archive for the Amiga music route. SKSAVE files are optional resume media; they are not required for a new game and do not relax the source-data gate.

DM Nexus

The original Saturn disc also contains level, model, menu and sound resources, including LEV*.DGN, *.MNS, MENU.BPK, FACE.BIN, STABG.BIN, SLEV*.BIN and SNDLEV*.SAL/SNDLEV*.MAP. Keep the complete data track rather than collecting individual files. Audio CD tracks are preserved with the original disc image but are not part of the current data-admission check.

Theron’s Quest

Track 02 is the required game-data track. Other tracks, including Track 19 metadata/audio media, are optional to admission. Preserve the complete CUE/BIN set when you have it so original track layout and future media routes remain available.

Preserve the untouched complete CUE/BIN set when available. Firestaff’s product runtime is native and does not invoke an emulator or require a PC Engine System Card. Individual authenticated Track 02 BIN/ISO files remain valid native-runtime inputs; a partial dump is never described as a complete disc.

When TQUS02.bin and TQJP02.bin coexist under theron/, choose the native edition with firestaff --theron-native us or firestaff --theron-native jp. The option resolves only the named canonical file and then applies its exact Track 02 hash gate; a missing JP file cannot borrow the installed US file, or vice versa.

For native Theron, keeping the matching known full-disc archive beside the verified Track 02 also enables original Track 01 title audio automatically. The CUE and audio come only from the hash-known regional archive and are materialized below Firestaff’s private cache.

Suggested layout

The launcher searches recursively, so this layout is only for convenience:

~/.firestaff/data/
  dm1/
  csb/
  dm2/
  nexus/
  theron/

Use the launcher setting or --data-dir DIR to choose another root. Check what Firestaff recognises without launching a game:

firestaff --scan-data
firestaff --data-dir /path/to/your/games --scan-data

By default, scanning does not invoke external archive programs. If your original media is only present in an archive that the native readers do not support, opt in explicitly for the scan or launch:

firestaff --enable-external-archive-tools --scan-data
firestaff --enable-external-archive-tools --game dm1

This allows an installed 7zz, 7z, or bsdtar to inspect archive members; it can increase scan time. The scanner reports archive candidates it skipped and does not unpack game files beside the original archive. This option must be supplied to each command that needs it.

Scan cache

Firestaff stores verified file hashes in its local scan cache. On a later scan of the same directory it reuses that inventory instead of hashing every file again. Each cached result is rechecked against its path, size and modification time, so removed, replaced or changed files are scanned again automatically. The cache grows with the library and is local-only; it never contains game data and must not be committed.

Do not commit game data, saves or disc images to the Firestaff repository.

Runtime-media ownership

The scan cache is metadata only. It stores no decoded game payload and does not become a launch source. When a supported archive or disc image is chosen, Firestaff keeps that selected original container as the owner for the running session and reads the required members in bounded memory. It does not unpack or materialise game data beside the archive, in the system temporary directory or in an asset cache.

This rule is especially important for FM Towns CSB: the CUE identifies the correct raw CD member, and the image, ISO files and CDDA layout are consumed directly from the selected original container. Unsupported containers are rejected rather than silently expanded or substituted with data from a nearby edition.