BGE — Box Game Engine

A 2D/3D game engine designed for development by AI agents using Claude Code.

Philosophy

BGE is built around a simple idea: every aspect of your game is a text file. Scenes are YAML, scripts are Python, configuration is TOML. There is no visual editor — AI agents (or humans) author content by reading and writing files directly. This makes the entire development workflow version-controlled, diffable, and transparent.

Features

• Entity-Component-System (ECS) architecture — composable, flat, agent-friendly
• YAML scenes — declarative entity definitions, trivial to diff and modify
• Python scripting — write behavior as plain Python classes, no DSL to learn
• Abstract renderer — 2D (pygame-ce) and 3D (ModernGL) backends behind one interface
• Addon system — extend the engine with new components, systems, and CLI commands
• CSS textures — any texture field accepts css:linear-gradient(...) strings
• Prefabs, save/load, particles, tilemaps, tweens, camera effects — built in
• Headless mode — run and test games without a display window
• CLI-first — all operations available as bge <command>

Quick Start

# Install with uv
uv pip install -e .

# Create a new project
bge new my_game

# Run a demo (headless smoke test)
SDL_VIDEODRIVER=dummy bge run demos/pong/ --headless --frames 120

# Run a demo interactively
bge run demos/snake/

# Validate scene files
bge validate my_game/

# Package a game as a standalone executable
bge build demos/snake/

Project Layout

my_game/
├── project.toml          # Window size, FPS, entry scene, renderer backend
├── scenes/
│   └── main.yaml         # Entity definitions
├── scripts/
│   └── player.py         # Behavior scripts
├── prefabs/              # Reusable YAML entity templates (optional)
├── addons/               # Project-local engine extensions (optional)
└── assets/               # Textures, sounds

Demos

Each directory under demos/ is a self-contained game: pong, snake, pacman_game_design_document (Pac-Man, including its source GDD), bouncing, particles, animation_demo, card_battle, roguelike, shader_demo, car_game (3D), and network_demo (LAN multiplayer via a project-local addon).

Documentation

• Getting Started
• Agent Guide
• Scene Reference
• Component Reference
• Scripting Guide
• Addon Development
• Build & Distribution

Architecture Decision Records

• ADR-001: Language Choice
• ADR-002: ECS Architecture
• ADR-003: Scene Format
• ADR-004: Renderer Abstraction
• ADR-005: Addon System
• ADR-006: Package Layout

License

MIT