Caffeine

🛠️ Caffeine Studio IDE — Plano de Desenvolvimento

Planned Milestone: 2.0 — Caffeine Studio Namespace: `Caffeine::Editor` RFs: RF6.1–RF6.6, RF4.7 Last updated:

Sumário Executivo#

O Caffeine Studio IDE é a camada de ferramentas visuais da Caffeine Engine. Atualmente existem componentes-base implementados (ImGuiIntegration, ProfilerWindow, ConsoleWindow, StatsOverlay, AssetPipeline CLI), mas falta o Scene Editor — o coração do IDE — e os sistemas de Scripting, Gestão de Projetos e Ferramentas Avançadas.

Este plano divide o desenvolvimento em 4 milestones progressivas:

Milestone Nome Foco Dependências
M1 Scene Editor Foundation Painéis core, viewport, serialização ECS, RHI, ImGui
M2 Visual Editing & Assets Gizmos, drag-and-drop, pipeline integrado, projeto M1 + AssetPipeline
M3 Scripting & Runtime LuaVM, ScriptSystem, bindings ECS, hot-reload M1 + ECS
M4 Advanced Tools & Polish Timeline, tilemap, materiais, build, prefabs, extensões M1–M3

Nota: Cada milestone é autónoma — pode ser entregue e testada independentemente.

Engine pillars: subsistemas de runtime (rendering Phong, Bullet3, OpenAL, networking, PBR, etc.) estão no roadmap de pilares — docs/plans/2026-09-22-engine-pillars-roadmap.md.


Estado Atual (Pré-M1)#

✅ Já Implementado#

Componente Ficheiros Estado
ImGuiIntegration doppio-archived/src/doppio/editor/ImGuiIntegration.hpp ✅ Integração SDL3+ImGui
ProfilerWindow doppio-archived/src/doppio/editor/ProfilerWindow.hpp ✅ Gráfico de frame times
ConsoleWindow doppio-archived/src/doppio/editor/ConsoleWindow.hpp ✅ Log filtering por nível
StatsOverlay doppio-archived/src/doppio/editor/StatsOverlay.hpp ✅ FPS, cache stats
EditorTypes doppio-archived/src/doppio/editor/EditorTypes.hpp ✅ FrameStats, tipos base
AssetPipeline CLI src/caffeine/tools/ ✅ Texture, Audio, Mesh encoders
UISystem (game) src/caffeine/ui/UISystem.hpp ✅ UI retained mode para jogos
SceneSerializer src/caffeine/scene/SceneSerializer.hpp ✅ Serialização .caf
ECS Core src/caffeine/ecs/World.hpp ✅ Archetypes, queries, systems
RHI src/caffeine/rhi/RenderDevice.hpp ✅ SDL_GPU abstraction

❌ Por Implementar#

Componente Prioridade Depende de
SceneEditor (orquestrador) 🔴 Crítico ImGuiIntegration, ECS
HierarchyPanel 🔴 Crítico ECS, Scene
InspectorPanel 🔴 Crítico ECS (component reflection)
SceneViewport 🔴 Crítico RHI, BatchRenderer, Camera
AssetBrowser 🟡 Alto AssetManager
Transform Gizmos 🟡 Alto SceneViewport
Project Manager 🟡 Alto Sistema de ficheiros
LuaVM + ScriptSystem 🟡 Alto ECS, sol2
Animation Timeline 🟢 Médio Animation ECS
Tilemap Editor 🟢 Médio SceneEditor
Material/Shader Editor 🟢 Médio RHI
Build System 🟢 Médio CMake
Prefab System 🔵 Baixo ECS, SceneSerializer

T0 — Desacoplamento Core↔IDE (Fundação)#

Objetivo: Separar o monolito atual em dois binários independentes — Caffeine Engine (core) e Doppio (IDE) — com uma fronteira de API bem definida.

Problema Atual#

Neste momento tudo vive na mesma biblioteca Caffeine, incluindo código editor que depende de ImGui. Isto significa que:

  • Uma build headless (servidor, CI, testes) paga o custo do ImGui e do editor
  • O core não pode ser reutilizado sem arrastar a IDE
  • A separação de responsabilidades é inexistente — target_link_libraries(Caffeine PUBLIC ImGui) torna ImGui numa dependência pública mesmo para quem só quer a engine

