simplex-engine

Simplex Engine is a modern game engine written in Python, featuring an Entity-Component-System (ECS) architecture with integrated development tools.

We believe hardware performance will continue to improve in the future. This project aims to deliver the best experience to our customers:

• Game players
• Game developers
• Video creators

We believe a simplified engine (less code complexity, more functionality) will make game and video development faster, easier, and better.

Current Focus: Building a Minecraft-like voxel game engine with infinite procedural worlds, multiplayer support, and comprehensive development tools.

• ECS Architecture: Entity-Component-System with component filtering and event integration
• OpenGL Voxel Rendering: Chunk meshes via greedy/naive meshing, VBO upload, ECS draw path
• Chunk Manager: LRU-cached chunk storage with preload/unload APIs
• First-Person Controls: WASD + mouse look for Minecraft-like demos
• Event-Driven Design: Unified event system for cross-subsystem communication
• Input System: Pygame backend with keyboard/mouse (OpenGL renderer owns display in 3D mode)
• 2D Collision: AABB collision for the ping-pong demo
• Subsystem Scheduler: Dependency-ordered engine initialization
• Development Tools: Debug overlay, logging, hot-reload hooks
• MCP Server: AI-native tools (tests, lint, world probe, docs resources)

• Block Interaction: Place and break voxels
• Cross-Chunk Meshing: Neighbor-aware face culling
• World Generation: Noise terrain, biomes, and structures
• Multiplayer: Network architecture for multiplayer voxel worlds
• Shader Pipeline: Modern GL rendering (replace fixed-function path)

# Clone the repository
git clone https://github.com/import1bones/simplex-engine.git
cd simplex-engine

# Install dependencies (using uv package manager)
uv sync

# Interactive first-person voxel demo (3×3 chunks)
uv run python3 examples/minecraft-like/run_player.py

# Basic demo (single chunk, 5 frames)
uv run python3 examples/minecraft-like/run.py

Controls for run_player.py: WASD move, mouse look, Space up, ESC toggle mouse capture.

uv run python3 examples/ping_pong/run_simple.py
# Or the full-featured version:
uv run python3 examples/ping_pong/main_gui.py

Ping-pong controls: W/S or arrow keys for paddle, F1–F4 debug keys when available.

Simplex includes an MCP server so Cursor and other AI clients can run tests, read docs, and probe the voxel world headlessly.

uv sync
uv run simplex-mcp --check  # smoke test (Cursor starts the server via .cursor/mcp.json)

Enable simplex-engine in Cursor MCP settings (config: .cursor/mcp.json). See AGENTS.md and docs/advanced/ai/README.md.

Comprehensive documentation is available in the docs/ directory:

• Getting Started - Installation, first project, and tutorials
• Core Concepts - Architecture, ECS, events, and systems
• Examples & Tutorials - Complete games and step-by-step guides
• API Reference - Complete API documentation
• Advanced Topics - Performance, networking, and expert techniques
• Development Guide - Contributing and extending the engine

• Engine: Central game engine coordinator
• ECS (Entity-Component-System): Manages game entities and their components
• Event System: Handles communication between systems
• Renderer: OpenGL backend (3D voxels) and SimpleRenderer (2D pygame)
• Voxel / World: Block palette, chunk storage, mesh generation, ChunkManager
• Input System: Pygame polling or OpenGL event forwarding to InputSystem
• Player Controller: First-person movement for voxel demos
• Collision / Movement / Scoring: 2D systems for ping-pong demo

All systems communicate through a unified event system:

# Emit events
engine.events.emit('input', input_event)
engine.events.emit('physics_collision', collision_data)

# Register event handlers
engine.events.register('score', handle_score_event)

2D (ping-pong): Pygame events → SimpleRenderer → EventSystem → InputSystem → game logic

3D (voxel): Pygame events → OpenGLRenderer (before ECS update) → EventSystem → InputSystem / FirstPersonController

By using Python for all subsystems, this engine provides dynamic behavior when building game or video systems. For example, when you write a command, you immediately see the result on your monitor. Once you confirm it works as intended, you can build for better performance.

Python offers a superior development interface, making development and debugging easier and faster.

Demonstrates the current development focus:

• OpenGL rendering of ECS chunk meshes
• Greedy meshing for 16³ chunks
• ChunkManager with LRU caching
• First-person player controls (run_player.py)

A complete 2D game demonstrating:

• Player vs AI gameplay
• Real-time input handling
• Collision detection between ball and paddles
• Scoring system with win conditions
• Debug overlay for development

from simplex.ecs.ecs import Entity
from simplex.ecs.components import PositionComponent, VelocityComponent

# Create a player entity
player = Entity('player')
player.add_component(PositionComponent(100, 200, 0))
player.add_component(VelocityComponent(0, 0, 0))
engine.ecs.add_entity(player)

from simplex.ecs.systems import InputSystem, MovementSystem

# Create and register systems
input_system = InputSystem(event_system=engine.events)
movement_system = MovementSystem(event_system=engine.events)

engine.ecs.add_system(input_system)
engine.ecs.add_system(movement_system)

• Debug Overlay: Real-time system information
• Pause System: Pause/resume game execution
• Development Console: Runtime debugging capabilities
• Logging System: Multi-level logging with configurable output

The engine uses TOML configuration files for settings:

[renderer]
backend = "opengl"
width = 800
height = 600

simplex-engine/
├── simplex/
│   ├── engine.py              # Core engine coordinator
│   ├── ecs/                   # Entity-Component-System
│   ├── renderer/              # OpenGL + SimpleRenderer backends
│   ├── voxel/                 # Blocks, chunks, mesh generation
│   ├── world/                 # ChunkManager streaming
│   ├── scheduler/             # SubsystemManager
│   └── event/                 # Event system
├── examples/
│   ├── minecraft-like/        # Voxel demos (run.py, run_player.py)
│   └── ping_pong/             # 2D ping-pong example
├── tests/                     # Unit tests (pytest)
└── docs/                      # Documentation

1. Fork the repository
2. Create a feature branch from main
3. Make your changes
4. Run uv run ruff check simplex/ tests/ and uv run pytest tests/
5. Submit a pull request (CI runs on push)

• OpenGL renderer with VBO manager and ECS mesh rendering
• Voxel subsystem: chunks, greedy meshing, ChunkManager
• First-person player demo (examples/minecraft-like/run_player.py)
• GitHub Actions CI: uv sync, ruff, pytest

See docs/todo/todo.md for the full roadmap.

MIT License — see LICENSE.

For issues, questions, or contributions, please visit the GitHub repository.