🔧 Hot-Reload de Assets
Visão Geral#
O Hot-Reload de Assets permite que as alterações feitas em ficheiros externos (como texturas editadas no Photoshop ou shaders escritos em VS Code) sejam refletidas instantaneamente no Caffeine Studio sem necessidade de reiniciar a aplicação. Esta funcionalidade é crucial para a produtividade, permitindo iterações rápidas em aspetos visuais e lógicos do jogo.
O sistema baseia-se na monitorização de carimbos temporais (timestamps) dos ficheiros e na capacidade do AssetManager de substituir os dados binários na memória da CPU e GPU, mantendo as referências (Handles) existentes válidas para os sistemas que os utilizam.
Implementação#
O Hot-Reload utiliza a infraestrutura existente do AssetManager e expande-a com um ciclo de poll e recarregamento seletivo.
Fluxo de Execução#
- Monitorização: O
HotReloadercorre um thread de baixa prioridade que verificapollFileChanges(). - Notificação: Ao detetar uma mudança, o Asset Pipeline é acionado para regenerar o ficheiro
.caf. - Substituição: O
AssetManagerrecarrega o ficheiro binário e atualiza o recurso na GPU (ex:glTexImage2D). - Feedback: Uma notificação (Toast) aparece no editor confirmando o sucesso.
Código de Exemplo (C++)#
namespace Caffeine::Assets {
class HotReloader {
public:
void Start(AssetManager* assetManager);
void Stop();
// Chamado no loop principal do Editor
void Update() {
auto changedAssets = m_AssetManager->PollFileChanges();
for (auto& assetHandle : changedAssets) {
ReloadAsset(assetHandle);
}
}
private:
void ReloadAsset(AssetHandle handle) {
AssetMetadata& meta = m_AssetManager->GetMetadata(handle);
// Recarregar conforme o tipo
switch (meta.Type) {
case AssetType::Texture:
ReloadTexture(handle, meta.ProcessedPath);
break;
case AssetType::Shader:
ReloadShader(handle, meta.ProcessedPath);
break;
}
// Notificar UI
EditorUI::ShowToast(meta.Name + " reloaded successfully.");
}
void ReloadTexture(AssetHandle handle, const std::path& path) {
// Ler novos dados do disco
auto newData = FileSystem::ReadBinary(path);
// Obter referência à textura na GPU e atualizar
RHI::Texture* gpuTex = m_AssetManager->GetRawResource<RHI::Texture>(handle);
gpuTex->UpdateData(newData.data(), newData.size());
}
AssetManager* m_AssetManager;
};
}
Tipos Suportados Iniciais#
- Texturas: .png, .jpg (via conversão para .caf)
- Shaders: .hlsl, .glsl
- Materiais: .mat (JSON)
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| In-Place Update | Atualizar a textura existente na GPU em vez de criar uma nova evita a necessidade de atualizar todos os materiais que a referenciam. |
| Toast Notifications | Notificar o utilizador no canto do ecrã fornece confirmação visual de que a alteração externa foi processada com sucesso. |
| Debounce Timer | Esperar 100ms após a última escrita no ficheiro antes de recarregar evita ler ficheiros parciais enquanto o software de edição (ex: Photoshop) ainda está a guardar. |
Critério de Aceitação#
- [ ] Alterar uma textura no disco reflete-se no Viewport em menos de 1 segundo.
- [ ] Alterar um shader recompila-o e atualiza os materiais que o utilizam.
- [ ] O editor não bloqueia nem crasha durante o processo de recarregamento.
- [ ] Uma notificação "Asset X reloaded" aparece no fundo do ecrã.
- [ ] As instâncias existentes de entidades mantêm os seus componentes e estados após o reload do asset.
Dependências#
- Upstream:
Caffeine::Assets::AssetManager,Caffeine::Assets::AssetPipeline - Downstream:
Caffeine::Editor::UI(Toasts)
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Asset Pipeline | Converte os raw assets alterados antes do hot-reload. |
| RHI (Rendering) | Fornece as funções para atualizar buffers na GPU. |
Referências#
- "Thebe" Engine Hot Reloading system.
- Live coding and hot asset loading in "Handmade Hero".