Arquitetura Alvo#

text
┌─────────────────────────────────────────────────────────────────┐
│                         DOCCIO (IDE)                            │
│  SceneEditor | HierarchyPanel | InspectorPanel | SceneViewport  │
│  AssetBrowser | ProfilerWindow | ConsoleWindow | StatsOverlay   │
│  Gizmos | Timeline | Tilemap Editor | Material Editor           │
│  Lua Script Editor | Plugin System | Build System               │
│                                                                 │
│  Depende de: Caffeine::Core (engine) + ImGui + SDL3             │
│  NÃO funciona sem o core                                        │
└──────────────────────────┬──────────────────────────────────────┘
                           │ #include "Caffeine/*.hpp"
                           │ link: Caffeine::Core
┌──────────────────────────▼──────────────────────────────────────┐
│                      CAFFEINE ENGINE (CORE)                     │
│  Core: Types, Memory, Platform, IO, Timer                       │
│  Math: Vec2/3/4, Mat4, Quat                                     │
│  Concurrency: JobSystem, ThreadPool, Work-Stealing              │
│  Input: InputManager, Action/Axis Mapping                       │
│  ECS: World, Entity, Archetypes, Queries, Systems               │
│  Scene: SceneManager, SceneSerializer (.caf)                    │
│  Events: EventBus, pub/sub                                      │
│  Assets: AssetManager, AssetHandle, Hot-Reload                  │
│  Rendering: RHI, BatchRenderer, Camera2D/3D, TextureAtlas       │
│  Audio: AudioSystem, AudioSource, Spatial                       │
│  Animation: AnimationClip, State Machine                         │
│  Physics: Physics2D, RigidBody, Collision                       │
│  UI: UISystem (game HUD, retained mode)                         │
│  Scripting: LuaVM, ScriptSystem, Bindings                       │
│  Debug: LogSystem, Profiler, DebugDraw                          │
│                                                                 │
│  ZERO dependência de ImGui ou editor code                       │
│  Funciona standalone (headless ou com rendering SDL3)           │
└─────────────────────────────────────────────────────────────────┘

Escopo#

0.1 Identificar a Fronteira Core↔IDE#

Listar exaustivamente o que pertence ao core vs. o que é IDE:

Pertence ao Core Pertence ao Doppio (IDE)
ECS (World, Entity, queries) HierarchyPanel
SceneManager + SceneSerializer InspectorPanel + Component Drawers
RHI (RenderDevice, CommandBuffer) SceneViewport (framebuffer + gizmos)
BatchRenderer, Camera2D/3D AssetBrowser
AssetManager, AssetPipeline SceneEditor (orquestrador)
InputManager ProfilerWindow
AudioSystem ConsoleWindow
Physics2D StatsOverlay
AnimationSystem Timeline Editor
UI System (game) Tilemap Editor
LuaVM + ScriptSystem Material/Shader Editor
LogSystem, Profiler, DebugDraw Entity Debugger
GameLoop Build System Integration
EventBus Plugin System
JobSystem Project Manager
Core Types, Memory, Math, Containers Script Editor Integration

0.2 Separar o Build em Dois Targets#

cmake
# CMakeLists.txt — Caffeine Engine Core
add_library(caffeine-core
    src/core/Timer.cpp
    src/core/GameLoop.cpp
    src/ecs/World.cpp
    src/ecs/CommandBuffer.cpp
    src/events/EventBus.cpp
    src/assets/AssetManager.cpp
    src/rhi/RenderDevice.cpp
    src/input/InputManager.cpp
    src/debug/LogSystem.cpp
    src/debug/Profiler.cpp
    src/threading/JobSystem.cpp
    src/script/ScriptEngine.cpp
    # ... resto do core, SEM editor/*
)

