Caffeine

🔧 Drag-and-Drop

Planned Milestone: M2 — Visual Editing & Assets Namespace: `Caffeine::Editor` Arquivos: `doppio-archived/src/doppio/editor/DragDropSystem.hpp`, `doppio-archived/src/doppio/editor/DragDropSystem.cpp` RF: RF6.2 Last updated:

Visão Geral#

O sistema de Drag-and-Drop (Arrastar e Largar) é o principal facilitador de fluxo de trabalho no Caffeine Studio. Ele permite que os utilizadores interajam de forma fluida entre os diferentes painéis do editor, como o Asset Browser, o Viewport, o Inspector e o Hierarchy.

Esta funcionalidade visa reduzir o número de cliques necessários para tarefas comuns, como instanciar entidades, atribuir texturas a componentes ou reorganizar a hierarquia de uma cena. A implementação utiliza as APIs nativas do ImGui para gerir o estado de arrasto e os payloads de dados entre widgets.


Implementação#

O sistema baseia-se em DragSource (origem) e DropTarget (destino), identificados por strings de tipo únicas (ex: ASSET_BROWSER_ITEM).

Fluxos de Trabalho Principais#

  1. Asset Browser → Viewport: Cria uma nova entidade na posição do rato com um SpriteRenderer se o asset for uma imagem.
  2. Asset Browser → Inspector: Atribui um asset (Textura, Shader, Material) a um campo específico de um componente.
  3. Hierarchy → Hierarchy: Reorganiza a árvore ECS, alterando relações pai/filho.

Código de Exemplo (C++)#

cpp
namespace Caffeine::Editor {

    struct DragDropPayload {
        std::string Type;
        void* Data;
        size_t DataSize;
    };

    class DragDropManager {
    public:
        // Define um item como arrastável
        static void Source(const std::string& type, const void* data, size_t size, const std::string& previewText) {
            if (ImGui::BeginDragDropSource()) {
                ImGui::SetDragDropPayload(type.c_str(), data, size);
                ImGui::Text("%s", previewText.c_str());
                ImGui::EndDragDropSource();
            }
        }

        // Define uma área como recetora
        template<typename T>
        static T* Target(const std::string& type) {
            if (ImGui::BeginDragDropTarget()) {
                if (const ImGuiPayload* payload = ImGui::AcceptDragDropPayload(type.c_str())) {
                    return static_cast<T*>(payload->Data);
                }
                ImGui::EndDragDropTarget();
            }
            return nullptr;
        }
    };
}

Integração no Viewport#

cpp
// No loop de renderização do Viewport
if (AssetMetadata* asset = DragDropManager::Target<AssetMetadata>("ASSET_ITEM")) {
    if (asset->Type == AssetType::Texture) {
        Entity e = scene.CreateEntity(asset->Name);
        auto& sprite = e.AddComponent<SpriteRenderer>();
        sprite.Texture = asset->Handle;
        
        // Posicionar na coordenada do mundo correspondente ao rato
        auto& transform = e.GetComponent<Transform>();
        transform.Position = m_ViewportCamera.ScreenToWorld(ImGui::GetMousePos());
    }
}

Decisões de Design#

Decisão Justificativa
Preview Visual durante Drag Mostrar o nome ou ícone do asset junto ao cursor confirma ao utilizador o que está a ser movido.
Validação de Tipo no Destino O campo do Inspector só deve aceitar o "Drop" se o tipo do asset (ex: .png) for compatível com o campo (ex: Texture Slot).
Delayed Action O processamento do drop ocorre apenas no frame em que o botão do rato é solto, evitando operações pesadas durante o movimento.

Critério de Aceitação#

  • [ ] Arrastar uma textura do Asset Browser para o Viewport cria uma entidade com SpriteRenderer.
  • [ ] Arrastar um asset para um campo compatível no Inspector (ex: campo "Albedo") atualiza o valor do campo.
  • [ ] Arrastar uma entidade no Hierarchy para cima de outra torna-a filha desta última.
  • [ ] O cursor muda visualmente quando está sobre um destino válido.
  • [ ] Tentar largar um asset num destino incompatível não executa qualquer ação e mostra feedback visual negativo.

Dependências#

  • Upstream: Caffeine::Editor::AssetBrowser, Caffeine::Editor::Inspector
  • Downstream: Caffeine::ECS::HierarchySystem

🔗 Tópicos Relacionados#

Tópico Descrição
Asset Browser Fonte principal de itens para arrastar.
ECS Core Gestão de entidades criadas via drag-and-drop.

Referências#

  • Dear ImGui Drag and Drop API Documentation
  • UX patterns in Godot/Unity for asset placement.