Caffeine

🔧 Asset Pipeline Integration

Planned Milestone: M2 — Visual Editing & Assets Namespace: `Caffeine::Assets` Arquivos: `src/caffeine/assets/AssetPipeline.hpp`, `src/caffeine/assets/AssetPipeline.cpp` RF: RF6.3 Last updated:

Visão Geral#

A Integração da Asset Pipeline é responsável pela transformação automatizada de ficheiros de origem (raw assets) em formatos otimizados para o motor de jogo Caffeine (.caf). O objetivo principal é garantir que o programador ou artista possa simplesmente colocar ficheiros numa pasta e o motor trate de os converter, comprimir e indexar sem intervenção manual.

Este sistema monitoriza a pasta assets/raw/ e, ao detetar novos ficheiros ou alterações, inicia um processo de conversão em segundo plano. O pipeline suporta a criação de um manifesto global que mapeia os caminhos originais para os recursos binários processados, permitindo carregamentos rápidos e gestão de dependências entre assets.


Implementação#

O pipeline funciona como um serviço de vigilância de ficheiros que despacha tarefas para compiladores específicos (TextureCompiler, MeshCompiler, AudioCompiler).

Arquitetura do Pipeline#

text
[ Pasta raw/ ] --(FileWatcher)--> [ AssetPipeline ] --(Dispatcher)--> [ Compilers ]
                                         |
                                         v
[ assets/manifest.caf ] <--- [ assets/processed/ ]

Estrutura de Classes#

cpp
namespace Caffeine::Assets {

    struct AssetImportContext {
        std::filesystem::path SourcePath;
        std::filesystem::path DestinationPath;
        std::vector<std::string> Logs;
        bool Success = false;
    };

    class IAssetCompiler {
    public:
        virtual ~IAssetCompiler() = default;
        virtual bool Compile(AssetImportContext& context) = 0;
        virtual std::vector<std::string> GetSupportedExtensions() = 0;
    };

    class AssetPipeline {
    public:
        void Initialize(const std::filesystem::path& projectRoot);
        void Update(); // Verifica alterações e progresso

        void RegisterCompiler(std::unique_ptr<IAssetCompiler> compiler);
        void Reimport(const std::filesystem::path& path);

        float GetProgress() const { return m_CurrentProgress; }
        bool IsProcessing() const { return m_Busy; }

    private:
        void OnFileDetected(const std::filesystem::path& path);
        void ProcessQueue();

        std::queue<std::filesystem::path> m_ImportQueue;
        std::map<std::string, IAssetCompiler*> m_Compilers;
        bool m_Busy = false;
        float m_CurrentProgress = 0.0f;
    };
}

Exemplo de Compilador (Textura)#

cpp
bool TextureCompiler::Compile(AssetImportContext& ctx) {
    // 1. Carregar imagem original (PNG/JPG)
    // 2. Comprimir para formato BC7 ou ASTC
    // 3. Gerar Mipmaps
    // 4. Serializar para ficheiro .caf (Header + Binary Data)
    ctx.Logs.push_back("Texture compiled successfully: " + ctx.DestinationPath.string());
    return true;
}

Decisões de Design#

Decisão Justificativa
Background Conversion A conversão em threads separadas evita que o editor bloqueie (freeze) durante a importação de grandes volumes de dados.
Manifest em JSON/Binário O manifesto permite que o motor saiba quais os assets disponíveis sem percorrer o disco no arranque, acelerando o "Cold Start".
Versionamento de Cache Se o formato .caf mudar, o pipeline deteta e força o re-import de todos os assets automaticamente.

Critério de Aceitação#

  • [ ] Detecção automática de novos ficheiros PNG, JPG, WAV na pasta assets/raw/.
  • [ ] Conversão automática para o formato binário .caf após detecção.
  • [ ] Exibição de uma barra de progresso no editor durante conversões longas.
  • [ ] Logs de conversão visíveis na ConsoleWindow.
  • [ ] Opção "Re-import" disponível no menu de contexto do Asset Browser.
  • [ ] O ficheiro assets/manifest.caf é atualizado corretamente após cada importação bem-sucedida.

Dependências#

  • Upstream: Caffeine::Core::FileSystem
  • Downstream: Caffeine::Assets::AssetManager

🔗 Tópicos Relacionados#

Tópico Descrição
Asset Manager Consome os ficheiros .caf produzidos por este pipeline.
Console Window Exibe os outputs e erros dos compiladores.

Referências#

  • O3DE Asset Processor Architecture
  • Unity Asset Database (v2) documentation
  • STB Image / DirectXTex libraries for texture processing.