pyg-engine 1.3.0

A Python game engine with Rust-powered native performance

PyG Engine

A Python game engine built on Rust and WebGPU (wgpu) with GPU rendering enabled by default

PyG Engine combines the ease of use of Python with the raw performance and safety of Rust. It leverages wgpu for modern, hardware-accelerated rendering across all major platforms (Vulkan, DirectX 12, Metal, OpenGL).

NOTE: This project is currently in Alpha. Features are under active development.

:rocket: Key Features

• Modern Rendering: Powered by wgpu for cross-platform, high-performance graphics.
• Rust Core: The heavy lifting is done in Rust, ensuring speed and memory safety.
• Pythonic API: Designed to feel natural for Python developers.
• Flexible Drawing: Easily draw lines, rectangles, circles, and pixels using pixel coordinates.
• Mesh System: Render textured quads and game objects with a component-based architecture (using normalized coordinates).
• Thread Safety: Safely issue rendering commands from background Python threads.
• Robust Logging: Integrated tracing-based logging system with file support and configurable levels.
• UI Components: Built in UI components built with extendability and custom styling. Easy callback function implementations included for buttons.
• Unified Input System: Easily implement controls with an Axis system, keyboard macros, and event-based callback functions.

:books: Documentation

• API Reference - Complete Python API documentation

:eyes: Gallary

• Snake: One of the provided examples

:package: Installation

Requires Python 3.7+.

From PyPI (Coming Soon)

pip install pyg-engine

From Source

git clone https://github.com/aram-ap/pyg-engine.git
cd pyg-engine
pip install -e .

:zap: Quick Start

1. Basic Window & Logging

import pyg_engine as pyg

# Initialize the engine
engine = pyg.Engine(log_level="INFO")
engine.log_info("Welcome to PyG Engine!")

# Run a window (blocks until closed)
engine.run(title="My First Window", width=800, height=600)

2. Drawing Primitives (Pixel Coordinates)

import pyg_engine as pyg

engine = pyg.Engine()

# Draw shape objects
engine.draw([
    pyg.Line(
        start=pyg.Vec2(20, 20),
        end=pyg.Vec2(220, 80),
        color=pyg.Color.CYAN,
        thickness=2.0,
    ),
    pyg.Rect(
        position=pyg.Vec2(60, 120),
        width=180,
        height=90,
        color=pyg.Color.ORANGE,
        filled=False,
        thickness=3.0,
    ),
    pyg.Arc(
        position=pyg.Vec2(320, 180),
        radius=42,
        start_angle=0.0,
        end_angle=3.8,
        color=pyg.Color.YELLOW,
        filled=False,
        thickness=5.0,
    ),
])

# Draw text as a shape object
engine.draw(
    pyg.Text(
        "Hello PyG",
        position=pyg.Vec2(32, 48),
        color=pyg.Color.WHITE,
        font_size=28.0,
    )
)

# Start the application
engine.run(title="Direct Draw Demo", show_fps_in_title=True)

3. Font Families And Styled Text

import pyg_engine as pyg

engine = pyg.Engine()
engine.register_font_family(
    "inter",
    regular="assets/fonts/Inter-Regular.ttf",
    bold="assets/fonts/Inter-Bold.ttf",
    italic="assets/fonts/Inter-Italic.ttf",
    bold_italic="assets/fonts/Inter-BoldItalic.ttf",
)

engine.draw(
    pyg.Text(
        "Family font text",
        position=pyg.Vec2(32, 48),
        color=pyg.Color.WHITE,
        font_size=28.0,
        font_family="inter",
        font_weight="bold",
    )
)

width, height = engine.measure_text(
    "Menu Title",
    font_size=32.0,
    font_family="inter",
    font_weight="bold",
)
engine.draw_text(
    "Italic caption",
    32,
    96,
    pyg.Color.WHITE,
    font_size=20.0,
    font_family="inter",
    font_style="italic",
    kerning=True,
)

engine.run(title="Font Family Demo")

4. Using Game Objects & Meshes (World Coordinates)

import pyg_engine as pyg

engine = pyg.Engine()

# Create a GameObject
player = pyg.GameObject("Player")

# Add components through the shared component API
mesh = pyg.MeshComponent("PlayerSprite")
mesh.set_geometry(pyg.Mesh.Rect(1.0, 1.0))  # 1 world unit wide and tall
mesh.set_fill_color(pyg.Color.RED)
player.add_component(mesh)

# Local transform (world-space while unparented)
player.position = pyg.Vec2(0.0, 0.0)
player.scale = pyg.Vec2(0.5, 0.5)

