Assets Hot-Reload — Design
Date: 2026-05-15
Issue: #93
**Milestone:**M2 — Visual Editing & Assets
Namespace: Caffeine::Assets
Overview#
Directory background monitoring assets/processed/ to detect file changes .caf newly compiled by Asset Pipeline and trigger in-place recharges in AssetManager — without restarting the engine or losing the state of the scene in the editor.
Arquitetura#
[ assets/processed/*.caf ] ←── AssetPipeline escreve .caf atualizado▼HotReloader (background thread)poll a cada 500msdebounce 100ms (configurável)detecta timestamp changeaguarda estabilidade (debounce)enfileira path em m_PendingReloads (mutex)
▼HotReloader::Update() ←── chamado na main thread (ex: EditorContext::Update)desenfileira batch sob mutexAssetManager::reloadAsset(path)reseta LinearAllocator + resolved dataloadInternal(id) — fopen, BlobLoader, resolveEntryretorna assetId
determina tipo via getResolved<T>()NotificationCallback(assetInfo) — editor toast
Componentes#
HotReloader (class)#
| Method | Description |
|---|---|
Start(manager, processedDir, debounceMs) |
Inicia thread de polling |
Stop() |
Join thread, limpa estado |
Update() |
Processa fila de reloads na main thread |
SetNotificationCallback(cb) |
Hook for Visual Notification (editor toast) |
IsRunning() |
Estado atual |
HotReloadedAsset (struct)#
| Campo | Tipo | Description |
|---|---|---|
assetId |
u32 |
ID do asset recarregado |
name |
std::string |
File name without extension |
type |
AssetType |
Texture / Audio / Shader |
AssetManager::reloadAsset(path)#
Added public method for external reload trigger:
- Busca
pathemm_pathIndex(comm_basePathprefixado) - Reseta:
allocator.reset(),header/metadata/payload = nullptr,resolved = {} - Subtrai
sizeBytesdem_cachedBytes - Status →
Unloaded - Libera mutex
loadInternal(id)— reloads the disc, re-solves- Retorna
assetId(ou~0uif not found)
Threading#
- Poll thread (criada em
Start()):- Itera
directory_iteratorin the directory processed every 500ms - Compara
last_write_timecom snapshot anterior - State Machine 3-state: unmodified → debouncing → ready
- Escreve em
m_PendingReloadssobm_Mutex
- Itera
- Main thread (via
Update()):- Read
m_PendingReloadssobm_Mutex, troca com vetor vazio - Executa reload fora do lock
- Fire notification callback
- Read
Debounce#
Three states per monitored file:
- Unmodified (
debounceStart == -1): timestamp stable between polls - First change detected (
debounceStart >= 0): timestamp mudou, timer inicia - Debounce elapsed (
>= debounceMsno new changes: reload is queued
Tests#
5 tests in tests/test_assetmanager.cpp :
| Teste | O que verifica |
|---|---|
default state is not running |
IsRunning() == false sem Start() |
Start/Stop lifecycle |
State transitions, idempotence of Stop() |
Start twice does not crash |
Start() → Start() → Stop() |
Update is safe when not running |
Update() antes de Start() and after Stop() |
integration reload and callback |
Poll discovers change, Update() recarrega, callback dispara |
Uso no Editor#
cpp
// Inicialização
m_HotReloader.Start(&m_AssetManager, "assets/processed/", 100);
m_HotReloader.SetNotificationCallback([](const HotReloadedAsset& a) {
EditorToast::Show(ICON_FA_SYNC " {} recarregado", a.name);
});
// A cada frame (main thread)
m_HotReloader.Update();