Firestaff

Firestaff is a clean-room engine for the Dungeon Master games. It reads the original files you own, identifies each edition by its content hash and keeps that data separate from the program.

Firestaff has bounded native routes for Dungeon Master, Chaos Strikes Back, Dungeon Master II: Skullkeep and Theron’s Quest using verified original media. Nexus is available in the launcher and has Saturn data and asset support, but does not yet reach playable gameplay through Firestaff. Coverage is deliberately conservative: a route is available only when the selected edition has a verified native handoff. Full campaign, save and visual parity remain active work, especially for Chaos Strikes Back, Nexus and Theron’s Quest.

Current status

The status pages were reviewed on 2026-10-28 against a working tree based on main commit 56f99cdcf. Fast-dev compilation and the authentic-media test_m12_main_menu_game_selection_real_media.sh confirmed keyboard and mouse selection for all five game cards and no-game default-root handoff for all five games. The no-game launcher opens while the full scan continues and publishes game cards as each source handoff is admitted. Separate real-media runs reached the Firestaff runtime for DM1, CSB, DM2 and Theron’s Quest. Nexus currently stops at its Saturn title evidence gate, so its media discovery and card availability do not establish a playable game. These SDL dummy and CLI checks do not verify native display, audio, or physical input, and do not establish complete game parity.

Firestaff detects real media and exposes paths only after their handoff gates pass. Edition ownership is checked per route, and mixed-source combinations remain unsupported until their data identity is verified. A known Nexus extracted-files-plus-disc ambiguity is documented in the platform status. The detailed status is kept in project status. The published documentation is available at yeager.github.io/firestaff. The preservation status is a dated 2026-08-12 snapshot; use the current status pages for today’s support boundary.

Dungeon Master II: Skullkeep

DM2 has bounded native routes from four authenticated source families:

The shared DM2 data root may contain all four editions. Firestaff resolves a selected version to its own source owner: the DOS data tree or symlink, Amiga installer, FM Towns disc archive, or Mac archive. Original archives are kept intact and archive members are read into bounded memory; Firestaff does not use a sibling edition as a fallback.

The Macintosh M11 HUD loads each movement icon with its own palette from the retail archive. The original-media New Game route verifies the HUD, movement, stairs, level transitions and combat handoff.

Language selection

Firestaff offers 20 interface languages: English, Swedish, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Russian, Japanese, Korean, Simplified Chinese, Danish, Norwegian, Finnish, Hungarian, Turkish and Indonesian. Auto uses the system language when it is supported and otherwise uses English. A language chosen in the start menu or with --lang <code> takes precedence over Auto.

For the Japanese FM Towns edition of DM2, Firestaff keeps the original Towns disc as the only game-data owner. A built-in, GDAT-keyed bridge maps the disc’s authenticated text records to canonical English gettext entries, so no PC-English GRAPHICS.DAT is required at runtime. The selected catalog then applies the chosen supported language, including Swedish. Catalog completeness is checked in CI; an unavailable or invalid catalog falls back to canonical English rather than to text from another edition. See translation status for the generated per-language coverage.

Focused real-media checks and their current boundaries are documented in TODO-dm2.md, DONE-dm2.md, DM2 platform variants and the DM2 FM Towns wiki guide.

Theron’s Quest uses a DM1-like dungeon keyboard layout in Firestaff: Up/W moves forward, Down/S moves backward, Left/Right/A/D step sideways, and Q/E turn. Home/End and keypad 4/6 are alternate turn keys; keypad 1/3 step, 8/5 move forward and 2 moves backward. Tab selects the next living member of the Soul Room party; G picks up a source-verified item in the facing cell; P drops the selected source item on the party square; and U uses a door ahead.