player_id = engine.add_game_object(player)

# Runtime lookup + lifecycle helpers
runtime_player = engine.objects.get_id(player_id)
camera = engine.camera
camera.position = pyg.Vec2(0.0, 0.0)
camera.viewport_size = pyg.Vec2(8.0, 4.5)
runtime_player.enabled = True
# engine.destroy(runtime_player)

engine.run(title="Game Object Demo")

5. World Text Meshes And Camera Properties

import pyg_engine as pyg

engine = pyg.Engine()

label = pyg.GameObject("WorldLabel")
label.position = pyg.Vec2(0.0, 1.0)
label.scale = pyg.Vec2(0.004, 0.004)

text_mesh = pyg.TextMeshComponent(
    "Hello from a GameObject",
    font_size=48.0,
    font_family="inter",
    font_weight="bold",
)
text_mesh.color = pyg.Color.WHITE
label.add_text_mesh_component(text_mesh)

engine.add_game_object(label)

# Camera behaves like an object-focused API
engine.camera.position = pyg.Vec2(0.0, 0.0)
engine.camera.position.x = 1.5
engine.camera.viewport_size = pyg.Vec2(10.0, 5.625)
engine.camera.aspect_mode = pyg.CameraAspectMode.FIT_BOTH

engine.run(title="Text Mesh Demo")

6. Function-Based Update Loop

import pyg_engine as pyg

engine = pyg.Engine()

def update(dt, engine, frame):
    if engine.input.key_down(pyg.Keys.ESCAPE):
        engine.log("Exiting Pyg-Engine!")
        return False
    engine.clear_draw_commands()
    # draw/update game state...

engine.run(
    title="Callback Loop",
    show_fps_in_title=True,
    update=update,
    max_delta_time=0.1,
)

run(update=...) supports callbacks with no arguments, a single context argument, or named argument injection (dt, engine, input, elapsed_time, frame, user_data).

For fully manual loop control, use start_manual(...) then drive poll_events(), update(), and render() yourself. The callback acts as a global frame hook; planned per-GameObject scripts are intended to run in the engine update phase before this global callback. Runtime guard: calling run(...)/start_manual(...) while another loop is active raises RuntimeError.

:wrench: Architecture & Roadmap

Current Capabilities

• Window Management: Resizable windows, VSync control, Fullscreen support.
• 2D Rendering:
  • Primitives: Shape-first immediate drawing using pixel coordinates.
  • Text: Built-in open-source font rendering with optional custom font files.
  • Meshes: Component-based world-space rendering plus immediate mesh drawing.
  • Layers: Float draw ordering for composition.
• Component System: Basic GameObject with TransformComponent and MeshComponent.
• Input System: Rust input manager (Keyboard, Mouse, Gamepad) to Python.
• Loop Control: run(...) with optional callback and explicit start_manual(...) mode.
• Object Positioning System: A straightforward method for moving and transforming your objects.
• Camera Controls: Move your camera, customize backgrounds, set view area and fitment properties.
• UI System: Built-in UI components.

Planned Features (Roadmap)

• Audio Manager: Audio loading, playback, mixing, and timing.
• Engine Loop (Upgrade): Coroutines and global event systems.
• Physics Engine: 2D rigid body physics and collision detection.
• Scripting: Enhanced script attachment to GameObjects with frame-lifecycle hooks.
• Additional Primitives: Added capabilities for more basic shapes, arcs, SVGs, and function-based shapes.
• Advanced Rendering: Shaders, Particles, and Post-processing.

:open_file_folder: Examples

Check the examples/ directory for more complete demonstrations:

• direct_draw_demo.py: Shows the new engine.draw(...) shape API.
• mesh_demo.py: Demonstrates GameObjects, object-based mesh geometry, and world text meshes.
• threading_demo.py: Advanced: Spawns a background thread that safely updates the UI using engine.get_handle().
• manual_loop.py: Shows how to control the game loop manually (start_manual -> poll -> update -> render).
• function_update_demo.py: Shows callback-based loop control via engine.run(update=...).
• snake_demo.py: Playable Snake game using immediate-mode drawing and keyboard input.
• camera_worldspace_demo.py: Shows object-style camera control along with world-space objects and HUD text.
• ui_demo.py: Demonstrates the UI system, button functions, and text label updates.

:hammer_and_wrench: Development & Testing

To set up the development environment:

# Install in editable mode
pip install -e .

# Run tests
pytest tests/ -v

📄 License

MIT License