# ⚠️ NÃO linkar ImGui — core é puro
target_link_libraries(caffeine-core PUBLIC SDL3::SDL3)
target_include_directories(caffeine-core PUBLIC src/)
cmake
# CMakeLists.txt — Doppio IDE
add_executable(doppio
    src/editor/SceneEditor.cpp
    src/editor/HierarchyPanel.cpp
    src/editor/InspectorPanel.cpp
    src/editor/SceneViewport.cpp
    src/editor/AssetBrowser.cpp
    src/editor/ProfilerWindow.cpp
    src/editor/ConsoleWindow.cpp
    src/editor/StatsOverlay.cpp
    src/editor/ImGuiIntegration.cpp
    tools/ide/main.cpp
)

target_link_libraries(doppio PRIVATE caffeine-core ImGui)
target_include_directories(doppio PRIVATE src/)

0.3 Remover Dependência de ImGui do Core#

  • editor/ incluído atualmente no Caffeine library → mover para doppio
  • ImGuiIntegration deixa de ser linked ao core
  • CF_HAS_IMGUI define apenas no target doppio
  • Headers do core que usam ImGui (ImGuiIntegration.hpp nos editor types) são movidos
  • Alternativa: se algum core system precisa de debug visualization, expor via interface abstrata (DebugDraw)

0.4 Definir Pontos de Extensão Core→IDE#

O core precisa de extension points para a IDE se conectar sem o core saber da IDE:

cpp
// Caffeine/Core/IDebugHooks.hpp — API de extensão core→IDE
namespace Caffeine::Core {

struct IDebugHooks {
    virtual ~IDebugHooks() = default;
    virtual void onEntityCreated(ECS::Entity e) = 0;
    virtual void onEntityDestroyed(ECS::Entity e) = 0;
    virtual void onLogMessage(const char* msg, u8 level) = 0;
    virtual void onFrameEnd(const FrameStats& stats) = 0;
};

// Core expõe um registry opcional de hooks
class DebugHookRegistry {
public:
    static void registerHooks(IDebugHooks* hooks);
    static IDebugHooks* hooks();
};

} // namespace Caffeine::Core
cpp
// Doppio implementa os hooks:
struct EditorDebugHooks : Caffeine::Core::IDebugHooks {
    void onEntityCreated(ECS::Entity e) override {
        // atualiza HierarchyPanel
    }
    void onLogMessage(const char* msg, u8 level) override {
        // adiciona ao ConsoleWindow
    }
    void onFrameEnd(const FrameStats& stats) override {
        // atualiza ProfilerWindow + StatsOverlay
    }
};

Outros pontos de extensão necessários:

  • AssetImportHook — core faz asset loading, IDE pode interceptar para mostrar progress bar
  • SelectionHook — core não tem conceito de "seleção", IDE gere
  • PlayModeHook — core tem game loop, IDE pode iniciar/parar play mode
  • InputOverride — IDE pode consumir input antes do core (ex: shortcuts do editor)

0.5 Headless Mode#

O core deve ser buildável sem SDL3:

cmake
option(CAFFEINE_BUILD_HEADLESS "Build core without SDL3/RHI" OFF)
if(CAFFEINE_BUILD_HEADLESS)
    target_compile_definitions(caffeine-core PUBLIC CF_HEADLESS=1)
    # SDL3 não linked, RHI não compilado
else()
    target_link_libraries(caffeine-core PUBLIC SDL3::SDL3)
endif()

Isto permite:

  • Servidor dedicado sem GPU
  • CI tests sem GPU
  • Runtime de jogo standalone (sem IDE)
  • Compilação mais rápida para development core-only

0.6 Renomear caffeine-studio → doppio#

  • Executável caffeine-studio → doppio
  • Namespace Caffeine::Editor → Doppio::Editor (ou manter Caffeine::Editor como sub-namespace de Doppio)
  • Ficheiro tools/ide/main.cpp → apps/doppio/main.cpp
  • Separar recursos estáticos (ícones, shaders editor) em apps/doppio/assets/

0.7 Atualizar Testes#

  • CaffeineTest passa a linkar caffeine-core (não a library monolítica)
  • Testes de editor (se existirem) passam a DoppioTest que linka doppio
  • CI ganha dois jobs: build-core (headless) e build-doppio (com SDL3)