The native dungeon view also provides a visible 4x3 Firestaff mouse panel. Its first two rows click to turn, move and sidestep; the remaining rows select the next champion, pick up or select an item, drop or use it, and wait. These host controls dispatch the same native Theron actions as the keyboard. They are not claimed as original PCE mouse hitboxes: the retail game is controller based, so clicks outside the panel are ignored until screen-space target semantics are authenticated. Mouse motion only moves the pointer. Mouse button 2 remains Button II for cancel/back and does not advance a dungeon tick by itself. On touch screens, a short touch is Button I and a long touch is Button II. The native dungeon presentation still needs a state-driven renderer, so working input dispatch alone does not establish visual gameplay parity.

Theron’s Quest runtime status

Firestaff runs Theron’s Quest through its native C/SDL runtime and admits hash-verified US or Japanese Track 02 data with --theron-native us or --theron-native jp. A native macOS Debug run with authentic Japanese Rev. 1 data advanced through stage select and Soul Room into a loaded dungeon using Firestaff’s SDL input path. The runtime reported about 2.8 game ticks/s and 5 rendered/presented frames/s in one interval. A follow-up native Linux Debug run on trv2 used Xvfb only as the SDL display and authentic JP Rev. 1 Track 02; it reached theron-runtime, loaded map 0 and advanced 73 game ticks in 18 seconds. No emulator ran the game. The latest Firestaff-presented capture is nonblack, but has not been paired with an original-emulator capture; original graphics-bank binding, palette and dungeon tile mapping are not yet connected to a validated renderer. These runs confirm native startup, input and tick-loop progress, not a visually playable game or complete parity. Source-only verification of all seven dungeon records establishes data admission, not campaign parity. Native movement, transitions, combat, audio, presentation and save parity remain open. README screenshots are Firestaff-rendered only; original-emulator captures are not presented as Firestaff output. See the platform status and capture handoff record for the evidence boundaries.

Chaos Strikes Back editions

Firestaff recognises original CSB editions by hash rather than by their folder names. The scanner currently covers the following families when the required matching data is present:

Recognition is deliberately separate from a playability claim. A recognised edition has passed the data gate; it does not imply that every screen, save format or gameplay path has reached parity. Firestaff keeps each edition on its own data path and never borrows files from another release to make a route appear to work.

CSBWin legacy saves

A complete original-named legacy CSBWin slot can resume with matching Atari ST 2.0/2.1 GRAPHICS.DAT and DUNGEON.DAT, from both the launcher and CLI:

firestaff --game csb --data-dir /path/to/CSB --save /path/to/CSBGAME2.DAT

The loader validates the full save body and source provenance before starting. It does not treat an arbitrary 512-byte header, renamed copy, compact roster, or DMSAVE.* file as a CSB resume. Extended Features/DSA saves remain fail-closed pending authenticated real-save coverage; its behavior is source-locked against CSBWin reference code and does not create a CSBWin game route.

Your game data

No game data is included. Keep your legally owned files in any directory and tell Firestaff where to look. It searches recursively and can inspect supported loose files, ZIP archives and disc-image containers without relying on filenames. Archives that need an external command-line tool are skipped by default. To allow an installed 7zz, 7z, or bsdtar to inspect them, pass --enable-external-archive-tools to the scan or game-launch command. The scan output identifies archive candidates it skipped. See game-data setup for details.

For the DAT-based games, GRAPHICS.DAT and DUNGEON.DAT must come from the same original edition. The launcher rejects incomplete or mismatched pairs. Optional title, animation, music and save files stay useful when they belong to the same edition, but they do not replace the required game data.

Suggested layout:

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

Use the launcher setting or --data-dir to select another root, then inspect what was recognised:

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

See game-data setup for the accepted media and the role of optional files for each game. The game-data format reference explains the verified containers, record families and save boundaries.

Firestaff never requires, searches for, reads, or bundles a BIOS, firmware, System Card, or external emulator. The only runtime input is your legally obtained game data in the local data directory; repository CI enforces this boundary.

The reproducible source dependency inventory is available as sbom/firestaff.spdx.json (SPDX 2.3). It excludes game media and every user-local input.

Included tools

Firestaff also ships desktop tools for working with files you own. They are optional and never run while playing a game.

