## Game‑Facing API Overview

This document summarizes the main engine APIs that are directly useful when building a game (spawn actors, control lights/animations, and interact via picking).

For details on the underlying systems, see also:

- `docs/Scene.md` – cameras, draw context, instances, picking.
- `docs/EngineContext.md` – access to managers and per‑frame state.
- `docs/RenderGraph.md` – render‑graph API for custom passes.
- `docs/InputSystem.md` – keyboard, mouse, and cursor mode handling.
- `docs/Picking.md` – object selection, hover detection, and drag-box multi-select.
- `docs/ImGuiSystem.md` – immediate-mode UI integration and debug widgets.

---

## `GameAPI::Engine` (High‑Level Game Wrapper)

Header: `src/core/game_api.h`  
Implementation: `src/core/game_api.cpp`

`GameAPI::Engine` is a thin, game‑friendly wrapper around `VulkanEngine`. It exposes stable, snake_case methods grouped by responsibility:

- Texture streaming and VRAM budget.
- Shadows and reflections.
- IBL volumes.
- Instances and animation.
- Post‑processing (tonemap, bloom, FXAA).
- Camera control.
- Lighting (directional, point, spot).
- Volumetrics (clouds, smoke, flame).
- Particle systems.
- Debug drawing.
- Picking and render‑graph pass toggles.
- Time and statistics.

Typical creation:

```cpp
#include "core/engine.h"
#include "core/game_api.h"

VulkanEngine engine;
engine.init();

GameAPI::Engine api(&engine); // non‑owning
```

You then call `api.*` from your game loop to spawn content and tweak settings.

### Texture Streaming & VRAM Budget

Relevant methods:

- `size_t get_texture_budget() const;`
- `void set_texture_loads_per_frame(int count);`
- `int get_texture_loads_per_frame() const;`
- `void set_texture_upload_budget(size_t bytes);`
- `size_t get_texture_upload_budget() const;`
- `void set_cpu_source_budget(size_t bytes);`
- `size_t get_cpu_source_budget() const;`
- `void set_max_upload_dimension(uint32_t dim);`
- `uint32_t get_max_upload_dimension() const;`
- `void set_keep_source_bytes(bool keep);`
- `bool get_keep_source_bytes() const;`
- `void evict_textures_to_budget();`

At a lower level, `VulkanEngine::query_texture_budget_bytes()` computes a conservative per‑frame texture budget using VMA heap info and constants in `src/core/config.h`:

- `kTextureBudgetFraction` – fraction of total device‑local VRAM reserved for streamed textures (default `0.35`).
- `kTextureBudgetFallbackBytes` – fallback budget when memory properties are unavailable (default `512 MiB`).
- `kTextureBudgetMinBytes` – minimum budget clamp (default `128 MiB`).

To globally change how aggressive streaming can be, edit these constants in `config.h` and rebuild. Use the `GameAPI::Engine` setters for per‑scene tuning (e.g. reducing upload bandwidth on low‑end machines).

#### Texture Loading

```cpp
// Load from file (relative to assets/textures/ or absolute path)
TextureHandle load_texture(const std::string& path, const TextureLoadParams& params = {});

// Load from memory (compressed image data: PNG, JPG, KTX2, etc.)
TextureHandle load_texture_from_memory(const std::vector<uint8_t>& data, const TextureLoadParams& params = {});

// Check if texture is loaded and resident in VRAM
bool is_texture_loaded(TextureHandle handle) const;

// Get internal Vulkan image view (VkImageView) for advanced use
void* get_texture_image_view(TextureHandle handle) const;

// Pin texture to prevent automatic eviction (for UI, critical assets)
void pin_texture(TextureHandle handle);
void unpin_texture(TextureHandle handle);
bool is_texture_pinned(TextureHandle handle) const;

// Unload texture and free VRAM (optional - cache auto-manages)
void unload_texture(TextureHandle handle);

// Create ImGui descriptor set for use with ImGui::Image()
void* create_imgui_texture(TextureHandle handle, void* sampler = nullptr);
void free_imgui_texture(void* imgui_texture_id);
```

**TextureLoadParams:**
```cpp
struct TextureLoadParams
{
    bool srgb{false};                      // Use sRGB color space (true for albedo/emissive)
    bool mipmapped{true};                  // Generate mipmap chain
    TextureChannels channels{Auto};        // Channel hint (Auto, R, RG, RGBA)
    uint32_t mipLevels{0};                 // 0 = full chain, otherwise limit to N levels
};
```

**Usage Example:**
```cpp
GameAPI::Engine api(&engine);

// Load UI texture and pin it to prevent eviction
GameAPI::TextureLoadParams params;
params.srgb = true;
params.mipmapped = false;  // UI textures don't need mipmaps
TextureHandle uiTex = api.load_texture("ui/button.png", params);
api.pin_texture(uiTex);

// Create ImGui descriptor for rendering
void* imguiId = api.create_imgui_texture(uiTex);
ImGui::Image(imguiId, ImVec2(128, 64));

// Later: cleanup
api.free_imgui_texture(imguiId);
api.unpin_texture(uiTex);
```

### Shadows: Resolution, Quality, and RT Modes

Shadows are controlled by a combination of:

- Global settings in `EngineContext::shadowSettings`.
- Config constants in `src/core/config.h`.
- The `ShadowPass` render pass and lighting shader (`shadow.vert`, `deferred_lighting.frag`).

High‑level game‑side controls:

- `void set_shadows_enabled(bool enabled);`
- `void set_shadow_mode(ShadowMode mode);`
  - `ClipmapOnly` – cascaded shadow maps only.
  - `ClipmapPlusRT` – cascades + optional ray‑query assist.
  - `RTOnly` – ray‑traced shadows only (no raster maps).
- `void set_hybrid_ray_cascade_mask(uint32_t mask);`
- `void set_hybrid_ray_threshold(float threshold);`

These map directly onto `EngineContext::shadowSettings` and are also visualized in the ImGui “Shadows / Ray Query” tab.

#### Shadow Map Resolution (`kShadowMapResolution`)

The shadow map resolution is driven by `kShadowMapResolution` in `src/core/config.h`:

- Used for:
  - The actual depth image size created for each cascaded shadow map in `VulkanEngine::draw()` (`shadowExtent`).
  - Texel snapping for cascade stabilization in `SceneManager::update_scene()`:
    - `texel = (2.0f * cover) / float(kShadowMapResolution);`
- Default: `2048.0f`, which gives a good compromise between quality and VRAM usage on mid‑range GPUs.

Increasing `kShadowMapResolution` has two important effects:

