Metadata-Version: 2.4
Name: bge
Version: 0.1.0
Summary: Box Game Engine — a 2D game engine optimized for AI agent development
Author: BGE Contributors
License: MIT
Keywords: 2d,ai-agent,ecs,game-engine,pygame
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: moderngl>=5.10.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pygame-ce>=2.4.0
Requires-Dist: pymunk>=6.9.0
Requires-Dist: pyyaml>=6.0.2
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: cairosvg>=2.7; extra == 'dev'
Requires-Dist: pillow>=10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: network
Requires-Dist: websockets>=12.0; extra == 'network'
Provides-Extra: svg
Requires-Dist: cairosvg>=2.7; extra == 'svg'
Requires-Dist: pillow>=10.0; extra == 'svg'
Description-Content-Type: text/markdown

# 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

```bash
# 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](docs/getting-started.md)
- [Agent Guide](docs/agent-guide.md)
- [Scene Reference](docs/scene-reference.md)
- [Component Reference](docs/component-reference.md)
- [Scripting Guide](docs/scripting-guide.md)
- [Addon Development](docs/addon-development.md)
- [Build & Distribution](docs/build-distribution.md)

### Architecture Decision Records

- [ADR-001: Language Choice](docs/architecture/ADR-001-language-choice.md)
- [ADR-002: ECS Architecture](docs/architecture/ADR-002-ecs-architecture.md)
- [ADR-003: Scene Format](docs/architecture/ADR-003-scene-format.md)
- [ADR-004: Renderer Abstraction](docs/architecture/ADR-004-renderer-abstraction.md)
- [ADR-005: Addon System](docs/architecture/ADR-005-addon-system.md)
- [ADR-006: Package Layout](docs/architecture/ADR-006-package-layout.md)

## License

MIT
