Caffeine

Transform Gizmos Implementation Plan

Historical Last updated:

For Claude: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task.

Goal: Implement Transform Gizmos (translate/rotate/scale) with axis-constrained dragging and snapping, supporting both 2D and 3D components.

Architecture: Dedicated TransformGizmo class owned by SceneViewport, using screen-space math for intersection testing and ImDrawList for rendering.

Tech Stack: C++20, ImGui (ImDrawList for gizmo rendering), ECS (Position2D/3D, Rotation/Rotation3D, Scale2D/Scale3D), SDL3 Input


Files#

  • Create: doppio-archived/src/doppio/editor/TransformGizmo.hpp
  • Create: doppio-archived/src/doppio/editor/TransformGizmo.cpp
  • Modify: doppio-archived/src/doppio/editor/SceneViewport.hpp (add member, refactor gizmo methods)
  • Modify: doppio-archived/src/doppio/editor/SceneViewport.cpp (integrate TransformGizmo)
  • Modify: src/caffeine/scene/EditorContext.hpp (already has GizmoMode/GizmoSpace enums)
  • Modify: CMakeLists.txt (add TransformGizmo.cpp)
  • Test: Manual verification in editor

Task 1: Create TransformGizmo.hpp#

Step 1: Write TransformGizmo.hpp

Create the header file with all type definitions and class declaration:

cpp
#pragma once
#include "core/Types.hpp"
#include "ecs/World.hpp"
#include "ecs/Entity.hpp"
#include "editor/EditorContext.hpp"

#ifdef CF_HAS_IMGUI
#include <imgui.h>
#endif

#include <glm/fwd.hpp>

namespace Caffeine::Editor {
namespace ECS = Caffeine::ECS;

class TransformGizmo {
public:
    TransformGizmo() = default;
    ~TransformGizmo() = default;

    void onImGuiRender(ECS::World& world, ECS::Entity entity, EditorContext& ctx);

private:
    // Input
    void handleInput(EditorContext& ctx);
    bool isKeyPressed(int key) const;

    // Rendering
    void renderTranslate(const glm::vec2& screenPos, float handleLen);
    void renderRotate(const glm::vec2& screenPos, float handleLen);
    void renderScale(const glm::vec2& screenPos, float handleLen);

    // 3D rendering (2.5D approach)
    void renderTranslate3D(const glm::vec2& screenPos, float handleLen, float rotation);
    void renderRotate3D(const glm::vec2& screenPos, float handleLen);
    void renderScale3D(const glm::vec2& screenPos, float handleLen);

    // Intersection testing
    GizmoAxis intersectTest(const glm::vec2& mousePos, const glm::vec2& screenPos, 
                            float handleLen, EditorContext::GizmoMode mode);

    // Transform application
    void applyTranslate(ECS::World& world, ECS::Entity entity, const glm::vec2& screenDelta, 
                       GizmoAxis axis, bool snapEnabled, float zoom);
    void applyRotate(ECS::World& world, ECS::Entity entity, float deltaX, bool snapEnabled);
    void applyScale(ECS::World& world, ECS::Entity entity, const glm::vec2& screenDelta,
                   GizmoAxis axis, bool snapEnabled, float zoom);

    // Snapping
    float applySnap(float value, float snapInterval);

    // Visual constants
    static constexpr float AXIS_LINE_LENGTH = 60.0f;
    static constexpr float AXIS_LINE_WIDTH = 3.0f;
    static constexpr float HANDLE_SIZE = 8.0f;
    static constexpr float HOVER_THRESHOLD = 8.0f;
    static constexpr float ARROW_SIZE = 8.0f;
    static constexpr float BOX_SIZE = 6.0f;

    // Colors (ImGui color format)
    static constexpr u32 COLOR_X_AXIS = IM_COL32(255, 50, 50, 255);
    static constexpr u32 COLOR_Y_AXIS = IM_COL32(50, 255, 50, 255);
    static constexpr u32 COLOR_Z_AXIS = IM_COL32(50, 100, 255, 255);
    static constexpr u32 COLOR_HOVERED = IM_COL32(255, 255, 50, 255);
    static constexpr u32 COLOR_DRAGGING = IM_COL32(255, 255, 255, 255);

    // Snap values
    float m_snapTranslate = 16.0f;  // pixels
    float m_snapRotate = 45.0f;     // degrees
    float m_snapScale = 0.5f;       // units