- **VRAM cost grows quadratically.**
  - Depth D32F, per cascade:
    - 2048 → ~16 MB.
    - 4096 → ~64 MB.
  - With 4 cascades, 4096×4096 can consume ~256 MB just for shadow depth, on top of swapchain, HDR, G‑buffers, IBL, and other images.
- **Allocation failures can effectively “kill” shadows.**
  - All shadow maps are created as transient RenderGraph images each frame run.
  - If VMA runs out of suitable device‑local memory, `vmaCreateImage` will fail, and the engine will assert via `VK_CHECK`. In practice (especially in a release build), this often manifests as:
    - No shadow rendering, or
    - The app aborting when the first frame tries to allocate these images.

Practical guidance:

- Prefer 2048 or 3072 on consumer hardware unless you have headroom and have profiled memory.
- If you push to 4096 and shadows “disappear”, suspect VRAM pressure:
  - Try reducing `kTextureBudgetFraction` so textures use less VRAM.
  - Or bring `kShadowMapResolution` back down and re‑test.

The following quality‑related shadow constants also live in `config.h`:

- `kShadowCascadeCount`, `kShadowCSMFar`, `kShadowCascadeRadiusScale`, `kShadowCascadeRadiusMargin`.
- `kShadowBorderSmoothNDC`, `kShadowPCFBaseRadius`, `kShadowPCFCascadeGain`.
- `kShadowDepthBiasConstant`, `kShadowDepthBiasSlope`.

These affect how cascades are distributed and how soft/filtered the resulting shadows are. Changing them is safe but should be tested against your content and FOV ranges.

### IBL (Image-Based Lighting)

**API:**
```cpp
// Load global IBL asynchronously
bool load_global_ibl(const IBLPaths& paths);

// Get/set global IBL paths (does not trigger reload)
IBLPaths get_global_ibl_paths() const;
void set_global_ibl_paths(const IBLPaths& paths);

// Add/remove local IBL volumes
size_t add_ibl_volume(const IBLVolume& volume);
size_t add_ibl_volume(const IBLVolumeD& volume);  // double-precision
bool remove_ibl_volume(size_t index);

// Get/set IBL volume properties
bool get_ibl_volume(size_t index, IBLVolume& out) const;
bool set_ibl_volume(size_t index, const IBLVolume& volume);
bool get_ibl_volume(size_t index, IBLVolumeD& out) const;  // double-precision
bool set_ibl_volume(size_t index, const IBLVolumeD& volume);

// Query active volume
int get_active_ibl_volume() const;  // -1 = global
size_t get_ibl_volume_count() const;
void clear_ibl_volumes();
```

**Structures:**
```cpp
struct IBLPaths
{
    std::string specularCube;  // .ktx2 specular cubemap
    std::string diffuseCube;   // .ktx2 diffuse cubemap
    std::string brdfLut;       // .ktx2 BRDF lookup table
    std::string background;    // .ktx2 background (optional, falls back to specular)
};

struct IBLVolume
{
    glm::vec3 center{0.0f};
    glm::vec3 halfExtents{10.0f};
    IBLPaths paths;
    bool enabled{true};
};

struct IBLVolumeD  // double-precision variant
{
    glm::dvec3 center{0.0};
    glm::vec3 halfExtents{10.0f};
    IBLPaths paths;
    bool enabled{true};
};
```

**Usage Example:**
```cpp
GameAPI::Engine api(&engine);

// Load global IBL (outdoor environment)
GameAPI::IBLPaths globalIBL;
globalIBL.specularCube = "ibl/outdoor_spec.ktx2";
globalIBL.diffuseCube = "ibl/outdoor_diff.ktx2";
globalIBL.brdfLut = "ibl/brdf_lut.ktx2";
api.load_global_ibl(globalIBL);

// Create local IBL volume for interior (overrides global when camera inside)
GameAPI::IBLVolume interior;
interior.center = glm::vec3(10.0f, 2.0f, -5.0f);
interior.halfExtents = glm::vec3(5.0f, 3.0f, 5.0f);
interior.paths.specularCube = "ibl/indoor_spec.ktx2";
interior.paths.diffuseCube = "ibl/indoor_diff.ktx2";
interior.paths.brdfLut = "ibl/brdf_lut.ktx2";
interior.enabled = true;

size_t idx = api.add_ibl_volume(interior);

// Query which IBL is active
int activeVol = api.get_active_ibl_volume();
if (activeVol == -1)
{
    // Using global IBL
}
else
{
    // Using local volume at index activeVol
}
```

### Reflections and Post‑Processing

Game‑side reflection controls:

- `void set_ssr_enabled(bool enabled);`
- `void set_reflection_mode(ReflectionMode mode);`
  (`SSROnly`, `SSRPlusRT`, `RTOnly`)

Tone mapping and bloom:

- `void set_exposure(float exposure);`
- `void set_tonemap_operator(TonemapOperator op);` (`Reinhard`, `ACES`)
- `void set_bloom_enabled(bool enabled);`
- `void set_bloom_threshold(float threshold);`
- `void set_bloom_intensity(float intensity);`

These wrap `TonemapPass` parameters and are equivalent to flipping the corresponding ImGui controls at runtime.

FXAA:

- `void set_fxaa_enabled(bool enabled);`
- `void set_fxaa_edge_threshold(float threshold);`
- `void set_fxaa_edge_threshold_min(float threshold);`

### Camera and Render Scale

Camera:

- `void set_camera_position(const glm::vec3 &position);`
- `void set_camera_position(const glm::dvec3 &position);`  // double-precision
- `glm::vec3 get_camera_position() const;`
- `glm::dvec3 get_camera_position_d() const;`  // double-precision
- `void set_camera_rotation(float pitchDeg, float yawDeg);`
- `void get_camera_rotation(float &pitchDeg, float &yawDeg) const;`
- `void set_camera_fov(float fovDegrees);`
- `float get_camera_fov() const;`
- `void camera_look_at(const glm::vec3 &target);`
- `void camera_look_at(const glm::dvec3 &target);`  // double-precision

These functions internally manipulate the quaternion‑based `Camera::orientation` and `position` in `SceneManager`. They respect the engine's `-Z` forward convention. Double-precision variants allow precise camera positioning in large worlds.

Render resolution scaling:

- `void set_render_scale(float scale); // 0.3–1.0`
- `float get_render_scale() const;`

This scales the internal draw extent relative to the swapchain and main HDR image sizes, trading resolution for performance.

### Picking & Pass Toggles

Picking:

- `Engine::PickResult get_last_pick() const;`
- `Engine::PickResultD get_last_pick_d() const;`  // double-precision
- `void set_use_id_buffer_picking(bool use);`
- `bool get_use_id_buffer_picking() const;`

**PickResult structure:**
```cpp
struct PickResult
{
    bool valid{false};
    std::string ownerName;
    glm::vec3 worldPosition{0.0f};
};

struct PickResultD  // double-precision variant
{
    bool valid{false};
    std::string ownerName;
    glm::dvec3 worldPosition{0.0};
};
```

These mirror `VulkanEngine::get_last_pick()` and `_useIdBufferPicking`, letting you choose between:

- CPU raycast picking (immediate, cheaper VRAM).
- ID‑buffer based picking (async, 1‑frame latency, robust for dense scenes).

Render‑graph pass toggles:

- `void set_pass_enabled(const std::string &passName, bool enabled);`
- `bool get_pass_enabled(const std::string &passName) const;`

This writes into `VulkanEngine::_rgPassToggles` and is applied during RenderGraph compilation. It allows you to permanently disable or enable named passes (e.g. `"ShadowMap[0]"`, `"FXAA"`, `"SSR"`) from game code, not just via the debug UI.

---

## Input System

Header: `src/core/input/input_system.h`
Docs: `docs/InputSystem.md`

The engine provides a unified input abstraction layer that wraps SDL2 events. Access it via `VulkanEngine::input()` or store a reference during initialization.

### Polled State (Recommended for Games)

Query current keyboard/mouse state each frame:

```cpp
void Game::update(VulkanEngine& engine)
{
    const InputState& input = engine.input().state();

    // Movement (held keys)
    glm::vec3 move{0.0f};
    if (input.key_down(Key::W)) move.z -= 1.0f;
    if (input.key_down(Key::S)) move.z += 1.0f;
    if (input.key_down(Key::A)) move.x -= 1.0f;
    if (input.key_down(Key::D)) move.x += 1.0f;

    // Sprint modifier
    float speed = input.modifiers().shift ? 10.0f : 5.0f;
    player.move(move * speed * dt);

    // Fire on left click (just pressed this frame)
    if (input.mouse_pressed(MouseButton::Left))
    {
        player.fire();
    }

    // Toggle menu on Escape (just pressed)
    if (input.key_pressed(Key::Escape))
    {
        ui.toggle_menu();
    }

    // Mouse look (right button held)
    if (input.mouse_down(MouseButton::Right))
    {
        engine.input().set_cursor_mode(CursorMode::Relative);
        glm::vec2 delta = input.mouse_delta();
        camera.rotate(delta.x * 0.1f, delta.y * 0.1f);
    }
    else
    {
        engine.input().set_cursor_mode(CursorMode::Normal);
    }

    // Scroll wheel for zoom
    float scroll = input.wheel_delta().y;
    if (scroll != 0.0f)
    {
        camera.zoom(scroll * 0.5f);
    }
}
```

### Key State Types

- `key_down(Key)` / `mouse_down(MouseButton)` — true while held (continuous actions)
- `key_pressed(Key)` / `mouse_pressed(MouseButton)` — true only on the frame it was pressed (one-shot)
- `key_released(Key)` / `mouse_released(MouseButton)` — true only on the frame it was released

### Available Keys

Letters: `Key::A` through `Key::Z`
Numbers: `Key::Num0` through `Key::Num9`
Special: `Key::Enter`, `Key::Escape`, `Key::Space`, `Key::Tab`, `Key::Backspace`
Modifiers: `Key::LeftShift`, `Key::LeftCtrl`, `Key::LeftAlt`, `Key::LeftSuper` (and Right variants)

### Mouse Buttons

`MouseButton::Left`, `MouseButton::Middle`, `MouseButton::Right`, `MouseButton::X1`, `MouseButton::X2`

### Cursor Modes

```cpp
enum class CursorMode : uint8_t
{
    Normal = 0,   // Default visible cursor
    Hidden = 1,   // Hidden but not captured
    Relative = 2, // FPS-style: hidden + captured, only delta matters
};

// Set via:
engine.input().set_cursor_mode(CursorMode::Relative);
```

### Mouse Position and Motion

```cpp
glm::vec2 pos   = input.mouse_position(); // Screen coordinates (pixels)
glm::vec2 delta = input.mouse_delta();    // Frame motion delta
glm::vec2 wheel = input.wheel_delta();    // Scroll wheel delta
```

### Modifier Keys

```cpp
InputModifiers mods = input.modifiers();
if (mods.ctrl && input.key_pressed(Key::S))
{
    save_game();
}
```

### Event-Driven Access (For UI)

For text input or other event-driven needs:

```cpp
for (const InputEvent& ev : engine.input().events())
{
    if (ev.type == InputEvent::Type::KeyDown)
    {
        if (ev.key == Key::Backspace)
        {
            text_field.delete_char();
        }
    }
    else if (ev.type == InputEvent::Type::MouseWheel)
    {
        scroll_view.scroll(ev.wheel_delta.y);
    }
}
```

### Window State

```cpp
if (engine.input().quit_requested())
{
    // Handle window close
}

if (engine.input().window_minimized())
{
    // Skip heavy rendering
}
```

---

## VulkanEngine Helpers

Header: `src/core/engine.h`

- Lifecycle
  - `void init()` – initialize SDL, device, managers, scene, render graph.
  - `void run()` – main loop: handles events, updates scene, builds Render Graph, submits frames.
  - `void cleanup()` – destroy managers and GPU resources.

- GLTF spawn helper
  - `bool addGLTFInstance(const std::string &instanceName, const std::string &modelRelativePath, const glm::mat4 &transform = glm::mat4(1.f));`
    - Loads a glTF from `assets/models/...` (via `AssetManager`) and registers it as a runtime scene instance.
    - `instanceName` becomes the logical name used by `SceneManager` (e.g. for picking and animation control).

- Picking access
  - `struct PickInfo` (nested in `VulkanEngine`)
    - `MeshAsset *mesh`, `LoadedGLTF *scene`, `Node *node`
    - `RenderObject::OwnerType ownerType` (e.g. `StaticGLTF`, `GLTFInstance`, `MeshInstance`)
    - `std::string ownerName`
    - `glm::vec3 worldPos`
    - `glm::mat4 worldTransform`
    - `uint32_t indexCount`, `firstIndex`, `surfaceIndex`
    - `bool valid`
  - `const PickInfo &get_last_pick() const`
    - Returns the last click selection result.
    - Filled by the engine from either CPU ray picking or ID‑buffer picking depending on `_useIdBufferPicking`.
    - Typical usage:
      - On mouse‑up in your game layer, read `engine->get_last_pick()` and, if `valid`, use `ownerName`/`worldPos` to drive selection logic.