Critério de Aceitação (T0)#

  • [ ] caffeine-core compila sem ImGui e sem editor code
  • [ ] caffeine-core compila em modo headless (sem SDL3)
  • [ ] doppio compila e linka caffeine-core + ImGui
  • [ ] Testes core-only (CaffeineTest) passam sem SDL3
  • [ ] DebugHookRegistry permite IDE ligar-se ao core sem core conhecer IDE
  • [ ] doppio substitui caffeine-studio com mesma funcionalidade
  • [ ] SceneEditor no doppio usa Caffeine::Core::DebugHookRegistry para console + profiler
  • [ ] Core não tem #include <imgui.h> em nenhum header público
  • [ ] Build headless não falha por falta de SDL3

Impacto nos Milestones Seguintes#

Milestone Impacto
M1–M4 Todo o código editor (painéis, gizmos, viewport) vive em doppio, linka caffeine-core. Nenhum milestone precisa de mudar a fronteira.
Testes Testes de editor precisam de doppio linkado; testes core puros usam caffeine-core
CI/CD caffeine-core testado em headless (rápido); doppio testado com SDL3 (lento, opcional)

M1 — Scene Editor Foundation#

Objetivo: Transformar o overlay de debug num editor de cenas funcional com os 4 painéis principais.

Escopo#

1.1 EditorContext & Undo/Redo#

Estado global de seleção e operações:

cpp
struct EditorCommand {
    enum Type { AddEntity, RemoveEntity, AddComponent,
                RemoveComponent, SetField, MoveEntity };
    Type type;
    // Serialized before/after state for undo
    std::vector<u8> beforeState;
    std::vector<u8> afterState;
};

class UndoStack {
    static constexpr u32 MAX_UNDO = 256;
    EditorCommand m_commands[MAX_UNDO];
    u32 m_head = 0, m_tail = 0, m_count = 0;
public:
    void push(const EditorCommand& cmd);
    bool undo(ECS::World& world);
    bool redo(ECS::World& world);
    void clear();
};

1.2 HierarchyPanel#

Árvore de entidades com suporte a:

  • Exibição hierárquica (Parent component)
  • Renomear (NameComponent)
  • Criar entidade vazia
  • Deletar (Delete key)
  • Drag-and-drop para reparenting
  • Context menu (right-click: Create, Duplicate, Delete, Copy/Paste)
  • Search/filter bar no topo

1.3 InspectorPanel#

Edição de componentes da entidade selecionada:

  • Drawers built-in: Transform, SpriteRenderer, RigidBody2D, Camera2D, AudioSource, NameComponent
  • Auto-detection: se o componente não tem drawer, mostrar raw fields (tipo + valor)
  • Add Component dropdown: lista todos os tipos de componente registados
  • Remove Component: botão X em cada header de componente
  • Reset to default: botão em cada field individual
  • Struct nesting: campos Vec2, Vec3, Color expandidos inline

1.4 SceneViewport#

Viewport com offscreen rendering:

  • Framebuffer separado (RHI::TextureHandle)
  • Renderização da cena via BatchRenderer
  • ImGui::Image para exibir o framebuffer
  • Botões de toolbar: grid toggle, gizmo mode (W/E/R), camera snap
  • Suporte a zoom (scroll) e pan (middle-click drag)
  • Grid 2D desenhada no framebuffer

1.5 AssetBrowser (v1)#

Navegação básica de ficheiros:

  • Listagem de diretórios e ficheiros .caf
  • Navegação por pastas (double-click)
  • Path bar clicável
  • Refresh button
  • Preview de textura ao selecionar (via AssetManager)

1.6 SceneEditor Orchestrator#

Layout docking usando Dear ImGui Docking:

text
┌─────────────────────────────────────────────────────────────┐
│  Menu: File | Edit | View | Build | Run                    │
├───────────┬───────────────────────────────┬─────────────────┤
│Hierarchy  │       Scene Viewport          │   Inspector     │
│  Panel    │                               │     Panel       │
│           │                               │                 │
│    ───    ├───────────────────────────────┴─────────────────┤
│           │  Asset Browser  |  Console  |  Profiler         │
├───────────┴─────────────────────────────────────────────────┤
│  Status Bar: Entity count | FPS | Scene path | Dirty flag   │
└─────────────────────────────────────────────────────────────┘
  • File > New Scene / Open / Save / Save As
  • Edit > Undo / Redo / Preferences
  • Integração com ProfilerWindow e ConsoleWindow existentes

