Skip to main content

Writing a kit (UEAMCP internal guide)

Read this fully before adding tools. Everything here is enforced by code review.

Layout​

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>)

Module name: UeaKit<Name> (e.g. UeaKitBlueprint). Class: UUeaKit_<Name>. Kit name (short namespace): KitName() override, e.g. "bp".

Tool shape​

/** 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 (required): <kit>.<verb>_<object> in snake_case.
  • Mutates: any change to assets/level/settings. Wrapped in a transaction by the core.
  • Destructive: deletes or irreversible operations (also set Mutates).
  • MinEngine="5.1": hides the tool on older engines. Prefer this over compiling the tool out.
  • Exactly two parameters: const FArgs& and FReply& (out). Reply structs derive from FUeaReply (in UeaTypes.h). Report failure with Reply.Fail(UeaErr::NotFound, "...", "hint") and return; never throw, never check() on user input.
  • Every UPROPERTY gets a /** tooltip */ (it becomes the JSON schema description). meta=(Required) marks required inputs. Bool fields use the b prefix in C++ (bRecursive) and appear without it in JSON (recursive).
  • Vectors/rotators use FUeaVec3 (rotator = pitch, yaw, roll). Object references are strings resolved with UeaHelpers::LoadAssetLoose / ResolveClass / LoadBlueprintLoose.
  • Return rich replies: after a mutation return the new state (e.g. the variable list), so the agent does not need a second call.
  • Names: use FString in args (agents send text); convert to FName internally.

Engine compatibility (UE 4.27.2 → 5.8.2)​

  • C++17-compatible code only (do not set CppStandard in Build.cs; each engine uses its default). No <format>, <ranges>, concepts, designated initialisers.
  • No TObjectPtr in your code (raw pointers in USTRUCT/UCLASS members are fine on every version).
  • 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.
  • Before using any engine API, verify it exists with the same signature in BOTH tags of the engine clone D:\GameEngineProjects\Unreal\EpicGames\UnrealEngine: git show 4.27.2-release:Engine/Source/... and git show 5.8.2-release:Engine/Source/.... If it differs, add a macro/inline to UeaCompat.h or branch with #if UEA_ENGINE_AT_LEAST.
  • Enhanced Input on 4.27 lives in Engine/Plugins/Experimental/EnhancedInput; on 5.x in Engine/Plugins/EnhancedInput. Module name is EnhancedInput on both.
  • FKismetEditorUtilities::CreateBlueprint(ParentClass, Outer, Name, BPTYPE_Normal, UBlueprint::StaticClass(), UBlueprintGeneratedClass::StaticClass(), CallingContext) is the same on both. FBlueprintEditorUtils::AddMemberVariable/RemoveMemberVariable/RenameMemberVariable too.
  • 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.

Style​

  • Namespaced anonymous helpers inside the .cpp; no shared "tools helper" headers between kits.
  • No FJsonObject parsing in kits: the core converts JSON ↔ structs.
  • Log with UE_LOG(LogUEAMCP, ...) only for warnings; results go in the reply.
  • Comment blocks in English; copyright header // Copyright (c) 2026 MNZ Sistemas. All rights reserved.
  • Do not reference, copy or paraphrase code from D:\GameEngineProjects\Unreal\UltimateEngineCopilot. Use only engine headers and this repository.

Guide file​

Docs/guides/<kit>.md: what the kit does, a 5–10 step recipe for the common workflow, the gotchas (compile before use, names with spaces, etc.). Written for an AI agent, in English.