    // State
    GizmoAxis m_hoveredAxis = GizmoAxis::None;
    GizmoAxis m_dragAxis = GizmoAxis::None;
    bool m_isDragging = false;
    glm::vec2 m_dragStartMouse = {0.f, 0.f};
    glm::vec2 m_entityStartPos = {0.f, 0.f};
};
}

Step 2: Run diagnostics

Run: lsp_diagnostics on doppio-archived/src/doppio/editor/TransformGizmo.hpp

Expected: No errors (only potential warnings about unused includes - ignore those)

Step 3: Commit

bash
git add src/editor/TransformGizmo.hpp
git commit -m "feat(editor): add TransformGizmo header with types and declaration"

Task 2: Create TransformGizmo.cpp#

Step 1: Write TransformGizmo.cpp

Create the implementation file:

cpp
#include "editor/TransformGizmo.hpp"

namespace Caffeine::Editor {

void TransformGizmo::onImGuiRender(ECS::World& world, ECS::Entity entity, EditorContext& ctx) {
    if (!entity.isValid()) return;
    if (ctx.gizmoMode == EditorContext::GizmoMode::None) return;

    // Handle keyboard input
    handleInput(ctx);

    // Get entity position in world space
    glm::vec2 screenPos(0.f, 0.f);
    float entityRotation = 0.f;

    // Try 2D components first
    auto* pos2D = world.get<ECS::Position2D>(entity);
    if (pos2D) {
        ImVec2 vpSize = ImGui::GetContentRegionAvail();
        float worldToScreen = ctx.viewportZoom * 50.0f;
        screenPos.x = vpSize.x * 0.5f + (pos2D->x + ctx.viewportPanX / worldToScreen) * worldToScreen;
        screenPos.y = vpSize.y * 0.5f + (pos2D->y + ctx.viewportPanY / worldToScreen) * worldToScreen;
    }

    // Get rotation if available
    if (auto* rot = world.get<ECS::Rotation>(entity)) {
        entityRotation = rot->angle;
    }

    float handleLen = 30.0f * ctx.viewportZoom;

    // Get mouse position relative to viewport
    ImVec2 mousePos = ImGui::GetMousePos();

    // Render the appropriate gizmo based on mode
    switch (ctx.gizmoMode) {
        case EditorContext::GizmoMode::Translate:
            if (world.get<ECS::Position3D>(entity)) {
                renderTranslate3D(screenPos, handleLen, entityRotation);
            } else {
                renderTranslate(screenPos, handleLen);
            }
            break;
        case EditorContext::GizmoMode::Rotate:
            if (world.get<ECS::Position3D>(entity)) {
                renderRotate3D(screenPos, handleLen);
            } else {
                renderRotate(screenPos, handleLen);
            }
            break;
        case EditorContext::GizmoMode::Scale:
            if (world.get<ECS::Position3D>(entity)) {
                renderScale3D(screenPos, handleLen);
            } else {
                renderScale(screenPos, handleLen);
            }
            break;
        default: break;
    }

    // Test intersection and handle dragging
    if (ImGui::IsWindowFocused()) {
        m_hoveredAxis = intersectTest(mousePos, screenPos, handleLen, ctx.gizmoMode);

        // Handle drag start
        if (ImGui::IsMouseDown(ImGuiMouseButton_Left) && !m_isDragging) {
            if (m_hoveredAxis != GizmoAxis::None) {
                m_isDragging = true;
                m_dragAxis = m_hoveredAxis;
                m_dragStartMouse = mousePos;
                if (pos2D) {
                    m_entityStartPos = {pos2D->x, pos2D->y};
                }
            }
        }

        // Handle drag continue
        if (m_isDragging && ImGui::IsMouseDown(ImGuiMouseButton_Left)) {
            ImVec2 delta = {
                mousePos.x - m_dragStartMouse.x,
                mousePos.y - m_dragStartMouse.y
            };

            bool snapEnabled = isKeyPressed(ImGuiKey_LeftShift) || isKeyPressed(ImGuiKey_RightShift);

            switch (ctx.gizmoMode) {
                case EditorContext::GizmoMode::Translate:
                    applyTranslate(world, entity, delta, m_dragAxis, snapEnabled, ctx.viewportZoom);
                    break;
                case EditorContext::GizmoMode::Rotate:
                    applyRotate(world, entity, delta.x, snapEnabled);
                    break;
                case EditorContext::GizmoMode::Scale:
                    applyScale(world, entity, delta, m_dragAxis, snapEnabled, ctx.viewportZoom);
                    break;
                default: break;
            }

            ctx.isDirty = true;
        } else if (m_isDragging && !ImGui::IsMouseDown(ImGuiMouseButton_Left)) {
            m_isDragging = false;
            m_dragAxis = GizmoAxis::None;
        }
    }
}

void TransformGizmo::handleInput(EditorContext& ctx) {
    if (ImGui::IsKeyPressed(ImGuiKey_W)) ctx.gizmoMode = EditorContext::GizmoMode::Translate;
    if (ImGui::IsKeyPressed(ImGuiKey_E)) ctx.gizmoMode = EditorContext::GizmoMode::Rotate;
    if (ImGui::IsKeyPressed(ImGuiKey_R)) ctx.gizmoMode = EditorContext::GizmoMode::Scale;
    if (ImGui::IsKeyPressed(ImGuiKey_Q)) ctx.gizmoMode = EditorContext::GizmoMode::None;
}

bool TransformGizmo::isKeyPressed(int key) const {
    return ImGui::IsKeyDown(key);
}

void TransformGizmo::renderTranslate(const glm::vec2& screenPos, float handleLen) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    // X axis (red)
    u32 xColor = (m_hoveredAxis == GizmoAxis::X || m_dragAxis == GizmoAxis::X) ? COLOR_HOVERED : COLOR_X_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y), 
                ImVec2(screenPos.x + handleLen, screenPos.y), xColor, AXIS_LINE_WIDTH);
    dl->AddTriangleFilled(
        ImVec2(screenPos.x + handleLen + ARROW_SIZE, screenPos.y),
        ImVec2(screenPos.x + handleLen, screenPos.y - ARROW_SIZE * 0.6f),
        ImVec2(screenPos.x + handleLen, screenPos.y + ARROW_SIZE * 0.6f),
        xColor);

    // Y axis (green)
    u32 yColor = (m_hoveredAxis == GizmoAxis::Y || m_dragAxis == GizmoAxis::Y) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x, screenPos.y - handleLen), yColor, AXIS_LINE_WIDTH);
    dl->AddTriangleFilled(
        ImVec2(screenPos.x, screenPos.y - handleLen - ARROW_SIZE),
        ImVec2(screenPos.x - ARROW_SIZE * 0.6f, screenPos.y - handleLen),
        ImVec2(screenPos.x + ARROW_SIZE * 0.6f, screenPos.y - handleLen),
        yColor);
}

