Saltar al contenido principal

Escribir un kit (guía interna de UEAMCP)

Lee esto completo antes de añadir herramientas. Todo lo que aparece aquí se exige en la revisión de código.

Estructura​

Source/UeaKit<Name>/
  UeaKit<Name>.Build.cs             # module rules (C++17, editor only)
  Private/UeaKit<Name>Module.cpp    # empty IModuleInterface + IMPLEMENT_MODULE
  Public/UeaKit_<Name>_Types.h      # USTRUCT args/replies
  Public/UeaKit_<Name>.h            # UCLASS UUeaKit_<Name> : UUeaKit with the tools
  Private/UeaKit_<Name>.cpp         # implementation
Docs/guides/<kit>.md                # agent-facing usage guide (served as uea://guide/<kit>)

Nombre del módulo: UeaKit<Name> (p. ej. UeaKitBlueprint). Clase: UUeaKit_<Name>. Nombre del kit (espacio de nombres corto): override de KitName(), p. ej. "bp".

Forma de una herramienta​

/** 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 (obligatorio): <kit>.<verb>_<object> en snake_case.
  • Mutates: cualquier cambio en assets/nivel/configuración. El núcleo lo envuelve en una transacción.
  • Destructive: eliminaciones u operaciones irreversibles (define también Mutates).
  • MinEngine="5.1": oculta la herramienta en motores más antiguos. Es preferible a excluirla de la compilación.
  • Exactamente dos parámetros: const FArgs& y FReply& (salida). Los structs de respuesta derivan de FUeaReply (en UeaTypes.h). Informa de un fallo con Reply.Fail(UeaErr::NotFound, "...", "hint") y retorna; nunca lances excepciones ni uses check() sobre la entrada del usuario.
  • Cada UPROPERTY lleva un /** tooltip */ (se convierte en la descripción del JSON schema). meta=(Required) marca las entradas obligatorias. Los campos bool usan el prefijo b en C++ (bRecursive) y aparecen sin él en el JSON (recursive).
  • Los vectores/rotadores usan FUeaVec3 (rotador = pitch, yaw, roll). Las referencias a objetos son strings que se resuelven con UeaHelpers::LoadAssetLoose / ResolveClass / LoadBlueprintLoose.
  • Devuelve respuestas completas: después de una modificación devuelve el nuevo estado (p. ej. la lista de variables), para que el agente no necesite una segunda llamada.
  • Nombres: usa FString en los argumentos (los agentes envían texto); conviértelos a FName internamente.

Compatibilidad con los motores (UE 4.27.2 → 5.8.2)​

  • Solo código compatible con C++17 (no definas CppStandard en Build.cs; cada motor usa su valor predeterminado). Nada de <format>, <ranges>, concepts ni inicializadores designados.
  • No uses TObjectPtr en tu código (los punteros crudos en miembros de USTRUCT/UCLASS funcionan en todas las versiones).
  • Usa 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 cualquier API del motor, verifica que existe con la misma firma en AMBOS tags del clon del motor D:\GameEngineProjects\Unreal\EpicGames\UnrealEngine: git show 4.27.2-release:Engine/Source/... y git show 5.8.2-release:Engine/Source/.... Si difiere, añade una macro/función inline a UeaCompat.h o bifurca con #if UEA_ENGINE_AT_LEAST.
  • Enhanced Input en 4.27 está en Engine/Plugins/Experimental/EnhancedInput; en 5.x, en Engine/Plugins/EnhancedInput. El nombre del módulo es EnhancedInput en ambos.
  • FKismetEditorUtilities::CreateBlueprint(ParentClass, Outer, Name, BPTYPE_Normal, UBlueprint::StaticClass(), UBlueprintGeneratedClass::StaticClass(), CallingContext) es igual en ambos. FBlueprintEditorUtils::AddMemberVariable/RemoveMemberVariable/RenameMemberVariable también.
  • UEdGraphSchema_K2::PC_Float (4.27) frente a PC_Real+PC_Double (5.x): usa UEA_PIN_CATEGORY_FLOAT.
  • FARFilter::ClassNames del asset registry (4.27/5.0) frente a ClassPaths (5.1+): UEA_ARFILTER_ADD_CLASS.
  • FAssetData::ObjectPath (≤5.0) frente a GetSoftObjectPath() (5.1+): UEA_ASSETDATA_OBJECT_PATH.

Estilo​

  • Helpers anónimos con namespace dentro del .cpp; sin headers compartidos de "tools helper" entre kits.
  • Nada de parsear FJsonObject en los kits: el núcleo convierte JSON ↔ structs.
  • Registra con UE_LOG(LogUEAMCP, ...) solo las advertencias; los resultados van en la respuesta.
  • Bloques de comentarios en inglés; cabecera de copyright // Copyright (c) 2026 MNZ Sistemas. All rights reserved.
  • No referencies, copies ni parafrasees código de D:\GameEngineProjects\Unreal\UltimateEngineCopilot. Usa solo los headers del motor y este repositorio.

Archivo de guía​

Docs/guides/<kit>.md: qué hace el kit, una receta de 5 a 10 pasos para el flujo de trabajo habitual y los detalles a tener en cuenta (compilar antes de usar, nombres con espacios, etc.). Escrito para un agente de IA, en inglés.