> Note: hover picks and drag selections are also available as internal fields on `VulkanEngine` (`_hoverPick`, `_dragSelection`) and are documented in `docs/Scene.md`. You can expose additional getters if you want to rely on them from game code.

---

## Scene & Instances (Actors, Lights, Animations)

Header: `src/scene/vk_scene.h`
Docs: `docs/Scene.md`

### Transform Structures

The GameAPI provides both single and double-precision transform representations:

```cpp
struct Transform
{
    glm::vec3 position{0.0f};
    glm::quat rotation{1.0f, 0.0f, 0.0f, 0.0f};
    glm::vec3 scale{1.0f};

    glm::mat4 to_matrix() const;
    static Transform from_matrix(const glm::mat4& m);
};

struct TransformD  // double-precision variant for large worlds
{
    glm::dvec3 position{0.0};
    glm::quat rotation{1.0f, 0.0f, 0.0f, 0.0f};
    glm::vec3 scale{1.0f};

    glm::mat4 to_matrix() const;
    static TransformD from_matrix(const glm::mat4& m);
};
```

Use `TransformD` for positioning objects in large worlds (e.g., space games, flight sims) where single-precision floating point loses sub-meter precision at large coordinates.

### GLTF Instances

**API:**
```cpp
// Add glTF model instance (path relative to assets/models/)
bool add_gltf_instance(const std::string& name,
                       const std::string& modelPath,
                       const Transform& transform = {},
                       bool preloadTextures = true);
bool add_gltf_instance(const std::string& name,
                       const std::string& modelPath,
                       const TransformD& transform,
                       bool preloadTextures = true);

// Add glTF model asynchronously (returns job ID, 0 on failure)
uint32_t add_gltf_instance_async(const std::string& name,
                                  const std::string& modelPath,
                                  const Transform& transform = {},
                                  bool preloadTextures = true);
uint32_t add_gltf_instance_async(const std::string& name,
                                  const std::string& modelPath,
                                  const TransformD& transform,
                                  bool preloadTextures = true);

// Remove glTF instance
bool remove_gltf_instance(const std::string& name);

// Get/set glTF instance transform
bool get_gltf_instance_transform(const std::string& name, Transform& out) const;
bool set_gltf_instance_transform(const std::string& name, const Transform& transform);
bool get_gltf_instance_transform(const std::string& name, TransformD& out) const;
bool set_gltf_instance_transform(const std::string& name, const TransformD& transform);

// Preload textures for an instance
void preload_instance_textures(const std::string& name);

// Clear all dynamic instances
void clear_all_instances();
```

### Primitive Mesh Instances

**API:**
```cpp
// Add primitive mesh instance
bool add_primitive_instance(const std::string& name,
                            PrimitiveType type,
                            const Transform& transform = {});
bool add_primitive_instance(const std::string& name,
                            PrimitiveType type,
                            const TransformD& transform);

// Remove mesh instance
bool remove_mesh_instance(const std::string& name);

// Get/set mesh instance transform
bool get_mesh_instance_transform(const std::string& name, Transform& out) const;
bool set_mesh_instance_transform(const std::string& name, const Transform& transform);
bool get_mesh_instance_transform(const std::string& name, TransformD& out) const;
bool set_mesh_instance_transform(const std::string& name, const TransformD& transform);
```

**Typical usage:**
- Spawn primitives or dynamic meshes at runtime (e.g. projectiles, props).
- Use `set_mesh_instance_transform` every frame to move them based on game logic.

### Textured Primitives

Spawn primitive meshes (cube, sphere, plane, capsule) with custom PBR textures at runtime.

#### PrimitiveMaterial Structure

```cpp
struct PrimitiveMaterial
{
    std::string albedoPath;        // Color/diffuse texture (relative to assets/)
    std::string metalRoughPath;    // Metallic (R) + Roughness (G) texture
    std::string normalPath;        // Tangent-space normal map
    std::string occlusionPath;     // Ambient occlusion (R channel)
    std::string emissivePath;      // Emissive map

    glm::vec4 colorFactor{1.0f};   // Base color multiplier (RGBA)
    float metallic{0.0f};          // Metallic factor (0-1)
    float roughness{0.5f};         // Roughness factor (0-1)
};
```

#### PrimitiveType Enum

```cpp
enum class PrimitiveType
{
    Cube,
    Sphere,
    Plane,
    Capsule
};
```

#### API Functions

```cpp
bool add_textured_primitive(const std::string& name,
                            PrimitiveType type,
                            const PrimitiveMaterial& material,
                            const Transform& transform = {});

bool add_textured_primitive(const std::string& name,
                            PrimitiveType type,
                            const PrimitiveMaterial& material,
                            const TransformD& transform);  // double-precision
```

#### Usage Example

```cpp
GameAPI::Engine api(&engine);

// Create material with textures
GameAPI::PrimitiveMaterial mat;
mat.albedoPath = "textures/brick_albedo.png";
mat.normalPath = "textures/brick_normal.png";
mat.metalRoughPath = "textures/brick_mro.png";  // Metallic-Roughness-Occlusion packed
mat.roughness = 0.7f;
mat.metallic = 0.0f;

// Spawn a textured cube
GameAPI::Transform transform;
transform.position = glm::vec3(0.0f, 1.0f, -5.0f);
transform.scale = glm::vec3(2.0f);

api.add_textured_primitive("my_brick_cube", GameAPI::PrimitiveType::Cube, mat, transform);

// Spawn a textured sphere with different material
GameAPI::PrimitiveMaterial metalMat;
metalMat.albedoPath = "textures/metal_albedo.png";
metalMat.normalPath = "textures/metal_normal.png";
metalMat.metallic = 1.0f;
metalMat.roughness = 0.3f;
metalMat.colorFactor = glm::vec4(0.9f, 0.9f, 1.0f, 1.0f);  // Slight blue tint

GameAPI::Transform sphereT;
sphereT.position = glm::vec3(3.0f, 1.0f, -5.0f);

api.add_textured_primitive("chrome_sphere", GameAPI::PrimitiveType::Sphere, metalMat, sphereT);
```

#### Notes

- Texture paths are relative to the `assets/` directory.
- If a texture path is empty, the engine uses default placeholder textures:
  - Albedo: error checkerboard (magenta/black)
  - Normal: flat normal (0.5, 0.5, 1.0)
  - MetalRough: white (default values from `metallic`/`roughness` factors)
  - Occlusion: white (no occlusion)
  - Emissive: black (no emission)