void TransformGizmo::renderRotate(const glm::vec2& screenPos, float handleLen) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    // Main circle
    u32 color = (m_hoveredAxis != GizmoAxis::None || m_dragAxis != GizmoAxis::None) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddCircle(ImVec2(screenPos.x, screenPos.y), handleLen, color, 32, AXIS_LINE_WIDTH);
    
    // Angle indicator line
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x + handleLen, screenPos.y), color, 2.0f);
}

void TransformGizmo::renderScale(const glm::vec2& screenPos, float handleLen) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    // X axis (red box)
    u32 xColor = (m_hoveredAxis == GizmoAxis::X || m_dragAxis == GizmoAxis::X) ? COLOR_HOVERED : COLOR_X_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x + handleLen, screenPos.y), xColor, AXIS_LINE_WIDTH);
    dl->AddRectFilled(ImVec2(screenPos.x + handleLen - BOX_SIZE, screenPos.y - BOX_SIZE),
                      ImVec2(screenPos.x + handleLen + BOX_SIZE, screenPos.y + BOX_SIZE), xColor);

    // Y axis (green box)
    u32 yColor = (m_hoveredAxis == GizmoAxis::Y || m_dragAxis == GizmoAxis::Y) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x, screenPos.y - handleLen), yColor, AXIS_LINE_WIDTH);
    dl->AddRectFilled(ImVec2(screenPos.x - BOX_SIZE, screenPos.y - handleLen - BOX_SIZE),
                      ImVec2(screenPos.x + BOX_SIZE, screenPos.y - handleLen + BOX_SIZE), yColor);
}

