Unified asset workflow
From raw PNG, WAV and OBJ files to a .cap the engine
maps into memory: one pipeline shared by Doppio, caf-pack, the runtime and CI.
Pipeline#
raw assets ──► caf-pack ──► .caf / .cap ──► AssetManager ──► renderer / audio / physics
(PNG WAV OBJ) (process) (binary) (async, hot reload)
| Stage | Tool | Output |
|---|---|---|
| Author | Any image, audio or DCC tool | assets/raw/** |
| Pack | caf-pack --input <dir> --output <file.cap> |
.caf payloads inside a .cap |
| Load | Caffeine::Assets::AssetManager |
Typed handles (Texture, AudioClip, Mesh, Prefab, ShaderBlob) |
| Use | Renderer, audio, physics, scripting | Resolved structs |
1. Raw assets#
Keep source files in the project's asset root, normally assets/raw/:
assets/raw/
Textures/brick.png
Audio/step.wav
Models/crate.obj
Materials/brick.mat
Doppio creates the standard folders (Textures, Models, Materials, Audio,
Animations, Prefabs, Sky) through the asset wizard.
2. Pack with caf-pack#
caf-pack --input assets/raw --output build/game.cap --gen-ids build/game_assets.hpp
The CLI:
- scans the input directory recursively;
- converts PNG to RGBA/CAF, WAV to PCM/CAF and OBJ to interleaved mesh/CAF;
- aligns each payload to 32 bytes;
- writes the CAP header, asset table (hash, offset, size) and blobs;
- optionally generates a C++ header with stable hash ids.
--compress enables optional compression (zstd is linked by the packer). See the
caf-pack README
for the formats and the current processor list.
In Doppio, the Assets → Pack tab runs the same CLI and writes the .cap into the
project. The binary is found via CAF_PACK, CAFFEINE_ENGINE_ROOT,
caf-pack/build/src or PATH.
3. Load in the engine#
AssetManager owns the cache and the async jobs:
#include "assets/AssetManager.hpp"
Caffeine::Threading::JobSystem jobs;
Caffeine::Assets::AssetManager assets(&jobs, "assets/raw", 256);
auto texture = assets.loadAsync<Caffeine::Assets::Texture>("Textures/brick.caf");
auto mesh = assets.loadAsync<Caffeine::Assets::Mesh>("Models/crate.caf");
// each frame
assets.tick(frameIndex);
if (texture.isReady()) {
const auto* data = texture.get();
// upload or bind data
}
assets.collectGarbage();
Key points:
loadAsync<T>/loadSync<T>return anAssetHandle<T>with a generation counter.tick()pumps completed jobs and checks hot reload.collectGarbage()evicts least-recently-used entries when the cache exceeds its budget (maxCacheMB).reloadAsset(path)reloads an already-loaded asset from disk.registerInvalidationCallbacknotifies systems when an asset changes.
The handle is invalidated if the entry is evicted or reloaded; check isValid() /
isReady() before dereferencing.
Project layout#
my_game/
project.caffeine
assets/raw/ # source assets
assets/processed/ # optional individual .caf files
build/game.cap # final pack
build/game_assets.hpp
scenes/
materials/
texture_sets/
Runtime and Doppio#
- Doppio previews raw assets and packs them; it does not parse
.capin Rust. - The engine
AssetManagerloads.caf/.cap; the C ABI exposes the same asset metadata and paths to the editor. - The runtime uses the same
AssetManagerand project layout, so a scene saved in Doppio points at the same relative paths.