- Textures are loaded asynchronously via `TextureCache`; placeholders appear until upload completes.
- For non-textured primitives with solid colors, use `add_primitive_instance()` instead.

- GLTF instances (actors)
  - `void addGLTFInstance(const std::string &name, std::shared_ptr<LoadedGLTF> scene, const glm::mat4 &transform = glm::mat4(1.f));`
  - `bool getGLTFInstanceTransform(const std::string &name, glm::mat4 &outTransform);`
  - `bool setGLTFInstanceTransform(const std::string &name, const glm::mat4 &transform);`
  - `bool removeGLTFInstance(const std::string &name);`
  - `void clearGLTFInstances();`
  - Usage pattern:
    - Treat each GLTF instance as an “actor” with a name; use transforms to place characters, doors, props, etc.

### Animations (GLTF)

**API:**
```cpp
// Set animation by index for a glTF instance (-1 to disable)
bool set_instance_animation(const std::string& instanceName, int animationIndex, bool resetTime = true);

// Set animation by name for a glTF instance
bool set_instance_animation(const std::string& instanceName, const std::string& animationName, bool resetTime = true);

// Set animation looping for a glTF instance
bool set_instance_animation_loop(const std::string& instanceName, bool loop);
```

**Notes:**
- All functions return `bool` indicating whether the named instance exists.
- Animation state is **independent per instance**:
  - Each glTF instance has its own `AnimationState`, even when sharing the same `LoadedGLTF`.
- An index `< 0` (e.g. `-1`) disables animation for that instance (pose is frozen at the last evaluated state).
- `SceneManager::update_scene()` advances each active animation state every frame using engine delta time.

**Usage Example:**
```cpp
GameAPI::Engine api(&engine);

// Play walk animation by index
api.set_instance_animation("player", 0, true);  // Reset to start
api.set_instance_animation_loop("player", true);

// Switch to run animation by name
api.set_instance_animation("player", "run", true);

// Stop animation (freeze pose)
api.set_instance_animation("player", -1);
```

### Per‑Instance Node / Joint Control (Non‑Skinned)

For rigid models and simple "joints" (e.g. flaps, doors, turrets), you can apply local‑space pose offsets to individual glTF nodes per instance:

**API:**
```cpp
bool set_instance_node_offset(const std::string& instanceName, const std::string& nodeName, const glm::mat4& offset);
bool clear_instance_node_offset(const std::string& instanceName, const std::string& nodeName);
void clear_all_instance_node_offsets(const std::string& instanceName);
```

Typical usage:

- Use glTF animation for the base motion (e.g. gear deployment).
- Layer game‑driven offsets on top for per‑instance control:

  ```cpp
  // Rotate a control surface on one aircraft instance
  glm::mat4 offset =
      glm::rotate(glm::mat4(1.f),
                  glm::radians(aileronDegrees),
                  glm::vec3(1.f, 0.f, 0.f));
  sceneMgr->setGLTFInstanceNodeOffset("plane01", "LeftAileron", offset);
  ```

### Lighting - Directional (Sunlight)

- `void set_sunlight_direction(const glm::vec3& dir);`
- `glm::vec3 get_sunlight_direction() const;`
- `void set_sunlight_color(const glm::vec3& color, float intensity);`
- `glm::vec3 get_sunlight_color() const;`
- `float get_sunlight_intensity() const;`

### Lighting - Point Lights

**Structs:**
```cpp
struct PointLight
{
    glm::vec3 position{0.0f};
    float radius{10.0f};
    glm::vec3 color{1.0f};
    float intensity{1.0f};
};

struct PointLightD  // double-precision variant
{
    glm::dvec3 position{0.0};
    float radius{10.0f};
    glm::vec3 color{1.0f};
    float intensity{1.0f};
};
```

**API:**
- `size_t add_point_light(const PointLight &light);`
- `size_t add_point_light(const PointLightD &light);`
- `bool remove_point_light(size_t index);`
- `bool get_point_light(size_t index, PointLight &out) const;`
- `bool get_point_light(size_t index, PointLightD &out) const;`
- `bool set_point_light(size_t index, const PointLight &light);`
- `bool set_point_light(size_t index, const PointLightD &light);`
- `size_t get_point_light_count() const;`
- `void clear_point_lights();`

**Typical usage:**
- On level load, add all static lights.
- At runtime, animate or toggle lights based on gameplay events (e.g. explosions, flickering lamps).

### Lighting - Spot Lights

**Structs:**
```cpp
struct SpotLight
{
    glm::vec3 position{0.0f};
    glm::vec3 direction{0.0f, -1.0f, 0.0f};
    float radius{10.0f};
    glm::vec3 color{1.0f};
    float intensity{1.0f};
    float inner_angle_deg{15.0f};
    float outer_angle_deg{25.0f};
};

struct SpotLightD  // double-precision variant
{
    glm::dvec3 position{0.0};
    glm::vec3 direction{0.0f, -1.0f, 0.0f};
    float radius{10.0f};
    glm::vec3 color{1.0f};
    float intensity{1.0f};
    float inner_angle_deg{15.0f};
    float outer_angle_deg{25.0f};
};
```

**API:**
- `size_t add_spot_light(const SpotLight &light);`
- `size_t add_spot_light(const SpotLightD &light);`
- `bool remove_spot_light(size_t index);`
- `bool get_spot_light(size_t index, SpotLight &out) const;`
- `bool get_spot_light(size_t index, SpotLightD &out) const;`
- `bool set_spot_light(size_t index, const SpotLight &light);`
- `bool set_spot_light(size_t index, const SpotLightD &light);`
- `size_t get_spot_light_count() const;`
- `void clear_spot_lights();`

**Usage Example:**
```cpp
GameAPI::Engine api(&engine);

// Create a flashlight
GameAPI::SpotLight flashlight;
flashlight.position = glm::vec3(0.0f, 1.5f, 0.0f);
flashlight.direction = glm::vec3(0.0f, 0.0f, -1.0f);
flashlight.radius = 20.0f;
flashlight.color = glm::vec3(1.0f, 0.95f, 0.8f);  // Warm white
flashlight.intensity = 50.0f;
flashlight.inner_angle_deg = 10.0f;
flashlight.outer_angle_deg = 25.0f;

size_t idx = api.add_spot_light(flashlight);

// Later: update flashlight direction to follow camera
flashlight.direction = camera_forward;
api.set_spot_light(idx, flashlight);
```

