Fluxo unificado de assets
De ficheiros PNG, WAV e OBJ brutos a um .cap que a
engine mapeia em memória: um pipeline partilhado pelo Doppio, caf-pack, runtime e CI.
Pipeline#
assets brutos ──► caf-pack ──► .caf / .cap ──► AssetManager ──► renderer / áudio / física
(PNG WAV OBJ) (processa) (binário) (async, hot reload)
| Etapa | Ferramenta | Saída |
|---|---|---|
| Autor | Qualquer ferramenta de imagem, áudio ou DCC | assets/raw/** |
| Empacotar | caf-pack --input <dir> --output <file.cap> |
Payloads .caf dentro de um .cap |
| Carregar | Caffeine::Assets::AssetManager |
Handles tipados (Texture, AudioClip, Mesh, Prefab, ShaderBlob) |
| Usar | Renderer, áudio, física, scripting | Structs resolvidas |
1. Assets brutos#
Mantenha os ficheiros-fonte na raiz de assets do projeto, normalmente assets/raw/:
assets/raw/
Textures/brick.png
Audio/step.wav
Models/crate.obj
Materials/brick.mat
O Doppio cria as pastas padrão (Textures, Models, Materials, Audio,
Animations, Prefabs, Sky) através do assistente de assets.
2. Empacotar com caf-pack#
caf-pack --input assets/raw --output build/game.cap --gen-ids build/game_assets.hpp
A CLI:
- varre o diretório de entrada recursivamente;
- converte PNG em RGBA/CAF, WAV em PCM/CAF e OBJ em mesh/CAF intercalada;
- alinha cada payload a 32 bytes;
- escreve o header CAP, a tabela de assets (hash, offset, size) e os blobs;
- opcionalmente gera um header C++ com ids de hash estáveis.
--compress ativa compressão opcional (zstd é ligado pelo packer). Veja o
README do caf-pack
para os formatos e a lista atual de processors.
No Doppio, o separador Assets → Pack corre a mesma CLI e escreve o .cap no
projeto. O binário é descoberto por CAF_PACK, CAFFEINE_ENGINE_ROOT,
caf-pack/build/src ou PATH.
3. Carregar na engine#
AssetManager detém a cache e os jobs assíncronos:
#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");
// a cada frame
assets.tick(frameIndex);
if (texture.isReady()) {
const auto* data = texture.get();
// fazer upload ou bind dos dados
}
assets.collectGarbage();
Pontos-chave:
loadAsync<T>/loadSync<T>devolvem umAssetHandle<T>com contador de geração.tick()processa jobs concluídos e verifica hot reload.collectGarbage()remove entradas LRU quando a cache excede o orçamento (maxCacheMB).reloadAsset(path)recarrega um asset já carregado do disco.registerInvalidationCallbacknotifica sistemas quando um asset muda.
O handle é invalidado se a entrada for removida ou recarregada; verifique isValid() /
isReady() antes de desreferenciar.
Layout do projeto#
my_game/
project.caffeine
assets/raw/ # assets-fonte
assets/processed/ # .caf individuais opcionais
build/game.cap # pack final
build/game_assets.hpp
scenes/
materials/
texture_sets/
Runtime e Doppio#
- O Doppio pré-visualiza assets brutos e empacota-os; não faz parsing de
.capem Rust. - O
AssetManagerda engine carrega.caf/.cap; a C ABI expõe os mesmos metadados e caminhos de assets ao editor. - O runtime usa o mesmo
AssetManagere layout de projeto, por isso uma cena guardada no Doppio aponta para os mesmos caminhos relativos.