Pular para o conteúdo principal

Escrevendo um kit (guia interno do UEAMCP)

Leia este guia por completo antes de adicionar ferramentas. Tudo aqui é cobrado na revisão de código.

Estrutura​

Source/UeaKit<Name>/
  UeaKit<Name>.Build.cs             # regras do módulo (C++17, somente editor)
  Private/UeaKit<Name>Module.cpp    # IModuleInterface vazio + IMPLEMENT_MODULE
  Public/UeaKit_<Name>_Types.h      # USTRUCT de args/replies
  Public/UeaKit_<Name>.h            # UCLASS UUeaKit_<Name> : UUeaKit com as ferramentas
  Private/UeaKit_<Name>.cpp         # implementação
Docs/guides/<kit>.md                # guia de uso voltado ao agente (servido como uea://guide/<kit>)

Nome do módulo: UeaKit<Name> (ex.: UeaKitBlueprint). Classe: UUeaKit_<Name>. Nome do kit (namespace curto): override de KitName(), ex.: "bp".

Formato de uma ferramenta​

/** One-line description shown to the agent. Mention units, defaults and what it returns. */
UFUNCTION(meta = (UeaTool = "bp.add_variable", Mutates))
static void AddVariable(const FUeaBpAddVariableArgs& Args, FUeaBpVariableReply& Reply);
  • UeaTool (obrigatório): <kit>.<verbo>_<objeto> em snake_case.
  • Mutates: qualquer alteração em assets/nível/configurações. O core envolve a chamada em uma transação.
  • Destructive: exclusões ou operações irreversíveis (defina Mutates também).
  • MinEngine="5.1": oculta a ferramenta em engines mais antigas. Prefira isso a excluir a ferramenta da compilação.
  • Exatamente dois parâmetros: const FArgs& e FReply& (saída). Structs de reply derivam de FUeaReply (em UeaTypes.h). Reporte falhas com Reply.Fail(UeaErr::NotFound, "...", "hint") e retorne; nunca lance exceções, nunca use check() em entrada do usuário.
  • Toda UPROPERTY recebe um /** tooltip */ (ele vira a descrição no JSON schema). meta=(Required) marca entradas obrigatórias. Campos bool usam o prefixo b em C++ (bRecursive) e aparecem sem ele no JSON (recursive).
  • Vetores/rotators usam FUeaVec3 (rotator = pitch, yaw, roll). Referências a objetos são strings resolvidas com UeaHelpers::LoadAssetLoose / ResolveClass / LoadBlueprintLoose.
  • Retorne respostas ricas: após uma mutação, devolva o novo estado (ex.: a lista de variáveis), para que o agente não precise de uma segunda chamada.
  • Nomes: use FString nos args (agentes enviam texto); converta para FName internamente.

Compatibilidade de engine (UE 4.27.2 → 5.8.2)​

  • Somente código compatível com C++17 (não defina CppStandard no Build.cs; cada engine usa o seu padrão). Sem <format>, <ranges>, concepts ou designated initializers.
  • Sem TObjectPtr no seu código (ponteiros brutos em membros de USTRUCT/UCLASS funcionam em todas as versões).
  • Use UeaCompat.h: UEA_ENGINE_AT_LEAST(5,1), UEA_PIN_CATEGORY_FLOAT, UEA_ARFILTER_ADD_CLASS, UEA_ASSETDATA_OBJECT_PATH, UEA_IMPORT_TEXT / UEA_EXPORT_TEXT, FUeaReal.
  • Antes de usar qualquer API da engine, verifique que ela existe com a mesma assinatura em AMBAS as tags do clone da engine D:\GameEngineProjects\Unreal\EpicGames\UnrealEngine: git show 4.27.2-release:Engine/Source/... e git show 5.8.2-release:Engine/Source/.... Se houver diferença, adicione uma macro/inline em UeaCompat.h ou ramifique com #if UEA_ENGINE_AT_LEAST.
  • O Enhanced Input na 4.27 fica em Engine/Plugins/Experimental/EnhancedInput; na 5.x em Engine/Plugins/EnhancedInput. O nome do módulo é EnhancedInput em ambas.
  • FKismetEditorUtilities::CreateBlueprint(ParentClass, Outer, Name, BPTYPE_Normal, UBlueprint::StaticClass(), UBlueprintGeneratedClass::StaticClass(), CallingContext) é igual nas duas. FBlueprintEditorUtils::AddMemberVariable/RemoveMemberVariable/RenameMemberVariable também.
  • UEdGraphSchema_K2::PC_Float (4.27) vs PC_Real+PC_Double (5.x): use UEA_PIN_CATEGORY_FLOAT.
  • Asset registry FARFilter::ClassNames (4.27/5.0) vs ClassPaths (5.1+): UEA_ARFILTER_ADD_CLASS.
  • FAssetData::ObjectPath (≤5.0) vs GetSoftObjectPath() (5.1+): UEA_ASSETDATA_OBJECT_PATH.

Estilo​

  • Helpers anônimos com namespace dentro do .cpp; sem headers de "helpers de ferramentas" compartilhados entre kits.
  • Sem parsing de FJsonObject nos kits: o core converte JSON ↔ structs.
  • Faça log com UE_LOG(LogUEAMCP, ...) apenas para avisos; resultados vão na reply.
  • Blocos de comentário em inglês; cabeçalho de copyright // Copyright (c) 2026 MNZ Sistemas. All rights reserved.
  • Não referencie, copie ou parafraseie código de D:\GameEngineProjects\Unreal\UltimateEngineCopilot. Use somente os headers da engine e este repositório.

Arquivo de guia​

Docs/guides/<kit>.md: o que o kit faz, uma receita de 5–10 passos para o fluxo de trabalho comum e as pegadinhas (compilar antes de usar, nomes com espaços etc.). Escrito para um agente de IA, em inglês.