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.

✨ 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 - Create your first game in minutes
• API Reference - Complete API documentation
• Android Build Guide - Deploy to Android devices
• Examples - Sample games for each template
• Python API Summary - High-level Python API overview
• Python Bindings - 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)

# 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)

# 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

# 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

# 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!)

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

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/ 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

# 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 for detailed Android deployment instructions using Buildozer.

# Quick Android build
buildozer android debug

🧪 Testing

# 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 for guidelines.

Development Setup

# 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 for details.

🙏 Acknowledgments

PyWRKGame uses these excellent libraries:

• pybind11 - Python bindings
• Bullet3 - 3D physics
• Box2D - 2D physics
• Vulkan - Graphics API
• OpenAL - Audio
• CMake - Build system

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our community

🗺️ Roadmap

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

---

Made with ❤️ by the PyWRKGame team