A text adventure game.

Dark Castle: Night of Awakening is a classic interactive fiction game. The player wakes inside a ruined castle, explores 8 rooms, collects 3 key fragments, assembles the Key of Awakening, and escapes through the sealed main door.

• 8 connected rooms with deterministic navigation
• 20+ interactive objects with pickup, use, open, read, combine, and light behaviors
• Puzzle logic based on physical common sense: light sources, locks, containers, and inventory limits
• A clean backend/frontend split for automated agent testing
• Session logging for replay and debugging

cd backend && pip install -r requirements.txt

python app.py

Open http://localhost:5000 in your browser.

                    [Attic]
                       |
[Bedroom] --- [Corridor] --- [Library]
                |
[Kitchen] --- [Hall] --- [Storage Room]
                |
            [Basement]

Type devmode or autoplay in the running game to launch the guided full-play demo:

• Runs the complete 38-step win path
• Shows live progress
• Can be interrupted with stop

The backend includes dedicated endpoints for agent-driven play:

# Create a game
curl -X POST http://localhost:5000/api/agent/new

# Send a command
curl -X POST http://localhost:5000/api/agent/command \
  -H "Content-Type: application/json" \
  -d '{"game_id":"<game_id>","command":"look"}'

See API Reference for the full contract.

dark-castle/
├── backend/                 # Python backend
│   ├── app.py               # Flask application
│   └── game/                # Game engine
├── .cache/                  # Generated cache artifacts
│   ├── data/                # Generated data files
│   └── log/                 # Session logs
├── frontend/                # Web frontend
│   ├── index.html
│   ├── css/style.css
│   └── js/
└── docs/                    # Project documentation

Each game session writes a JSON log into .cache/log/:

• Format: game_YYYYMMDD_HHMMSS_<game_id>.json
• Contains commands, responses, and lightweight state snapshots
• Browse via GET /api/logs

This project is useful for evaluating:

1. Spatial reasoning across connected rooms
2. Item interaction logic and inventory management
3. Physical common-sense reasoning around light, locks, and containers
4. Multi-step planning and puzzle solving
5. Natural-language command understanding