// 3D Gizmos (2.5D with Z axis)
void TransformGizmo::renderTranslate3D(const glm::vec2& screenPos, float handleLen, float rotation) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    // Calculate Z axis endpoint (going into screen at 45 degrees)
    float zOffset = handleLen * 0.7f;
    
    // X axis
    u32 xColor = (m_hoveredAxis == GizmoAxis::X || m_dragAxis == GizmoAxis::X) ? COLOR_HOVERED : COLOR_X_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x + handleLen, screenPos.y), xColor, AXIS_LINE_WIDTH);
    // X arrow
    dl->AddTriangleFilled(
        ImVec2(screenPos.x + handleLen + ARROW_SIZE, screenPos.y),
        ImVec2(screenPos.x + handleLen, screenPos.y - ARROW_SIZE * 0.6f),
        ImVec2(screenPos.x + handleLen, screenPos.y + ARROW_SIZE * 0.6f), xColor);

    // Y axis
    u32 yColor = (m_hoveredAxis == GizmoAxis::Y || m_dragAxis == GizmoAxis::Y) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x, screenPos.y - handleLen), yColor, AXIS_LINE_WIDTH);
    // Y arrow
    dl->AddTriangleFilled(
        ImVec2(screenPos.x, screenPos.y - handleLen - ARROW_SIZE),
        ImVec2(screenPos.x - ARROW_SIZE * 0.6f, screenPos.y - handleLen),
        ImVec2(screenPos.x + ARROW_SIZE * 0.6f, screenPos.y - handleLen), yColor);

    // Z axis (diagonal, going "into" screen)
    u32 zColor = (m_hoveredAxis == GizmoAxis::Z || m_dragAxis == GizmoAxis::Z) ? COLOR_HOVERED : COLOR_Z_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x - zOffset, screenPos.y + zOffset), zColor, AXIS_LINE_WIDTH);
    // Z arrow
    dl->AddTriangleFilled(
        ImVec2(screenPos.x - zOffset * 2.f, screenPos.y + zOffset * 2.f),
        ImVec2(screenPos.x - zOffset - ARROW_SIZE, screenPos.y + zOffset - ARROW_SIZE),
        ImVec2(screenPos.x - zOffset - ARROW_SIZE, screenPos.y + zOffset + ARROW_SIZE), zColor);
}

void TransformGizmo::renderRotate3D(const glm::vec2& screenPos, float handleLen) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    // X circle (vertical arc suggestion)
    u32 xColor = (m_hoveredAxis == GizmoAxis::X || m_dragAxis == GizmoAxis::X) ? COLOR_HOVERED : COLOR_X_AXIS;
    dl->AddCircle(ImVec2(screenPos.x, screenPos.y), handleLen, xColor, 32, AXIS_LINE_WIDTH * 0.8f);
    
    // Y circle (larger, slight offset to suggest depth)
    u32 yColor = (m_hoveredAxis == GizmoAxis::Y || m_dragAxis == GizmoAxis::Y) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddCircle(ImVec2(screenPos.x + 4, screenPos.y + 4), handleLen * 1.1f, yColor, 32, AXIS_LINE_WIDTH * 0.6f);
    
    // Z circle (smallest, suggesting forward direction)
    u32 zColor = (m_hoveredAxis == GizmoAxis::Z || m_dragAxis == GizmoAxis::Z) ? COLOR_HOVERED : COLOR_Z_AXIS;
    dl->AddCircle(ImVec2(screenPos.x - 3, screenPos.y - 3), handleLen * 0.9f, zColor, 32, AXIS_LINE_WIDTH * 0.6f);
}