1.7 Save/Load Scene#

  • SceneEditor::saveScene(path) → delega no SceneSerializer
  • SceneEditor::loadScene(path) → limpa world + deserializa
  • Indicador de dirty (ficheiro não salvo)
  • Prompt "Save changes?" ao fechar cena suja

Critério de Aceitação (M1)#

  • [ ] HierarchyPanel mostra todas as entidades em árvore com nomes
  • [ ] Clicar numa entidade na Hierarchy seleciona-a e atualiza o Inspector
  • [ ] InspectorPanel permite editar Transform (pos, rot, scale) com sliders/input
  • [ ] InspectorPanel permite editar SpriteRenderer (texture, color, flip)
  • [ ] Add Component dropdown mostra componentes disponíveis
  • [ ] SceneViewport renderiza a cena para framebuffer offscreen
  • [ ] SceneViewport exibe o framebuffer via ImGui::Image
  • [ ] Scroll no viewport faz zoom, middle-click arrasta a câmara
  • [ ] AssetBrowser lista diretórios e ficheiros .caf
  • [ ] File > Save serializa a cena para .caf e limpa dirty flag
  • [ ] File > Open deserializa .caf e popula o ECS
  • [ ] Undo/Redo funcionam para AddEntity e RemoveEntity
  • [ ] Docking layout persiste entre sessões
  • [ ] ProfilerWindow e ConsoleWindow continuam a funcionar no novo layout

M2 — Visual Editing & Assets#

Objetivo: Tornar o editor visualmente produtivo — gizmos, drag-and-drop, pipeline de assets integrado.

Escopo#

2.1 Transform Gizmos#

Implementação de gizmos 2D (inspirado em ImGuizmo):

text
Translate (W):       Rotate (E):          Scale (R):
     ▲ Y                  ◯                    ■ Y
     │                 ╱     ╲                 │
     └────► X          │       │               └────■ X
   ╱                 ╲       ╱               ╱
 ╱ Z (3D)              ╲   ╱               ╱ Z (3D)
  • Arrastar eixo: modifica apenas esse eixo
  • Arrastar centro: modificação livre (2D) ou plano (3D)
  • Snap: Shift+drag usa snapping configurável (16px, 45° rotation)
  • Highlight a hover (eixo fica amarelo)
  • Gizmo mode switcher na toolbar ou teclas W/E/R/Q

2.2 Drag-and-Drop#

  • Arrastar AssetBrowser → SceneViewport cria entidade com SpriteRenderer + Transform
  • Arrastar AssetBrowser → Inspector field de textura atribui diretamente
  • Arrastar Hierarchy → reorganiza parent/child

2.3 Asset Pipeline Integration#

  • Auto-import: ao detetar novo ficheiro em assets/raw/, converter automaticamente para .caf
  • Progress bar para conversões longas
  • Log de conversão no ConsoleWindow
  • Re-import button no AssetBrowser (context menu)
  • Asset manifest (assets/manifest.caf) com metadados por asset

2.4 Hot-Reload de Assets#

  • AssetManager::pollFileChanges() already exists
  • Atualizar textura na GPU sem restart
  • Mostrar toast notification: "hero.caf reloaded"
  • Suporte a: texturas, shaders HLSL/GLSL

2.5 Project Manager#

text
┌─────────────────────────────────────────────┐
│       ☕ Caffeine Studio — Project Manager   │
├─────────────────────────────────────────────┤
│                                             │
│  Recent Projects:                           │
│  ┌─────────────────────────────────────┐    │
│  │ 📁 MyGame       C:/projects/mygame  │    │
│  │ 📁 Platformer    .../platformer     │    │
│  │ 📁 RPG           .../rpg           │    │
│  └─────────────────────────────────────┘    │
│                                             │
│  [  New Project  ]  [  Open Project  ]      │
│                                             │
└─────────────────────────────────────────────┘
  • New Project Wizard: nome, path, template (2D/3D/Empty)
  • Project structure criada automaticamente: assets/raw/, scripts/, build/
  • project.caffeine ficheiro de configuração do projeto (JSON)
  • Lembrar último projeto aberto (auto-open)

