Cafpack — Unified Asset Layer
How caf-pack turns raw assets into aligned .caf files and .cap packs, and how the engine consumes them.
Repository: caf-pack (submodule)
View#
The Cafpack is the driver wire of the Caffeine Studio ecosystem (Adobe Creative Suite style):
External art tools ──┐External audio tools ─┼──► Cafpack ──► .caf / .cap ──► Doppio / RuntimeDoppio / CI ──────────┘single source of truth for asset reading/writing
-
- Central rule:** Every new type of asset (mesh, texture, audio, animation, scene, prefab...) is defined first in Cafpack**. No app invents internal format — it only consumes the API.
Contract by application#
| App | Responsabilidade | API Cafpack |
|---|---|---|
| External art tools | Edit textures/meshes (optional) | caf-pack CLI or caf-pack-lib |
| External audio tools | Edit audio (optional) | caf-pack CLI or 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 — No bypass
Formatos#
| Extension | Description | Magic |
|---|---|---|
.caf |
Asset individual binary | 0x43414621 ("CAF!") |
.cap |
Pack de assets (mmap) | 0x4341502F ("CAP/") |
Detailed package documentation: caf-pack/README.md.
Two CAF heads (migration)#
| 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) |
Phase 2 unifies in a single schema; until then, runtime assets always use 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
External tools should invoke the same script or link caf-pack-lib directly.
CMake Integration (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 |
Migration phases#
| Phase | Delivery | 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 | External tool export → Cafpack (optional) | 📅 |
| 5 | Deprecar tools/caf-encode |
📅 |
Principles#
-
- One type, one site* — schema + processor + reader in the caf-pack
- No bypass — engine loaders read
.caf/.cap, not raw PNG in runtime - ** Unified project** — one
.cappor jogo, partilhado por todas as apps - Single repo — the engine builds Doppio and caf-pack; external tools stay out of the monorepo
See also#
ECOSYSTEM_WORKFLOW.mdassets/caf-format.md— engine-internal format (legated)plans/2026-05-17-unified-ecosystem-build.md