Organização do projeto e padrões de Blueprints para manutenção da lógica de gameplay

Por que organização e padrões importam em Blueprints

Em projetos com Blueprints, a manutenção costuma piorar quando a lógica fica espalhada, nomes não dizem o que são, e um Blueprint “faz tudo”. Organização do projeto e padrões de responsabilidade ajudam você a: localizar assets rapidamente, reduzir duplicação de lógica e dados, evitar dependências desnecessárias e tornar mudanças de gameplay mais seguras.

Estrutura de pastas recomendada (Content Browser)

Uma estrutura simples e consistente reduz tempo de busca e evita “assets perdidos”. Abaixo está um modelo inicial que funciona bem para projetos pequenos e médios.

Modelo de pastas

Content/ProjectName/ Blueprint/ Actors/ Components/ Interfaces/ Gameplay/ UI/ Widgets/ Audio/ SFX/ Music/ VFX/ Niagara/ Maps/ Data/ DataAssets/ Enums/ Materials/ Textures/

Passo a passo: criar e aplicar a estrutura

• No Content Browser, crie uma pasta raiz do projeto: Content/ProjectName.
• Crie as pastas principais: Blueprint, UI, Audio, VFX, Maps, Data.
• Dentro de Blueprint, separe por função (ex.: Actors, Components, Gameplay, Interfaces) em vez de separar por “qualquer coisa”.
• Mova assets existentes para as pastas corretas (arrastar e soltar). Quando o Unreal perguntar, confirme o “Fix Up Redirectors” depois.
• Após mover, clique com botão direito na pasta raiz do projeto e execute Fix Up Redirectors in Folder para evitar referências quebradas e lixo de redirecionamento.

Regra prática

Se você não sabe onde colocar um asset, crie uma subpasta por domínio (ex.: Gameplay/Items) e não por tipo genérico (ex.: “Misc”).

Convenções de nomes (prefixos e legibilidade)

Prefixos padronizados permitem identificar o tipo do asset sem abrir. Além disso, nomes consistentes ajudam em buscas e evitam duplicatas.

Prefixos recomendados

Regras de nomeação que evitam dor

• Use PascalCase após o prefixo: BP_PlayerCharacter.
• Evite nomes genéricos: em vez de BP_Manager, prefira BP_ScoreManager (ou melhor: um sistema adequado, não um “manager” genérico).
• Se houver variações, use sufixos claros: BP_Door_Sliding, BP_Door_Hinged.
• Para versões temporárias, use _WIP e remova depois: WBP_HUD_WIP.

Padrões de responsabilidade: quem deve fazer o quê

Um padrão de responsabilidade define onde a lógica vive e evita “efeito dominó” quando algo muda.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Evite lógica demais no Level Blueprint

O Level Blueprint é útil para scripts específicos daquele mapa (ex.: uma porta que abre quando um evento do mapa ocorre). Mas ele vira um problema quando concentra regras de gameplay, porque: é difícil reutilizar em outros mapas, aumenta dependências do nível e dificulta testes.

Alternativas práticas ao Level Blueprint

• Blueprint Actors para lógica que pertence a um objeto do mundo (porta, item, checkpoint, trigger).
• Actor Components para capacidades reutilizáveis (ex.: “pode ser interagido”, “tem vida”, “tem cooldown”).
• Blueprint Interfaces para contratos de comunicação sem acoplamento (ex.: “Interact”).
• Data Assets e Enums para dados e variações (ex.: tipos de item e valores) sem duplicar nós.

Checklist de responsabilidade (rápido)

• Se a lógica depende do mapa específico: pode ficar no Level Blueprint, mas mínima e bem comentada.
• Se a lógica é do objeto: fica no BP_ do objeto.
• Se a lógica é uma habilidade reutilizável: vira ActorComponent.
• Se a lógica é “dados + variação”: vira DA_ e/ou E_.

Reduzindo duplicação com Enums e Data Assets (exemplo de itens)

Duplicação comum: vários Blueprints de item com valores hardcoded (pontuação, cura, preço) e lógica repetida para aplicar efeito. Uma abordagem mais limpa é separar: tipo (Enum) e dados (Data Asset).

Passo a passo: criar um Enum simples de tipo de item

• Crie uma pasta: Content/ProjectName/Data/Enums.
• Crie um Blueprint Enum chamado E_ItemType.
• Adicione entradas, por exemplo: Health, Score, KeyItem.

Passo a passo: criar um Data Asset para dados do item

Você pode usar Data Assets para centralizar valores e evitar editar dezenas de Blueprints.

• Crie uma pasta: Content/ProjectName/Data/DataAssets.
• Crie um Primary Data Asset (ou Data Asset baseado em uma classe criada para isso) chamado DA_Item_HealthPotion.
• Campos sugeridos para o asset (exemplo):

ItemType: E_ItemType  DisplayName: Text  Icon: Texture2D  Value: Float (ex.: cura ou pontos)  SFX_OnUse: SoundBase (opcional)  VFX_OnUse: NiagaraSystem (opcional)

Com isso, o Blueprint do pickup (BP_ItemPickup) pode ter apenas uma variável ItemData (referência ao Data Asset) e usar os valores dela para exibir UI e aplicar efeito.

Padrão de uso no Blueprint do pickup

• Variável: ItemData do tipo DA_Item (sua classe de Data Asset).
• No BeginPlay (ou Construction Script, se fizer sentido): configurar mesh/ícone/nome com base em ItemData.
• No evento de uso/coleta: usar ItemData.ItemType para decidir o comportamento e ItemData.Value para aplicar o valor.

Mesmo sem entrar em detalhes de implementação de sistemas anteriores, a ideia é: o Blueprint fica genérico e os dados variam por Data Asset. Para criar um novo item, você cria um novo DA_ e aponta no pickup, sem duplicar Blueprint.

Quando usar Enum vs Data Asset

• Enum: lista pequena e estável de categorias/estados (tipo de item, raridade, estado de porta).
• Data Asset: dados editáveis por designers e variações (valores, ícones, efeitos, referências de áudio/VFX).

Padrões de Blueprint para legibilidade e manutenção

Organização visual do Graph

• Use Reroute Nodes para reduzir fios cruzando a tela.
• Separe blocos por “faixas” (Input → Validação → Execução → Feedback).
• Use Comments com títulos curtos e objetivos (ex.: “Validar referência do jogador”, “Aplicar efeito do item”).
• Prefira funções para trechos reutilizáveis e testáveis (ex.: ApplyItemEffect), evitando Graphs gigantes.

Evite dependências desnecessárias

• Evite referências diretas a muitos Blueprints específicos quando um contrato (interface) ou dado (Data Asset) resolve.
• Evite “pegar tudo no mundo” sem necessidade (ex.: múltiplos Get All Actors of Class em runtime). Se for inevitável, faça uma vez e cacheie.

Tarefa prática de limpeza (refatoração guiada)

Esta tarefa é para aplicar organização e reduzir acoplamento/duplicação. Faça em um branch/cópia do projeto para comparar antes/depois.

1) Revisar dependências e referências

• Escolha 3 Blueprints centrais (ex.: personagem, um item, um widget).
• Abra cada um e liste: quais Blueprints ele referencia diretamente (variáveis do tipo BP_*, casts, chamadas diretas).
• Pergunte: “isso precisa ser uma referência concreta ou pode ser interface/dado?”

2) Remover casts desnecessários

• Procure por sequências do tipo: Cast To BP_X logo após já ter uma referência do tipo BP_X.
• Se o cast só existe para acessar uma função que poderia ser contrato, substitua por chamada via BPI_ (quando aplicável).
• Se o cast é inevitável, centralize: faça o cast uma vez, valide, e reutilize a referência cacheada em vez de repetir casts em vários pontos.

3) Padronizar nomes e mover assets para as pastas corretas

• Renomeie assets fora do padrão (ex.: DoorBlueprint → BP_Door).
• Mova para a estrutura definida (Blueprint/UI/Audio/VFX/Maps/Data).
• Execute Fix Up Redirectors na pasta raiz do projeto.

4) Comentar fluxos críticos

Fluxos críticos são trechos que, se quebrar, o jogo “para” (interação, coleta, pontuação, respawn, UI principal). O objetivo é que outra pessoa entenda em 30 segundos.

• Adicione um comentário no início do fluxo explicando: o que dispara, o que valida, qual o efeito final.
• Em cada validação importante (ex.: referência nula), comente a intenção: “Evita aplicar efeito sem ItemData”.
• Se houver números mágicos (ex.: 25.0), substitua por variável com nome (ex.: HealAmount) ou mova para Data Asset.

5) Pequeno checklist de qualidade (antes de considerar “limpo”)

• O Level Blueprint do mapa tem apenas lógica específica do mapa (sem regras gerais de gameplay).
• Itens/variações são dados por DA_, não por duplicação de Blueprints.
• Enums são usados para categorias/estados simples e consistentes.
• Graphs têm comentários e blocos organizados, com poucas linhas cruzadas.
• Menos casts repetidos; referências cacheadas quando necessário.