Error Boundaries 🎮🤖

A self-improving RPG game engine where AI agents collaborate with you to build games in real-time

🌟 Overview

Error Boundaries is a revolutionary game development framework that combines:

🎮 Traditional RPG gameplay with a meta-programming twist
🤖 Multi-agent AI system with specialist bots (Rendering, Mechanics, Story, Data, Testing, Assets)
🔧 Real-time game development powered by Claude AI via API and MCP server
🛡️ Error Boundary architecture that monitors system health and self-heals
🎯 Entity-Component-System (ECS) for flexible game architecture
📚 RAG-based knowledge system with vector embeddings and concept graphs

What Makes This Unique?

In Error Boundaries, bugs don't crash the game—they become part of the gameplay. Error entities spawn when systems degrade, and the AI bots work to fix issues while you play. It's a living game that evolves through AI-assisted development.

🎮 Included Mini-Games

The engine comes with several complete mini-games demonstrating different mechanics:

Game	Genre	Description
Dojo Warriors	Fighting	Martial arts combat with belt progression and special moves
Pixel Dive	Underwater Adventure	Dive for treasure, manage oxygen, fight sea creatures
Asteroid Miner	Space Mining	Mine asteroids, fight pirates, upgrade your ship
Gem Matcher	Puzzle	Match-3 gem puzzle with combos and power-ups
Robot Rumble	Combat Arena	Build and battle robots with upgrades
Turbo Track	Racing	High-speed racing with vehicle upgrades
Tower Scramble	Platformer	Climb towers, collect items, avoid obstacles
Block Cascade	Puzzle	Falling blocks with cascade mechanics
Street Brawler	Beat 'em Up	Side-scrolling combat action
Laser Guardian	Defense	Protect your base from waves of enemies
Neon Bullet Storm	Bullet Hell	Dodge patterns, shoot enemies
Cosmic Siege	Space Shooter	Space combat with power-ups
Void Defenders	Tower Defense	Strategic tower placement and upgrades
Starblast Squadron	Space Combat	Team-based space warfare

🚀 Quick Start

Prerequisites

Python 3.10 or higher
Windows/Linux/macOS
Anthropic API key (for AI bots) or OpenAI API key

Installation

Clone the repository

git clone <your-repo-url>
cd "Error Boundaries"

Install dependencies

pip install pygame chromadb networkx numpy python-dotenv anthropic openai mcp flask flask-cors

Verify setup (optional)
```
python setup_check.py
```
This will verify all packages are installed and directories are in place.
Set up environment variables

Copy the example file and add your API keys:
```
# On Windows
copy .env.example .env

# On Linux/Mac
cp .env.example .env
```
Edit .env and add your API key:
```
ANTHROPIC_API_KEY=your_anthropic_key_here
```
Note: The knowledge base (ChromaDB) is included in the repository, so you don't need to regenerate it! Just add your API key and you're ready to go.

Run the game!

# With AI bots (requires API key)
python main.py

# Or without AI (just play the games)
python main.py --no-bots

Command Line Options

python main.py [options]

Options:
  --no-bots          Disable AI bot system (runs as regular game)
  --no-mcp           Disable MCP server
  --debug            Enable debug mode with verbose logging
  --fps FPS          Target frame rate (default: 60)
  --width WIDTH      Window width (default: 1280)
  --height HEIGHT    Window height (default: 720)
  --fullscreen       Start in fullscreen mode

Quick Test

# Run without AI bots (faster startup)
python main.py --no-bots

# Run with full AI system
python main.py

# Run in debug mode
python main.py --debug

🏗️ Architecture

Core Components