The desktop bundles build translations from their .po source catalogs during packaging. Generated .mo files are not stored in the source tree.

Platform status at a glance

This table is a summary. Use Platform status for the exact feature boundary and Project status for cross-game evidence rules.

Running Firestaff

Build from source when a suitable package is not available:

git clone https://github.com/yeager/firestaff.git
cd firestaff
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=OFF
cmake --build build --target firestaff --parallel
./build/firestaff --scan-data

This builds the game without registering the large CTest suite or hashing test-only game archives during configuration. To configure the full test suite, use -DBUILD_TESTING=ON in a separate build directory, then build the specific test targets you need before running them with ctest.

Firestaff requires CMake, a C11 compiler and SDL3. On macOS, SDL3 is available through Homebrew:

brew install sdl3

Useful command-line options:

firestaff --game <dm1|csb|dm2|nexus|theron>
          --data-dir <path>
          --platform <auto|pc|amiga|atari-st|fm-towns|mac|pce|saturn>
          --dm1-fmtowns-ja
          --csb-fmtowns-ja
          --csb-utility-disk
          --scan-data
          --enable-external-archive-tools
          --fullscreen
          --scale-mode <n>
          --no-music | --music
          --version

--game starts the selected game directly. When you choose Return to Menu afterward, Firestaff exits. Add --menu to open the launcher first and return to it after the game ends.

Use the shared data root to choose a game in the five-game launcher:

./build/firestaff --menu --data-dir "$HOME/.firestaff/data"

To request one game from the command line, use its game ID:

./build/firestaff --game dm1 --data-dir "$HOME/.firestaff/data"
./build/firestaff --game csb --data-dir "$HOME/.firestaff/data"
./build/firestaff --game dm2 --data-dir "$HOME/.firestaff/data"
./build/firestaff --game theron --theron-native us --data-dir "$HOME/.firestaff/data/theron"
./build/firestaff --game nexus --platform saturn --data-dir "$HOME/.firestaff/data/nexus"

Theron accepts us or jp with --theron-native; choose the region whose authentic Track 02 data is installed. Nexus currently admits and renders the five authentic MAPD title planes in a bounded sequence, but Firestaff does not yet reproduce the native Saturn title composition or menu and its playable route remains gated. A successful menu selection or data scan does not by itself mean that a game is fully playable. See the platform status for each edition’s verified scope.

In the startup menu, Settings → Audio → Music Volume → Off disables music while preserving sound effects and UI audio. --no-music applies the same choice for a direct CLI launch; --music explicitly re-enables it.

Nexus decodes and renders the five retail MAPD title planes from the original CUE/BIN in a bounded sequence. That source-backed asset route does not yet reproduce the native Saturn title composition or menu. Ymir reference evidence confirms a no-save Japanese retail cold boot and a separate English-version disc-image cold boot to the native title menu, plus a separate Japanese diagnostic replay from New Game to a native 3D corridor viewport. Replaying the English screenshot from the captured frame reproduces it pixel-for-pixel; the English source join has 126 informative matches among 137 textured draws, with 11 zero-filled spans excluded. These are emulator results; they do not establish Firestaff’s full Saturn title composition or menu rendering/control. Firestaff’s menu, HUD, viewport and dungeon routes remain fail-closed until their real consumer ownership and presentation evidence is bound.

Firestaff never delegates Nexus startup or gameplay to Mednafen (or another emulator); emulator tooling is used only outside the product to obtain and validate capture evidence.

--csb-fmtowns-ja explicitly selects the hash-verified Japanese FM Towns package and fails if that original package is not present; it never guesses from the host language or substitutes the English package.

--dm1-fmtowns-ja explicitly selects the hash-verified Japanese FM Towns edition and fails closed if its original members are unavailable; the default FM Towns selection remains the English edition.

Theron’s Quest (PC Engine CD)

Place the original US Track 02 BIN in .firestaff/data/theron/ (or pass a data root that contains theron/TQUS02.bin). When both regions are installed, select either one without moving files:

