simvx.graphics.app

Graphics application layer — engine wrapper with node tree support.

Module Contents

Classes

App	Graphics application wrapper. Supports both raw callbacks and node tree scenes.

Data

log
__all__

API

simvx.graphics.app.log

‘getLogger(…)’

simvx.graphics.app.__all__

[‘App’, ‘AVAILABLE_BACKENDS’]

class simvx.graphics.app.App(title: str = 'SimVX', width: int = 1280, height: int = 720, backend: str | None = None, physics_fps: int = 60, target_fps: int | None = None, visible: bool = True, vsync: bool = True, bg_colour: tuple[float, float, float, float] | str | None = None, **_kwargs)

Graphics application wrapper. Supports both raw callbacks and node tree scenes.

Args: title: Window title string. width: Window width in pixels (must be >= 1). height: Window height in pixels (must be >= 1). backend: Windowing backend name. One of "glfw" (desktop), "sdl3" (touch/mobile), "qt" (embedding). None auto-detects. physics_fps: Fixed-timestep physics simulation rate (Hz). Independent of the display rate; the run loop drives physics via an accumulator so changing this never affects render cadence. target_fps: Maximum display frame rate. None (default) means uncapped (vsync-gated only). Mirrors Godot’s Engine.max_fps, Unity’s Application.targetFrameRate, and Bevy’s FrameRateLimit::Limit. Combine with vsync=False to make the cap dominant on high-refresh displays. visible: Open a visible window. Set False for headless tests. vsync: Enable vertical sync at present time. bg_colour: Background clear colour. "transparent", an RGBA tuple, or None to use the theme background.

Usage with node tree (recommended)::

app = App(title="My Game", width=1280, height=720)
app.run(MyGameScene())  # Node subclass with ready()/process()

Usage with raw callbacks::

app = App(title="My Game")
app.run(update=my_update, render=my_render)

After run() has created the window, window_title, window_size, and active_backend reflect the live state.

Initialization

toggle_fullscreen() → None

Toggle fullscreen mode.

property is_fullscreen: bool

property engine: simvx.graphics.engine.Engine | None

Access the graphics engine (available after run() starts).

property scene_adapter

Scene adapter bridging SceneTree to the renderer (available after run() starts).

property active_backend: str | None

Return the resolved backend name (e.g. "glfw"), or None if the engine has not yet initialised a window.

property window_title: str

Current window title. Writable once the window exists.

property window_size: tuple[int, int]

Current window (width, height). Writable once the window exists.

property cursor_pos: tuple[float, float]

Current cursor position in screen coordinates, (0.0, 0.0) before run().

property vsync: bool

Whether vertical sync is currently enabled.

set_vsync(value: bool) → None

Toggle vsync at runtime.

Before run() this just stores the boot-time value. After run(), the engine recreates the swapchain with the new present mode (FIFO when on, MAILBOX/IMMEDIATE when off).

run(root_or_update: Any = None, *, update: collections.abc.Callable[[], None] | None = None, render: collections.abc.Callable[[object, tuple[int, int]], None] | None = None) → None

Run the graphics engine.

Args: root_or_update: Either a Node (scene root) or a legacy update callback. When a Node is passed, SceneTree and input are set up automatically. update: Legacy per-frame callback (alternative to positional arg). render: Custom render callback (cmd, extent). Only used in callback mode.

quit() → None

Request a clean shutdown of the running app.

Safe to call from process/physics_process or input handlers. The main loop exits at the end of the current frame; audio and Vulkan resources are torn down in the usual finally-paths. Prefer this over sys.exit which can leave background threads (e.g. miniaudio) alive and stall process exit.

run_headless(root_node: Any, *, frames: int = 1, on_frame: collections.abc.Callable[[int, float], bool | None] | None = None, capture_frames: list[int] | None = None, capture_fn: collections.abc.Callable[[int], bool] | None = None) → list

Run the engine headlessly for frames frames and return captured pixels.

Args: root_node: Scene root node. frames: Total number of frames to simulate. on_frame: Optional callback invoked with (frame_index, time) before each frame. Return False to stop early. capture_frames: Which frame indices to capture (None = capture all). capture_fn: Dynamic capture predicate — called with frame index, captures if True. Takes precedence over capture_frames when provided.

Returns: List of (H, W, 4) uint8 RGBA numpy arrays.

run_streaming(root_node: Any, server: Any) → None

Run the engine headlessly and stream frames to browsers via WebRTC.

Args: root_node: Scene root node. server: A StreamingServer instance (from simvx.graphics.streaming).