2.6 AssetBrowser (v2)#

  • Thumbnails gerados para texturas (miniaturas GPU)
  • Preview panel: ao selecionar asset, mostra preview
  • Drag preview: thumbnail segue o cursor durante drag
  • Search/filter por nome e tipo
  • Grid view / list view toggle
  • Folder creation (right-click > New Folder)

2.7 Multiple Scene Tabs#

  • Abas para cada cena aberta (tab bar no topo do viewport)
  • Cada aba tem o seu próprio ECS World
  • Arrastar tab para desacoplar em janela flutuante

Critério de Aceitação (M2)#

  • [ ] Gizmo Translate arrasta entidade no eixo X/Y
  • [ ] Gizmo Rotate roda entidade visualmente
  • [ ] Gizmo Scale escala entidade no eixo ou uniformemente
  • [ ] Snap funciona com Shift+drag
  • [ ] Drag de textura do AssetBrowser para o Viewport cria entidade
  • [ ] Drag de textura para Inspector field atribui diretamente
  • [ ] Asset Pipeline converte PNG/WAV automaticamente em background
  • [ ] Hot-reload atualiza textura modificada sem restart
  • [ ] Project Manager cria novo projeto com estrutura de pastas
  • [ ] AssetBrowser mostra thumbnails de texturas
  • [ ] Múltiplas scenes abertas em tabs funcionam independentemente
  • [ ] Toast notification aparece em hot-reload e conversões

M3 — Scripting & Runtime#

Objetivo: Permitir scripting Lua com bindings ECS, hot-reload e integração total no editor.

Escopo#

3.1 LuaVM#

Implementação da máquina virtual Lua com sol2:

cpp
class LuaVM {
    sol::state m_lua;
public:
    bool init();
    void shutdown();
    bool loadScript(std::string_view path);
    bool reloadScript(std::string_view path);
    template<typename... Args>
    bool call(std::string_view function, Args&&... args);
    sol::state& state() { return m_lua; }
    
private:
    void registerCaffeineBindings();
    void registerEntityBindings();
    void registerTransformBindings();
    void registerInputBindings();
    void registerEventBindings();
    void registerDebugBindings();
    void registerMathBindings();
};

3.2 ScriptComponent + ScriptSystem#

cpp
struct ScriptComponent {
    Assets::AssetHandle<ScriptAsset> script;
};

class ScriptSystem : public ECS::ISystem {
    LuaVM* m_vm;
public:
    void onInit(ECS::World& world) override;
    void onUpdate(ECS::World& world, f32 dt) override;
    void onShutdown(ECS::World& world) override;
    void initNewScripts(ECS::World& world);
};

Ciclo de vida Lua exposto:

  • onCreate(entity) — chamado uma vez após criação
  • onUpdate(entity, dt) — chamado todo frame
  • onDestroy(entity) — chamado antes de destruição
  • onCollision(entity, other) — chamado ao colidir

3.3 Bindings ECS → Lua#

lua
local e = caffeine.world.create()
caffeine.world.addTransform(e, { x=100, y=200 })
caffeine.world.addSprite(e, { texture="hero.caf" })

local t = caffeine.world.getTransform(e)
t.x = t.x + 10
caffeine.world.setTransform(e, t)

if caffeine.input.isKeyDown("Space") then
    -- ...
end

local mx, my = caffeine.input.mousePosition()

3.4 Sandboxing#

Permitido Bloqueado
caffeine.* APIs os.*, io.* (excepto editor mode)
math.*, string.*, table.* load, loadstring
require (apenas módulos do projeto) debug.*

3.5 ScriptWatcher#

  • Monitoriza scripts/ com file timestamps
  • Hot-reload de .lua modificado via LuaVM::reloadScript()
  • Log de erros de compilação Lua no ConsoleWindow
  • Indicador visual no editor: "Script modified — reloaded"

3.6 Editor Integration#

  • InspectorPanel: field para atribuir script a ScriptComponent
  • Script editor: botão "Edit Script" abre ficheiro .lua no editor de sistema
  • Syntax highlight preview (futuro: editor embutido)
  • Error panel: erros Lua mostrados com linha e mensagem

