# App Class

The `App` class bridges the SimVX core engine with the Vulkan rendering backend. It provides a ready-to-use game loop with fixed-timestep physics, input handling, and automatic scene rendering.

## Basic Usage

```python
from simvx.core import Node, Camera3D, MeshInstance3D, Mesh, Material
from simvx.graphics import App

class MyGame(Node):
    def ready(self):
        cam = Camera3D(position=(0, 5, 10))
        cam.look_at((0, 0, 0))
        self.add_child(cam)

        cube = MeshInstance3D(mesh=Mesh.cube(), material=Material(colour=(1, 0, 0)))
        self.add_child(cube)

app = App(width=1280, height=720, title="My Game")
app.run(MyGame())
```

## `App.run()` Signature

```python
app.run(scene, *, update=None, render=None)
```

The first argument is always a `Node` instance (scene root). Optional `update` and `render` callbacks are for raw/advanced usage without a node tree.

## Context Manager

`App` supports `__enter__`/`__exit__` for clean resource management:

```python
with App(title="My Game", width=1280, height=720) as app:
    app.run(MyGame())
```

The Vulkan engine is shut down automatically when the `with` block exits.

## Configuration

```python
app = App(
    width=1920,
    height=1080,
    title="SimVX Game",
    physics_fps=60,       # Fixed physics tick rate
    visible=False,        # Hidden window for headless testing
    vsync=True,           # Vertical sync
    bg_colour=(0.1, 0.1, 0.1, 1.0),  # Background colour (RGBA 0-1)
)
```

## Windowing Backend

SimVX supports multiple windowing backends. Pass `backend=` to select one:

```python
app = App(backend="glfw")   # Default — fastest, fewest dependencies
app = App(backend="sdl3")   # SDL3 (if installed)
app = App(backend="qt")     # PySide6 (if installed)
```

All backends produce the same Vulkan rendering. The default priority when no backend is specified: GLFW, SDL3, PySide6.

## API Reference

See {py:mod}`simvx.graphics.app` for the complete App API.