Error Boundaries/
│
├── 🎮 engine/                   # Core game engine
│   ├── core/                    # ECS, event system, game loop
│   ├── ecs/                     # Entity-Component-System
│   ├── boundaries/              # Error boundary monitoring
│   ├── subsystems/              # Rendering, audio, physics
│   └── gameplay/                # Entity factories, game logic
│
├── 🕹️ game/                     # Game implementations
│   ├── *_game.py               # Individual mini-games
│   ├── systems/                 # Game systems (input, combat, etc.)
│   ├── utils/                   # Game utilities
│   └── entities/                # Entity templates (JSON)
│
├── 🤖 bots/                     # Multi-agent AI system
│   ├── core/                    # Orchestrator, communication, tasks
│   │   ├── orchestrator.py     # Coordinates specialist bots
│   │   ├── bot_base.py         # Base bot class
│   │   ├── communication.py    # Message bus for inter-bot comms
│   │   └── task_queue.py       # Priority task distribution
│   │
│   ├── specialists/             # Specialist AI bots
│   │   ├── rendering_bot.py    # Graphics & UI specialist
│   │   ├── mechanics_bot.py    # Gameplay mechanics specialist
│   │   ├── story_bot.py        # Narrative & dialogue specialist
│   │   ├── data_bot.py         # Data management specialist
│   │   ├── testing_bot.py      # Testing & QA specialist
│   │   └── asset_bot.py        # Asset management specialist
│   │
│   ├── knowledge/               # RAG knowledge base
│   │   ├── knowledge_base.py   # ChromaDB + NetworkX
│   │   ├── embeddings.py       # Vector embeddings
│   │   ├── graph_db.py         # Concept graph
│   │   └── first_principles/   # Seed knowledge (JSON)
│   │
│   ├── tools/                   # Bot tools
│   │   └── engine_api.py       # High-level engine interface
│   │
│   └── api/                     # HTTP API server
│       └── http_server.py      # Claude Code integration (port 5555)
│
├── 🔌 mcp_server/               # Model Context Protocol server
│   ├── server.py                # MCP server for Claude Desktop
│   ├── tools/                   # MCP tool implementations
│   └── streaming.py             # Real-time event streaming
│
├── 📊 data/                     # Runtime data
│   ├── knowledge/               # Knowledge base storage
│   ├── saves/                   # Save files
│   └── templates/               # Entity templates
│
├── 🎨 assets/                   # Game assets
│   ├── sprites/                 # Images
│   ├── audio/                   # Sounds & music
│   └── fonts/                   # Fonts
│
├── 📝 docs/                     # Documentation
└── 🧪 tests/                    # Test suite

System Flow

graph TD
    A[Player/Claude Code] --> B[HTTP API :5555]
    A --> C[MCP Server]
    B --> D[Orchestrator Bot]
    C --> D
    D --> E[Task Queue]
    E --> F1[Rendering Bot]
    E --> F2[Mechanics Bot]
    E --> F3[Story Bot]
    E --> F4[Data Bot]
    E --> F5[Testing Bot]
    E --> F6[Asset Bot]
    F1 --> G[Engine API]
    F2 --> G
    F3 --> G
    F4 --> G
    F5 --> G
    F6 --> G
    G --> H[Game Engine/World]
    H --> I[Boundary Registry]
    I --> J[Health Monitor]
    J -.feedback.-> D

🤖 AI Bot System

Orchestrator Bot

The orchestrator receives high-level requests and coordinates specialist bots:

# Example: Natural language game modification
result = await orchestrator.process_prompt(
    "Create a quest where the player collects 10 magic mushrooms"
)

Specialist Bots

Each specialist has deep expertise in their domain:

Bot	Responsibilities
Rendering Bot	Graphics, UI/UX, shaders, visual effects, animations
Mechanics Bot	Game mechanics, physics, interactions, combat systems
Story Bot	Narrative design, dialogue, characters, quests, lore
Data Bot	Data structures, serialization, save/load, schemas
Testing Bot	Test creation, validation, QA, boundary monitoring
Asset Bot	Asset management, loading, optimization, pipelines

Knowledge Base

The bots use a RAG (Retrieval-Augmented Generation) system:

ChromaDB: Vector embeddings for semantic search
NetworkX: Concept graph for relationships
50+ game concepts: Seeded knowledge about game development

# Query the knowledge base
results = knowledge_base.query(
    "How do I implement a quest system?", 
    n_results=5
)

# Traverse concept relationships
related = knowledge_base.get_related_concepts(
    "quest", 
    max_depth=2
)

🔌 Integration with Claude Code

HTTP API (Port 5555)

The bot system exposes an HTTP API for external integration:

# Get bot status
curl http://localhost:5555/bots/status

# Send a prompt to orchestrator
curl -X POST http://localhost:5555/bots/orchestrator/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add a health potion item"}'

# Query knowledge base
curl -X POST http://localhost:5555/knowledge/query \
  -H "Content-Type: application/json" \
  -d '{"query": "combat system", "n_results": 3}'

MCP Server

