Porting Mainframe Zork to the Sharpee Interactive Fiction Engine
Project Dungeo is an ambitious effort to port the complete Mainframe Zork (also known as "Dungeon") to Sharpee, a modern interactive fiction engine. The project is feature-complete with all 169 rooms, 33 treasures (650 points), and continues to expand puzzle mechanics and infrastructure improvements.
Rooms: 169 / 169
Treasures: 650 / 650 points
Core Puzzles: 25+ implemented
World state verification discovered silent failures
The "dropping bug" revealed that stdlib actions could appear to work (emit events, show messages) while failing to actually mutate world state. This pattern was also found in the drinking action. Both are now fixed with comprehensive world state verification tests.
// New golden test pattern ensures actual mutations expect(world.getLocation(ball.id)).toBe(room.id); // Precondition executeAction(droppingAction, context); expect(world.getLocation(ball.id)).toBe(player.id); // CRITICAL - verify mutation
| Puzzle | Mechanic | Status |
|---|---|---|
| Balloon Flight | Inflate/deflate, TIE wire to railing, daemon-controlled flight | New Jan 4 |
| Coal Machine | PUT COAL IN MACHINE, TURN ON SWITCH creates diamond | New Jan 5 |
| Coffin Transport | Gold coffin becomes takeable after dam drains reservoir | New Jan 5 |
| Basket Elevator | LOWER/RAISE basket via capability dispatch pattern | New Jan 5 |
| Tiny Room/Pool | Size-based access to tiny room via pool | New Jan 5 |
| Rope Puzzle | TIE ROPE TO RAILING in Dome Room for descent | New Jan 9 |
| River Navigation | Boat as vehicle, river entry blocked without boat | New Jan 7 |
| Dam Flooding | Dam controls flood/drain reservoir over time | New Jan 4 |
Natural language commands for robot NPC
Implemented comprehensive robot command system matching Mainframe Zork FORTRAN source:
> tell robot to follow "Whirr, buzz, click!" > robot, push button The robot presses the button... [Carousel mechanism activates] > order robot to dance "I am only a stupid robot and cannot perform that command."
Robot recognizes: FOLLOW, STAY, PUSH BUTTON, WALK, TAKE, DROP, PUT, THROW, TURN, LEAP
Scoring System - Event-based scoring to solve handler collision
Event Handler Unification - Multiple handlers per event type
Action-Centric Grammar - .forAction() API for verb patterns
Grammar Engine Refactor - Cleaner pattern matching
Pronoun Identity System - IT/THEM/HIM/HER resolution
Entity-Centric Action Dispatch - Capability behaviors
Text Decorations - Styled text output support
Smart Transcript Directives - Enhanced test assertions
Total ADRs: 99 (92 in main documentation)
Feature Complete - 650/650 Points!
Egg/Canary/Bauble puzzle. Mail Order system. All 33 treasures. 636 tests.
Balloon Puzzle & Scoring ADR
3-phase balloon implementation. Braided wire fix. ADR-085 scoring system. Dam flooding mechanics. Undo system. GDT KL command.
Advanced Puzzles & Grammar Fixes
Coal machine, coffin transport, basket elevator, tiny room puzzles. Grammar conflict resolution. ADR-087 action-centric grammar.
Critical Bug Fixes & Robot Commands
Dropping action fix (missing moveEntity). Robot COMMANDING action. River navigation with boat mechanics. Wave/rainbow puzzle fix. Stdlib test review analysis reveals drinking bug.
Stdlib Testing Initiative
Drinking action fix. World state verification tests (golden tests). stdlib-testing branch merged. 24 new mutation verification tests.
Region Consolidation & Rope Puzzle
6 regions consolidated into single files. Dome Room rope puzzle. Magic word system. Walkthrough chain fixes. 61 transcript tests.
Golden tests ensure actions actually mutate state
After discovering the dropping/drinking bug pattern, we established "golden tests" that verify:
Coverage: taking, dropping, putting, going, drinking, inserting, removing, entering, exiting
An action can emit perfect events with perfect messages while failing to change world state. Always verify both events AND actual mutations.
ADR-090 established when to use capability dispatch (LOWER, RAISE, TURN) vs stdlib actions (TAKE, DROP, OPEN). Entity-specific behaviors implement 4-phase pattern.
Single-file regions are easier to maintain than scattered room/object files. Index.ts exports all creators and handles connections.
New verbs (SAY, INCANT, RING, COMMANDING) are story actions. Standard verbs with entity-specific behavior use capability dispatch.
| Category | Items |
|---|---|
| Vehicle Polish | Boat travel along full river, balloon landing variations |
| Testing | Full walkthrough transcript, edge case coverage |
| Documentation | Update CLAUDE.md with golden test patterns |
| Polish | Message refinements, additional room descriptions |
All core gameplay is complete!
Players can explore all 169 rooms, collect all 33 treasures (650 points), and achieve victory.
a322cfb refactor(dungeo): Complete region consolidation, fix walkthrough chain 050ba0f refactor(dungeo): Consolidate 6 regions into single files, fix aliases d476618 docs: Add session summaries and room catalog 1ba9b3b test(dungeo): Add transcripts for rope puzzle and walkthrough goals 389f8eb feat(dungeo): Add Dome Room rope puzzle and magic words 7442dfd fix(transcript-tester): Improve entity resolution and isAlive check 3df7014 feat(transcript-tester): Implement ADR-092 smart transcript directives cf51e9c Merge pull request #48 from ChicagoDave/stdlib-testing 30bb4e6 fix(stdlib): Complete stdlib testing mitigation plan 79152f3 fix(stdlib): Fix drinking action mutations + add world state tests b55834c fix(stdlib): Fix dropping action missing moveEntity