Converte assets brutos (PNG, WAV, OBJ) em ficheiros
.caf alinhados e empacota-os num .cap pronto para memory
mapping. A engine lê o binário diretamente; não há parsing de texto em runtime.
| Princípio | O que significa |
|---|---|
| Zero-parsing | A CLI entrega a struct binária no layout C++ de include/caffeine/CafTypes.hpp. |
| Alinhamento | Cada payload começa num limite de 32 bytes (Packer::Config::alignment). |
| Hash-based | Assets são referenciados por u64 (MurmurHash3), sem procuras por string em runtime. |
| Pack | Processa cada asset para .caf em memória e agrega tudo num .cap. |
caf-pack/
├── include/
│ ├── caffeine/CafTypes.hpp # Formatos CAF e CAP partilhados com a engine
│ └── caf-pack/
│ ├── Packer.hpp # Descoberta, processamento e container CAP
│ ├── Registry.hpp # Registo de processors por extensão
│ ├── Reader.hpp # Ler .caf e .cap
│ ├── HeaderGenerator.hpp # IDs C++ a partir dos assets
│ └── *Processor.hpp # PNG, WAV, OBJ → .caf
├── src/
│ ├── main.cpp # CLI
│ ├── Packer.cpp
│ ├── Registry.cpp
│ ├── Reader.cpp
│ ├── AssetProcessor.cpp
│ ├── TextureProcessor.cpp
│ ├── AudioProcessor.cpp
│ ├── MeshProcessor.cpp
│ └── HeaderGenerator.cpp
└── CMakeLists.txt
caf-pack --input ./assets_raw --output game.cap
caf-pack --input ./assets_raw --output game.cap --gen-ids assets_ids.hpp
caf-pack --input ./assets_raw --output game.cap --compress| Opção | Efeito |
|---|---|
--input <dir> |
Diretório de assets brutos (obrigatório). |
--output <file> |
Ficheiro .cap de saída (padrão assets.cap). |
--gen-ids <file> |
Gera um header C++ com constantes de id. |
--compress |
Ativa compressão opcional. |
--help |
Mostra a ajuda. |
O Doppio usa a mesma CLI no assistente de Assets (Create/Import/Pack); o caminho do
binário é descoberto por CAF_PACK, CAFFEINE_ENGINE_ROOT, caf-pack/build/src ou
PATH.
A CLI é uma camada fina sobre a biblioteca partilhada:
#include "caf-pack/Packer.hpp"
#include "caf-pack/Reader.hpp"
#include "caf-pack/Registry.hpp"
CafPack::Packer::Config config;
config.inputDir = "assets/raw";
config.outputFile = "build/game.cap";
config.generateHeader = true;
config.headerPath = "build/game_assets.hpp";
CafPack::Packer packer(config);
if (!packer.pack()) {
// packer.getError()
}
auto assets = CafPack::Reader::loadCap("build/game.cap");
CafPack::CafAsset one;
CafPack::Reader::loadCaf("assets/raw/Textures/brick.caf", one);| Classe | Responsabilidade |
|---|---|
Packer |
Descobre assets, processa e escreve o container CAP. |
Registry |
Registo extensível de processors; makeDefaultRegistry() inclui textura, áudio e mesh. |
Reader |
loadCap, loadCaf e readCafHeader para consumidores C++ e tools. |
HeaderGenerator |
Gera constantes C++ com os hashes dos assets. |
- Adicione o valor em
CafAssetType(include/caffeine/CafTypes.hpp). - Defina a metadata no mesmo header, se o asset precisar de campos próprios.
- Implemente
AssetProcessor(canProcess+process). - Registe-o em
Registry(ou emmakeDefaultRegistry()para um processor built-in). - Consumidores usam
Reader/AssetManager; não fazem parsing do.cafà mão.
CafHeader tem 32 bytes: magic CAF!, versão, tipo de asset, tamanho do payload,
flags e CRC64. Metadados específicos seguem o header:
| Tipo | Metadados |
|---|---|
| Textura | width, height, format (RGBA8/BC1/BC4/BC5), mipLevels |
| Áudio | sampleRate, sampleCount, channels, format (PCM16/PCM32) |
| Mesh | vertexCount, indexCount, vertexStride, indexFormat |
Os dados começam no próximo limite de 32 bytes.
| Secção | Conteúdo |
|---|---|
| Header | CapHeader com magic CAP/, versão e contagem de assets. |
| Table | CapEntry[] com hashID, offset e size. |
| Padding | Alinhamento a 32 bytes. |
| Blobs | Payloads .caf concatenados. |
O runtime mapeia o .cap e resolve assets pelo hash, sem varrer diretórios.
Requisitos: C++17, CMake 3.20+, libpng, zlib e zstd.
cmake -S caf-pack -B caf-pack/build -DCAFFEINE_ROOT="$PWD"
cmake --build caf-pack/build -jO binário fica em caf-pack/build/src/caf-pack num build standalone, ou em
build/caf-pack/src/caf-pack no monorepo. A partir do repositório da engine, o build normal também o compila
quando o submódulo está presente.
Os testes do caf-pack vivem em tests/ no repositório do submódulo. No monorepo, a
engine compila a biblioteca partilhada e os testes de integração usam o mesmo
CafTypes.hpp; execute ctest a partir de build/.
include/caffeine/CafTypes.hppé a fonte de verdade dos layouts.- O asset manager carrega
.caf/.cappor hash e faz memory mapping. - O pipeline de import do Doppio chama a CLI e atualiza a cache de assets.