---

## Picking System

Header: `src/core/picking/picking_system.h`
Docs: `docs/Picking.md`

The engine provides a unified picking system that handles click selection, hover detection, and drag-box multi-select. Access it via `VulkanEngine::picking()`.

### Accessing Pick Results

```cpp
void Game::handle_interaction(VulkanEngine& engine)
{
    PickingSystem& picking = engine.picking();

    // Last click selection
    const PickingSystem::PickInfo& pick = picking.last_pick();
    if (pick.valid)
    {
        fmt::println("Selected: {}", pick.ownerName);
        interact_with(pick.ownerName, pick.worldPos);
    }

    // Current hover (for tooltips)
    const PickingSystem::PickInfo& hover = picking.hover_pick();
    if (hover.valid)
    {
        show_tooltip(hover.ownerName);
    }

    // Drag-box multi-select
    for (const auto& sel : picking.drag_selection())
    {
        if (sel.valid)
        {
            add_to_selection(sel.ownerName);
        }
    }
}
```

### PickInfo Structure

```cpp
struct PickInfo
{
    MeshAsset *mesh;                     // Source mesh
    LoadedGLTF *scene;                   // Source glTF
    Node *node;                          // glTF node
    RenderObject::OwnerType ownerType;   // StaticGLTF, GLTFInstance, MeshInstance
    std::string ownerName;               // Logical name (e.g., "player")
    WorldVec3 worldPos;                  // Hit position (double-precision)
    glm::mat4 worldTransform;            // Object transform
    uint32_t indexCount, firstIndex;     // Picked surface indices
    uint32_t surfaceIndex;               // Surface index in mesh
    bool valid;                          // True if hit something
};
```

### Picking Modes

```cpp
// CPU ray picking (default) - immediate, BVH-accelerated
picking.set_use_id_buffer_picking(false);

// ID-buffer picking - pixel-perfect, 1-frame latency
picking.set_use_id_buffer_picking(true);
```

### Owner Types

```cpp
enum class OwnerType
{
    None,
    StaticGLTF,    // Loaded via loadScene()
    GLTFInstance,  // Runtime glTF instance
    MeshInstance,  // Runtime mesh instance
};
```

---

## ImGui System

Header: `src/core/ui/imgui_system.h`
Docs: `docs/ImGuiSystem.md`

The engine integrates Dear ImGui for debug UI and editor tools. Access it via `VulkanEngine::imgui()`.

### Adding Custom UI

```cpp
void Game::init(VulkanEngine& engine)
{
    // Register your UI callback
    engine.imgui().add_draw_callback([this]() {
        draw_game_ui();
    });
}

void Game::draw_game_ui()
{
    if (ImGui::Begin("Game HUD"))
    {
        ImGui::Text("Score: %d", _score);
        ImGui::Text("Health: %.0f%%", _health * 100.0f);

        if (ImGui::Button("Pause"))
        {
            toggle_pause();
        }
    }
    ImGui::End();
}
```

### Input Capture

Always check ImGui input capture before processing game input:

```cpp
void Game::update(VulkanEngine& engine)
{
    // Skip game mouse input when ImGui wants it
    if (!engine.imgui().want_capture_mouse())
    {
        handle_mouse_input();
    }

    // Skip game keyboard input when ImGui wants it
    if (!engine.imgui().want_capture_keyboard())
    {
        handle_keyboard_input();
    }
}
```

### Built-in Debug UI

The engine provides comprehensive debug widgets in `src/core/engine_ui.cpp`:

- **Window Tab**: Monitor selection, fullscreen modes, HiDPI info
- **Stats Tab**: Frame time, FPS, draw calls, triangle count
- **Scene Tab**: Instance spawning, point light editor, ImGuizmo gizmos
- **Render Graph Tab**: Pass toggles, resource tracking
- **Texture Streaming Tab**: VRAM budget, cache stats
- **Shadows Tab**: Shadow mode, cascade visualization
- **Post Processing Tab**: Tonemapping, bloom, FXAA, SSR settings

### ImGuizmo Integration

For 3D transform gizmos on selected objects:

```cpp
#include "ImGuizmo.h"

void draw_gizmo(const PickingSystem::PickInfo& pick,
                const glm::mat4& view, const glm::mat4& proj)
{
    if (!pick.valid) return;

    glm::mat4 transform = pick.worldTransform;

    ImGuizmo::SetOrthographic(false);
    ImGuizmo::SetDrawlist();

    ImGuiIO& io = ImGui::GetIO();
    ImGuizmo::SetRect(0, 0, io.DisplaySize.x, io.DisplaySize.y);

    if (ImGuizmo::Manipulate(glm::value_ptr(view),
                             glm::value_ptr(proj),
                             ImGuizmo::TRANSLATE,
                             ImGuizmo::WORLD,
                             glm::value_ptr(transform)))
    {
        // Apply transform to the picked object
        scene->setGLTFInstanceTransform(pick.ownerName, transform);
    }
}
```

---

## Time and Statistics

Header: `src/core/game_api.h`

### Delta Time

```cpp
// Get delta time in seconds for the current frame (clamped to 0.0-0.1)
float get_delta_time() const;
```

Use this for frame-rate independent movement and animation.

### Engine Statistics

```cpp
struct Stats
{
    float frametime{0.0f};       // ms
    float drawTime{0.0f};        // ms
    float sceneUpdateTime{0.0f}; // ms
    int triangleCount{0};
    int drawCallCount{0};
};

Stats get_stats() const;
```

**Usage Example:**
```cpp
GameAPI::Engine api(&engine);

// Frame-rate independent movement
float dt = api.get_delta_time();
player_position += velocity * dt;

// Display performance stats
GameAPI::Stats stats = api.get_stats();
fmt::println("FPS: {:.1f} | Tris: {} | Draws: {}",
             1000.0f / stats.frametime,
             stats.triangleCount,
             stats.drawCallCount);
```

---

## Volumetrics (Clouds, Smoke, Flame)

Header: `src/core/game_api.h`

The engine supports GPU-based voxel volumetric rendering for clouds, smoke, and flame effects. Up to 4 independent volumes can be active simultaneously.

### API

```cpp
// Enable/disable volumetrics system
void set_volumetrics_enabled(bool enabled);
bool get_volumetrics_enabled() const;

// Get/set voxel volume settings by index (0-3)
bool get_voxel_volume(size_t index, VoxelVolumeSettings& out) const;
bool set_voxel_volume(size_t index, const VoxelVolumeSettings& settings);

// Get maximum number of voxel volumes
size_t get_max_voxel_volumes() const;  // Returns 4
```

