Cafpack — Camada Unificada de Assets
Como o caf-pack transforma assets brutos em ficheiros .caf alinhados e packs .cap, e como a engine os consome.
Repositório: caf-pack (submodule) Status: 🟡 Fase 1 — biblioteca activa; migração de tipos em curso
Visão#
O Cafpack é o "fio condutor" do ecossistema Caffeine Studio (estilo Adobe Creative Suite):
Ferramentas de arte externas ──┐Ferramentas de áudio externas ──┼──► Cafpack ──► .caf / .cap ──► Doppio / RuntimeDoppio / CI ────────────────────┘ ▲única fonte de verdade para leitura/escrita de dados
Regra central: todo novo tipo de asset (mesh, textura, áudio, animação, scene, prefab…) é definido primeiro no Cafpack. Nenhuma app inventa formato interno — só consome a API.
Contrato por aplicação#
| App | Responsabilidade | API Cafpack |
|---|---|---|
| Ferramentas de arte externas | Editar texturas/meshes (opcional) | CLI caf-pack ou caf-pack-lib |
| Ferramentas de áudio externas | Editar áudio (opcional) | CLI caf-pack ou caf-pack-lib |
| Doppio | IDE / preview / pack projeto | Packer, HeaderGenerator e os processors |
| Runtime | Carregar jogo | Packer / asset manager (zero parsing) |
| caf-pack CLI | CI / batch | caf-pack --input raw --output game.cap |
Estrutura da biblioteca (caf-pack-lib)#
caf-pack/include/caffeine/CafTypes.hpp ← fonte de verdade (.caf + .cap)caf-pack/AssetProcessor.hpp ← interface base dos processorscaf-pack/Packer.hpp ← descobrir, processar e escrever .capTextureProcessor / AudioProcessor / MeshProcessor ← conversoresHeaderGenerator.hpp ← IDs hash para C++*Processor.hpp ← PNG, WAV, OBJ → .caf
caf-pack/src/
Adicionar um novo tipo de asset#
- Adicionar valor em
CafAssetType(include/caffeine/CafTypes.hpp) - Definir struct de metadata no mesmo ficheiro
- Implementar
AssetProcessoremcaf-pack/src/TextureProcessor.cpp - Registar em
Packer::registerProcessors()(caf-pack/src/Packer.cpp) - Consumir no asset manager da engine — sem bypass
Formatos#
| Extensão | Descrição | Magic |
|---|---|---|
.caf |
Asset binário individual | 0x43414621 ("CAF!") |
.cap |
Pack de assets (mmap) | 0x4341502F ("CAP/") |
Documentação detalhada do pack: caf-pack/README.md.
Dois headers CAF (migração)#
| Header | Magic | Uso |
|---|---|---|
caf-pack/include/caffeine/CafTypes.hpp |
CAF! |
Assets importados + .cap |
src/caffeine/core/io/CafTypes.hpp |
0xCAFECAFE |
Scene/Prefab engine-internal (legado) |
Fase 2 unifica num único schema; até lá, runtime assets usam sempre caf-pack.
Pipeline de projeto#
my_game/raw_assets/ ← PNG, WAV, OBJ (fonte)processed/ ← opcional: .caf individuaisgame.cap ← pack final (mmap no runtime)game_assets.hpp ← IDs hash gerados pelo HeaderGenerator
Export manual (qualquer ferramenta)#
bash
./scripts/export-to-cap.sh raw_assets/ game.cap include/game_assets.hpp
Ferramentas externas devem invocar o mesmo script ou ligar caf-pack-lib diretamente.
Integração CMake (monorepo)#
bash
git submodule update --init caf-pack
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
| Target | Origem |
|---|---|
caf-pack-lib |
Submodule caf-pack |
caf-pack |
CLI |
doppio-ui |
IDE Rust; chama a CLI caf-pack no Pack |
Fases de migração#
| Fase | Entregável | Estado |
|---|---|---|
| 0 | Submodule caf-pack populado + .gitmodules |
✅ |
| 1 | Reader, Registry, CapLoader via Reader |
✅ |
| 2 | Unificar CafTypes engine ↔ caf-pack |
📅 |
| 3 | MeshLoader/AssetManager sem bypass PNG/OBJ | 📅 |
| 4 | Export de ferramentas externas → Cafpack (opcional) | 📅 |
| 5 | Deprecar tools/caf-encode |
📅 |
Princípios#
- Um tipo, um sítio — schema + processor + reader no caf-pack
- Sem bypass — loaders da engine leem
.caf/.cap, não PNG cru em runtime - Projeto unificado — um
.cappor jogo, partilhado por todas as apps - Repo único — a engine compila Doppio e caf-pack; ferramentas externas ficam fora do monorepo
Ver também#
ECOSYSTEM_WORKFLOW.mdassets/caf-format.md— formato engine-internal (legado)plans/2026-05-17-unified-ecosystem-build.md