3.7 Basic Particle System#

  • ParticleEmitter component (ECS)
  • Lua API para spawn de partículas
  • Visual preview no SceneViewport (play mode)
  • Suporte a: lifetime, velocity, color over time, size over time

Critério de Aceitação (M3)#

  • [ ] LuaVM executa script .lua simples (caffeine.debug.log("hello"))
  • [ ] ScriptComponent pode ser adicionado via InspectorPanel
  • [ ] onUpdate é chamado todo frame para entidades com ScriptComponent
  • [ ] Bindings de Transform (get/set pos, rot, scale) funcionam
  • [ ] Bindings de Input (isKeyDown, getAxis) funcionam
  • [ ] Bindings de Eventos (on, emit) funcionam
  • [ ] Erros Lua são logados no ConsoleWindow sem crash
  • [ ] Hot-reload: modificar .lua recarrega sem restart
  • [ ] Sandbox bloqueia os.execute(), io.open()
  • [ ] ParticleEmitter cria partículas com parâmetros configuráveis
  • [ ] Script pode ser atribuído/removido via Inspector

M4 — Advanced Tools & Polish#

Objetivo: Completar o IDE com ferramentas de produção — animação, tilemap, materiais, build, prefabs, extensões.

Escopo#

4.1 Animation Timeline Editor#

Editor de animação estilo timeline:

text
┌─────────────────────────────────────────────────────────────┐
│  Animation: "hero_idle"    [▶ Play]  [■ Stop]  [⟳ Loop]   │
│  Duration: 1.2s    FPS: 12                                 │
├─────────────────────────────────────────────────────────────┤
│  Timeline:  |──●──●──●──●──●──●──●──●──●──●──●──●──|      │
│             0s   0.1  0.2  0.3  0.4  0.5  0.6  ...  1.2s   │
├─────────────────────────────────────────────────────────────┤
│  Tracks:                                                     │
│  ▸ Sprite     [hero_1] [hero_2] [hero_3] ...               │
│  ▸ Position   ●─────────────●──────────────●               │
│  ▸ Rotation   ───●─────────────────────●────               │
│  ▸ Events     [play_sfx]        [spawn_particle]            │
└─────────────────────────────────────────────────────────────┘
  • Keyframe creation and editing
  • Sprite track (frame indices)
  • Transform tracks (position, rotation, scale)
  • Event track (calls Lua functions at specific times)
  • Onion skinning (semi-transparent previous/next frame)
  • Export to .caf animation asset

4.2 Tilemap Editor#

Editor de níveis 2D baseado em tiles:

  • Tile palette with drag-and-drop placement
  • Multiple layers (background, foreground, collision)
  • Auto-tiling (rule-based tile placement)
  • Bucket fill, erase, selection tools
  • Layer visibility and locking
  • Export to .caf tilemap asset

4.3 Material/Shader Editor#

  • Visual shader graph (nodes) ou editor de código HLSL/GLSL
  • Preview de shader em tempo real no viewport
  • Propriedades expostas editáveis (sliders, cores)
  • Compilação com feedback de erros
  • Biblioteca de shaders pré-definidos (unlit, lit, sprite, post-process)

4.4 Audio Preview & Spatial Placement#

  • Waveform preview no Inspector
  • Play/Stop no AssetBrowser
  • Spatial audio placement no SceneViewport (AudioSource gizmo)
  • Volume slider, pitch slider, falloff distance
  • Mixing desk: bus de áudio, volume por category (SFX, Music, Voice)

4.5 Build System Integration#

  • One-click "Build & Run"
  • Build configuration dialog (Debug/Release, platforms)
  • Build progress in ConsoleWindow
  • Post-build: open output directory
  • Build settings stored in project.caffeine

4.6 Prefab System#

  • Create prefab from entity (save as .prefab.caf)
  • Prefab instance: linked copy (updates propagate)
  • Prefab override: campos podem diferir da instância
  • Prefab nesting (prefab dentro de prefab)
  • AssetBrowser mostra prefabs com ícone distinto
  • Drag prefab do AssetBrowser → Viewport instancia

4.7 Entity Debugger#

Ferramenta de debug visual de entidades:

