{"id":49262275,"url":"https://github.com/yeager/firestaff","last_synced_at":"2026-05-19T10:01:29.854Z","repository":{"id":352608640,"uuid":"1215795564","full_name":"yeager/firestaff","owner":"yeager","description":"Open Dungeon Master engine with V1 original-faithful mode, V2 enhanced 2D, and V3 modern 3D","archived":false,"fork":false,"pushed_at":"2026-05-10T06:07:40.000Z","size":220620,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-10T08:41:28.161Z","etag":null,"topics":["c","chaos-strikes-back","cross-platform","deterministic","dungeon-master","ftl-games","game-engine","linux","macos","open-source","preservation","retro-gaming","reverse-engineering","sdl3","windows"],"latest_commit_sha":null,"homepage":"https://github.com/yeager/firestaff","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yeager.png","metadata":{"files":{"readme":"README.md","changelog":"changelog_m12.c","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["yeager"]}},"created_at":"2026-04-20T09:05:45.000Z","updated_at":"2026-05-10T06:07:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yeager/firestaff","commit_stats":null,"previous_names":["yeager/firestaff"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/yeager/firestaff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeager%2Ffirestaff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeager%2Ffirestaff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeager%2Ffirestaff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeager%2Ffirestaff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yeager","download_url":"https://codeload.github.com/yeager/firestaff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeager%2Ffirestaff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33103971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","chaos-strikes-back","cross-platform","deterministic","dungeon-master","ftl-games","game-engine","linux","macos","open-source","preservation","retro-gaming","reverse-engineering","sdl3","windows"],"created_at":"2026-04-25T08:01:52.204Z","updated_at":"2026-05-16T13:04:29.723Z","avatar_url":"https://github.com/yeager.png","language":"C","funding_links":["https://github.com/sponsors/yeager"],"categories":[],"sub_categories":[],"readme":"# Firestaff\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/branding/firestaff-logo.png\" alt=\"Firestaff logo\" width=\"420\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/yeager/firestaff/actions/workflows/verify.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/yeager/firestaff/actions/workflows/verify.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Platforms\" src=\"https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey\"\u003e\n  \u003ca href=\"https://github.com/sponsors/yeager\"\u003e\u003cimg alt=\"GitHub Sponsors\" src=\"https://img.shields.io/badge/GitHub%20Sponsors-support%20Firestaff-pink\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Firestaff is a long-haul reverse-engineering and parity project. If you want to help fund the verification runs, reference capture work, packaging, and token burn behind it, you can support it at \u003ca href=\"https://github.com/sponsors/yeager\"\u003eGitHub Sponsors\u003c/a\u003e.\n\u003c/p\u003e\n\nAn open-source engine project for **Dungeon Master** (1987), **Chaos Strikes Back** (1989), and later **Dungeon Master II**, with a clear three-track product plan:\n\n- **V1, Original**: original-faithful presentation and behaviour, with a shared startup menu above the games\n- **V2, Enhanced 2D**: higher-resolution 2D presentation, wider aspect ratios, richer assets, same game feel\n- **V3, Modern / 3D**: a later full reinterpretation\n\n## Status\n\n**Firestaff 0.2.0 is an early macOS preview release.**\n\nIt already has a real launcher, a real in-game DM1 slice, a modern high-resolution startup menu, bounded original-version detection, and a growing verified engine core. Recent work has also tightened V1 parity honestly: movement / door / sensor ownership is being pushed into source-backed compat/runtime paths, original-reference tooling is now in-tree, and `SONG.DAT` decoding groundwork has landed.\n\n**Working today:**\n- launcher with DM1 / CSB / DM2 entries\n- modern high-resolution true-color startup menu (1280x720 HD, 24-bit RGB) as the shared front door\n- persistent startup settings\n- selected-version status and per-game checksum indicators in the startup menu\n- MD5-based original-data detection for bounded DM1 / CSB / DM2 version sets\n- self-contained macOS app packaging with bundled SDL3 for preview releases\n- explicit launcher / game / settings flow\n- real dungeon loading from `DUNGEON.DAT`\n- real movement / facing / ticking backed by world state\n- melee attack, item, spell, stair, pit, teleporter, XP, save/load, and survival slices wired through the game core\n- source-backed ownership migration landed for post-move environment, movement legality, door actuation, sensor runtime wiring, animating door states, and creature walkability\n- increasingly asset-backed viewport rendering using real `GRAPHICS.DAT` data\n- original-reference capture / overlay tooling now exists for stricter V1 parity measurement\n- `SONG.DAT` format + loader/decoder groundwork is landed and probe-verified\n- deterministic verification suite still green\n\n**Not there yet:**\n- full V1 original-presentation parity\n- complete CSB / DM2 runtime support\n- runtime audio still uses placeholder playback paths even though `SONG.DAT` decoding groundwork exists\n- full endgame / dialog / launcher-product polish\n- final cross-platform packaging\n\n## Creature Art\n\nFirestaff currently ships five finished launcher creature cards, with five more creatures tracked as the next art set.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/cards/creatures/red-dragon.png\" alt=\"Red Dragon\" width=\"180\"\u003e\n  \u003cimg src=\"assets/cards/creatures/skeleton.png\" alt=\"Skeleton\" width=\"180\"\u003e\n  \u003cimg src=\"assets/cards/creatures/stone-golem.png\" alt=\"Stone Golem\" width=\"180\"\u003e\n  \u003cimg src=\"assets/cards/creatures/giant-scorpion.png\" alt=\"Giant Scorpion\" width=\"180\"\u003e\n  \u003cimg src=\"assets/cards/creatures/mummy.png\" alt=\"Mummy\" width=\"180\"\u003e\n\u003c/p\u003e\n\nFinished card art currently shown in the launcher sidebar:\n- Red Dragon\n- Skeleton\n- Stone Golem\n- Giant Scorpion\n- Mummy\n\nNext creature set tracked for card-art follow-up:\n- Swamp Slime\n- Giggler\n- Screamer\n- Demon\n- Vexirk\n\nThe finished creature cards in `assets/cards/creatures/` are used in the startup menu sidebar today, selected fresh each launch. The remaining five creatures are present in the repository as reference inputs and should be promoted to finished launcher cards before they are shown in the README gallery.\n\n## What Firestaff is\n\nFirestaff is a deterministic, modular re-implementation of the FTL Games engine, designed to run on **macOS, Linux, and Windows**.\n\nThe project is built around portable C, explicit data structures, and aggressive verification. The goal is not just to \"run the game somehow\", but to preserve its behaviour in a form that is inspectable, testable, and maintainable.\n\n## Current feature snapshot\n\n### Launcher\n- DM1 / CSB / DM2 game list\n- startup settings screen\n- built-in and external-ready card-art path\n- persistent configuration\n- clean base for explicit **V1 / V2 / V3** mode selection\n\n### Engine-backed game view\n- boots from real `DUNGEON.DAT`\n- enters a real game-view state from the launcher\n- movement / turning / ticking mutate real world state\n- melee attack, inspect, and champion cycling work in the live view\n- item pickup/drop, spells, stairs, pits, teleporters, XP, quicksave/load, and survival systems are wired through the core\n- viewport rendering now includes real walls, floor sets, ornaments, item sprites, creature sprites, dynamic lighting, torch decay, and combat feedback slices\n\n### Validation\n- deterministic verification remains green\n- DM1 asset detection is MD5-based, not filename-based\n- M10 remains protected while M11/M12 advance in verified slices\n- CSB / DM2 support is planned honestly, without pretending the runtime is already complete\n\n## Running Firestaff\n\n### Quick start for macOS preview\n\n1. Put your legal original game files under `~/.firestaff/originals/`\n2. Launch Firestaff\n3. Pick a game and version in the startup menu\n4. Look for a green checkmark before launch\n\nLauncher / game view:\n\n```sh\n./firestaff --data-dir \"$HOME/.firestaff/data\"\n```\n\nOriginal-data search order:\n1. an explicit path, if provided\n2. `~/.firestaff/originals/` on macOS/Linux, or `\u003cinstallation-directory\u003e\\originals` on Windows\n3. legacy Firestaff data-dir fallback such as `~/.firestaff/data/`\n\nVersion status in the startup menu:\n- green checkmark = matching original file(s) found for the selected version\n- red cross = selected version is missing or does not match the expected checksum\n- unmatched versions stay visible, but launch is blocked honestly until matching originals are found\n\nIn the game view: `Enter` inspects, `Space` acts or waits, `Tab` cycles the active champion, `Esc` returns to the launcher. You can also click the viewport to inspect, click the control strip to move/act, and click a party card to arm a champion directly.\n\nHeadless launcher smoke test:\n\n```sh\n./run_firestaff_m11_launcher_smoke.sh\n```\n\nVerification suite:\n\n```sh\n./run_firestaff_m10_verify.sh \"$HOME/.firestaff/data/GRAPHICS.DAT\"\n```\n\n## Roadmap\n\n### V1, Original\nThis is the priority track.\n\nGoal: make Firestaff feel like the original games first, with only a shared startup menu above them.\n\nCurrent focus:\n- original-facing presentation parity\n- original timing / animation / light behaviour\n- finishing the current V1 parity chain pass by pass, with source-backed blocker tracking instead of vague \"close enough\" claims\n- dialog and endgame runtime coverage\n- verified CSB and then DM2 runtime integration\n- bug/profile handling that preserves original behaviour where needed\n\n### V2, Enhanced 2D\nBuilt on top of a finished V1 baseline.\n\nPlanned direction:\n- higher resolution\n- wider aspect ratios including 16:9 and 4K presentation\n- richer 2D assets and UI polish\n- improved readability without losing the underlying game feel\n\nCurrent bounded V2 UI slice status:\n- real Wave 1 assets exist for the viewport frame, action area, spell area, status-box family, party HUD cell family, and a first shared four-slot party HUD strip expansion\n- the current engine-side V2 slice remains opt-in behind `FIRESTAFF_V2_VERTICAL_SLICE=1`\n- a first bounded initial in-game 4K capture/composition path now exists; see `assets-v2/ui/wave1/vertical-slice/FIRST_4K_RENDER.md`\n- portraits and a full final HUD typography system are still pending future V2 passes\n\n### V3, Modern / 3D\nA later reinterpretation track.\n\nPlanned direction:\n- modern presentation\n- 3D rendering\n- freer redesign, built only after V1 has a trustworthy parity baseline\n\n## Design principles\n\n- **V1 parity comes before V2/V3 polish**\n- **Use real game data whenever possible**\n- **Do not fake support we have not verified**\n- **Keep deterministic behaviour intact**\n- **Build additive slices that stay green**\n- **Prefer honest progress over flashy shortcuts**\n\n## Credits\n\nFirestaff's development has been informed by **Christophe Fontanel's** reverse-engineering work on [ReDMCSB](http://dmweb.free.fr/community/redmcsb/). His documentation of the original engine's bugs, quirks, and mechanics has been invaluable as a reference, though no ReDMCSB source code is included in Firestaff.\n\nThe original Dungeon Master and Chaos Strikes Back games were designed by **Doug Bell**, **Dennis Walker**, **Mike Newton**, **Andy Jaros**, and **Wayne Holder** at FTL Games.\n\n## Licence\n\nFirestaff is released under the **MIT Licence**. See [LICENSE](LICENSE).\n\nThis licence covers **only the engine code**. Dungeon Master and Chaos Strikes Back are © FTL Games / Software Heaven, Inc. You must own a legal copy of the original games to use them with Firestaff. No original assets are distributed with this project.\n\n## Sponsorship\n\nIf you want to help fund the absurd amount of reverse-engineering, verification, packaging, captures, and token burn behind Firestaff, you can sponsor the project on GitHub Sponsors.\n\n- GitHub Sponsors: **https://github.com/sponsors/yeager**\n\nIt helps pay for the unglamorous but essential work: long parity passes, capture tooling, verification runs, and keeping the project moving without pretending the hard parts are already solved.\n\n## Contributing\n\nIssues and discussion are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for repository policy and current contribution guidance.\n\n## Links\n\n- Dungeon Master Encyclopaedia: [dmweb.free.fr](http://dmweb.free.fr/)\n- ReDMCSB reference project: [dmweb.free.fr/community/redmcsb/](http://dmweb.free.fr/community/redmcsb/)\n- Project tagline: *An open Dungeon Master engine, deterministic, modular, museum-grade*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeager%2Ffirestaff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeager%2Ffirestaff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeager%2Ffirestaff/lists"}