Archetype Asset

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

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.

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.

// 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.

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.