text
┌────────────────────────────────────────────┐
│  🔬 Entity Debugger                        │
├────────────────────────────────────────────┤
│  Entity: 142 (Hero)                        │
│  Archetype: [Transform, Sprite, RigidBody] │
│                                            │
│  Components:                               │
│  ✅ Transform    size: 28 bytes            │
│     └ pos: [120.0, 340.0]                 │
│  ✅ Sprite       size: 16 bytes            │
│  ✅ RigidBody2D  size: 32 bytes            │
│                                            │
│  Memory: 76 bytes total                    │
│  Queries matching: MovementSystem,         │
│                    RenderSystem, Physics    │
└────────────────────────────────────────────┘
  • Entity selector (pick from viewport)
  • Component list with memory size
  • Archetype info
  • Matching systems list
  • Component byte viewer (hex dump)

4.8 Extension/Plugin System#

  • Plugin loading from plugins/ directory
  • Plugin API: register panels, menu items, component drawers
  • Hot-reload de plugins (shared libraries)
  • Plugin marketplace UI (list available, install, update)
  • Example plugin: "Caffeine Script Editor" (embutido com syntax highlight)

Critério de Aceitação (M4)#

  • [ ] Animation Timeline permite criar keyframes e reproduzir
  • [ ] Onion skinning mostra frame anterior semi-transparente
  • [ ] Tilemap Editor coloca tiles em múltiplas camadas
  • [ ] Auto-tiling funciona com regras configuráveis
  • [ ] Material Editor permite alterar parâmetros de shader
  • [ ] Preview de shader compila e mostra resultado em tempo real
  • [ ] Audio preview toca som no AssetBrowser
  • [ ] Spatial audio gizmo mostra alcance no viewport
  • [ ] Build & Run compila o projeto e inicia o jogo
  • [ ] Prefab instancia com linked copy; alterações propagam
  • [ ] Entity Debugger mostra archetype e memória por componente
  • [ ] Plugin system carrega .dll/.so e regista novo painel

Dependências entre Milestones#

text
M1 ─────────────────────────────────────────────►
  │                                                  │
  ├── ECS Core (World, Entity, queries)          ✅  │
  ├── RHI (RenderDevice, CommandBuffer)           ✅  │
  ├── ImGuiIntegration                            ✅  │
  ├── BatchRenderer, Camera2D                     ✅  │
  ├── SceneSerializer                             ✅  │
  ├── AssetManager                                ✅  │
  └── ProfilerWindow, ConsoleWindow               ✅  │
                                                   │
M2 ─────────────────────────────────────────────►  │
  │                                                  │
  ├── M1 + SceneViewport                          🔲  │
  ├── AssetPipeline encoders                      ✅  │
  └── FileWatcher (AssetManager::pollFileChanges) ✅  │
                                                   │
M3 ─────────────────────────────────────────────►  │
  │                                                  │
  ├── M1                                           🔲  │
  ├── sol2 (Lua binding)                          ⬜  │
  └── Debug::LogSystem, Debug::DebugDraw          ✅  │
                                                   │
M4 ─────────────────────────────────────────────►  │
  │                                                  │
  ├── M1, M2, M3                                  🔲  │
  └── Animation ECS, Physics 2D                    ✅  │

Riscos & Mitigações#

Risco Impacto Probabilidade Mitigação
ImGui Docking não estável M1 atrasado Baixa Usar fallback manual layout
sol2 com C++20 complexo M3 atrasado Média Protótipo isolado antes de integrar
Gizmos matemáticos complexos M2 atrasado Média Usar ImGuizmo como base
Hot-reload de shaders instável M2 atrasado Alta Implementar fallback com shader default
Prefab serialização complexa M4 atrasado Média Começar com prefabs flat (sem nesting)
Plugin system cross-platform M4 atrasado Alta Windows-first, Linux/Mac depois

Estimativa de Esforço#

Milestone Ficheiros Ficheiros Novos Estimativa
M1 ~15 8 (.hpp + .cpp) 3–4 semanas
M2 ~10 5 2–3 semanas
M3 ~12 6 3–4 semanas
M4 ~20 12 4–6 semanas

Total estimado: 12–17 semanas (3–4 meses) para o Caffeine Studio IDE completo.


Referências#