The MCP (Model Context Protocol) server allows Claude Desktop to interact with the game:

Available MCP Tools:

prompt_game_change - Natural language game modifications
get_game_state - Query current game state
get_error_boundaries - Check system health
query_knowledge_base - Search game dev concepts
get_bot_status - Monitor bot system
force_spawn_error - Test error handling

Setup for Claude Desktop:

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "error-boundaries": {
      "command": "python",
      "args": ["C:\\path\\to\\Error Boundaries\\mcp_server\\server.py"]
    }
  }
}

🎯 Game Controls

Basic Controls

WASD / Arrow Keys - Move player
Mouse - Aim/interact (game-specific)
Space - Jump/action
ESC - Pause menu
P - Pause/Resume
F1 - Toggle debug overlay

Debug Controls (when --debug enabled)

F2 - Show entity inspector
F3 - Show system performance
F4 - Show boundary health
F5 - Spawn test error
` (Backtick) - Open bot console

🛡️ Error Boundary System

Each game subsystem is wrapped in an error boundary that:

Validates changes against defined contracts
Tracks health (0.0 = critical, 1.0 = perfect)
Logs errors and violations
Triggers AI bots when health degrades
Spawns error entities as gameplay elements

# Error boundaries monitor critical systems
boundaries = [
    "rendering",    # Graphics rendering
    "mechanics",    # Game mechanics
    "story",        # Narrative systems
    "data",         # Data management
    "audio",        # Sound systems
    "physics",      # Physics simulation
]

When a boundary's health drops below threshold, the corresponding specialist bot is automatically tasked with diagnosis and repair.

📚 Entity-Component-System (ECS)

Core Concepts

Entities: Unique IDs with components

player_id = world.create_entity()

Components: Pure data (no logic)

world.add_component(player_id, Transform(x=100, y=200))
world.add_component(player_id, Health(current=100, maximum=100))
world.add_component(player_id, Velocity(dx=0, dy=0))

Systems: Logic that operates on component combinations

class MovementSystem(System):
    def update(self, world, dt):
        for entity_id in world.get_entities_with_components(Transform, Velocity):
            transform = world.get_component(entity_id, Transform)
            velocity = world.get_component(entity_id, Velocity)
            
            transform.x += velocity.dx * dt
            transform.y += velocity.dy * dt

Available Components

Core: Transform, Velocity, Health, Renderable, Collider, Tag

Gameplay: Player, Enemy, Inventory, Quest, Dialogue, AI

Effects: Particle, Animation, SoundEmitter, Light

🔧 Development

Creating a New Game

Create game file in game/ directory:

class MyGame:
    def __init__(self):
        self.score = 0
    
    def update(self, dt, keys, mouse_pos):
        # Update game logic
        pass
    
    def render(self, screen):
        # Render game
        pass

Register with engine:

from game.my_game import MyGame

# In main.py or registration script
game_registry.register_game(
    game_id="my_game",
    game_class=MyGame,
    metadata={
        "name": "My Awesome Game",
        "description": "A cool game",
        "author": "You"
    }
)

Adding New Components

# In engine/ecs/component.py
from dataclasses import dataclass
from engine.ecs.component import Component

@dataclass
class MyComponent(Component):
    my_field: int = 0
    my_other_field: str = ""

Adding New Systems

# In game/systems/
from engine.core.system import System
from engine.ecs.world import World

class MySystem(System):
    def __init__(self):
        super().__init__(priority=50)  # Lower = earlier
    
    def update(self, world: World, dt: float) -> None:
        # Your system logic here
        for entity_id in world.get_entities_with_components(MyComponent):
            component = world.get_component(entity_id, MyComponent)
            # Do something with component

Creating Entity Templates

Create JSON files in data/templates/:

{
  "name": "Magic Potion",
  "components": {
    "Transform": {
      "x": 0,
      "y": 0
    },
    "Renderable": {
      "sprite_path": "assets/sprites/potion.png",
      "layer": 5,
      "width": 32,
      "height": 32
    },
    "Collider": {
      "radius": 16
    },
    "Item": {
      "item_type": "consumable",
      "effect": "heal",
      "amount": 50
    }
  }
}

🧪 Testing

# Run basic game test
python tests/test_basic.py

# Test ECS system
python tests/test_ecs_system.py

# Test bot orchestration
python tests/test_bot_orchestration.py

# Test specific game
python tests/test_dojo_warriors.py

# Test LLM integration
python tests/test_llm_manager.py

📖 Documentation

Detailed documentation is available in the docs/ directory:

FRAMEWORK_OVERVIEW.md - Bot framework architecture
BOT_INTEGRATION_COMPLETE.md - Bot integration guide
MCP_SETUP_INSTRUCTIONS.md - MCP server setup
*_SUMMARY.md - Individual game documentation

🤝 Contributing

Contributions are welcome! This project is designed to be extended and improved by both humans and AI.

Ways to Contribute

Create new mini-games using the engine
Add new components/systems to expand capabilities
Improve bot intelligence with better prompts/tools
Expand knowledge base with more game dev concepts
Add new specialist bots for additional domains
Improve documentation and examples

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly (python tests/test_basic.py)
Commit your changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Troubleshooting

"ANTHROPIC_API_KEY not set"

Add your API key to .env file
Or run with --no-bots flag to disable AI system

"Failed to initialize renderer"

Install pygame: pip install pygame
Verify your system supports OpenGL

"Template directory does not exist"

Run python config.py to create directories

"Bot system not responding"

Check that API keys are valid
Review logs in error_boundaries.log
Try running with --debug flag

"MCP server connection failed"

Ensure game engine is running first
Check MCP server logs
Verify paths in Claude config

Port already in use (5555 or 8765)

Change port in config.py
Or stop other services using those ports

🔮 Future Enhancements

📦 What's Included in the Repository

This repository includes everything you need to start playing and developing:

✅ Included (tracked in Git):

Complete game engine source code
All 14+ mini-games
AI bot system (orchestrator + 6 specialists)
Knowledge base with 50+ game dev concepts (ChromaDB pre-seeded)
Concept graph with relationships (NetworkX)
Entity templates (JSON)
Asset placeholders (sprites, basic graphics)
Documentation and examples
Test suite

❌ Not included (you provide):

API keys (Anthropic/OpenAI) - add to .env
User save files (generated during play)
Log files (generated at runtime)
User-generated game databases

This means you can clone and play immediately - just add your API key for AI features, or use --no-bots to play without AI!

📄 License

MIT License - See LICENSE file for details.

🙏 Credits

Game Engine: Built with Python, Pygame
AI Integration: Powered by Anthropic Claude & OpenAI GPT
Knowledge Base: ChromaDB, NetworkX
MCP Protocol: Model Context Protocol for Claude Desktop
Inspiration: React Error Boundaries, ECS architecture, AI-assisted development

📞 Contact & Support

Issues: Open an issue on GitHub
Discussions: Use GitHub Discussions for questions
Documentation: Check the docs/ folder

Built with ❤️ by humans and AI working together

Error Boundaries - Where bugs become features 🐛✨

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
assets/sprites		assets/sprites
bots		bots
data/knowledge/chroma_db		data/knowledge/chroma_db
docs		docs
engine		engine
game		game
mcp_server		mcp_server
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
config.py		config.py
main.py		main.py
setup_check.py		setup_check.py

Folders and files

Latest commit

History

Repository files navigation

Error Boundaries 🎮🤖

🌟 Overview

What Makes This Unique?

🎮 Included Mini-Games

🚀 Quick Start

Prerequisites

Installation

Command Line Options

Quick Test

🏗️ Architecture

Core Components

System Flow

🤖 AI Bot System

Orchestrator Bot

Specialist Bots

Knowledge Base

🔌 Integration with Claude Code

HTTP API (Port 5555)

MCP Server

🎯 Game Controls

Basic Controls

Debug Controls (when --debug enabled)

🛡️ Error Boundary System

📚 Entity-Component-System (ECS)

Core Concepts

Available Components

🔧 Development

Creating a New Game

Adding New Components

Adding New Systems

Creating Entity Templates

🧪 Testing

📖 Documentation

🤝 Contributing

Ways to Contribute

Development Workflow

🐛 Troubleshooting

"ANTHROPIC_API_KEY not set"

"Failed to initialize renderer"

"Template directory does not exist"

"Bot system not responding"

"MCP server connection failed"

Port already in use (5555 or 8765)

🔮 Future Enhancements

📦 What's Included in the Repository

📄 License

🙏 Credits

📞 Contact & Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages