Getting Started: Python SDK

Alpha — APIs change frequently. Report issues

This guide covers installing the Python SDK, opening a window, drawing a sprite, and handling input.

See also: C# guide · TypeScript guide · Rust guide · Go guide · Kotlin guide · Lua guide

Prerequisites

• Python 3.9 or later
• A supported OS: Windows x64, macOS x64, macOS ARM64, or Linux x64

Installation

pip install goudengine

The package bundles the native Rust library (.so, .dylib, or .dll). No separate build step is needed when installing from PyPI.

First Project

Create main.py:

from goudengine import GoudGame, Key

game = GoudGame(800, 600, "My Game")

while not game.should_close():
    game.begin_frame()

    if game.is_key_just_pressed(Key.ESCAPE):
        game.close()

    game.end_frame()

game.destroy()

Run it:

python main.py

A window opens at 800x600 and closes when you press Escape.

begin_frame() polls events and clears the screen. end_frame() presents the frame. Everything you draw goes between those two calls.

Debugger Runtime

Enable debugger mode before creating the headless context:

from goudengine import (
    GoudContext,
)
from goudengine.generated._types import ContextConfig, DebuggerConfig

ctx = GoudContext(
    ContextConfig(
        debugger=DebuggerConfig(
            enabled=True,
            publish_local_attach=True,
            route_label="getting-started-python",
        )
    )
)

ctx.set_debugger_profiling_enabled(True)
snapshot_json = ctx.get_debugger_snapshot_json()
manifest_json = ctx.get_debugger_manifest_json()
ctx.destroy()

For a ready-made headless route, run python3 examples/python/feature_lab.py. The example publishes feature-lab-python-headless, confirms manifest and snapshot access, and prints the manual attach steps:

1. start cargo run -p goudengine-mcp
2. call goudengine.list_contexts
3. call goudengine.attach_context

Drawing a Sprite

Load textures once before the game loop, then draw each frame.

from goudengine import GoudGame, Key

game = GoudGame(800, 600, "My Game")

player_tex = game.load_texture("assets/player.png")

while not game.should_close():
    game.begin_frame()

    if game.is_key_just_pressed(Key.ESCAPE):
        game.close()

    game.draw_sprite(player_tex, 400, 300, 64, 64)

    game.end_frame()

game.destroy()

draw_sprite takes the center position of the sprite, not the top-left corner.

An optional sixth argument sets rotation in radians:

import math
game.draw_sprite(player_tex, 400, 300, 64, 64, math.pi / 4)

Handling Input

Keyboard

Two modes are available: pressed this frame, or held continuously.

from goudengine import GoudGame, Key

game = GoudGame(800, 600, "My Game")

x = 400.0

while not game.should_close():
    game.begin_frame()
    dt = game.delta_time

    if game.is_key_just_pressed(Key.ESCAPE):
        game.close()

    if game.is_key_pressed(Key.LEFT):
        x -= 200 * dt
    if game.is_key_pressed(Key.RIGHT):
        x += 200 * dt

    game.end_frame()

game.destroy()

delta_time is the elapsed seconds since the last frame. Use it to make movement frame-rate independent.

Common key constants: Key.ESCAPE, Key.SPACE, Key.ENTER, Key.W, Key.A, Key.S, Key.D, Key.LEFT, Key.RIGHT, Key.UP, Key.DOWN.

Mouse

from goudengine import GoudGame, MouseButton

game = GoudGame(800, 600, "My Game")

while not game.should_close():
    game.begin_frame()

    if game.is_mouse_button_just_pressed(MouseButton.LEFT):
        pos = game.get_mouse_position()
        print(f"Click at ({pos.x:.0f}, {pos.y:.0f})")

    game.end_frame()

game.destroy()

Mouse button constants: MouseButton.LEFT, MouseButton.RIGHT, MouseButton.MIDDLE.

Running an Example Game

The repository includes a complete Flappy Bird clone in Python. Clone the repo and run it with dev.sh:

git clone https://github.com/aram-devdocs/GoudEngine.git
cd GoudEngine
./dev.sh --sdk python --game python_demo    # Basic demo
./dev.sh --sdk python --game flappy_bird    # Flappy Bird clone
./dev.sh --sdk python --game sandbox        # Full feature sandbox
python3 examples/python/feature_lab.py      # Supplemental smoke coverage

dev.sh builds the native library and launches the example. It requires a Rust toolchain (cargo) to be installed.

Running Examples from Source (Without dev.sh)

If you have the repository checked out and the native library built, add the SDK path manually:

import sys
from pathlib import Path

sdk_path = Path(__file__).parent.parent.parent / "sdks" / "python"
sys.path.insert(0, str(sdk_path))

from goudengine import GoudGame, Key

Build the native library first:

cargo build --release

Available Types

Next Steps

• Python examples — source code for main.py, flappy_bird.py, and sandbox.py
• Python SDK README — full API reference
• Build Your First Game — end-to-end minimal game walkthrough
• Debugger Runtime — local attach, capture, replay, and metrics workflow
• Example Showcase — current cross-language parity matrix
• Cross-Platform Deployment — packaging and release workflow
• FAQ and Troubleshooting — common runtime and build issues
• Architecture overview — how the Rust core and Python SDK connect
• Development guide — building from source, running tests