### VoxelVolumeSettings Structure

```cpp
struct VoxelVolumeSettings
{
    bool enabled{false};
    VoxelVolumeType type{VoxelVolumeType::Clouds};  // Clouds, Smoke, Flame

    // Volume positioning
    bool followCameraXZ{false};     // Follow camera in XZ, offset in Y
    bool animateVoxels{true};       // Run voxel advection/update compute
    glm::vec3 volumeCenterLocal{0.0f, 2.0f, 0.0f};
    glm::vec3 volumeHalfExtents{8.0f, 8.0f, 8.0f};
    glm::vec3 volumeVelocityLocal{0.0f, 0.0f, 0.0f};  // Drift when not following camera

    // Raymarch/composite controls
    float densityScale{1.0f};
    float coverage{0.0f};        // 0..1 threshold (higher = emptier)
    float extinction{1.0f};      // Absorption/extinction scale
    int stepCount{48};           // Raymarch steps

    // Voxel grid resolution (cubic)
    uint32_t gridResolution{48};

    // Voxel animation (advection + injection) parameters
    glm::vec3 windVelocityLocal{0.0f, 2.0f, 0.0f};  // Local units/sec (buoyancy)
    float dissipation{1.25f};    // Density decay rate (1/sec)
    float noiseStrength{1.0f};   // Injection rate
    float noiseScale{8.0f};      // Noise frequency in UVW space
    float noiseSpeed{1.0f};      // Time scale for injection noise

    // Smoke/flame source in normalized volume UVW space
    glm::vec3 emitterUVW{0.5f, 0.05f, 0.5f};
    float emitterRadius{0.18f};  // Normalized (0..1)

    // Shading
    glm::vec3 albedo{1.0f, 1.0f, 1.0f};  // Scattering tint (cloud/smoke)
    float scatterStrength{1.0f};
    glm::vec3 emissionColor{1.0f, 0.6f, 0.25f};  // Flame emissive tint
    float emissionStrength{0.0f};
};
```

### Usage Example

```cpp
GameAPI::Engine api(&engine);

// Enable volumetrics
api.set_volumetrics_enabled(true);

// Create a flame effect
GameAPI::VoxelVolumeSettings flame;
flame.enabled = true;
flame.type = GameAPI::VoxelVolumeType::Flame;
flame.volumeCenterLocal = glm::vec3(0.0f, 1.0f, -5.0f);
flame.volumeHalfExtents = glm::vec3(2.0f, 3.0f, 2.0f);
flame.gridResolution = 64;
flame.densityScale = 1.5f;
flame.coverage = 0.3f;
flame.windVelocityLocal = glm::vec3(0.0f, 5.0f, 0.0f);  // Upward
flame.emitterUVW = glm::vec3(0.5f, 0.1f, 0.5f);
flame.emitterRadius = 0.2f;
flame.emissionStrength = 2.0f;
flame.emissionColor = glm::vec3(1.0f, 0.5f, 0.1f);

api.set_voxel_volume(0, flame);

// Create cloud layer that follows camera
GameAPI::VoxelVolumeSettings clouds;
clouds.enabled = true;
clouds.type = GameAPI::VoxelVolumeType::Clouds;
clouds.followCameraXZ = true;
clouds.volumeCenterLocal = glm::vec3(0.0f, 50.0f, 0.0f);  // Offset in Y
clouds.volumeHalfExtents = glm::vec3(100.0f, 20.0f, 100.0f);
clouds.gridResolution = 128;
clouds.densityScale = 0.8f;
clouds.coverage = 0.5f;
clouds.albedo = glm::vec3(0.9f, 0.95f, 1.0f);  // Bluish tint

api.set_voxel_volume(1, clouds);
```

---

## Particle Systems

Header: `src/core/game_api.h`

GPU-accelerated particle systems with flipbook animation, soft particles, and flexible spawning.

### API

```cpp
// Create/destroy particle systems
uint32_t create_particle_system(uint32_t particle_count);
bool destroy_particle_system(uint32_t id);
bool resize_particle_system(uint32_t id, uint32_t new_count);

// Get/set particle system settings
bool get_particle_system(uint32_t id, ParticleSystem& out) const;
bool set_particle_system(uint32_t id, const ParticleSystem& system);

// Query particle systems
std::vector<uint32_t> get_particle_system_ids() const;
uint32_t get_allocated_particles() const;
uint32_t get_free_particles() const;
uint32_t get_max_particles() const;

// Preload VFX textures (e.g., "vfx/flame.ktx2")
void preload_particle_texture(const std::string& assetPath);
```

### ParticleSystem Structure

```cpp
struct ParticleSystem
{
    uint32_t id{0};
    uint32_t particleCount{0};
    bool enabled{true};
    bool reset{true};
    ParticleBlendMode blendMode{ParticleBlendMode::Additive};  // Additive or Alpha
    ParticleParams params{};

    // Asset-relative texture paths (e.g., "vfx/flame.ktx2")
    std::string flipbookTexture{"vfx/flame.ktx2"};
    std::string noiseTexture{"vfx/simplex.ktx2"};
};

struct ParticleParams
{
    glm::vec3 emitterPosLocal{0.0f, 0.0f, 0.0f};
    float spawnRadius{0.1f};
    glm::vec3 emitterDirLocal{0.0f, 1.0f, 0.0f};
    float coneAngleDegrees{20.0f};

    float minSpeed{2.0f};
    float maxSpeed{8.0f};
    float minLife{0.5f};
    float maxLife{1.5f};
    float minSize{0.05f};
    float maxSize{0.15f};

    float drag{1.0f};
    float gravity{0.0f};  // Positive pulls down -Y in local space

    glm::vec4 color{1.0f, 0.5f, 0.1f, 1.0f};

    // Soft particles (fade near opaque geometry)
    float softDepthDistance{0.15f};

    // Flipbook animation (atlas layout)
    uint32_t flipbookCols{16};
    uint32_t flipbookRows{4};
    float flipbookFps{30.0f};
    float flipbookIntensity{1.0f};

    // Noise UV distortion
    float noiseScale{6.0f};
    float noiseStrength{0.05f};
    glm::vec2 noiseScroll{0.0f, 0.0f};
};
```

### Usage Example

