YIKES is a framework for creating LLM-powered text adventures using context engineering. It provides a structured approach to maintaining game state and communicating with language models, enabling rich, interactive storytelling experiences.
Context Engineering Flow
┌──────────────────┐ ┌─────────────────────┐ ┌──────────────────┐
│ Game State │ │ LLM Response │ │ State Update │
│ ───────────── │ │ ───────────── │ │ ───────────── │
│ - System │ │ { │ │ - Parse Effects │
│ - Character │──► │ narrative: "...", │──► │ - Update State │
│ - World │ │ effects: {...}, │ │ - Save History │
│ - History │ │ actions: [...] │ │ - Validate │
└──────────────────┘ │ } │ └──────────────────┘
▲ └─────────────────────┘ │
│ │
└────────────────────────────────────────────────────┘
State Feedback Loop
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ User Input │ │ Game Master │ │ Response │
│ ────────── │ │ ────────── │ │ ────────── │
│ "look around" │───────► │ Context-aware │───────► │ Rich narrative │
│ "take sword" │ │ State-tracking │ │ State changes │
│ "talk to NPC" │ │ Rule-enforcing │ │ New actions │
└─────────────────┘ └─────────────────┘ └─────────────────┘
The system must maintain a hierarchical state structure:
{
system: {
role: "Game Master",
rules: [...],
constraints: [...]
},
character: {
current: {...},
history: [...],
relationships: [...]
},
world: {
current_location: {...},
known_locations: [...],
active_quests: [...]
}
}All interactions with the LLM must use a structured format:
{
"narrative": "Description of what happens",
"effects": {
"health_change": number,
"discovered_features": ["array of new features"],
"knowledge_gained": ["array of new information"],
"inventory_changes": {
"add": ["items to add"],
"remove": ["items to remove"]
}
},
"available_actions": ["possible", "next", "actions"]
}Any implementation must support:
-
State Tracking
- Health/status management
- Inventory system
- Discovery logging
- Feature tracking
-
Error Handling
- Response validation
- Graceful fallbacks
- State consistency checks
-
Basic Commands
- Status display
- Game exit
- Help system
-
State Updates
- Validate all state changes
- Maintain state consistency
- Handle edge cases gracefully
-
Response Processing
- Parse structured responses
- Handle missing or malformed data
- Maintain conversation context
-
User Interface
- Clear status display
- Intuitive command system
- Helpful error messages
- Node.js - Reference implementation using Ollama
We welcome new implementations in different languages and frameworks. When contributing:
-
Create a new directory under
implementations/ -
Include a README with:
- Setup instructions
- Dependencies
- Usage examples
- Implementation-specific details
-
Follow the core requirements:
- Structured state management
- Standard communication protocol
- Required features implementation
ISC License - See LICENSE.md for details.