4.6 Prefab System

[LyeZinho]

🔧 Prefab System

Milestone: M4 — Advanced Tools & Polish
Namespace: Caffeine::Editor
Arquivos: src/editor/PrefabSystem.hpp, src/editor/PrefabSystem.cpp
Status: 📅 Planeado
RF: RF6.6

---

Visão Geral

O Prefab System é uma ferramenta fundamental para a escalabilidade e reutilização de conteúdo no Caffeine Studio. Um "Prefab" (abreviatura de Prefabricated) é um modelo de entidade ou hierarquia de entidades que pode ser guardado como um asset (.prefab.caf) e instanciado múltiplas vezes em diferentes cenas.

A principal força deste sistema reside na sua natureza dinâmica: qualquer alteração feita no ficheiro original do Prefab propaga-se automaticamente para todas as suas instâncias na cena. No entanto, o sistema também suporta "Overrides", permitindo que instâncias específicas tenham valores de propriedades diferentes (ex: uma posição ou cor única) sem quebrar a ligação com o modelo base. O suporte para "Prefab Nesting" permite criar prefabs complexos a partir de prefabs mais simples (ex: um prefab de Carro que contém prefabs de Rodas).

---

Implementação

O sistema gere a relação entre o asset em disco e as entidades instanciadas através de um ID de ligação (PrefabID).

Estrutura do Sistema de Prefabs

namespace Caffeine::Editor {

struct PrefabOverride {
    UUID entityID;
    std::string componentName;
    std::string propertyName;
    std::variant<int, float, std::string, glm::vec3> value;
};

class PrefabInstanceComponent {
public:
    UUID prefabSourceID;
    std::vector<PrefabOverride> overrides;
    
    bool IsOverridden(const std::string& comp, const std::string& prop) const;
};

class PrefabManager {
public:
    // Criar um novo asset de prefab a partir de uma entidade existente
    static Ref<Prefab> CreateFromEntity(Entity entity, const std::string& path);
    
    // Instanciar um prefab na cena ativa
    static Entity Instantiate(Ref<Prefab> prefab, Scene* scene);
    
    // Aplicar alterações de uma instância de volta para o asset (Push changes)
    static void ApplyOverridesToPrefab(Entity instance);
    
    // Reverter uma instância para o estado original do asset
    static void RevertOverrides(Entity instance);

private:
    static void PropagateChanges(Ref<Prefab> prefab);
};

} // namespace Caffeine::Editor

Lógica de Propagação (Pseudo-C++)

void PrefabManager::PropagateChanges(Ref<Prefab> prefab) {
    auto activeScenes = Editor::GetActiveScenes();
    for (auto scene : activeScenes) {
        auto view = scene->m_registry.view<PrefabInstanceComponent>();
        for (auto entity : view) {
            auto& instance = view.get<PrefabInstanceComponent>(entity);
            if (instance.prefabSourceID == prefab->ID) {
                // Atualizar componentes, mantendo os overrides locais
                UpdateInstanceFromPrefab(entity, prefab, instance.overrides);
            }
        }
    }
}

Diagrama de Hierarquia e Overrides (ASCII)

┌─────────────────────────────────────────────────────────────┐
│ Scene Hierarchy                                             │
├─────────────────────────────────────────────────────────────┤
│ ▼ Scene_Main                                                │
│   ▸ Camera                                                  │
│   ▸ Light_Directional                                       │
│   ▼ [🟦] Prefab: Hero_Instance_01  (Linked)                 │
│     └─ [🔹] Transform  [pos: 10, 0] <-- OVERRIDDEN          │
│     └─ [🔹] Sprite     [id: hero_idle]                      │
│     └─ [🔹] Script     [path: player.lua]                   │
│   ▼ [🟦] Prefab: Enemy_Instance_A                           │
│     └─ [🔹] Transform  [pos: 50, 20]                        │
│     └─ [🔹] Sprite     [id: enemy_bat]                      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Inspector (Hero_Instance_01)                                │
├─────────────────────────────────────────────────────────────┤
│ [Prefab Controls]   [Revert All] [Apply to Prefab]          │
│                                                             │
│ [x] Transform                                               │
│     - Position: [ 10.0 ] [  0.0 ]  <-- (Texto a Negrito)    │
│ [ ] Sprite                                                  │
│     - Texture: [ hero_idle    ]  [v]                        │
└─────────────────────────────────────────────────────────────┘

---

Decisões de Design

Decisão	Justificativa
Gravação em Formato Binário	Otimiza o carregamento de grandes quantidades de instâncias durante o runtime.
Sistema de Overrides Granular	Permite personalização extrema sem perder a facilidade de manutenção global.
Prefab Nesting	Crucial para projetos complexos onde objetos são compostos por outros sub-objetos modulares.
Ícones Distintos na Hierarquia	Ajuda o utilizador a identificar rapidamente o que é um objeto único e o que é uma instância de um template.

---

Critério de Aceitação

• Criação de Prefabs a partir de qualquer entidade via drag-and-drop para o Asset Browser.
• Instanciação correta de Prefabs no Scene Viewport mantendo a hierarquia original.
• Deteção automática de alterações em propriedades e marcação como "Override".
• Botão "Apply" que guarda as alterações da instância no asset base.
• Botão "Revert" que descarta overrides locais e restaura os valores do asset.

---

Dependências

• Upstream: docs/ecs/scene.md (necessário para a gestão de entidades e componentes)
• Downstream: docs/editor/scene-editor.md (integração visual na hierarquia)

---

🔗 Tópicos Relacionados

Tópico	Descrição
ECS Core	Como as entidades e componentes são estruturados internamente.
Serialization	O processo de converter entidades em ficheiros YAML/Binário.
Asset Browser	Onde os ficheiros .prefab.caf são visualizados e geridos.

---

Referências

• Análise do sistema de Prefabs do Unity e Blueprint Classes do Unreal Engine.
• Padrão de design "Prototype" aplicado a sistemas de entidades.
• Técnicas de diff e merge de dados para reconciliação de overrides.