archetype_asset 0.2.0

# Archetype Asset - Architecture Guide


## Overview


`archetype_asset` is a high-performance, modular asset management system designed for game engines. It prioritizes:
1.  **Zero-Overhead Abstractions**: Generic over GPU backends and Async runtimes.
2.  **Spatial Awareness**: Built-in spatial preloading and prioritization.
3.  **Memory Efficiency**: Unified memory pooling and smart eviction policies.

## Core Components


### 1. AssetCache (`src/cache/mod.rs`)

The central hub of the system.
- **Generics**: `AssetCache<G, S>` where `G: GpuDevice` and `S: AsyncSpawner`.
- **Storage**: Uses `DashMap` for high-concurrency access to `CachedAsset<T>`.
- **Residency**: Assets are uploaded to the GPU immediately upon loading. The cache stores the *GPU resident* handles (e.g., `G::Texture`, `GpuModel`).

### 2. GpuDevice Trait (`src/gpu/mod.rs`)

Abstracts the GPU backend.
- **Responsibilities**: Creating buffers, textures, and uploading data.
- **Implementations**:
    - `VulkanDevice` (Production): Uses `ash` and `vk-mem` (when `gpu-vulkan` feature enabled).
    - `MockGpu` (Testing/Headless): No-op implementation for logic verification.

### 3. AsyncSpawner Trait (`src/runtime/mod.rs`)

Abstracts the async execution environment.
- **Implementations**:
    - `TokioSpawner`: Uses `tokio::spawn` (when `runtime-tokio` feature enabled).
    - `MockSpawner`: Deterministic execution for tests (Drop or Blocking).

## Key Subsystems


### Spatial Preloading (`src/spatial/`)

- **AssetPreloader**: Manages a queue of assets to load based on priority.
- **SceneGraph**: Trait for querying assets near a world position.
- **Workflow**: `frame_update(pos)` -> Query SceneGraph -> Diff with current cache -> Queue new loads -> Spawn background tasks.

### LOD & Simplification (`src/lod/`)

- **MeshoptSimplifier**: Uses `meshopt` to generate simplified index buffers.
- **LodModel**: Stores multiple levels of detail for a single asset.
- **Usage**: Automatically generates LODs on load if configured.

### Memory Management (`src/cache/pool.rs`)

- **AssetMemoryPool**: A shared arena for vertex/index data.
- **Benefit**: Reduces allocator fragmentation by pooling short-lived mesh data before GPU upload.

## Usage Flows


### Loading an Asset

1.  `cache.get_or_load_model("path/to/model.glb")` called.
2.  **Fast Path**: Check `DashMap`. If found, update LRU and return `Arc`.
3.  **Slow Path**: 
    - Check disk/existence.
    - Spawn async task (or run if sync).
    - Load bytes -> Parse GLTF -> Generate LODs (optional).
    - **Upload to GPU** via `GpuDevice`.
    - Insert into `DashMap`.
    - Return `Arc<GpuModel>`.

### Concurrency Model

- `DashMap` handles internal bucket locking.
- `AsyncSpawner` allows non-blocking loading on background threads.
- `Arc` ensures thread-safe access to assets.

## Integration


To integrate `archetype_asset` into your engine:
1.  Implement `GpuDevice` for your renderer (or use `VulkanDevice`).
2.  Instantiate `AssetCache` with your GPU and Spawner.
3.  Call `start_frame()` / `frame_update(pos)` in your game loop.