pywrkgame 3.0.3
High-performance game engine with Python bindings for 2D/3D games
License: MIT
Requires Python: >=3.7
Keywords: game, engine, gamedev, 2d, 3d, graphics, physics, audio, mobile, cross-platform

# PyWRKGame 3.0.3

🎮 **High-Performance Game Engine for Python**

PyWRKGame 3.0.0 is a revolutionary game development library with a C/C++ core and Python bindings, designed for maximum performance on mobile devices while maintaining ease of use.

[![Build Status](https://github.com/pywrkgame/pywrkgame/workflows/CI/badge.svg)](https://github.com/pywrkgame/pywrkgame/actions)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)

## ✨ Features

- **🚀 High Performance**: C/C++ core optimized for mobile devices (30+ FPS on low-end Android)
- **🌍 Cross-Platform**: Windows, macOS, Linux, Android, iOS, consoles, VR/AR
- **🎨 Modern Graphics**: PBR rendering, global illumination, advanced post-processing
- **🎯 Complete Engine**: Physics, audio, networking, AI, UI systems included
- **💡 Easy to Use**: Create games in 10 lines of code or less
- **📱 Mobile-First**: Touch controls, sensors, haptics, battery optimization
- **🎮 Game Templates**: Built-in templates for platformers, RPGs, shooters, puzzles

## 📚 Documentation

- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Create your first game in minutes
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[Android Build Guide](ANDROID_BUILD.md)** - Deploy to Android devices
- **[Examples](examples/)** - Sample games for each template
- **[Python API Summary](docs/PYTHON_API.md)** - High-level Python API overview
- **[Python Bindings](docs/PYTHON_BINDINGS_SUMMARY.md)** - C++ to Python binding details

## 📦 Installation

### ⚠️ Important: Install C++ Dependencies First

PyWRKGame requires C++ libraries that **must be installed before** running `pip install`. Choose your platform:

#### Windows (using vcpkg - recommended)

```bash
# 1. Install vcpkg (one-time setup)
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# 2. Install dependencies
.\vcpkg install glm:x64-windows box2d:x64-windows bullet3:x64-windows

# 3. Integrate with Visual Studio
.\vcpkg integrate install

# 4. Now install PyWRKGame
pip install pywrkgame
```

#### Linux (Ubuntu/Debian)

```bash
# 1. Install dependencies
sudo apt-get update
sudo apt-get install -y libglm-dev libbox2d-dev libbullet-dev build-essential python3-dev

# 2. Now install PyWRKGame
pip install pywrkgame
```

#### macOS

```bash
# 1. Install dependencies
brew install glm box2d bullet

# 2. Now install PyWRKGame
pip install pywrkgame
```

### Troubleshooting

If you see errors about missing `glm/glm.hpp`, `Box2D`, or `Bullet3`:
1. Make sure you installed the C++ dependencies above
2. On Windows, run `vcpkg integrate install` after installing libraries
3. On Linux, ensure `build-essential` and `python3-dev` are installed
4. Try installing in a clean virtual environment

**Note:** PyWRKGame compiles C++ code during installation. This is normal and may take 2-5 minutes.

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/pywrkgame/pywrkgame.git
cd pywrkgame

# Build C++ core
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

# Install Python package
cd ..
pip install -e .
```

### Your First Game (8 lines!)

```python
from pywrkgame_api import Game

game = Game("My First Game", 800, 600)
player = game.create_sprite("player.png", 400, 300)

@game.on_update
def update(dt):
    player.move(game.input.x * 200 * dt, game.input.y * 200 * dt)

game.run()
```

### Using Game Templates

```python
from pywrkgame_api import quick_platformer

# Create a platformer in 4 lines!
game = quick_platformer("My Platformer")
game.add_player(100, 100)
game.add_platform(0, 500, 800, 50)
game.run()
```

## 🎮 Game Templates

PyWRKGame includes ready-to-use templates:

- **🏃 Platformer**: Gravity, jumping, platforms
- **⚔️ RPG**: NPCs, dialog, 8-directional movement
- **🚀 Shooter**: Bullets, enemies, auto-fire
- **🧩 Puzzle**: Grid system, piece matching, swapping

See [examples/](examples/) for complete implementations.

## 🏗️ Building

## 🏗️ Building from Source

### Prerequisites

- **CMake** 3.16 or higher
- **C++17** compatible compiler
- **Python** 3.7 or higher
- **pybind11** (automatically fetched by CMake)

### Platform-Specific Requirements

**Windows:**
- Visual Studio 2019+ or MinGW-w64
- DirectX 12 SDK (included with Windows 10+)

**macOS:**
- Xcode 11+ with Command Line Tools
- Metal framework (included with macOS)

**Linux:**
- GCC 7+ or Clang 6+
- Vulkan SDK: `sudo apt install libvulkan-dev`

### Build Instructions

```bash
# Clone repository
git clone https://github.com/pywrkgame/pywrkgame.git
cd pywrkgame

# Configure build
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build C++ core
cmake --build build --config Release

# Install Python package
pip install -e .

# Run tests
cd build
ctest --output-on-failure
cd ..
python -m pytest tests/python -v
```

### Android Build

See [ANDROID_BUILD.md](ANDROID_BUILD.md) for detailed Android deployment instructions using Buildozer.

```bash
# Quick Android build
buildozer android debug
```

## 🧪 Testing

```bash
# Run C++ tests
cd build
ctest --output-on-failure

# Run Python tests
python -m pytest tests/python -v

# Run integration tests
python -m pytest tests/python/test_integration_comprehensive.py -v

# Run specific test
python -m pytest tests/python/test_high_level_api.py -v
```

## 🏛️ Architecture

PyWRKGame uses a modern **Entity-Component-System (ECS)** architecture:

```
┌─────────────────────────────────────┐
│      Python High-Level API          │  ← Game templates, quick functions
├─────────────────────────────────────┤
│      Python Bindings (pybind11)     │  ← C++ ↔ Python bridge
├─────────────────────────────────────┤
│         C++ Engine Core             │  ← High-performance core
│  ┌──────────┬──────────┬─────────┐  │
│  │ Rendering│ Physics  │  Audio  │  │
│  ├──────────┼──────────┼─────────┤  │
│  │    AI    │ Network  │   UI    │  │
│  └──────────┴──────────┴─────────┘  │
├─────────────────────────────────────┤
│    Platform Abstraction Layer       │  ← Cross-platform support
├─────────────────────────────────────┤
│  Vulkan │ Metal │ D3D12 │ OpenGL   │  ← Graphics APIs
└─────────────────────────────────────┘
```

### Key Components

- **ECS Framework**: Efficient entity-component-system for game objects
- **Rendering Engine**: PBR, global illumination, post-processing
- **Physics Engine**: Bullet3 (3D) and Box2D (2D) integration
- **Audio System**: 3D positional audio with HRTF
- **Network Manager**: Client-server and P2P multiplayer
- **AI Framework**: Behavior trees, pathfinding, procedural generation
- **UI System**: Responsive layouts, touch controls, themes

## 📱 Platform Support

| Platform | Status | Graphics API | Notes |
|----------|--------|--------------|-------|
| Windows 10+ | ✅ Supported | D3D12, Vulkan | Full feature support |
| macOS 10.15+ | ✅ Supported | Metal | Full feature support |
| Linux | ✅ Supported | Vulkan | Ubuntu 18.04+ tested |
| Android 5.0+ | ✅ Supported | Vulkan, OpenGL ES | API level 21+ |
| iOS 12+ | ✅ Supported | Metal | iPhone 6s and newer |
| PlayStation | 🚧 Planned | GNM | Requires dev kit |
| Xbox | 🚧 Planned | D3D12 | Requires dev kit |
| Nintendo Switch | 🚧 Planned | NVN | Requires dev kit |
| Oculus Quest | ✅ Supported | Vulkan | Via Android build |
| HTC Vive | ✅ Supported | Vulkan | Via desktop build |

## 🎯 Performance

PyWRKGame is optimized for performance:

- **30+ FPS** on low-end Android devices (2D games)
- **20+ FPS** on low-end Android devices (3D games)
- **Automatic quality scaling** based on device capabilities
- **Memory leak prevention** with automatic management
- **Battery optimization** for mobile devices

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone with submodules
git clone --recursive https://github.com/pywrkgame/pywrkgame.git

# Create development build
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

# Run tests before committing
python -m pytest tests/python -v
```

## 📄 License

PyWRKGame is released under the MIT License. See [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

PyWRKGame uses these excellent libraries:

- [pybind11](https://github.com/pybind/pybind11) - Python bindings
- [Bullet3](https://github.com/bulletphysics/bullet3) - 3D physics
- [Box2D](https://github.com/erincatto/box2d) - 2D physics
- [Vulkan](https://www.vulkan.org/) - Graphics API
- [OpenAL](https://www.openal.org/) - Audio
- [CMake](https://cmake.org/) - Build system

## 📞 Support

- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/pywrkgame/pywrkgame/issues)
- **Discussions**: [GitHub Discussions](https://github.com/pywrkgame/pywrkgame/discussions)
- **Discord**: [Join our community](https://discord.gg/pywrkgame)

## 🗺️ Roadmap

- [x] Core engine architecture
- [x] Cross-platform rendering
- [x] Physics integration
- [x] Audio system
- [x] Python bindings
- [x] Game templates
- [x] Android support
- [ ] iOS support (in progress)
- [ ] Console support (planned)
- [ ] Visual editor (planned)
- [ ] Asset pipeline (planned)

---

**Made with ❤️ by the PyWRKGame team**