Caffeine

🔧 Script Watcher

Planned Milestone: M3 — Scripting & Runtime Namespace: `Caffeine::Scripting` Arquivos: `src/caffeine/script/ScriptWatcher.hpp`, `src/caffeine/script/ScriptWatcher.cpp` RF: RF6.5 Last updated:

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.

cpp
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#

text
[ 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 .lua externo 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.

Referências#