π¦ Asset Manager
The runtime cache for textures, audio, shaders, meshes and prefabs:
zero-copy .caf loading, async jobs, refcounted handles, LRU eviction and debug
hot-reload.
Overview#
Asset Manager loads, caches and provides assets (textures, audio, shaders) transparently to the game. Supports async loading via Job System and hot-reload in builds debug.
** Philosophy:** Game code asks for an asset on the way; Asset Manager returns a AssetHandle<T> . The game never sees raw bytes β only AssetHandle<Texture> .
Carregamento zero-copy: Os assets sΓ£o carregados via BlobLoader that makes a single fread() para um LinearAllocator . As structs Texture , AudioClip e ShaderBlob are views about this buffer β no copying, no demerialization.
Arquitetura#
Game code:auto tex = assets.loadAsync<Texture>("textures/hero.caf");1. acquireOrCreate("textures/hero.caf", AssetType::Texture)JΓ‘ em cache? β retorna ID existente, incrementa cacheHitNovo? β cria AssetEntry, adiciona ao pathIndex
2. scheduleLoad(id)status = LoadingJobSystem::scheduleData(Background priority)loadInternal(id):BlobLoader::load(path, allocator)resolveEntry() β Texture/Audio/Shaderstatus = Loaded
(se jobs == nullptr: loadInternal roda inline)
3. handle.isReady() β truehandle.get() β ponteiro const T* para o asset resolvido
Public API#
namespace Caffeine::Assets {
// ============================================================================
// LoadStatus β estado de carregamento de um asset
// ============================================================================
enum class LoadStatus : u8 {
Pending, // slot created, load not yet scheduled
Loading,
Ready, // payload resolved and safe to use
Failed,
Invalid // slot invalidado (LRU/GC); generation foi incrementada
};
// ============================================================================
// Tipos de asset runtime (zero-copy views)
// ============================================================================
struct Texture {
u32 width;
u32 height;
u32 format; // 0 = RGBA8
u32 mipLevels;
const u8* pixels;
u64 pixelDataSize;
};
struct AudioClip {
u32 sampleRate;
u16 channels;
u16 bitsPerSample;
u32 sampleCount;
const u8* pcmData;
u64 pcmDataSize;
};
struct ShaderBlob {
u32 stage; // 0=vertex, 1=fragment, 2=compute
const u8* bytecode;
u64 bytecodeSize;
};
struct Mesh {
const Vertex3D* vertices;
u32 vertexCount;
const u32* indices;
u32 indexCount;
u64 vertexDataSize;
u64 indexDataSize;
};
struct Prefab {
const u8* payloadData;
u64 payloadSize;
};
// ============================================================================
// CacheStats β snapshot do estado do cache
// ============================================================================
struct CacheStats {
u64 totalCachedBytes;
u64 maxCacheBytes;
u32 textureCount;
u32 audioCount;
u32 pendingJobs;
u32 evictedCount; // entradas removidas por LRU desde o boot
f32 cacheHitRate;
};
// ============================================================================
// AssetHandle<T> β handle RAII com ref counting + generation counter
//
// - Copiar um handle incrementa o ref count do asset.
// - O destructor decrementa o ref count.
// - collectGarbage() descarrega assets com refCount == 0.
// - invalidateEntry() (LRU/GC) incrementa generation β handles antigos ficam Invalid.
// - Hot-reload NΓO incrementa generation β handles activos continuam vΓ‘lidos.
// ============================================================================
template<typename T>
class AssetHandle {
public:
AssetHandle();
AssetHandle(AssetManager* mgr, u32 id, u16 generation);
~AssetHandle();
AssetHandle(const AssetHandle& o);
AssetHandle& operator=(const AssetHandle& o);
AssetHandle(AssetHandle&& o) noexcept;
AssetHandle& operator=(AssetHandle&& o) noexcept;
bool isValid() const; // id + generation coincidem com a entrada
bool isReady() const; // isValid() && status == Ready
const T* get() const; // nullptr se nΓ£o estiver pronto ou generation stale
explicit operator bool() const;
u32 id() const;
u16 generation() const;
};
using AssetInvalidationCallback = void (*)(const InvalidatedAsset& info, void* userData);
// ============================================================================
// AssetManager β gerenciador central
// ============================================================================
class AssetManager {
public:
explicit AssetManager(Threading::JobSystem* jobs,
const char* basePath,
u64 maxCacheMB = 256);
~AssetManager();
// ββ Loading ββββββββββββββββββββββββββββββββββββββββββββββββ
// Async: retorna imediatamente, carrega em background
template<typename T>
AssetHandle<T> loadAsync(const char* path);
// Sync: bloqueia atΓ© carregado (use somente no init)
template<typename T>
AssetHandle<T> loadSync(const char* path);
// ββ Gerenciamento de cache βββββββββββββββββββββββββββββββββ
void collectGarbage(); // descarrega assets sem referΓͺncias
CacheStats cacheStats() const; // estatΓsticas do cache
// ββ Invalidation callbacks (GPU textures, etc.) ββββββββββββ
void registerInvalidationCallback(AssetInvalidationCallback cb, void* userData);
void unregisterInvalidationCallback(AssetInvalidationCallback cb, void* userData);
// ββ Frame tick βββββββββββββββββββββββββββββββββββββββββββββ
void tick(u64 frameIndex = 0); // atualiza frame index + hot-reload + LRU
// Reload a loaded asset from disk by its .caf path. Returns the asset id,
// or ~0u if it is not in the cache. Thread-safe.
u32 reloadAsset(const char* path);
private:
// incRef / decRef / getStatus β usados por AssetHandle
void incRef(u32 id);
void decRef(u32 id);
LoadStatus getStatus(u32 id) const;
template<typename T>
const T* getResolved(u32 id) const; // retorna Texture/Audio/Shader resolvido
// ... (membros internos)
};
} // namespace Caffeine::Assets
Estrutura Interna#
Each loaded asset is represented by one AssetEntry :
AssetEntrypath : std::string (caminho completo no disco)cafType : AssetTypestatus : std::atomic<LoadStatus>allocator : unique_ptr<LinearAllocator> (dono do buffer)header : const CafHeader*metadata : const void* (TextureMetadata, AudioMetadata, etc.)payload : const void* (pixels brutos, PCM, bytecode)resolved : ResolvedData { Texture, AudioClip, ShaderBlob, Mesh, Prefab }refCount : std::atomic<u32>generation : u16 (incrementada em invalidateEntry, nΓ£o em hot-reload)sizeBytes : u64lastAccessFrame : u64
O LinearAllocator aloca um buffer de fileSize + 64 bytes. O BlobLoader faz a fread() unique and adjusts the hands header , metadata e payload dentro desse buffer. As structs resolved are filled with the values extracted from the methadata + payload.
Hot-Reload (RF3.9)#
Em builds debug ( #ifdef CF_DEBUG ):
tick()chamacheckHotReload()a cada frame- Para cada asset carregado, compara
last_write_timefile on disk - Se mudou:
clearEntryData()+loadInternal()sem incrementargeneration AssetHandle<T>::get()remains valid and points to reloaded payload
Zero overhead in release: The hot-reload is compiled conditionally β it does not exist in production builds.
LRU Eviction and Invalidation#
Quando totalCachedBytes > maxCacheBytes (after load or collectGarbage ):
evictLruToFitBudget()escolhe entradas comrefCount == 0e menorlastAccessFrameinvalidateEntry()limpa payload, incrementageneration, notifica callbacks- Handles antigos passam a
LoadStatus::Invalid;get()devolvenullptr
Callbacks: subsistemas GPU (ex.: TerrainGpuTextureCache ) registam registerInvalidationCallback to release textures when the corresponding asset is evicted.
void onAssetInvalidated(const InvalidatedAsset& info, void* userData) {
if (info.type == AssetType::Texture) {
// libertar GPUTexture associada a info.id / info.generation
}
}
Exemplos de Uso#
#include <Caffeine.hpp>
using namespace Caffeine;
using namespace Caffeine::Assets;
// ββ Init ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Threading::JobSystem jobs(4);
AssetManager assets(&jobs, "assets/", 256); // max 256 MB cache
// ββ Async loading (nΓ£o bloqueia) ββββββββββββββββββββββββββββββ
auto heroTex = assets.loadAsync<Texture>("textures/hero.caf");
auto bgMusic = assets.loadAsync<AudioClip>("audio/level1.caf");
// ββ Game loop βββββββββββββββββββββββββββββββββββββββββββββββββ
while (running) {
assets.tick(frameCounter);
if (heroTex.isReady()) {
const Texture* t = heroTex.get();
// t->width, t->height, t->pixels, t->pixelDataSize ...
}
// ββ Coleta lixo a cada 60 frames ββββββββββββββββββββββββββ
if (frameCounter % 60 == 0) {
assets.collectGarbage();
}
++frameCounter;
}
// ββ Sync no init (aceitΓ‘vel no boot) βββββββββββββββββββββββββ
auto uiAtlas = assets.loadSync<Texture>("textures/ui.caf");
const Texture* atlas = uiAtlas.get(); // pronto imediatamente
Tests#
21 casos de teste em tests/test_assetmanager.cpp (inclui HotReloader):
| Teste | O que verifica |
|---|---|
AssetManager - construction with null JobSystem |
Builder without jobs not crash |
AssetManager - loadSync Texture |
Textura carregada, campos width/height/pixels corretos |
AssetManager - loadSync AudioClip |
AudioClip carregado, campos sampleRate/channels corretos |
AssetManager - loadSync ShaderBlob |
ShaderBlob carregado, campos stage/bytecode corretos |
AssetManager - second load of same path is cache hit |
Cache hit rate > 0 no segundo load |
AssetManager - cacheStats counts textures and audio |
textureCount/audioCount corretos |
AssetManager - collectGarbage unloads unreferenced assets |
Asset downloaded after handle exits scope |
AssetManager - collectGarbage does not unload referenced assets |
Asset mantido enquanto handle existe |
AssetManager - handle copy increments ref, original still valid |
Handle copy keeps asset alive |
AssetManager - loadAsync returns handle that becomes ready |
Async loading via JobSystem completa |
AssetManager - failed load returns handle with Failed status |
Path inexistente retorna Failed |
AssetManager - stale handle after eviction returns nullptr |
Generation stale after LRU |
AssetManager - invalidation callback fires on collectGarbage |
Callback notified in invalidation |
AssetManager - LRU evicts unreferenced assets when over budget |
Eviction por maxCacheBytes |
AssetManager - reload after eviction works with new generation |
New load after eviction |
AssetManager - tick advances frame index |
tick() not crash |
HotReloader - * |
Lifecycle and reload integration |
Dependencies#
| Dependence | Uso |
|---|---|
Caffeine::Threading::JobSystem |
Background jobs para async loading |
Caffeine::IO::BlobLoader |
Zero-copy reading of .caf files |
Caffeine::IO::CafTypes |
CafHeader, TextureMetadata, AudioMetadata, ShaderMetadata |
Caffeine::LinearAllocator |
Linear allocation for asset buffer |
std::filesystem (CF_DEBUG) |
Hot-reload check via last write time |
Design Decisions#
| Decision | Justificativa |
|---|---|
AssetHandle<T> tipado |
Erro de tipo pego em compile time |
loadAsync aceita JobSystem* nullable |
Fallback sync when there is no JobSystem (useful in testing) |
| Zero-copy resolved views | No conversion overhead; structs are filled in the load |
collectGarbage() explicit |
Evita pausas inesperadas; jogo controla quando descarregar |
| Generation counter | Detects handsles stale after LRU without dangling pointers |
| Hot-reload sem bump de generation | Handles activos sobrevivem a reload em debug |
LRU por lastAccessFrame |
Predictable memory pressure with maxCacheMB |
tick() as a single point |
Unifies frame counter, hot-reload and avoidance in one method |
| Hot-reload CF DEBUG only | Zero custo em release |
std::unordered_map + std::vector |
Simplicity about cache performance; Custom HashMap would be over-engineering at this stage |
std::mutex (no lock-free) |
Low containment; simplicity of implementation |
Acceptance Criteria#
- [x]
loadAsyncretorna imediatamente, carrega em background via JobSystem - [x]
loadSyncblocks until loading complete - [x] Cache com ref counting: handle copy incrementa, destructor decrementa
- [x]
collectGarbage()download assets without references - [x]
cacheStats()retorna contagem por tipo, bytes totais, hit rate - [x] Hot-reload em debug builds via
tick()βcheckHotReload() - [x] Zero-copy:
BlobLoaderβLinearAllocatorβ resolved fields - [x] Tipos suportados: Texture, AudioClip, ShaderBlob, Mesh, Prefab
π Related Topics#
| Topic | Description |
|---|---|
| Assets & Pipeline | Asset Manager como runtime do pipeline |
| Competition & Runtime | Async loading via Job System |
References#
architecture_specs.mdβ Β§7 Asset Managerassets/caf-format.mdβ Binary format .cafconcurrency/job-system.mdβ Background jobs for loading- Transversal Topic Index
- Issue #26 β Asset Manager task