Scene Viewport Fix & Entity Type System Expansion
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Fix empty Scene Viewport by adding grid rendering and expand entity type system with Camera, Light, and Mesh components for professional game editor.
Architecture:
- Add grid drawing to SceneViewport using ImGui drawing lists
- Create camera component system (Camera2D, Camera3D)
- Create light component system (Directional, Point, Spot)
- Create mesh renderer component
- Add entity type selector in Hierarchy panel context menu
- Maintain compatibility with existing 2D entity system
Tech Stack: C++20, ECS (caffeine-core), ImGui, RHI (SDL3 optional)
Task 1: Add Grid Drawing to Scene Viewport#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(add grid drawing function) - Modify:
doppio-archived/src/doppio/editor/SceneViewport.hpp(add grid drawing method)
Step 1: Add grid drawing method declaration
In doppio-archived/src/doppio/editor/SceneViewport.hpp, add to private methods:
#ifdef CF_HAS_IMGUI
void drawGrid(ImDrawList* drawList, ImVec2 origin, ImVec2 viewportSize, const EditorContext& ctx);
#endif
Step 2: Implement grid drawing function
In doppio-archived/src/doppio/editor/SceneViewport.cpp, after the drawGizmo function, add:
void SceneViewport::drawGrid(ImDrawList* drawList, ImVec2 origin, ImVec2 viewportSize, const EditorContext& ctx) {
if (!m_config.grid) return;
f32 gridSpacing = m_config.gridSpacing;
f32 scale = ctx.viewportZoom * 50.0f;
f32 scaledSpacing = gridSpacing * scale;
f32 centerX = origin.x + viewportSize.x * 0.5f;
f32 centerY = origin.y + viewportSize.y * 0.5f;
f32 offsetX = ctx.viewportPanX * scale;
f32 offsetY = ctx.viewportPanY * scale;
ImU32 gridColor = IM_COL32(100, 100, 120, 80);
ImU32 axisColor = IM_COL32(200, 100, 100, 150);
if (scaledSpacing < 2.0f) return;
f32 startX = centerX - fmod(centerX - offsetX - origin.x, scaledSpacing) - scaledSpacing;
f32 startY = centerY - fmod(centerY - offsetY - origin.y, scaledSpacing) - scaledSpacing;
for (f32 x = startX; x < origin.x + viewportSize.x + scaledSpacing * 2; x += scaledSpacing) {
if (fabs(x - centerX) < 2.0f) {
drawList->AddLine(ImVec2(x, origin.y), ImVec2(x, origin.y + viewportSize.y), axisColor, 1.5f);
} else {
drawList->AddLine(ImVec2(x, origin.y), ImVec2(x, origin.y + viewportSize.y), gridColor, 0.5f);
}
}
for (f32 y = startY; y < origin.y + viewportSize.y + scaledSpacing * 2; y += scaledSpacing) {
if (fabs(y - centerY) < 2.0f) {
drawList->AddLine(ImVec2(origin.x, y), ImVec2(origin.x + viewportSize.x, y), axisColor, 1.5f);
} else {
drawList->AddLine(ImVec2(origin.x, y), ImVec2(origin.x + viewportSize.x, y), gridColor, 0.5f);
}
}
drawList->AddCircle(ImVec2(centerX, centerY), 8.0f, IM_COL32(255, 200, 0, 200), 12, 2.0f);
}
Step 3: Call grid drawing in render method
In doppio-archived/src/doppio/editor/SceneViewport.cpp, in the render() function after line 142 where gizmo text is drawn, add:
drawGrid(drawList, origin, viewportSize, ctx);
Full context (around line 142):
if (m_config.grid) {
char modeStr[16];
// ... existing code ...
drawList->AddText(ImVec2(origin.x + 8, origin.y + 8), IM_COL32(200, 200, 200, 200), buf);
}
drawGrid(drawList, origin, viewportSize, ctx); // ADD THIS LINE
if (ctx.selectedEntity.isValid() && hovered) {
drawGizmo(world, ctx, origin, viewportSize);
}
Step 4: Verify compilation
Run:
cd /home/pedro/repo/caffeine/build && cmake .. && make -j4 2>&1 | grep -E "error:|Built target doppio"
Expected: No errors, "Built target doppio" appears
Step 5: Commit
cd /home/pedro/repo/caffeine && git add src/editor/SceneViewport.hpp src/editor/SceneViewport.cpp && git commit -m "feat: add grid rendering to Scene Viewport
- Implement drawGrid() method for ImGui grid overlay
- Grid respects zoom and pan transformations
- Center axis highlighted in different color
- Grid spacing configurable via SceneViewport::Config"
Task 2: Create Camera Component System#
Files:
- Create:
src/caffeine/ecs/CameraComponents.hpp - Modify:
src/caffeine/ecs/Components.hpp(add include)
Step 1: Create Camera components header
Create src/caffeine/ecs/CameraComponents.hpp:
#pragma once
#include "core/Types.hpp"
#include "math/Vec3.hpp"
#include "math/Vec4.hpp"
namespace Caffeine::ECS {
using namespace Caffeine;
struct Camera2D {
f32 zoom = 1.0f;
f32 nearClip = 0.1f;
f32 farClip = 1000.0f;
};
struct Camera3D {
f32 fov = 60.0f;
f32 nearClip = 0.1f;
f32 farClip = 1000.0f;
f32 aspectRatio = 16.0f / 9.0f;
};
struct CameraActive {
bool is2D = true;
};
} // namespace Caffeine::ECS
Step 2: Include in Components.hpp
At the end of src/caffeine/ecs/Components.hpp before the closing namespace, add:
#include "ecs/CameraComponents.hpp"
Step 3: Verify it compiles
Run:
cd /home/pedro/repo/caffeine/build && make -j4 2>&1 | grep -E "error:|CameraComponents"
Expected: No errors
Step 4: Commit
cd /home/pedro/repo/caffeine && git add src/ecs/CameraComponents.hpp src/ecs/Components.hpp && git commit -m "feat: add Camera2D and Camera3D components
- Camera2D: zoom-based orthographic camera
- Camera3D: FOV-based perspective camera
- CameraActive: marker for active camera
- Both include near/far clip planes"
Task 3: Create Light Component System#
Files:
- Create:
src/caffeine/ecs/LightComponents.hpp - Modify:
src/caffeine/ecs/Components.hpp(add include)
Step 1: Create Light components header
Create src/caffeine/ecs/LightComponents.hpp:
#pragma once
#include "core/Types.hpp"
#include "math/Vec3.hpp"
#include "math/Vec4.hpp"
namespace Caffeine::ECS {
using namespace Caffeine;
struct Light {
Vec4 color = Vec4(1.0f, 1.0f, 1.0f, 1.0f);
f32 intensity = 1.0f;
};
struct DirectionalLight {
f32 shadowDistance = 100.0f;
bool castShadows = true;
};
struct PointLight {
f32 radius = 10.0f;
bool castShadows = false;
};
struct SpotLight {
f32 radius = 10.0f;
f32 angle = 45.0f;
bool castShadows = false;
};
} // namespace Caffeine::ECS
Step 2: Include in Components.hpp
At the end of src/caffeine/ecs/Components.hpp, add:
#include "ecs/LightComponents.hpp"
Step 3: Verify compilation
Run:
cd /home/pedro/repo/caffeine/build && make -j4 2>&1 | grep -E "error:|LightComponents"
Expected: No errors
Step 4: Commit
cd /home/pedro/repo/caffeine && git add src/ecs/LightComponents.hpp src/ecs/Components.hpp && git commit -m "feat: add Light components (Directional, Point, Spot)
- Light base component with color and intensity
- DirectionalLight: shadow distance and casting control
- PointLight: radius-based attenuation
- SpotLight: angle and radius for cone lighting"
Task 4: Create Mesh Renderer Component#
Files:
- Create:
src/caffeine/ecs/MeshComponents.hpp - Modify:
src/caffeine/ecs/Components.hpp(add include)
Step 1: Create Mesh components header
Create src/caffeine/ecs/MeshComponents.hpp:
#pragma once
#include "core/Types.hpp"
#include <string>
namespace Caffeine::ECS {
using namespace Caffeine;
struct MeshRenderer {
std::string meshPath;
std::string materialPath;
bool castShadows = true;
bool receiveShadows = true;
};
struct SkinnedMeshRenderer {
std::string meshPath;
std::string materialPath;
std::string skeletonPath;
bool castShadows = true;
bool receiveShadows = true;
};
} // namespace Caffeine::ECS
Step 2: Include in Components.hpp
At the end of src/caffeine/ecs/Components.hpp, add:
#include "ecs/MeshComponents.hpp"
Step 3: Verify compilation
Run:
cd /home/pedro/repo/caffeine/build && make -j4 2>&1 | grep -E "error:|MeshComponents"
Expected: No errors
Step 4: Commit
cd /home/pedro/repo/caffeine && git add src/ecs/MeshComponents.hpp src/ecs/Components.hpp && git commit -m "feat: add MeshRenderer components
- MeshRenderer: static mesh with material
- SkinnedMeshRenderer: animated mesh with skeleton
- Both support shadow casting and receiving"
Task 5: Add Entity Type Selector to Hierarchy Panel#
Files:
- Modify:
doppio-archived/src/doppio/editor/HierarchyPanel.cpp(expand entity creation menu) - Modify:
doppio-archived/src/doppio/editor/HierarchyPanel.hpp(add helper methods)
Step 1: Add helper methods to header
In doppio-archived/src/doppio/editor/HierarchyPanel.hpp, add to private section:
private:
void createEntityWithType(ECS::World& world, const char* name, const char* componentType);
Step 2: Implement helper in cpp
In doppio-archived/src/doppio/editor/HierarchyPanel.cpp, add before the onImGuiRender() function:
void HierarchyPanel::createEntityWithType(ECS::World& world, const char* name, const char* componentType) {
m_context->beginUndo(EditorCommand::AddEntity, u32_max, world);
ECS::Entity e = world.create();
setEntityName(world, e, name);
if (strcmp(componentType, "Camera2D") == 0) {
world.add<ECS::Camera2D>(e);
} else if (strcmp(componentType, "Camera3D") == 0) {
world.add<ECS::Camera3D>(e);
world.add<ECS::Position3D>(e);
world.add<ECS::Rotation3D>(e);
world.add<ECS::Scale3D>(e);
} else if (strcmp(componentType, "DirectionalLight") == 0) {
world.add<ECS::Light>(e);
world.add<ECS::DirectionalLight>(e);
} else if (strcmp(componentType, "PointLight") == 0) {
world.add<ECS::Light>(e);
world.add<ECS::PointLight>(e);
world.add<ECS::Position3D>(e);
} else if (strcmp(componentType, "SpotLight") == 0) {
world.add<ECS::Light>(e);
world.add<ECS::SpotLight>(e);
world.add<ECS::Position3D>(e);
world.add<ECS::Rotation3D>(e);
} else if (strcmp(componentType, "MeshRenderer") == 0) {
world.add<ECS::MeshRenderer>(e);
world.add<ECS::Position3D>(e);
world.add<ECS::Rotation3D>(e);
world.add<ECS::Scale3D>(e);
}
m_context->selectedEntity = e;
m_context->endUndo(world);
}
Step 3: Update renderEmptyContextMenu
In renderEmptyContextMenu(), replace the simple menu with:
void HierarchyPanel::renderEmptyContextMenu() {
if (ImGui::BeginPopupContextWindow("context_menu", ImGuiPopupFlags_MouseButtonRight)) {
if (ImGui::BeginMenu("Create Entity")) {
if (ImGui::MenuItem("Empty Entity")) {
m_context->beginUndo(EditorCommand::AddEntity, u32_max, *m_world);
ECS::Entity e = m_world->create();
setEntityName(*m_world, e, "New Entity");
m_context->selectedEntity = e;
m_context->endUndo(*m_world);
}
ImGui::Separator();
ImGui::TextDisabled("Camera");
if (ImGui::MenuItem("Camera 2D")) {
createEntityWithType(*m_world, "Camera 2D", "Camera2D");
}
if (ImGui::MenuItem("Camera 3D")) {
createEntityWithType(*m_world, "Camera 3D", "Camera3D");
}
ImGui::Separator();
ImGui::TextDisabled("Lights");
if (ImGui::MenuItem("Directional Light")) {
createEntityWithType(*m_world, "Directional Light", "DirectionalLight");
}
if (ImGui::MenuItem("Point Light")) {
createEntityWithType(*m_world, "Point Light", "PointLight");
}
if (ImGui::MenuItem("Spot Light")) {
createEntityWithType(*m_world, "Spot Light", "SpotLight");
}
ImGui::Separator();
ImGui::TextDisabled("Rendering");
if (ImGui::MenuItem("Mesh Renderer")) {
createEntityWithType(*m_world, "Mesh Renderer", "MeshRenderer");
}
ImGui::EndMenu();
}
ImGui::EndPopup();
}
}
Step 4: Verify compilation
Run:
cd /home/pedro/repo/caffeine/build && cmake .. && make -j4 2>&1 | grep -E "error:|undefined reference" | head -20
Expected: No errors
Step 5: Commit
cd /home/pedro/repo/caffeine && git add src/editor/HierarchyPanel.hpp src/editor/HierarchyPanel.cpp && git commit -m "feat: add entity type selector to Hierarchy panel
- Context menu now shows 'Create Entity' submenu
- Options: Empty, Camera 2D/3D, Directional/Point/Spot Light, Mesh Renderer
- Each type auto-populates required components
- 3D entities get Position3D, Rotation3D, Scale3D
- Lights get Light component plus type-specific components"
Task 6: Final Verification and Testing#
Files:
- No new files
Step 1: Full rebuild
Run:
cd /home/pedro/repo/caffeine/build && cmake .. && make clean && make -j4 2>&1 | tail -20
Expected: All targets build successfully, zero errors
Step 2: Launch doppio and verify viewport
Run:
cd /home/pedro/repo/caffeine/build && ./doppio
Expected:
- Scene Viewport shows grid with axis lines
- Grid responds to zoom (mouse wheel)
- Grid responds to pan (middle mouse drag)
- Right-click in Hierarchy → "Create Entity" menu appears
- Can create Camera 2D, Camera 3D, Lights, Mesh Renderer
Step 3: Test entity creation
In doppio:
- Right-click in Hierarchy panel
- Hover "Create Entity"
- Click "Camera 3D"
- Verify new entity appears in Hierarchy with "Camera 3D" name
- Select it → Inspector should show Camera3D and 3D transform components
Step 4: Commit verification
cd /home/pedro/repo/caffeine && git log --oneline | head -10
Expected: All 6 commits visible
Step 5: Final comprehensive test
Run:
cd /home/pedro/repo/caffeine/build && make -j4 2>&1 | grep -c "Built target"
Expected: All targets built (doppio, caffeine-core, CaffeineTest, DoppioTest)
Verification Checklist#
- [ ] Grid visible in Scene Viewport
- [ ] Grid zooms with mouse wheel
- [ ] Grid pans with middle mouse drag
- [ ] Entity creation menu accessible via right-click in Hierarchy
- [ ] Can create Camera 2D entity
- [ ] Can create Camera 3D entity (with 3D transforms)
- [ ] Can create Directional Light
- [ ] Can create Point Light
- [ ] Can create Spot Light
- [ ] Can create Mesh Renderer
- [ ] All new components appear in Inspector when entity selected
- [ ] No compilation errors
- [ ] No linker errors
- [ ] doppio executable runs without crashes
Execution Strategy#
This plan has 6 tasks, each taking 2-5 minutes:
- Grid rendering (SceneViewport)
- Camera components
- Light components
- Mesh components
- Entity type selector UI
- Verification
Estimated total time: 30-45 minutes
All tasks are independent compilation-wise (no circular dependencies) and should be committed individually.