void TransformGizmo::renderScale3D(const glm::vec2& screenPos, float handleLen) {
    ImDrawList* dl = ImGui::GetWindowDrawList();
    
    float zOffset = handleLen * 0.7f;
    
    // X axis with cube
    u32 xColor = (m_hoveredAxis == GizmoAxis::X || m_dragAxis == GizmoAxis::X) ? COLOR_HOVERED : COLOR_X_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x + handleLen, screenPos.y), xColor, AXIS_LINE_WIDTH);
    dl->AddRectFilled(ImVec2(screenPos.x + handleLen - BOX_SIZE, screenPos.y - BOX_SIZE),
                      ImVec2(screenPos.x + handleLen + BOX_SIZE, screenPos.y + BOX_SIZE), xColor);

    // Y axis with cube
    u32 yColor = (m_hoveredAxis == GizmoAxis::Y || m_dragAxis == GizmoAxis::Y) ? COLOR_HOVERED : COLOR_Y_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x, screenPos.y - handleLen), yColor, AXIS_LINE_WIDTH);
    dl->AddRectFilled(ImVec2(screenPos.x - BOX_SIZE, screenPos.y - handleLen - BOX_SIZE),
                      ImVec2(screenPos.x + BOX_SIZE, screenPos.y - handleLen + BOX_SIZE), yColor);

    // Z axis with cube
    u32 zColor = (m_hoveredAxis == GizmoAxis::Z || m_dragAxis == GizmoAxis::Z) ? COLOR_HOVERED : COLOR_Z_AXIS;
    dl->AddLine(ImVec2(screenPos.x, screenPos.y),
                ImVec2(screenPos.x - zOffset, screenPos.y + zOffset), zColor, AXIS_LINE_WIDTH);
    dl->AddRectFilled(ImVec2(screenPos.x - zOffset - BOX_SIZE, screenPos.y + zOffset - BOX_SIZE),
                      ImVec2(screenPos.x - zOffset + BOX_SIZE, screenPos.y + zOffset + BOX_SIZE), zColor);
}

GizmoAxis TransformGizmo::intersectTest(const glm::vec2& mousePos, const glm::vec2& screenPos,
                                        float handleLen, EditorContext::GizmoMode mode) {
    // Check center first (for uniform/free manipulation)
    float centerDist = glm::distance(mousePos, screenPos);
    if (centerDist < HOVER_THRESHOLD) {
        return GizmoAxis::Center;
    }

    // Check each axis
    float zOffset = handleLen * 0.7f;

    // X axis line test
    if (pointToLineDistance(mousePos, screenPos, 
        ImVec2(screenPos.x + handleLen, screenPos.y)) < HOVER_THRESHOLD) {
        return GizmoAxis::X;
    }

    // Y axis line test
    if (pointToLineDistance(mousePos, screenPos,
        ImVec2(screenPos.x, screenPos.y - handleLen)) < HOVER_THRESHOLD) {
        return GizmoAxis::Y;
    }

    // Z axis line test (for 3D modes)
    if (mode != EditorContext::GizmoMode::None) {
        if (pointToLineDistance(mousePos, screenPos,
            ImVec2(screenPos.x - zOffset, screenPos.y + zOffset)) < HOVER_THRESHOLD) {
            return GizmoAxis::Z;
        }
    }

    return GizmoAxis::None;
}

void TransformGizmo::applyTranslate(ECS::World& world, ECS::Entity entity, const glm::vec2& screenDelta,
                                     GizmoAxis axis, bool snapEnabled, float zoom) {
    // Convert screen delta to world delta
    float pixelsPerUnit = zoom * 50.0f;
    float worldDeltaX = screenDelta.x / pixelsPerUnit;
    float worldDeltaY = -screenDelta.y / pixelsPerUnit; // Y is inverted

    // Try 2D component
    auto* pos2D = world.get<ECS::Position2D>(entity);
    if (pos2D) {
        float newX = pos2D->x;
        float newY = pos2D->y;

        if (axis == GizmoAxis::X || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            newX += worldDeltaX;
            if (snapEnabled) newX = applySnap(newX, m_snapTranslate / pixelsPerUnit);
        }
        if (axis == GizmoAxis::Y || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            newY += worldDeltaY;
            if (snapEnabled) newY = applySnap(newY, m_snapTranslate / pixelsPerUnit);
        }

        pos2D->x = newX;
        pos2D->y = newY;
        return;
    }

    // Try 3D component
    auto* pos3D = world.get<ECS::Position3D>(entity);
    if (pos3D) {
        if (axis == GizmoAxis::X || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            float delta = worldDeltaX;
            if (snapEnabled) delta = applySnap(pos3D->x + delta, m_snapTranslate / pixelsPerUnit) - pos3D->x;
            pos3D->x += delta;
        }
        if (axis == GizmoAxis::Y || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            float delta = worldDeltaY;
            if (snapEnabled) delta = applySnap(pos3D->y + delta, m_snapTranslate / pixelsPerUnit) - pos3D->y;
            pos3D->y += delta;
        }
        if (axis == GizmoAxis::Z) {
            float delta = worldDeltaX * 0.5f; // Z movement on diagonal
            if (snapEnabled) delta = applySnap(pos3D->z + delta, m_snapTranslate / pixelsPerUnit) - pos3D->z;
            pos3D->z += delta;
        }
    }
}

