🔧 Script Watcher
Visão Geral#
O ScriptWatcher é um utilitário de produtividade que monitoriza alterações em tempo real nos ficheiros de script do projeto. Quando um programador guarda um ficheiro .lua num editor externo (como VS Code ou Notepad++), o ScriptWatcher deteta a alteração através das "timestamps" do sistema de ficheiros e solicita à LuaVM que recarregue o script imediatamente.
Esta funcionalidade de "Hot-Reload" permite ver alterações de comportamento no jogo sem necessidade de reiniciar a aplicação ou recarregar a cena. É uma peça fundamental para o fluxo de trabalho iterativo do Caffeine Studio.
Implementação#
Monitorização de Ficheiros#
O sistema mantém um mapa de caminhos de ficheiros e as suas últimas datas de modificação.
namespace Caffeine::Scripting {
struct ScriptFileEntry {
std::filesystem::path path;
std::filesystem::file_time_type lastModified;
};
class ScriptWatcher {
std::vector<ScriptFileEntry> m_watchedFiles;
f32 m_checkInterval = 1.0f; // Verificar a cada segundo
f32 m_timer = 0.0f;
public:
void update(f32 dt, LuaVM& vm) {
m_timer += dt;
if (m_timer >= m_checkInterval) {
checkFiles(vm);
m_timer = 0.0f;
}
}
private:
void checkFiles(LuaVM& vm) {
for (auto& entry : m_watchedFiles) {
auto currentTime = std::filesystem::last_write_time(entry.path);
if (currentTime > entry.lastModified) {
vm.reloadScript(entry.path.string());
entry.lastModified = currentTime;
// Notificar o sistema de UI
Events::Publish("ScriptReloaded", entry.path.string());
}
}
}
};
} // namespace Caffeine::Scripting
Integração com a UI do Editor#
Quando um script é recarregado, o editor deve fornecer feedback visual:
- Consola: Log de sucesso ou erro de compilação.
- Notificação Toast: "Script modificado — recarregado com sucesso".
- Scene View: Atualização imediata do comportamento das entidades.
Diagrama de Hot-Reload#
[ EDITOR EXTERNO ] --- (Save File) ---> [ FILE SYSTEM ]
|
v
[ ENGINE ] <-------------------------- [ SCRIPT WATCHER ]
| |
| (1) Detect Change |
| (2) Call LuaVM::reloadScript() <---------+
| (3) Re-bind local tables
| (4) Clear caches
v
[ RUNNING GAME ] (Updated Logic!)
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Polling Controlado (1s) | Evita sobrecarga do sistema de ficheiros e lida com editores que guardam ficheiros de forma atómica/temporária. |
Reload via LuaVM |
Garante que o estado global do motor não é corrompido durante a substituição da lógica. |
Evento ScriptReloaded |
Permite que outros sistemas (como o Inspector) se atualizem se houver novos campos expostos. |
Critério de Aceitação#
- [ ] Modificar um ficheiro
.luaexterno resulta num log na consola do motor. - [ ] Alterações na lógica de movimento são visíveis imediatamente após o "Save".
- [ ] Erros de sintaxe introduzidos durante a edição são capturados e exibidos.
- [ ] O motor não crasha se o ficheiro for guardado vazio ou com erros.
Dependências#
- Upstream:
LuaVM,AssetManager - Downstream:
ConsoleWindow,EditorUI
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
docs/debug/debug-tools.md |
Como os erros são reportados na consola. |
docs/assets/asset-manager.md |
Monitorização base de ficheiros. |