# Architecture

SimVX is a Godot-inspired game engine in pure Python: node-based scene hierarchy, Vulkan GPU-driven rendering, and NumPy-based math. This page covers the key internal pipelines.

## Node Lifecycle

Every node progresses through these stages:

```
construction --> enter_tree --> ready --> [process / physics_process] --> exit_tree
```

1. **Construction** -- `__init__()` sets properties and `Property` defaults. No tree access yet.
2. **Enter tree** -- `add_child()` inserts the node. `Child` descriptors are instantiated. The node receives a reference to its `SceneTree`.
3. **Ready** -- Called bottom-up (children first, then parent). `OnReady` descriptors resolve. Safe to access children by path: `self["Camera"]`.
4. **Process** -- `process(dt)` runs every frame with wall-clock delta. `physics_process(dt)` runs at a fixed rate (default 60 Hz) with accumulator-based catch-up.
5. **Exit tree** -- Triggered by `destroy()`. Signals are disconnected, children are recursively removed, and the node is dequeued from the `SceneTree`.

Children added during `ready()` go through the full lifecycle before the parent's `ready()` returns. This guarantees that `self["Player/Camera"]` is valid inside `ready()`.

## Scene Tree

`SceneTree` owns the root node and drives the frame loop:

```
SceneTree.process(dt)          # walk tree, call process(dt) on every node
SceneTree.physics_process(dt)  # walk tree, call physics_process(dt)
SceneTree.draw(Draw2D)         # 2D draw pass -- nodes emit draw commands
```

Groups allow batch queries: `tree.get_group("enemies")` returns all nodes tagged with that group. The tree also manages deferred deletions -- `destroy()` queues removal until the end of the current frame to avoid mutation during iteration.

## Render Pipeline

SimVX uses a **GPU-driven forward renderer**. No per-object draw calls from Python.

```
Scene submission --> SSBO upload --> Multi-draw indirect --> Swapchain present
```

### Frame flow

1. **Scene submission** -- `SceneAdapter` walks the node tree, collecting `MeshInstance3D` transforms, materials, and lights into flat NumPy arrays.
2. **Frustum culling** -- CPU-side bounding-sphere test per viewport. Culled instances are excluded from the draw command buffer.
3. **SSBO upload** -- Transform, material, and light arrays are `memcpy`'d to Shader Storage Buffer Objects. One upload per frame.
4. **Draw command build** -- A `VkDrawIndexedIndirectCommand` array is built (one entry per visible mesh instance).
5. **Pre-render** -- Shadow map passes and SSAO compute dispatch run before the main render pass.
6. **Main render pass** -- A single `vkCmdDrawIndexedIndirect` call draws all opaque geometry. Transparent objects follow in a separate sorted pass.
7. **2D overlay** -- Text, UI widgets, and `Draw2D` geometry are rendered in an orthographic pass over the 3D scene.
8. **Present** -- The swapchain image is presented. Frame capture (for headless testing) happens here if requested.

### Key data structures

| Buffer | Contents | Update frequency |
|--------|----------|-----------------|
| Transform SSBO | 4x4 model matrices (float32) | Every frame |
| Material SSBO | Color, roughness, metallic, texture IDs | On change |
| Light SSBO | Position, color, intensity, type | Every frame |
| Indirect draw buffer | `VkDrawIndexedIndirectCommand` per instance | Every frame |

Bindless textures are stored in a single descriptor array (up to 4096 slots). Materials reference textures by integer index -- no per-material descriptor set switching.

## Input Flow

```
GLFW key/mouse event --> input_adapter --> Input singleton --> InputMap --> game code
```

1. **GLFW callback** -- `key_callback_with_ui` receives raw key events from GLFW.
2. **Input adapter** -- Translates GLFW key codes to `Key`/`MouseButton` enums, updates the `Input` singleton's pressed/released state, and routes events to the UI system.
3. **Input singleton** -- Stores per-frame state. `Input.is_key_pressed(Key.W)` checks instantaneous state; `Input.is_action_just_pressed("jump")` checks action bindings.
4. **InputMap** -- Maps named actions to typed key bindings: `InputMap.add_action("jump", [Key.SPACE, JoyButton.A])`. Actions are queried by name in `process(dt)`.

UI widgets receive input first. If a focused widget consumes the event, it does not propagate to game nodes.

## Performance Notes

- **Node counts**: The tree walk is pure Python, so keep node counts under ~5,000 for 60 fps process ticks. Use groups and `find()` to avoid deep recursive searches.
- **Draw call batching**: All opaque geometry is drawn in a single indirect draw call regardless of material count. Only transparent objects require sorting.
- **SSBO capacity**: Default buffers support 16,384 instances and 256 lights. Exceeding these triggers a buffer resize (one-time stall).
- **Physics tick**: Fixed at 60 Hz by default. Multiple physics steps per frame occur when the frame rate drops below 60 fps (capped at 100 ms accumulation to prevent spiral-of-death).
- **Headless mode**: `App(visible=False)` creates a real Vulkan surface with an invisible GLFW window. Rendering is identical to visible mode -- useful for automated visual tests in CI.