void TransformGizmo::applyRotate(ECS::World& world, ECS::Entity entity, float deltaX, bool snapEnabled) {
    float deltaAngle = deltaX * 0.01f; // Sensitivity

    if (snapEnabled) {
        deltaAngle = applySnap(deltaAngle, glm::radians(m_snapRotate));
    }

    // Try 2D rotation
    auto* rot = world.get<ECS::Rotation>(entity);
    if (rot) {
        rot->angle += deltaAngle;
        return;
    }

    // Try 3D rotation
    auto* rot3D = world.get<ECS::Rotation3D>(entity);
    if (rot3D) {
        // Apply around Z axis (most common for 2D editors)
        // This is simplified - full 3D rotation would need proper quaternion handling
        // For now, accumulate into the quaternion
        // Note: Proper implementation would multiply quaternions
        (void)rot3D; // Placeholder for 3D rotation
    }
}

void TransformGizmo::applyScale(ECS::World& world, ECS::Entity entity, const glm::vec2& screenDelta,
                                GizmoAxis axis, bool snapEnabled, float zoom) {
    float pixelsPerUnit = zoom * 50.0f;
    float deltaX = screenDelta.x / pixelsPerUnit;
    float deltaY = -screenDelta.y / pixelsPerUnit;

    // Try 2D scale
    auto* scl2D = world.get<ECS::Scale2D>(entity);
    if (scl2D) {
        float factor = 1.0f;
        if (axis == GizmoAxis::X || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            factor = 1.0f + deltaX * 0.5f;
        }
        if (axis == GizmoAxis::Y || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            float yFactor = 1.0f + deltaY * 0.5f;
            factor = axis == GizmoAxis::Center ? (factor + yFactor) * 0.5f : yFactor;
        }

        if (axis == GizmoAxis::X || axis == GizmoAxis::None) {
            float newX = scl2D->x * factor;
            if (snapEnabled) newX = applySnap(newX, m_snapScale);
            scl2D->x = glm::max(0.01f, newX);
        }
        if (axis == GizmoAxis::Y || axis == GizmoAxis::None) {
            float newY = scl2D->y * factor;
            if (snapEnabled) newY = applySnap(newY, m_snapScale);
            scl2D->y = glm::max(0.01f, newY);
        }
        return;
    }

    // Try 3D scale
    auto* scl3D = world.get<ECS::Scale3D>(entity);
    if (scl3D) {
        if (axis == GizmoAxis::X || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            float newX = scl3D->x * (1.0f + deltaX * 0.5f);
            if (snapEnabled) newX = applySnap(newX, m_snapScale);
            scl3D->x = glm::max(0.01f, newX);
        }
        if (axis == GizmoAxis::Y || axis == GizmoAxis::Center || axis == GizmoAxis::None) {
            float newY = scl3D->y * (1.0f + deltaY * 0.5f);
            if (snapEnabled) newY = applySnap(newY, m_snapScale);
            scl3D->y = glm::max(0.01f, newY);
        }
        if (axis == GizmoAxis::Z) {
            float newZ = scl3D->z * (1.0f + deltaX * 0.5f);
            if (snapEnabled) newZ = applySnap(newZ, m_snapScale);
            scl3D->z = glm::max(0.01f, newZ);
        }
    }
}

float TransformGizmo::applySnap(float value, float snapInterval) {
    if (snapInterval <= 0.0f) return value;
    return glm::round(value / snapInterval) * snapInterval;
}

// Helper function - point to line segment distance
float pointToLineDistance(const glm::vec2& point, const glm::vec2& lineStart, const glm::vec2& lineEnd) {
    glm::vec2 lineDir = lineEnd - lineStart;
    float lineLengthSq = glm::dot(lineDir, lineDir);
    
    if (lineLengthSq < 0.0001f) {
        return glm::distance(point, lineStart);
    }

    float t = glm::dot(point - lineStart, lineDir) / lineLengthSq;
    t = glm::clamp(t, 0.0f, 1.0f);
    
    glm::vec2 projection = lineStart + t * lineDir;
    return glm::distance(point, projection);
}

} // namespace Caffeine::Editor

