Porting Mainframe Zork to the Sharpee Interactive Fiction Engine
Project Dungeo is an ambitious effort to port the complete 1981 Mainframe Zork (MDL source: mdlzork_810722) to Sharpee, a modern interactive fiction engine. All 191+ rooms are implemented, with 32 treasures, canonical MDL combat, and the game is playable in browser, CLI, and Tauri desktop clients. The project has driven massive platform improvements including action interceptors, state machines, plugins, and a complete text pipeline.
Rooms: 191+ implemented
Score Achieved: 455 / 616 points in walkthroughs
Transcript Test Pass Rate: ~96% (1291 / 1333)
(entity as any) property patternsMatching MDL melee.137 and dung.355 exactly
Complete rewrite of combat to match the original 1981 MDL source. The fight-strength formula scales from 2 (score=0) to 7 (score=616). Nine outcome types per blow, three result tables (DEF1/DEF2/DEF3), wound tracking with 30-turn cure clock.
| Phase | Implementation | Status |
|---|---|---|
| 1. Melee Tables | 6 raw result arrays, fight-strength scaling | Done |
| 2. Melee Messages | 5 message tables, 3-7 variants per outcome | Done |
| 3. Melee Interceptor | ADR-118 attacking interceptor with preValidate/postExecute | Done |
| 4. Disengagement | Villain heals on flee, cure-daemon (30 turns/wound) | Done |
| 5. Thief Behavior | Canonical WINNING? function, engrossed state | Done |
| 6. DIAGNOSE | Canonical MDL wound descriptions | Done |
| 7. NPC Combat | Pluggable NpcCombatResolver, NPC-to-PC attacks | Done |
// DO/UNTIL transcript syntax for robust combat testing [RETRY: max=5] [DO] > attack troll with sword [UNTIL "troll breathes his last" OR "You have died"] [ENSURES: not entity "troll" alive] [END RETRY]
| Puzzle / Region | Mechanic | Status |
|---|---|---|
| Frigid River | 5 river rooms, boat navigation, launch action, shore landings | New Jan 11 |
| Rainbow Bridge | Wave sharp stick at Aragain Falls to solidify rainbow | New Jan 11 |
| Maze Topology | Complete rewrite: 15 rooms + 4 dead ends + 5 self-loops from MDL | Fixed Jan 12 |
| Coal Mine Maze | 7 rooms fully corrected against MDL source | Fixed Jan 12 |
| Dam Controls | Instant toggle matching FORTRAN objects.f (not multi-stage) | Fixed Jan 27 |
| Riddle Room | ANSWER "a well" opens passage to Pearl Room | New Jan 14 |
| Trap Door Auto-Close | State machine: slams shut and bars when player descends | New Jan 14 |
| Tea Room Cakes | Eat-me (shrink/teleport), Blue (enlarge), Red (dissolve pool), Orange (explosion) | New Feb 6 |
| Cage/Sphere Puzzle | Robot raises cage, 10-turn poison countdown, sphere taking interceptor | New Feb 6 |
| Low Room Carousel | Scrambled navigation; triangular button fixes both carousels | New Feb 7 |
| Gas Room Entry | ADR-126 destination interceptor blocks flame sources | New Feb 9 |
| Exorcism Ritual | Bell + Book + Candle sequence in Entry to Hades | Fixed Jan 23 |
Matching act1.254 and dung.355 exactly
if.action.taking, if.action.attacking, if.action.talkingMajor platform evolution driven by Dungeo requirements
I18N-Aware Entity Vocabulary — adjective system for disambiguation
Event Chaining — cascade/override/keyed modes for container reveals
Text Service Architecture — FyreVM channels, message templates, formatters
Domain Event Migration — meta/platform actions use domain events
Implicit Inference — pronoun-only single-candidate inference
Domain Events are Immutable Records — not pub/sub
Debug & Testing Extension — 24 $commands, playtester annotations
Browser Platform Package — reduced dungeo browser-entry from 1631 to 279 lines
Three-Tier Mutation Model — Actions, Daemons, Extensions
Stdlib Action Interceptors — 8+ actions with 5-hook interception
Declarative State Machines — states, transitions, guards, effects
Engine Plugin Architecture — priority-based turn processing
Entity Annotations — illustration/media metadata system
Destination Interceptors — room entry conditions (gas room)
Play Dungeo in CLI, browser, or desktop
| Platform | Details | Status |
|---|---|---|
| CLI | Node.js, transcript testing, --play interactive mode | Done |
| Browser | Infocom-style CSS, 4 themes (DOS, Modern, Retro, Paper), menu bar | Done |
| Zifmia Runner | .sharpee bundle (147KB), delta saves (~4KB), story library | Done |
| Tauri Desktop | Electron-alternative, 8 IPC commands, native file I/O | Done |
| Website | Astro + Tailwind, docs, games showcase, Play Dungeon page | Done |
Feature Complete — 650/650 Points (original scoring)
All 33 original treasures, 636 tests, published to npm.
6-Phase Parser Refactor
hasTrait API, 4-tier scope (AWARE/VISIBLE/REACHABLE/CARRIED), disambiguation, implicit takes. 266 parser tests. PR #49 merged.
Frigid River, Scoring Audit, Sceptre Removal
10 new river/shore rooms. Rainbow puzzle. FORTRAN scoring decoded (616 max). Sceptre removed (not in MDL). 20 treasure values fixed. Test pass rate: 74.7% to 88%.
Maze Rewrite, Scoring Complete, Adjective Disambiguation
Complete maze topology from MDL (22 rooms). Room visit scoring (215 pts, 13 rooms). LIGHT-SHAFT (10 pts). Death penalty. Fixed hard-coded empty adjectives. Pass rate: ~93%.
Event Chaining & Text Pipeline
ADR-094/095/096. FyreVM channel I/O. Message templates with formatters. Perspective placeholders. 33 formatter tests.
Playtest-Driven Fixes (TR-001/TR-002)
Trap door auto-close. Riddle room answer. 14+ room descriptions matched to 1981 MDL source exactly. Dynamic exit management pattern.
Browser Client, Pronoun Fix, 17+ Issue Fixes
Infocom-style browser client (1.0MB). Pronoun "it" pipeline fix. ADR-104 implicit inference. Engine remediation (-21%). Save/restore in browser. Egg protection. Sword glow daemon.
Troll Logic Complete + Universal Capability Dispatch
All canonical MDL troll features. 3 states, axe mechanics, recovery daemon, player interactions. Capability dispatch white paper. 104 troll tests.
Testing Infrastructure & React Client
89 transcripts baselined. ext-testing extension (24 $commands). React client with map, events, notes. 4 themes. Walkthroughs 1-6 all passing (165 tests). Pass rate: 46% to 86%+.
Trait Migration & Action Interceptors
467 ad-hoc property instances audited, ~20 new traits created. 0 remaining. ADR-118 interceptors on 8+ stdlib actions. Browser platform package (1631 to 279 lines). 4 browser themes.
Plugins, State Machines, Zifmia Runner
ADR-119/120. 5 state machines. 3 plugins (scheduler, state-machine, npc). .sharpee bundle format (147KB). Tauri desktop. Delta saves (~4KB).
Tea Room Region & Canonical Combat
8 new rooms, 4 cake mechanics, cage/sphere puzzle, carousel. 7-phase melee engine from MDL. Fight-strength scaling. 9 outcome types. 9 walkthroughs, 216 tests passing.
Coal Mine, Thief Fight, Combat Fixes
Gas room via ADR-126 destination interceptors. wt-10 coal mine (59 tests). wt-12 thief fight. UNCONSCIOUS bug fix. DO/UNTIL transcript syntax. Score: 455/616.
12 walkthrough chains + 89 unit transcripts
| Walkthrough | Description | Tests |
|---|---|---|
| wt-01 | Get Torch Early (troll fight) | 35 |
| wt-02 | Bank Puzzle | 16 |
| wt-03 | Maze & Cyclops | 25 |
| wt-04 | Dam & Reservoir | 17 |
| wt-05 | Egyptian Room | 10 |
| wt-06 | Exorcism Ritual | 19 |
| wt-07 | River & Rainbow | 37 |
| wt-08 | Egg from Tree | 9 |
| wt-09 | Tea Room | 44 |
| wt-10 | Coal Mine | 59 |
| wt-11 | Scattered Treasures | ~30 |
| wt-12 | Thief Fight | ~50 |
Test infrastructure features: $save/$restore checkpoints, DO/UNTIL loops for combat, RETRY blocks, NAVIGATE directives, contains_any assertions, $teleport for walkthrough reliability.
mdlzork_810722 is the ground truth, not the 1994 FORTRAN port. Room descriptions, treasure values, maze topology, combat tables, and puzzle mechanics all verified against MDL line numbers.
467 instances of (entity as any).property were audited and eliminated. Custom properties are NOT serialized by the checkpoint system. All mutable entity state must live in proper traits.
ADR-118 interceptors replace event handlers for "one entity + one action" patterns. Handlers remain for time-based daemons, multi-entity coordination, and custom event orchestration.
Pre-check loops (WHILE) check state. Post-check loops (DO/UNTIL) check output. Combat testing needs post-check because the condition ("enemy died" vs "player died") only appears in command output.
esbuild can resolve stale dist-npm/ files over current dist/. Explicit --alias flags in build.sh ensure the correct module versions are bundled.
| Date | Score | Milestone |
|---|---|---|
| Jan 3 | 650/650 | Original scoring system (pre-FORTRAN audit) |
| Jan 11 | 616 target | FORTRAN scoring decoded, values corrected |
| Feb 9 (before fix) | 20/616 | Scoring bug discovered (ISSUE-053) |
| Feb 9 (after fix) | 281/616 | TreasureTrait moved to platform, scoring fixed |
| Feb 9 | 291/616 | Exorcism achievement fix (+10) |
| Feb 9 | 328/616 | Coal mine treasures (+37) |
| Feb 10 | ~455/616 | Scattered treasures + thief death |
| Category | Items |
|---|---|
| Combat Blocker | meleeOstrength=0 initialization bug (troll starts dead); meleeWoundAdjust=-1 (player starts wounded) |
| Missing Walkthroughs | Coal mine volcano, well/tea room edge cases, mirror rooms, royal puzzle, endgame sequence |
| Platform Bugs | ISSUE-052 (capability registry cross-module), ISSUE-054 (template placeholders), ISSUE-055 (nested container scope) |
| Remaining Score | 161 points remaining: room visits, remaining treasures, endgame achievements |
| Test Failures | 28 pre-existing: basket(7), trophy case(7), troll recovery(5), flooding(4), other(5) |
The game is fully playable across CLI, browser, and desktop!
191+ rooms, 32 treasures, canonical MDL combat, 12 walkthrough chains, 455/616 points achieved. Original Mainframe Zork lives again.