🔧 Prefab System
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.