Step 2: Run diagnostics

Run: lsp_diagnostics on doppio-archived/src/doppio/editor/TransformGizmo.cpp

Expected: May need to include <glm/geometric.hpp> for glm::round and glm::clamp, or use std::round and manually clamp

Step 3: Fix any compilation issues

If glm::round or glm::clamp not found, change to:

cpp
#include <algorithm>
// And use std::round, std::clamp

Step 4: Commit

bash
git add src/editor/TransformGizmo.cpp
git commit -m "feat(editor): implement TransformGizmo class with translate/rotate/scale modes"

Task 3: Integrate TransformGizmo into SceneViewport#

Step 1: Modify SceneViewport.hpp

Add the TransformGizmo member:

cpp
#include "editor/TransformGizmo.hpp"

// In class SceneViewport, add to private section:
Editor::TransformGizmo m_Gizmo;

Step 2: Modify SceneViewport.cpp

Simplify the drawGizmo and handleGizmoInput methods to delegate to TransformGizmo, or remove them entirely and let TransformGizmo handle everything.

The key integration point is calling m_Gizmo.onImGuiRender(world, ctx.selectedEntity, ctx) where the old code had drawGizmo and handleGizmoInput.

Step 3: Run diagnostics

Run: lsp_diagnostics on doppio-archived/src/doppio/editor/SceneViewport.hpp and doppio-archived/src/doppio/editor/SceneViewport.cpp

Step 4: Commit

bash
git add src/editor/SceneViewport.hpp src/editor/SceneViewport.cpp
git commit -m "refactor(editor): integrate TransformGizmo into SceneViewport"

Task 4: Update CMakeLists.txt#

Step 1: Add TransformGizmo.cpp to build

cmake
# Find the line with src/ecs/World.cpp
# Add nearby:
src/editor/TransformGizmo.cpp

Step 2: Verify build

Run: cd build && cmake .. && make -j4 2>&1 | head -100

Expected: Build completes without errors related to TransformGizmo

Step 3: Commit

bash
git add CMakeLists.txt
git commit -m "build: add TransformGizmo.cpp to Caffeine library"

Task 5: Test and Verify#

Step 1: Build the project

bash
cd build && cmake .. && make -j4

Step 2: Run the editor (if there's a run target)

bash
./build/caffeine  # or whatever the executable is called

Step 3: Verify acceptance criteria

Manual testing checklist:

  • [ ] Press W - gizmo changes to Translate mode
  • [ ] Press E - gizmo changes to Rotate mode
  • [ ] Press R - gizmo changes to Scale mode
  • [ ] Hover over X axis - turns yellow
  • [ ] Hover over Y axis - turns yellow
  • [ ] Drag X axis - entity moves only on X
  • [ ] Drag Y axis - entity moves only on Y
  • [ ] Hold Shift + drag - snaps to grid
  • [ ] Entity transform updates in real-time during drag

Step 4: Commit final changes

bash
git add -A && git commit -m "feat(editor): complete Transform Gizmos implementation

- Add TransformGizmo class with translate/rotate/scale modes
- Support both 2D and 3D components
- Axis hover highlighting in yellow
- Shift key for snapping
- Real-time transform updates during drag

Closes #90"

Verification Checklist#

  • [ ] doppio-archived/src/doppio/editor/TransformGizmo.hpp exists and compiles
  • [ ] doppio-archived/src/doppio/editor/TransformGizmo.cpp exists and compiles
  • [ ] SceneViewport.hpp includes TransformGizmo
  • [ ] SceneViewport.cpp calls m_Gizmo.onImGuiRender()
  • [ ] CMakeLists.txt includes TransformGizmo.cpp
  • [ ] Build completes successfully
  • [ ] All acceptance criteria from spec pass

Notes#

  • The TransformGizmo class uses ImGui's ImDrawList for rendering, which is consistent with the existing editor architecture
  • Screen-space math for intersection testing keeps the implementation simple and avoids complex 3D math
  • The 3D gizmos use a "2.5D" approach with a visible Z axis at 45 degrees - proper 3D gizmos would require raycasting and depth testing
  • Snapping is applied in world space, converted from screen-space snap values