Binary Prefabs & Scenes

[LyeZinho]

Implementação: Serializador binário que despeja o estado das entidades ECS diretamente em um arquivo .caf tipo Prefab
Vantagem: Instanciar um Prefab torna-se um memcpy de um bloco binário para o ComponentPool da engine

[LyeZinho]

📦 4.2: Sistema de Assets — O Formato .caf (Caffeine Asset Format)

Responsável: Architects
Status: 📅 Planejado (Integração com Fase 3 & 4)

O formato .caf (Caffeine Asset Format) serve como espinha dorsal de dados da engine. Filosofia: Zero-parsing, Zero-copy. O arquivo no disco é um espelho direto da memória RAM/VRAM.

Estrutura do Header (src/core/io/CafTypes.hpp)

namespace Caffeine {
    enum class AssetType : u16 {
        Unknown = 0,
        Texture,    // RGBA8, BC7, ASTC
        Audio,      // PCM, ADPCM
        Mesh,       // Vertex/Index Buffers
        Prefab,     // ECS Entity Template (Binary)
        Scene,      // World State
        Shader      // SPIR-V / Bytecode
    };
<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">struct</span> <span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">CafHeader</span> {
    <span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">u32</span> magic;          <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> 0xCAFECAFE</span>
    <span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">u16</span> version;        <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> Versão do formato</span>
    AssetType type;     <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> Tipo de dado</span>
    <span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">u64</span> metadataSize;   <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> Offset para o início dos dados brutos</span>
    <span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">u64</span> dataSize;       <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> Tamanho do payload binário</span>
    <span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">u64</span> alignment;      <span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);"><span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">//</span> 16 ou 32 bytes (para SIMD/GPU)</span>
};

}

<clipboard-copy aria-label="Copy" class="ClipboardButton btn btn-invisible js-clipboard-copy m-2 p-0 d-flex flex-justify-center flex-items-center" data-copy-feedback="Copied!" data-tooltip-direction="w" value="namespace Caffeine {
enum class AssetType : u16 {
Unknown = 0,
Texture, // RGBA8, BC7, ASTC
Audio, // PCM, ADPCM
Mesh, // Vertex/Index Buffers
Prefab, // ECS Entity Template (Binary)
Scene, // World State
Shader // SPIR-V / Bytecode
};

struct CafHeader {
    u32 magic;          // 0xCAFECAFE
    u16 version;        // Versão do formato
    AssetType type;     // Tipo de dado
    u64 metadataSize;   // Offset para o início dos dados brutos
    u64 dataSize;       // Tamanho do payload binário
    u64 alignment;      // 16 ou 32 bytes (para SIMD/GPU)
};

}" tabindex="0" role="button" style="box-sizing: border-box; padding: 0px !important; font-size: 14px; font-weight: 500; white-space: nowrap; vertical-align: middle; cursor: pointer; user-select: none; appearance: none; border: 0px; border-radius: 6px; line-height: 20px; display: flex !important; position: relative; color: rgb(68, 147, 248); background-color: rgba(0, 0, 0, 0); box-shadow: none; transition: color 80ms cubic-bezier(0.33, 1, 0.68, 1), background-color 80ms cubic-bezier(0.33, 1, 0.68, 1), box-shadow 80ms cubic-bezier(0.33, 1, 0.68, 1), border-color 80ms cubic-bezier(0.33, 1, 0.68, 1); justify-content: center !important; align-items: center !important; margin: 8px !important; width: 28px; height: 28px;">

Requisitos de Engenharia para o .caf

Categoria	Requisito Técnico	Motivação
Endianness	Little-endian (padrão x86/x64)	Evitar swap de bytes no carregamento (Zero CPU overhead)
Alignment	Global: 16-byte / Mesh: 32-byte	Compatibilidade com instruções SIMD e otimização de barramento da GPU
IO Pattern	Single-Shot Read	Minimiza o seek time do HD/SSD ao ler Metadata + Data em uma única chamada de IO
Versioning	Semantic Versioning no Header	Permitir que a engine identifique assets obsoletos e force a re-compilação via IDE

Integração no Roadmap

Fase 3: RHI & Asset Foundation (Update)

RF3.0: Caffeine Binary System (.caf)

• Implementação: BlobLoader para leitura assíncrona de blocos binários
• DOD: Uso de Memory Mapping (mmap) ou Direct Storage (se disponível) para carregar assets sem passar pela cópia intermediária da CPU
• Suporte Multimídia:
  • Imagens: Conversão de metadados para SDL_GPUTextureCreateInfo
  • Audio: Mapeamento de buffers PCM direto para o AudioStream
  • 3D: Alinhamento de buffers de vértices para 32 bytes (pré-requisito para Fase 5)

Fase 4: ECS & Sistemas (Update)

RF4.2: Binary Prefabs & Scenes

• Implementação: Serializador binário que despeja o estado das entidades ECS diretamente em um arquivo .caf tipo Prefab
• Vantagem: Instanciar um Prefab torna-se um memcpy de um bloco binário para o ComponentPool da engine

Fluxo de Implementação: "The Loading Chain"

Para que isso funcione em escala, a engine seguirá este fluxo:

1. FileSystem::Open — Localiza o asset no disco
2. BlobLoader::Load — O JobSystem (Fase 2) reserva memória via LinearAllocator e faz a leitura bruta
3. AssetResolver::Cast:
   • Se type == Texture: O ponteiro é passado para a GPU
   • Se type == Audio: O ponteiro é enviado para o Mixer
   • Se type == Prefab: Os dados são injetados no ECS
4. Lifetime Management — O asset permanece em memória até que a Cena seja descarregada, sem nunca ter sido "parseado"

Critério de Aceitação (Stress Test)

Benchmark: Carregar um "Mega-Bundle" de 1GB contendo texturas, áudios e meshes.

Sucesso: O tempo de carregamento deve ser limitado apenas pela velocidade de leitura do SSD (ex: 500MB/s), com uso de CPU inferior a 2% durante o processo.