```cpp
GameAPI::Engine api(&engine);

// Create fire particle system
uint32_t fireId = api.create_particle_system(4096);

GameAPI::ParticleSystem fire;
fire.id = fireId;
fire.particleCount = 4096;
fire.enabled = true;
fire.blendMode = GameAPI::ParticleBlendMode::Additive;
fire.flipbookTexture = "vfx/flame.ktx2";
fire.noiseTexture = "vfx/simplex.ktx2";

fire.params.emitterPosLocal = glm::vec3(0.0f, 0.0f, -5.0f);
fire.params.spawnRadius = 0.5f;
fire.params.emitterDirLocal = glm::vec3(0.0f, 1.0f, 0.0f);
fire.params.coneAngleDegrees = 15.0f;
fire.params.minSpeed = 2.0f;
fire.params.maxSpeed = 4.0f;
fire.params.minLife = 0.8f;
fire.params.maxLife = 1.5f;
fire.params.minSize = 0.3f;
fire.params.maxSize = 0.6f;
fire.params.gravity = -2.0f;  // Upward buoyancy
fire.params.color = glm::vec4(1.0f, 0.7f, 0.3f, 1.0f);
fire.params.flipbookCols = 16;
fire.params.flipbookRows = 4;
fire.params.flipbookFps = 24.0f;

api.set_particle_system(fireId, fire);

// Later: move emitter to follow player
fire.params.emitterPosLocal = player_position;
api.set_particle_system(fireId, fire);

// Reset particles (trigger burst)
fire.reset = true;
api.set_particle_system(fireId, fire);
```

---

## Debug Drawing

Header: `src/core/game_api.h`

Runtime debug visualization for primitives (lines, spheres, boxes, etc.) with optional depth testing and duration.

### Settings API

```cpp
// Enable/disable debug drawing system
void set_debug_draw_enabled(bool enabled);
bool get_debug_draw_enabled() const;

// Control which debug layers are visible (bitmask)
void set_debug_layer_mask(uint32_t mask);
uint32_t get_debug_layer_mask() const;

// Show/hide depth-tested primitives
void set_debug_show_depth_tested(bool show);
bool get_debug_show_depth_tested() const;

// Show/hide overlay (always-on-top) primitives
void set_debug_show_overlay(bool show);
bool get_debug_show_overlay() const;

// Set tessellation quality (segments for circles/spheres)
void set_debug_segments(int segments);
int get_debug_segments() const;

// Clear all debug draw commands
void debug_draw_clear();
```

### Drawing API

All drawing functions support both single and double-precision variants:

```cpp
// Line
void debug_draw_line(const glm::vec3& a, const glm::vec3& b,
                     const glm::vec4& color = glm::vec4(1.0f),
                     float duration_seconds = 0.0f,
                     bool depth_tested = true);
void debug_draw_line(const glm::dvec3& a, const glm::dvec3& b, ...);

// Ray (origin + direction + length)
void debug_draw_ray(const glm::vec3& origin, const glm::vec3& direction, float length,
                    const glm::vec4& color = glm::vec4(1.0f),
                    float duration_seconds = 0.0f,
                    bool depth_tested = true);
void debug_draw_ray(const glm::dvec3& origin, const glm::dvec3& direction, double length, ...);

// AABB (axis-aligned bounding box)
void debug_draw_aabb(const glm::vec3& center, const glm::vec3& half_extents,
                     const glm::vec4& color = glm::vec4(1.0f),
                     float duration_seconds = 0.0f,
                     bool depth_tested = true);
void debug_draw_aabb(const glm::dvec3& center, const glm::vec3& half_extents, ...);

// Sphere
void debug_draw_sphere(const glm::vec3& center, float radius,
                       const glm::vec4& color = glm::vec4(1.0f),
                       float duration_seconds = 0.0f,
                       bool depth_tested = true);
void debug_draw_sphere(const glm::dvec3& center, float radius, ...);

// Capsule (line segment + radius)
void debug_draw_capsule(const glm::vec3& p0, const glm::vec3& p1, float radius,
                        const glm::vec4& color = glm::vec4(1.0f),
                        float duration_seconds = 0.0f,
                        bool depth_tested = true);
void debug_draw_capsule(const glm::dvec3& p0, const glm::dvec3& p1, float radius, ...);

// Circle (center + normal + radius)
void debug_draw_circle(const glm::vec3& center, const glm::vec3& normal, float radius,
                       const glm::vec4& color = glm::vec4(1.0f),
                       float duration_seconds = 0.0f,
                       bool depth_tested = true);
void debug_draw_circle(const glm::dvec3& center, const glm::dvec3& normal, float radius, ...);

// Cone (apex + direction + length + angle)
void debug_draw_cone(const glm::vec3& apex, const glm::vec3& direction,
                     float length, float angle_degrees,
                     const glm::vec4& color = glm::vec4(1.0f),
                     float duration_seconds = 0.0f,
                     bool depth_tested = true);
void debug_draw_cone(const glm::dvec3& apex, const glm::dvec3& direction,
                     float length, float angle_degrees, ...);
```

### Usage Example

```cpp
GameAPI::Engine api(&engine);

// Enable debug drawing
api.set_debug_draw_enabled(true);
api.set_debug_segments(32);  // Smooth circles/spheres

// Visualize player bounds (persistent, depth-tested)
api.debug_draw_aabb(player_pos, glm::vec3(0.5f, 1.0f, 0.5f),
                    glm::vec4(0.0f, 1.0f, 0.0f, 1.0f),
                    0.0f,    // Duration 0 = single frame
                    true);   // Depth tested

// Visualize raycast (red ray, always on top, 2 seconds)
api.debug_draw_ray(ray_origin, ray_dir, 100.0f,
                   glm::vec4(1.0f, 0.0f, 0.0f, 1.0f),
                   2.0f,     // Show for 2 seconds
                   false);   // Always on top

// Visualize trigger volume (transparent sphere)
api.debug_draw_sphere(trigger_pos, trigger_radius,
                      glm::vec4(1.0f, 1.0f, 0.0f, 0.3f),  // Yellow, 30% alpha
                      0.0f,
                      true);

// Visualize spot light cone
api.debug_draw_cone(light_pos, light_dir, light_radius, light_angle_deg,
                    glm::vec4(1.0f, 0.9f, 0.7f, 0.5f),
                    0.0f,
                    true);

// One-shot clear (useful for clearing persistent debug viz)
api.debug_draw_clear();
```

**Notes:**
- `duration_seconds = 0.0f`: Draw for a single frame (re-submit each frame for persistent viz).
- `duration_seconds > 0.0f`: Draw for N seconds, then automatically expire.
- `depth_tested = true`: Primitive is occluded by scene geometry.
- `depth_tested = false`: Always on top (overlay mode).
- All primitives support alpha blending via the color's alpha channel.