archetype_asset 0.2.1

# Archetype Asset


**A modular asset pipeline that handles the "boring" parts of loading files into GPU memory.**

[![Crates.io](https://img.shields.io/crates/v/archetype_asset)](https://crates.io/crates/archetype_asset)
[![Documentation](https://docs.rs/archetype_asset/badge.svg)](https://docs.rs/archetype_asset)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## What This Is (Probably)


`archetype_asset` is a high-performance bridge between files on disk and data in your GPU. It follows the "Dumb Pipe" philosophy: it handles the messy parsing, parallel decoding, and memory management, but stays out of your way when it comes to actual rendering.

**Fair Warning**: This is a library component, not a engine. You'll need to provide your own `GpuDevice` implementation (though a Mock is provided for testing) and your own rendering logic. Think of it as the gas station for your car—it provides the fuel, but you still have to drive.

## Core Concepts


### What It Does

- ✅ **Optimized GLTF Loading**: Parallel mesh and material extraction.
- ✅ **Async Pipeline**: Non-blocking I/O and decoding.
- ✅ **Spatial Preloading**: Background loading triggered by player proximity.
- ✅ **LOD Generation**: Automatic mesh simplification via `meshopt`.
- ✅ **Memory Pooling**: Contiguous arenas for vertex/index data to minimize fragmentation.
- ✅ **Zero-Copy IBL**: Memory-mapped access to HDR/Irradiance cubemaps.
- ✅ **Texture Compression**: Native support for WebP and KTX2 (ETC1S/UASTC).

### What It Doesn't Do

- ❌ **Rendering**: (Use `ash`, `wgpu`, or your own).
- ❌ **Scene Management**: (That's your engine's job).
- ❌ **Physics**: (Maybe in another life).

## Quick Start


### 1. The Async Asset Cache

The heart of the system. It manages memory budgets and handles deduplication.

```rust
use archetype_asset::cache::AssetCache;
use archetype_asset::gpu::mock::MockGpu;
use archetype_asset::runtime::tokio::TokioSpawner;

#[tokio::main]

async fn main() -> anyhow::Result<()> {
    // 1. Initialize your GPU backend and async spawner
    let gpu = MockGpu::new(); 
    let spawner = TokioSpawner::new();
    
    // 2. Create the cache with a 256MB memory budget
    let cache = AssetCache::new(gpu, spawner, 256 * 1024 * 1024);

    // 3. Load a model (parallel decoding happens here)
    let model = cache.get_or_load_model("assets/character.glb").await?;
    
    println!("Loaded {} meshes for the GPU", model.meshes.len());
    Ok(())
}
```

### 2. Spatial Preloading

Stop your game from stuttering when moving through large worlds.

```rust
// Update player position to trigger background preloading
cache.update_player_position(vec3(100.0, 0.0, -50.0)).await;

// Call this once per frame to progress the preload queue
cache.frame_update(player_pos).await;
```

### 3. Zero-Copy Cubemaps (IBL)

Load massive HDR cubemaps without the `memcpy` tax.

```rust
use archetype_asset::ibl::MappedIblAsset;

fn load_lighting() -> anyhow::Result<()> {
    let ibl = MappedIblAsset::load("assets/skybox.aibl")?;
    let raw_data = ibl.cubemap_data(); // Slices straight into the memory-map
    
    Ok(())
}
```

## Performance Notes


We take performance seriously because we have to.

- **20% faster** model loader instantiation compared to v0.1.2.
- **7% faster** cache hit lookups via `DashMap` concurrency.
- **Zero allocation** path for mesh creation when using internal pools.

*Benchmarks run on: Intel Core i5-11400F, Intel Arc A380, 16GB RAM.*

## Architecture


Data flows from disk to GPU in a clean, isolated stream:

1. **Loader**: Reads raw bytes (supports `mmap`).
2. **Parser**: GLTF/HDR/Ktx2 decoding (Parallel on `AsyncSpawner`).
3. **Pooler**: Allocates contiguous memory in `AssetMemoryPool`.
4. **Cache**: Atomic deduplication using `DashMap`.
5. **GPU**: Direct upload via your `GpuDevice` implementation.

## Known Limitations


- **GLTF**: Currently reads the first skin/scene only.
- **LOD**: Requires the `lod` feature (depends on `meshopt`).
- **Platforms**: Primary testing on Windows (Vulkan/Arc).

## Version History


### v0.2.1 — The Polish Release

- ✅ Refactored `AssetCache` to be generic over `AsyncSpawner`.
- ✅ Replaced sync locks with `DashMap` for concurrent performance.
- ✅ Fixed `await-holding-lock` deadlocks in spatial updates.
- ✅ Added support for Ktx2 (ETC1S/UASTC) and WebP.
- ✅ Achievement: 100% Documentation coverage.

---