4.5 Build System Integration

[LyeZinho]

🔧 Build System Integration

Milestone: M4 — Advanced Tools & Polish
Namespace: Caffeine::Editor
Arquivos: src/editor/BuildSystem.hpp, src/editor/BuildSystem.cpp
Status: 📅 Planeado
RF: RF6.5

---

Visão Geral

O Build System Integration transforma o Caffeine Studio num ambiente de desenvolvimento completo, permitindo que os criadores passem do design à execução com um único clique. Esta ferramenta gere todo o pipeline de compilação, desde a recolha de assets e scripts até à geração de um executável final otimizado para a plataforma de destino (Windows, Linux, etc.).

A integração inclui um painel de configuração onde se definem cenas de arranque, ícones, versões e níveis de otimização (Debug vs Release). Durante o processo de build, o progresso é exibido de forma transparente na consola do editor, fornecendo feedback detalhado em caso de erro. Após a conclusão, o sistema pode iniciar automaticamente o jogo ou abrir a pasta de saída para distribuição.

---

Implementação

O sistema de build atua como um coordenador entre o compilador de C++, o processador de scripts Lua e o empacotador de assets.

Estrutura do Sistema de Build

namespace Caffeine::Editor {

enum class BuildPlatform {
    Windows_x64,
    Linux_x64,
    Android,
    WebAssembly
};

struct BuildSettings {
    std::string projectName;
    std::string outputDir;
    BuildPlatform platform;
    bool isDebug = false;
    std::vector<std::string> scenesToInclude;
};

class BuildSystem {
public:
    static bool ExecuteBuild(const BuildSettings& settings);
    static void RunGame(const std::string& executablePath);

private:
    static bool PrepareOutputDirectory(const std::string& path);
    static bool CompileScripts();
    static bool PackageAssets(const std::vector<std::string>& assets);
    static bool LinkExecutable();
};

class BuildDialog : public EditorPanel {
public:
    void OnImGuiRender() override;

private:
    BuildSettings m_currentSettings;
    float m_progress = 0.0f;
    std::string m_currentStatus;
    bool m_isBuilding = false;
};

} // namespace Caffeine::Editor

Exemplo de Fluxo de Execução (Pseudo-C++)

bool BuildSystem::ExecuteBuild(const BuildSettings& settings) {
    Log::Info("A iniciar build para a plataforma: Windows");
    
    // 1. Limpar e preparar diretório
    if (!PrepareOutputDirectory(settings.outputDir)) return false;
    
    // 2. Processar Assets (Texturas -> .dds, Shaders -> SPIR-V)
    AssetCooker cooker;
    for (const auto& asset : settings.scenesToInclude) {
        cooker.Process(asset);
        // Atualizar UI progress
    }
    
    // 3. Copiar Runtime e Ficheiros Necessários
    std::filesystem::copy("bin/CaffeineRuntime.exe", settings.outputDir);
    
    // 4. Gerar ficheiro de configuração do projeto
    ProjectFile::Export(settings, settings.outputDir + "/project.caffeine");
    
    Log::Info("Build concluída com sucesso!");
    return true;
}

Consola de Progresso (ASCII)

┌─────────────────────────────────────────────────────────────┐
│  🔨 Build Project: "MySuperGame"                            │
├─────────────────────────────────────────────────────────────┤
│  Platform: [Windows x64 v]    Config: [Release v]           │
│  Output:   [C:/Users/Dev/Desktop/Build/           ] [...]   │
├─────────────────────────────────────────────────────────────┤
│  Progress: [██████████████████░░░░░░░░░] 65%                │
│  Status:   Packaging Assets: "textures/skybox_night.png"     │
├─────────────────────────────────────────────────────────────┤
│  Log:                                                       │
│  [Build] Started at 14:30:05                                │
│  [AssetCooker] Compiling Shaders... Done.                   │
│  [AssetCooker] Processing Textures...                       │
│  [Linker] Merging data fragments...                         │
└─────────────────────────────────────────────────────────────┘

---

Decisões de Design

Decisão	Justificativa
Configuração em JSON/YAML	Permite que o ficheiro de projeto seja facilmente lido e editado por ferramentas externas ou Git.
Separação Runtime/Editor	O executável final não contém o código do editor, resultando em binários mais leves e rápidos.
Sistema de "Cooking" de Assets	Assets são convertidos para formatos binários nativos de GPU durante a build para evitar conversões lentas no arranque do jogo.
Threading Dedicado	O processo de build corre numa thread separada para não bloquear a interface do utilizador.

---

Critério de Aceitação

• Diálogo de configuração permite definir o nome do executável e a pasta de destino.
• O comando "Build & Run" inicia a compilação e executa o jogo automaticamente após o sucesso.
• A consola exibe erros detalhados se a compilação de scripts ou shaders falhar.
• O ficheiro project.caffeine é gerado corretamente com as cenas de arranque definidas.
• Suporte para builds incrementais (apenas reprocessa assets alterados).

---

Dependências

• Upstream: docs/scripting/scripting.md (necessário para validar scripts antes da build)
• Downstream: Distribuição do jogo (ficheiros .exe e pastas de data)

---

🔗 Tópicos Relacionados

Tópico	Descrição
Asset Cooking	O processo de transformar ficheiros fonte (.png, .obj) em binários otimizados.
Project Configuration	Definições globais do jogo armazenadas no ficheiro de projeto.
Console Window	Onde todos os logs do processo de build são centralizados.

---

Referências

• Documentação de sistemas de build (CMake, MSBuild).
• Melhores práticas para empacotamento de assets em motores de jogo (ex: Unreal's Pak files).
• Normas de segurança para execução de processos externos em C++.