./build/firestaff --theron-native us --data-dir "$HOME/.firestaff/data"
./build/firestaff --theron-native jp --data-dir "$HOME/.firestaff/data"

Hash-verified Track 02 members in external archives can also be read directly in memory when the installed host archive tool is explicitly enabled:

./build/firestaff --theron-native jp \
  --enable-external-archive-tools \
  --data-dir "$HOME/.firestaff/data/theron"

When both a loose regional BIN and an archive member are present, the loose BIN is preferred. Archive-only US and Japanese 7z startup—including the authentic Track 01 CDDA handoff—is covered by the theron_v1_us_7z_direct_boot and theron_v1_jp_7z_direct_boot real-media tests when those corpora are installed.

When a complete CUE is present, native startup may bind matching original Track 01 CDDA. A loose Track 02 never borrows audio from an unrelated file.

Firestaff’s native input path maps Enter to title, stage and Soul Room selection actions. These controls have not yet been shown on a rendered Theron frame. The mapping does not establish the original game’s multi-second button-hold timing. For original-menu capture guidance and the current unverified hold, see Theron input notes. The Japanese Rev 1 CUE then reaches the bounded native Akutuba runtime through hash-verified Track 02 records. For a headless, reproducible CLI receipt, use:

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy ./build/firestaff \
  --game theron --data-dir "$HOME/.firestaff/data/theron" --boot-probe \
  --script 'enter,enter,action' \
  --boot-probe-expect-phase theron-runtime --boot-probe-expect-runtime \
  --boot-probe-expect-level-loaded 1 --boot-probe-expect-party 1,0,0 \
  --boot-probe-expect-startup-active 0

This confirms the native source-backed runtime route, not a recovered PC Engine CD-runtime semantic handoff. Uncaptured creature AI, combat, generator, sound-effect and text-control semantics remain unavailable rather than being replaced with host behavior. --csb-utility-disk opens the separately preserved FM Towns C06 Utility Disk after the normal verified CSB F31 boot; it implies --game csb --platform fm-towns and fails closed if that package is unavailable. The start menu also has a dedicated CSB Utility Disk (FM Towns) entry. This is distinct from the Atari R1 Hint Oracle (--csb-hint-oracle) and never substitutes its data or UI. The Hint Oracle needs --data-dir <root> containing the verified Atari R1 HCSB.HTC, HCSB.DAT and native MINI.DAT; those files may be loose or inside a supported archive. --save <MINI.DAT> is optional and selects an explicit native save instead of the verified R1 MINI.DAT found in that root. The initial Japanese C06 Utility chooser additionally requires the user’s authorised 256 KiB FMT_FNT.ROM; set FIRESTAFF_FMTOWNS_FONT_ROM to that file before launch. Firestaff uses the ROM only for its original Shift-JIS glyphs and keeps the route closed if the file is missing or malformed; it never substitutes a system font or installs the ROM into game data.

Run the local test suite with:

ctest --test-dir build --output-on-failure

Some tests need original game data and skip when that corpus is not present.

How the project is built

The launcher selects a game and its verified data. The game layer then owns rendering, input and runtime state, while the data layer reads the original files and models the dungeon.

Launcher
  └─ Game runtime
       └─ Dungeon and data layer
            └─ Original game files supplied by the player

Gameplay work is checked against primary references. DM1 and CSB use ReDMCSB, with CSBWin and documented original formats as additional references. DM2 uses skproject; Nexus and Theron’s Quest use their respective platform analysis and original media.

The documentation index links the user guides, data notes and technical references. The project status is the place to check the current boundary before relying on a development route.

Legal

Firestaff is a clean-room engine reimplementation. You need game files from copies you legally own; the repository contains no copyrighted game data.

Dungeon Master, Chaos Strikes Back and Dungeon Master II are trademarks of FTL Games. DM Nexus is a trademark of Victor Interactive Software. Theron’s Quest is a trademark of Working Designs and Victor Interactive Software.

License

MIT. See LICENSE.