🛠️ Caffeine Studio IDE — Plano de Desenvolvimento
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#
┌─────────────────────────────────────────────────────────────────┐
│ 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#
# 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/)
# 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 noCaffeinelibrary → mover paradoppioImGuiIntegrationdeixa de ser linked ao coreCF_HAS_IMGUIdefine apenas no targetdoppio- Headers do core que usam ImGui (
ImGuiIntegration.hppnos 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:
// 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
// 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:
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 manterCaffeine::Editorcomo 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#
CaffeineTestpassa a linkarcaffeine-core(não a library monolítica)- Testes de editor (se existirem) passam a
DoppioTestque linkadoppio - CI ganha dois jobs:
build-core(headless) ebuild-doppio(com SDL3)
Critério de Aceitação (T0)#
- [ ]
caffeine-corecompila sem ImGui e sem editor code - [ ]
caffeine-corecompila em modo headless (sem SDL3) - [ ]
doppiocompila e linkacaffeine-core+ ImGui - [ ] Testes core-only (
CaffeineTest) passam sem SDL3 - [ ]
DebugHookRegistrypermite IDE ligar-se ao core sem core conhecer IDE - [ ]
doppiosubstituicaffeine-studiocom mesma funcionalidade - [ ]
SceneEditorno doppio usaCaffeine::Core::DebugHookRegistrypara 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:
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:
┌─────────────────────────────────────────────────────────────┐
│ 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 SceneSerializerSceneEditor::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
.cafe limpa dirty flag - [ ] File > Open deserializa
.cafe 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):
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#
┌─────────────────────────────────────────────┐
│ ☕ 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.caffeineficheiro 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:
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#
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çãoonUpdate(entity, dt)— chamado todo frameonDestroy(entity)— chamado antes de destruiçãoonCollision(entity, other)— chamado ao colidir
3.3 Bindings ECS → 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
.luamodificado 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
.luano 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
.luasimples (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
.luarecarrega 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:
┌─────────────────────────────────────────────────────────────┐
│ 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
.cafanimation 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
.caftilemap 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:
┌────────────────────────────────────────────┐
│ 🔬 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/.soe regista novo painel
Dependências entre Milestones#
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#
docs/editor/scene-editor.md— Documentação atual do Scene Editordocs/ui/editor-ui.md— Embedded UI / ImGuiIntegrationdocs/ui/game-ui.md— UI System (game HUD)docs/scripting/scripting.md— Scripting (Lua)docs/assets/asset-pipeline.md— Asset Pipeline CLIdocs/ecs/core.md— ECS Coredocs/ecs/scene.md— Scene Manager / Serializerdocs/rendering/rhi.md— RHIdocs/debug/debug-tools.md— LogSystem, Profilerdocs/architecture_specs.md— Technical specifications- Dear ImGui Docking
- ImGuizmo — Gizmo library
- sol2 — Lua/C++ binding
- Lua 5.4 Manual