🔧 Asset Pipeline Integration
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#
[ Pasta raw/ ] --(FileWatcher)--> [ AssetPipeline ] --(Dispatcher)--> [ Compilers ]
|
v
[ assets/manifest.caf ] <--- [ assets/processed/ ]
Estrutura de Classes#
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)#
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
.cafapó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.