AI Agent Guide

Documentation Unreal Engine Combat AI Tutorial

Guide for AI agents: build a player and enemies from your own meshes and animations, including enemies that fight with action graph combos. How to hand the guide to your agent, the two ways it reaches the editor, and what to ask it, with the full guide below.


The plugin ships a guide written for an AI coding agent; the agent itself is not included, so use the one you already have. Hand it the guide with the editor open, and it builds a player and enemies from your own meshes and animations: the player's combos, dodge, weapon and lock-on, the enemies' weapons, reactions and bosses, and enemies that fight with combos from an action graph.
The guide is Resources/AGENTS.md in the plugin folder, and its full text is at the end of this page. It tells an agent such as Claude Code, Codex or Cursor how to reach your open Unreal Editor, what to ask you, and every step of each build, with checks along the way. Everything it makes is assets and Blueprints in your own folder, with no C++.

Set it up

2 minutes, then the build
  1. 1

    Open your project

    Open the project in the Unreal Editor and leave it open. The agent works in the running editor.
  2. 2

    Hand your agent the guide

    Do one of these in your agent's chat:
    • Drag AGENTS.md from the plugin's Resources folder into it.
    • Paste this page's link: https://rigbak.com/docs/universal-combat-framework/agents.
    • Type: "Read Resources/AGENTS.md in the UniversalCombatFramework plugin folder before you start".
    A plugin installed from Fab sits in your engine folder, under Engine/Plugins/Marketplace/.
  3. 3

    Say yes to the one-time setup

    On first use the agent offers to point your project at the guide, so later sessions find it without being handed it. With your OK it adds one line naming the guide to CLAUDE.md and to AGENTS.md in your project folder: Claude Code reads the first, Codex and Cursor the second. For Claude Code it also copies the ucf-agent skill into your project's .claude/skills folder, so typing /ucf-agent starts a later session on the guide.
  4. 4

    Ask for a player or an enemy

    Tell it what to build and where your assets are. It asks for anything it cannot work out from your asset names, builds step by step, and ends with a report of what it made and what it assumed.

How the agent reaches the editor

There are two ways in. The agent uses the Python bridge unless you ask for Epic's Unreal MCP, or your session already has it connected. Either way it asks your OK before it turns on a plugin or edits your project's config files, and tells you when the editor needs a restart.
RouteEngine versionsWhat it needs
Python bridge5.6, 5.7 and 5.8The engine's Python plugin and its remote execution, turned on in your project: two edits the agent makes, then one editor restart. The bridge itself, Resources/AgentBridge/run_in_editor.py, runs with the engine's own Python, so nothing gets installed.
Epic's Unreal MCP5.8The engine plugins ModelContextProtocol and AllToolsets turned on, their server starting with the editor, and an entry for it in your agent's MCP settings; then a restart of the editor and of the agent session. The plugin adds a toolset of its own, UCFAgentTools, for the steps Epic's tools do not cover.
Other Unreal MCP servers are not supported, even when your agent has one connected.
On either route the plugin's agent tools make montages, add notify windows to them, make a locomotion Animation Blueprint for a skeleton that has none, add blade sockets to a weapon mesh, and wire the moves of an action graph.

What it asks you

  1. What to build: a player, an enemy, or both, and whether an enemy should also fight with combos from an action graph.
  2. The mesh: the Skeletal Mesh of each character.
  3. The animations: a folder or a list. It sorts them by name into attacks in combo order, a heavy attack, a dodge, hit reactions, idle and locomotion, and asks when the order of a combo or which attack is light and which is heavy is unclear.
  4. An Animation Blueprint for each skeleton with a DefaultSlot Slot node. With none, it makes one from the plugin's locomotion template.
  5. A weapon mesh, if the character holds one. Without one, a player fights with its hands, and an enemy hits with its hands.
  6. The folder and name: /Game/Player/ for the player and /Game/Enemies/<Name>/ for an enemy, unless you say otherwise.
It creates everything in those folders and never edits the plugin's own content: to change a shipped asset, it duplicates it into your folder first. Outside them it adds blade sockets to your weapon mesh, sets the open level's GameMode Override to the player's game mode, and places enemies in the level you have open.

What to ask it

AskWhat you get
"Make a playable character called Knight from SKM_Knight."A character Blueprint on your mesh and a game mode that spawns it in the open level, moving with the camera following.
"Give it a light combo from Attack_01 to Attack_03, a heavy attack and a dodge."An action graph of the moves, with hit volumes on the hands and keys to press, and a dodge whose frames let enemy swings pass through.
"Build an enemy called DarkKnight from SKM_DarkKnight with the sword SM_Sword."An enemy that notices the player, keeps its distance, attacks by range, lands hits with its sword and flinches, placed in your level.
"Make DarkKnight fight with a three-hit combo from an action graph, locked on its target."An action graph of the enemy's three moves and an action that plays them as one combo, each move aimed at the player its AI is fighting.
"Make a boss version that switches moves at half health."A boss with more health, a role of its own, a moveset whose second half starts at half health, and an arena that opens the fight.
"How does an enemy pick its combos?"An answer from these docs, with the page's link.
A few steps are left to you, and the agent names them in its report, such as the health bar a boss fight shows on screen.

What ships with the plugin

FileWhat it is
Resources/AGENTS.mdThe guide, in full below.
Resources/AgentGuide/The guide's reference files, one per area of the enemy layer, the player layer and what crosses them, which the guide reads as it builds.
Resources/AgentBridge/run_in_editor.pyThe Python bridge: sends the agent's Python to the open editor and prints what the editor printed.
Resources/AgentSkills/ucf-agent/SKILL.mdThe /ucf-agent skill for Claude Code.
Content/Python/ucf_agent_toolsThe plugin's agent tools: Python helpers for montages, notify windows, blade sockets, a locomotion Animation Blueprint and action graphs, offered on Epic's MCP as the UCFAgentTools toolset.

The rest of this page is the guide as the plugin ships it. An agent handed this page's link reads it from here.

Universal Combat Framework: guide for AI agents

For the customer (an agent reading this file skips this block): an AI agent may not find this file on its own. Fab installs the plugin under the engine's Engine/Plugins/Marketplace/ folder. Tell the agent "Read Resources/AGENTS.md in the UniversalCombatFramework plugin folder before you start". The same text is at https://rigbak.com/docs/universal-combat-framework/agents. On first use, the agent offers to point the project at this file, so later sessions find it on their own.
Universal Combat Framework (UCF) is an Unreal Engine 5.6 to 5.9 plugin for both sides of a fight. The player gets combos built as action graphs, dodges, items that bring their own moves, weapon hit detection, lock-on and a combat camera. Enemies get souls-like AI: they notice the player, keep their distance, circle, pick attacks by range and timing, land hits through swept weapon traces and react to being hit. An enemy can also fight with an action graph combo, the same kind of move graph the player's moves live in. You build players and enemies from Blueprints, data assets and the customer's animations; no C++ is needed.
This file is written for an AI coding agent working in a customer's project while the Unreal Editor is open. Read all of it before you start. With the reference files in AgentGuide/ beside it, it is enough to build what it describes; do not search the plugin's source files.

One-time setup in a project

The first time this guide is used in a project, offer the customer this setup, which lets later sessions find the guide without being handed it. Make it only with their OK. It does not hold up the build: if they have not answered, build first and offer it again in your final report. Skip it when the project's CLAUDE.md or AGENTS.md already names this guide.
  1. Find the plugin folder, the one holding UniversalCombatFramework.uplugin: Plugins/UniversalCombatFramework in the project folder, or, when Fab installed the plugin into the engine, a folder under Engine/Plugins/Marketplace/ in the engine folder ("The Python bridge" below, step 1, finds the engine folder).
  2. Point the project at this guide. Add this line to CLAUDE.md and to AGENTS.md in the project folder, making a file that is missing, with the plugin folder written out (relative to the project folder when the plugin is inside it): For Universal Combat Framework, read <plugin folder>/Resources/AGENTS.md before building anything with it. Claude Code reads CLAUDE.md; Codex and Cursor read AGENTS.md.
  3. Claude Code only: the /ucf-agent command. Copy the folder <plugin folder>/Resources/AgentSkills/ucf-agent into the project's .claude/skills/ folder. Typing /ucf-agent in a later session then starts it on this guide.

Connecting to the editor

Everything below runs in the customer's open Unreal Editor. There are two ways in. Use the Python bridge unless the customer asks for Epic's Unreal MCP or this session already has it connected. Other Unreal MCP servers are not supported, even when one is connected.

The Python bridge (UE 5.6 to 5.9)

The plugin ships AgentBridge/run_in_editor.py in its Resources folder, beside this file. If this file reached you on its own, without the AgentBridge folder beside it, find the plugin folder ("One-time setup in a project", step 1) and use its Resources/AgentBridge. Run with the engine's own Python, it sends Python to the open editor and prints what the editor printed. It needs a shell and nothing installed.
  1. Read the project's .uproject. EngineAssociation is the engine version. For a version such as 5.7, the engine folder is the InstallLocation of the UE_5.7 entry in the launcher's LauncherInstalled.dat (JSON text despite its extension, so search it as text when a file reader refuses it): C:/ProgramData/Epic/UnrealEngineLauncher/LauncherInstalled.dat on Windows, usually naming C:/Program Files/Epic Games/UE_5.7, and ~/Library/Application Support/Epic/UnrealEngineLauncher/LauncherInstalled.dat on a Mac. A source-built engine, and every engine on Linux, which has no launcher, is an identifier in EngineAssociation that UnrealEngine/Install.ini lists under [Installations] with its folder, in ~/.config/Epic/ on Linux and ~/Library/Application Support/Epic/ on a Mac; on Windows the registry key HKEY_CURRENT_USER\Software\Epic Games\Unreal Engine\Builds lists it. When none of these names the folder, ask the customer.
  2. Check the connection:
    "<engine folder>/Engine/Binaries/ThirdParty/Python3/Win64/python.exe" "<plugin>/Resources/AgentBridge/run_in_editor.py" --project "<path to the .uproject>" -c "import unreal; print(unreal.SystemLibrary.get_engine_version())"
    
    It prints the engine version when it is connected. On a Mac the engine's Python is Engine/Binaries/ThirdParty/Python3/Mac/bin/python3, on Linux Engine/Binaries/ThirdParty/Python3/Linux/bin/python3. In PowerShell, put & and a space before the quoted python.exe path.
  3. Exit code 2 means no editor answered. If the editor is closed, ask the customer to open the project. If it is open, the project needs a one-time setup. The bridge runs on Epic's Python Editor Script Plugin, which the engine marks Beta and UCF itself does not need, so make these two edits only with the customer's OK, then ask them to restart the editor:
    • In the .uproject's Plugins list: { "Name": "PythonScriptPlugin", "Enabled": true }.
    • In Config/DefaultEngine.ini:
      [/Script/PythonScriptPlugin.PythonScriptPluginSettings]
      bRemoteExecution=True
Write each step's Python to a file and run it: ... run_in_editor.py --project "<path to the .uproject>" step.py. Exit code 1 means the Python raised; the traceback follows.
  • Names a run defines stay defined in the editor until it restarts. Run the setup block in "Driving the editor with Python" once per editor session, and again after a restart or a NameError.
  • The editor does nothing else while a run is going. Never wait or sleep inside the Python; start Play in one run and inspect it in the next.

Epic's Unreal MCP (UE 5.8 and 5.9)

Epic's Unreal MCP is two engine plugins, ModelContextProtocol and AllToolsets, which the engine marks Experimental and UCF itself does not need, so turn them on only with the customer's OK. Its tools are list_toolsets, describe_toolset and call_tool. To set it up, with that OK, make these edits, then ask them to restart the editor and this agent session:
  • In the .uproject's Plugins list: { "Name": "ModelContextProtocol", "Enabled": true } and { "Name": "AllToolsets", "Enabled": true }.
  • In Config/DefaultEditorPerProjectUserSettings.ini, so the server starts with the editor:
    [/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
    bAutoStartServer=True
  • The client entry, for Claude Code .mcp.json in the project root: { "mcpServers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }. Cursor reads the same shape from .cursor/mcp.json; Codex reads [mcp_servers.unreal-mcp] with url = "http://127.0.0.1:8000/mcp" from .codex/config.toml.
It runs no editor Python (its execute_tool_script only strings its own tools together in a sandbox), so use the tool table in "Driving the editor without Python". The plugin adds its own toolset, UCFAgentTools (list_toolsets names it ucf_agent_tools._toolset.UCFAgentTools; pass that name as toolset_name), for the steps Epic's tools do not cover.

The plugin's agent tools

On both routes the plugin's agent tools make montages, notify windows and the locomotion Animation Blueprint, add blade sockets to a weapon mesh, and wire the moves of an action graph. In Python they are the module ucf_agent_tools, which ships with the plugin; on the Epic route they are the tools of the same names in UCFAgentTools, which take their arguments as "Driving the editor without Python" says.

Before you start: ask the customer

Ask only what you cannot work out from asset names. State your assumptions in your final report so the customer can correct them.
A character they already have. A request to change the customer's player or one of their enemies ("give my player a dodge", "turn my knight into a boss") works on that character. Find it before building anything; build a new one only when there is none, and ask which one when there are several:
reg = unreal.AssetRegistryHelpers.get_asset_registry()
parents = {str(a.package_name): a.get_tag_value("NativeParentClass") or ""
           for a in reg.get_assets_by_path("/Game", recursive=True)}
players = [p for p, parent in parents.items() if parent.endswith(".UCFCharacterBase'")]
enemies = [p for p, parent in parents.items() if parent.endswith("EnemyCharacterBase'")]
print(players, enemies)
On Epic's MCP, list the customer's assets with AssetTools.find_assets and read each Blueprint's parent with BlueprintTools.get_parent. Then read what the character has and add to it, rebuilding nothing it already does. A player: the DefaultItem on its EquipmentManagerComponent, the StartingItems on its InventoryComponent, and their action graphs (ucf.describe_action_graph); a new move goes into the graph of the item it belongs to, a new weapon into the inventory's StartingItems. An enemy: its AIConfig and that config's sets; new attacks and reactions go into those sets.
  1. What to build. A player, an enemy, or both. An enemy fights with attacks its AI picks one at a time (Enemy Recipes 1 to 5), and can also play whole combos from an action graph (the Combo Enemy Recipe).
  2. The mesh of each character. The Skeletal Mesh asset path. Read its Skeleton from the mesh.
  3. The animations. A folder or a list. Sort them by name: for a player into light attacks (in combo order), heavy attack, dodge, hit reactions, idle and locomotion; for an enemy into attacks, hit reactions, dodge, idle and locomotion. Ask when the order of a combo, or which attack is light and which heavy, is unclear. An enemy needs no death animation: one built from Enemy Recipe 1 goes limp when it dies. Playing one instead is a Blueprint step on the enemy controller's On Death event; tell the customer.
  4. An Animation Blueprint for each skeleton, with a Slot node named DefaultSlot in its AnimGraph. If the customer has none, make one from the plugin's template ("No Animation Blueprint" below).
  5. A weapon mesh, if the character holds one. Without one, a player fights with its hands, and an enemy hits with its hands.
  6. The folder and name. Default: /Game/Player/ for the player and /Game/Enemies/<Name>/ for an enemy, with <Name> a short PascalCase name such as Knight or DarkKnight.

Rules

  • Create everything in the customer's folder. Do not edit or save anything under /UniversalCombatFramework/; duplicate a plugin asset into the customer's folder when you need to change it.
  • Level steps work in the level open in the editor. If that level is the plugin's own (its path starts with /UniversalCombatFramework/), ask the customer which of their levels to use, or make one in their folder.
  • Name assets <Prefix>_<Name>_<Purpose>. A player: BP_Knight, GM_Knight, ABP_Knight, AM_Knight_Light1, AG_Knight_Unarmed, Item_Knight_Unarmed, Item_Knight_Sword, IMC_Knight_Unarmed, Damage_Knight_Light. An enemy: BP_DarkKnight, AM_DarkKnight_Attack01, ActionSet_DarkKnight, ReactionSet_DarkKnight, EnemyConfig_DarkKnight, Awareness_DarkKnight, Damage_DarkKnight_Light, BP_DarkKnight_Sword, AG_DarkKnight_Combo.
  • Save each asset as soon as you finish it.
  • Check each step as described before you move on. A wrong value fails silently in several places; the checks catch it.
  • Use the exact property names in this file. set_editor_property accepts the C++ name (HeldMesh, bIsMainWeapon, SocketIDs) as well as the Python name. Several editor labels differ from the property: the Visuals fragment's Mesh is HeldMesh, a transition's Fires On is its trigger, When No Window Is Authored is ChainWithoutWindow, Main Weapon is bIsMainWeapon.
  • In Python, a C++ type drops its U, A, F or E prefix: UUCFItemDefinition is unreal.UCFItemDefinition, UEnemyAIConfig is unreal.EnemyAIConfig, FActionSpec is unreal.ActionSpec. Enum values are upper snake case: EUCFTraceShape::CapsuleTwoPoint is unreal.UCFTraceShape.CAPSULE_TWO_POINT. The engine's animation functions are unreal.AnimationLibrary.
  • An input tag on an item mapping, on a graph transition and in a combo's steps must match exactly. A parent tag does not count.
  • Make montages only from animations on the character's own skeleton, the one its mesh names. An animation of another skeleton plays with that skeleton's proportions, or not at all, and nothing warns: a player's attacks do not fit an enemy on another skeleton. When one does not match, ask the customer for the mesh's own animation or a retargeted copy.
  • An ability an enemy's action or reaction runs must reach End Ability on every path: completion, cancel and interrupt. The shipped GA_UCF_MontageAbility does; check any custom ability for it.
  • Give unreal.new_object the asset that will hold the object as its outer, never a class default object (unreal.get_default_object(...), defaults(...)), not even to look at a class's properties: a later object of that class with the same name takes it as its template, and the asset holding that object fails to save.

Driving the editor with Python

Run this once at the start of each Python session. Every later snippet uses it.
import unreal
import ucf_agent_tools as ucf
EAL = unreal.EditorAssetLibrary
ANIM = unreal.AnimationLibrary
TOOLS = unreal.AssetToolsHelpers.get_asset_tools()
DEMO = "/UniversalCombatFramework/Demo"
 
def load(path):
    obj = EAL.load_asset(path)
    if obj is None:
        raise RuntimeError(f"No asset at {path}")
    return obj
 
def bp_class(path):
    return EAL.load_blueprint_class(path)
 
def new_data_asset(cls, folder, name):
    factory = unreal.DataAssetFactory()
    factory.set_editor_property("DataAssetClass", cls)
    return TOOLS.create_asset(name, folder, cls, factory)
 
def duplicate(source_path, folder, name):
    return EAL.duplicate_asset(source_path, f"{folder}/{name}")
 
def defaults(bp):
    return unreal.get_default_object(bp.generated_class())
 
def bp_component(bp, name_start):
    sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
    lib = unreal.SubobjectDataBlueprintFunctionLibrary
    for handle in sds.k2_gather_subobject_data_for_blueprint(bp):
        obj = lib.get_associated_object(lib.get_data(handle))
        if obj and obj.get_name().startswith(name_start):
            return obj
    return None
 
def tag(name):
    t = unreal.GameplayTag()
    t.import_text(name)
    return t
 
def tags(*names):
    return unreal.GameplayTagLibrary.make_gameplay_tag_container_from_array([tag(n) for n in names])
 
def length(anim):
    return ANIM.get_sequence_length(anim)
 
def save(*assets):
    for a in assets:
        if not EAL.save_loaded_asset(a, False):
            raise RuntimeError(f"{a.get_path_name()} did not save; log_warnings('EditorErrors') says why")
 
def log_warnings(prefix="LogUCF"):
    name = unreal.Paths.get_base_filename(unreal.Paths.get_project_file_path())
    path = unreal.Paths.project_log_dir() + name + ".log"
    with open(path, encoding="utf-8", errors="ignore") as f:
        return [l.strip() for l in f if prefix in l and ("Warning" in l or "Error" in l)]
The agent tools you call through ucf:
CallDoes
ucf.create_montage_from_animation(animation, folder, name, enable_root_motion)Makes a montage on the DefaultSlot slot, turns the animation's root motion on unless enable_root_motion is False, saves both.
ucf.add_notify_state_to_montage(montage, notify_state_class, start_seconds, duration_seconds, track)Adds a notify window on the track named (Combat when left out) and returns it, so you can set its properties. Save the montage afterward.
ucf.create_locomotion_anim_blueprint(skeleton, folder, name, idle, walk, run)Makes an Animation Blueprint for a skeleton that has none, and saves it.
ucf.add_blade_sockets(static_mesh)Adds the TraceStart and TraceEnd sockets a blade trace sweeps between, saves the mesh, and says where they sit.
ucf.add_montage_node(graph, node_name, montage, play_rate)Adds a move to an action graph.
ucf.add_transition(graph, from_node, to_node, input_tag, fires_on, timing, priority)Wires an input from one move to another. fires_on, timing and priority can be left out.
ucf.compile_action_graph(graph)Compiles the graph; returns an empty string when it is clean, else one line per problem.
ucf.describe_action_graph(graph)Lists the compiled moves and transitions.
ucf.add_node, ucf.get_node_settings, ucf.set_node_settings, ucf.get_transition_settings, ucf.set_transition_settings, ucf.add_sub_graph, ucf.remove_node, ucf.remove_transitionOther kinds of moves, a move's or a transition's settings, sub graphs, removing: AgentGuide/Player/ActionGraphs.md.
ucf.set_montage_sections(montage, sections), ucf.add_gameplay_tag(tag, comment), ucf.validate_asset(asset)Montage sections, a new gameplay tag, an asset's own checks as text: AgentGuide/Player/Python.md.
Each call raises with a sentence saying what is wrong when it cannot do its job; read it and fix that before going on. log_warnings() is how you read UCF's setup warnings after a Play session. Each warning names the asset and the fix.

Driving the editor without Python (Epic Unreal MCP, UE 5.8 and 5.9)

Epic's MCP lists three tools: list_toolsets, describe_toolset and call_tool. Use describe_toolset to read the exact argument names. In call_tool, toolset_name is the name list_toolsets prints, such as editor_toolset.toolsets.asset.AssetTools, and tool_name is the tool's own name, such as find_assets. Map each Python step to these tools:
Python stepEpic Unreal MCP tool
load, find assetsAssetTools.find_assets, AssetTools.load_asset
duplicateAssetTools.duplicate
new_data_assetDataAssetTools.create
Blueprint with a parent classBlueprintTools.create (asset_type is the parent class)
defaults(bp) and setting class defaultsBlueprintTools.get_default_object, then ObjectTools.set_properties
Instanced objects (item fragments, execution methods, payloads, scorers, selectors)ObjectTools.set_properties with the class path, as below
Add a component to a BlueprintActorTools.add_component
saveAssetTools.save_assets
Play and lookEditorAppToolset.StartPIE, StopPIE, CaptureViewport
log_warningsLogsToolset.GetLogEntries, as below
ucf.*UCFAgentTools tools of the same names, given every argument ([] for no tags). A class is its path: add_notify_state_to_montage takes /Script/UCFCore.UCFMeleeTraceNotifyState and a track name (Combat), add_node takes /Script/UCFActions.UCFHoldActionPayload. set_montage_sections takes three lists in place of tuples: names, start seconds and next sections.
The property names and values in every step are the same on both routes. How Epic's tools take values:
  • An asset is its object path: the package path, a dot, and the asset name again, as in /Game/Player/AM_Knight_Light1.AM_Knight_Light1. The package path alone is refused.
  • A class is /Script/<Module>.<Name>, the C++ name without its first letter. The classes this guide uses are in these modules: UCFCore (damage configs, trace sockets, the melee trace, state tag, telegraph and anim effect windows, telegraph shapes, the gameplay event notify, vitals and teams), UCFMotion (the approach window), UCFActions (action graphs, the action window, transitions, input mappings, input steps, ability sets), UCFEquipment (item definitions and their fragments, hold places, the inventory, the equipment manager, the equip commit notify), UCFTargeting (targetable, combat styles, targeting configs), UCFFoundation (telegraph marker windows, the movement component), UCFGame (the character base), UCFEnemy (action and reaction sets, the AI config and the awareness config, movement profiles, execution methods, payloads, scorers, gates, selectors, the encounter trigger) and UCFBridge (the Action Graph Combo, UCF Enemy Character Base and its components, the UCF Enemy Loadout). For example /Script/UCFActions.UCFActionWindowNotifyState, /Script/UCFEquipment.UCFItemDefinition, /Script/UCFEnemy.ActionSet and /Script/UCFBridge.UCFActionGraphExecutionMethod.
  • An instanced object (an item fragment, an execution method, a payload, a scorer, a selector) is made by giving its class path as a plain string: {"Fragments": ["/Script/UCFEquipment.UCFItemFragment_Visuals", "/Script/UCFEquipment.UCFItemFragment_Equippable"]}, or {"TargetSelector": "/Script/UCFEnemy.AwarenessFilteredTargetSelector"}. Properties written beside the class path are dropped. Read the owner back with ObjectTools.get_properties, which gives each new object's path (.../Item_Knight_Sword.Item_Knight_Sword:UCFItemFragment_Visuals_0), and set its own properties on that path.
  • An array changes one way per ObjectTools.set_properties call: elements added or removed while every other element stays exactly as get_properties returned it, or elements changed at the same length. Keep an existing instanced element as {"refPath": "<its path>"}. A call refused as ambiguous does both at once; split it in two.
  • Log lines come from LogsToolset.GetLogEntries, which requires pattern, a regular expression, and reads only its own category unless category is empty: {"category": "", "pattern": "LogUCF[A-Za-z]*: (Warning|Error)"}.

What to build

  • A playable character: Player Recipe 1, then its combo (Player Recipe 2), a dodge (Player Recipe 3), a weapon with its own moves (Player Recipe 4) and lock-on (Player Recipe 5).
  • An enemy: Enemy Recipe 1, then its weapon (Enemy Recipe 2), more attacks and pacing (Enemy Recipe 3), reactions (Enemy Recipe 4) and a boss (Enemy Recipe 5).
  • An enemy that fights with action graph combos: the enemy and its weapon first (Enemy Recipes 1 and 2), then the Combo Enemy Recipe.
A player and enemies built here fight each other with nothing more to set up: the enemy's sight finds the player, the player's lock-on locks onto the enemy, and each side's hits land on the other.

Player Recipe 1: a playable character from the customer's mesh

Set these first:
F = "/Game/Player"                 # the customer's folder
N = "Knight"                       # the player's name
mesh = load("/Game/.../SKM_Knight")
abp = load("/Game/.../ABP_Knight") # the customer's Animation Blueprint, or the one "No Animation Blueprint" makes
probe = load("/Game/.../Attack_01")  # any animation on this skeleton, for bone checks

Step 1. Check the skeleton

Items are held at sockets or bones named hand_r (main hand) and hand_l (off hand).
for bone in ("hand_r", "hand_l"):
    print(bone, unreal.AnimationLibrary.does_bone_name_exist(probe, bone))
Check: both print True. If not, find the hand bones' names with the customer; Step 2 points the body places at them.

Step 2. Make the character Blueprint

Duplicate the demo player. It carries everything a player needs beyond the base class: camera, movement and look input, sprint, Motion Warping, physical reactions, telegraph markers and a starting ability set with lock-on, and its TeamComponent from the base class is set to the player's team (Team ID 0). Give it a copy of that ability set without the demo's parry recoil and stun:
bp = duplicate(f"{DEMO}/Characters/Player/BP_UCF_Character", F, f"BP_{N}")
abilities = duplicate(f"{DEMO}/Abilities/AbilitySet_UCF_Default", F, f"AbilitySet_{N}")
rows = [r for r in abilities.get_editor_property("GrantedGameplayAbilities")
        if r.get_editor_property("Ability").get_name() not in ("GA_UCF_ParryRecoil_C", "GA_UCF_PlayerStun_C")]
abilities.set_editor_property("GrantedGameplayAbilities", rows)
save(abilities)
 
d = defaults(bp)
d.set_editor_property("StartingAbilitySet", abilities)
body = d.get_editor_property("Mesh")
body.set_editor_property("SkeletalMeshAsset", mesh)
body.set_editor_property("AnimClass", abp.generated_class())
print(body.get_editor_property("ComponentTags"))       # must hold UCF.Montage and UCF.Attachment.Body
places = d.get_editor_property("EquipmentManagerComponent").get_editor_property("BodyPlaces")
for p in places:
    print(p.get_editor_property("Place"), p.get_editor_property("Socket"))
save(bp)
  • GA_UCF_ParryRecoil and GA_UCF_PlayerStun play the demo mannequin's recoil and stun montages, which would make the customer's character perform the demo's motion. The copy keeps lock-on, sprint, interact, drop and the flinch on a poise break (GA_UCF_HitReact, which plays no animation). Without them the copy is never stunned and does not stagger back from a parried blow. To bring a recoil back on the customer's own animation, make a child Blueprint of GA_UCF_ParryRecoil, set its StunMontage, and add it to the copy. A stun is a child of GA_UCF_Stun added the same way; the duplicate's UCF.Vital.Stance row already sends UCF.Event.GuardBreak as its DepletedGameplayEvent, which starts it when the stance runs out. The demo's own player stun also lists UCF.Style.Soulslike in its ActivationRequiredTags, so only the Soulslike style stuns the demo player; leave that list empty for a stun under every style.
  • UCF.Montage on the mesh is where montages play; UCF.Attachment.Body is where items attach. Without the attachment tag, items do not show. The duplicate keeps both.
  • BodyPlaces maps each place to a socket: UCF.Place.Main to hand_r, UCF.Place.Off to hand_l, and three back places to the mannequin's stow_back_r, stow_back_l and back_center_heavy sockets. It also carries the demo's worn gear places: UCF.Place.Head on head, UCF.Place.Ring.Left on ring_01_l, UCF.Place.Ring.Right on ring_01_r, UCF.Place.Shoulders on back_center_heavy, and UCF.Place.Chest, .Hands, .Feet and .Neck with no socket. Change a row's Socket if the customer's skeleton names those bones otherwise, and delete the worn rows a game does not use. The back places matter only for items that hang on the body, the worn places only for worn gear (AgentGuide/Player/ItemsEquipment.md, Worn gear).
  • The duplicate keeps the demo mannequin's mesh placement, which fits a character built like the UE5 mannequin (origin at the feet, facing +Y). If the character floats, sinks or faces sideways, adjust the Mesh component's RelativeLocation and RelativeRotation.
Check: capture the Blueprint viewport; the mesh stands inside the capsule, facing along the blue arrow.

Step 3. Make the game mode and use it

This step sets the GameMode Override of the level open in the editor to the new game mode, so Play spawns the customer's character. Make the change, then name the level in your final report: it is one setting of that level, which the customer can set back in its World Settings.
Make the game mode a child Blueprint of the demo's BP_UCF_GameMode rather than a duplicate: the duplicated player's death and the respawn key bring the player back only through a BP_UCF_GameMode. A project with its own game mode makes it a child of BP_UCF_GameMode too. On Epic's MCP, BlueprintTools.create makes the child, with asset_type /UniversalCombatFramework/Demo/Game/BP_UCF_GameMode.BP_UCF_GameMode_C.
factory = unreal.BlueprintFactory()
factory.set_editor_property("ParentClass", load(f"{DEMO}/Game/BP_UCF_GameMode").generated_class())
gm = TOOLS.create_asset(f"GM_{N}", F, unreal.Blueprint, factory)
defaults(gm).set_editor_property("DefaultPawnClass", bp.generated_class())
save(gm)
 
world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
world.get_world_settings().set_editor_property("DefaultGameMode", gm.generated_class())
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
The game mode keeps the demo's player controller, BP_UCF_PlayerController, which adds the movement keys (IMC_UCF_Default: move, look, sprint, lock-on, dash) and the belt of item slots. To use it in every level, the customer sets it in Project Settings, Maps and Modes.
Check: press Play. The character spawns, moves with the movement keys, and the camera follows. It has no attacks yet.

Player Recipe 2: a combo

A move is a node in an action graph. A node plays a montage; a transition names the input that leads from one node to the next. The graph reaches the character through an item: the item that drives combat hands its graph over while it is drawn. A character with nothing in its hands uses its Default Item, so a bare-handed combo lives on an "unarmed" item.
seqs = {"Light1": load("/Game/.../Attack_01"),
        "Light2": load("/Game/.../Attack_02"),
        "Light3": load("/Game/.../Attack_03"),
        "Heavy": load("/Game/.../Attack_Heavy")}

Step 1. Make a montage per attack

skeleton = mesh.get_editor_property("Skeleton")
other = [key for key, seq in seqs.items() if seq.get_editor_property("Skeleton") != skeleton]
if other:
    raise RuntimeError(f"{other} are animations of another skeleton than {mesh.get_name()}'s")
am = {key: ucf.create_montage_from_animation(seq, F, f"AM_{N}_{key}") for key, seq in seqs.items()}
The tool turns root motion on, so an attack that steps forward moves the player, and saves the montage. It plays on the DefaultSlot slot.
For an attack animation that stops on its strike pose, with no return to idle, set the montage's Blend Out to the fade length (the demo combos use 0.5 s) and Blend Out Trigger Time to 0. The montage then holds its last frame and fades to idle, and looks the same on every player's machine in multiplayer.
Check: no error. An animation of another skeleton stops the step: ask the customer for the mesh's own animation or a retargeted copy, as the Rules say.

Step 2. Make the damage configs

A Damage Config (UUCFDamageConfig) says what one hit is worth: its health damage, and a poise row for how hard it staggers.
def poise(amount):
    row = unreal.UCFVitalDamage()
    row.set_editor_property("VitalTag", tag("UCF.Vital.Poise"))
    row.set_editor_property("Amount", amount)
    return row
 
dmg_light = new_data_asset(unreal.UCFDamageConfig, F, f"Damage_{N}_Light")
dmg_light.set_editor_property("Damage", 10.0)
dmg_light.set_editor_property("AdditionalVitalDamage", [poise(20.0)])
dmg_heavy = new_data_asset(unreal.UCFDamageConfig, F, f"Damage_{N}_Heavy")
dmg_heavy.set_editor_property("Damage", 25.0)
dmg_heavy.set_editor_property("AdditionalVitalDamage", [poise(60.0)])
save(dmg_light, dmg_heavy)
The demo characters flinch only on the hit that empties their poise, so a config with no poise row never flinches them. 20 and 60 match the demo's punch and the sword's heavy swing; AgentGuide/Player/DamageDefense.md, Hit reactions, covers poise.

Step 3. Mark the montages

Two notify windows on each attack:
  • UCF Melee Trace Window (UUCFMeleeTraceNotifyState) over the frames that connect. Nothing takes damage without it. Without frame data from the customer, start it at 30% of the montage (40% for the heavy attack) and make it 25% long.
  • UCF Action Window (UUCFActionWindowNotifyState) where the next press may start the next attack. It has no settings. Put it on every attack that leads into another, from about 55% to 90%. A press made earlier waits for the window.
for key in ("Light1", "Light2", "Light3", "Heavy"):
    m, L = am[key], length(am[key])
    start = 0.40 if key == "Heavy" else 0.30
    w = ucf.add_notify_state_to_montage(m, unreal.UCFMeleeTraceNotifyState, L * start, L * 0.25)
    w.set_editor_property("SocketIDs", [])          # [] sweeps every socket the item registered
    w.set_editor_property("DamageConfig", dmg_heavy if key == "Heavy" else dmg_light)
    if key in ("Light1", "Light2"):
        ucf.add_notify_state_to_montage(m, unreal.UCFActionWindowNotifyState, L * 0.55, L * 0.35)
    save(m)
Tell the customer the times you picked; only a person can judge whether the window sits on the right frames.
Check: unreal.AnimationLibrary.get_animation_notify_events(am["Light1"]) lists both windows.

Step 4. Build the action graph

Every graph starts with a node named ROOT, the character standing idle. Add one node per move and wire the transitions. A move that ends with nothing leading on returns to ROOT by itself.
graph = new_data_asset(unreal.UCFActionGraphAsset, F, f"AG_{N}_Unarmed")
for key in ("Light1", "Light2", "Light3", "Heavy"):
    ucf.add_montage_node(graph, key, am[key], 1.0)
ucf.add_transition(graph, "ROOT", "Light1", "UCF.Input.LightAttack")
ucf.add_transition(graph, "Light1", "Light2", "UCF.Input.LightAttack")
ucf.add_transition(graph, "Light2", "Light3", "UCF.Input.LightAttack")
ucf.add_transition(graph, "ROOT", "Heavy", "UCF.Input.HeavyAttack")
print(ucf.compile_action_graph(graph))    # empty means no problems
print(ucf.describe_action_graph(graph))
save(graph)
Compile after the last edit and before saving: an edited graph keeps running its previous compile until then. Node names must be unique; ROOT is taken.
Transition triggers (fires_on, unreal.UCFTransitionTrigger):
ValueEditor labelFires when
ON_STARTEDInput PressedThe input is pressed. The default; combos use it.
ON_COMPLETEDInput ReleasedThe input is released.
ON_CANCELLEDInput Released EarlyThe input is released before a hold finishes.
AUTOAction CompletedThe move finished with nothing chaining. Pass "" as the input tag.
ON_FAILEDAction FailedThe move could not start. Pass "" as the input tag.
Timing (timing, unreal.UCFTransitionTiming): WAIT_FOR_WINDOW, the default, waits for the running move's action window; INTERRUPT cuts the running move at once, for a dodge or a parry.
Check: the describe output lists ROOT, the four moves with their montages, and each transition with its input tag.

Step 5. Make the unarmed item's keys

The item adds its own key mapping while drawn. Duplicate the demo unarmed mapping context:
imc = duplicate(f"{DEMO}/Weapons/Unarmed/IMC_UCF_Unarmed", F, f"IMC_{N}_Unarmed")
IMC_UCF_Unarmed already maps the left mouse button to IA_UCF_LightAttack, the right mouse button to IA_UCF_HeavyAttack, Q to IA_UCF_Guard and Space to IA_UCF_Dash, with gamepad keys for each, so the copy needs no new key. For a key the demo lacks, key = unreal.Key(), key.import_text("F"), imc.map_key(action, key), then save(imc).

Step 6. Make the unarmed item

An Item Definition (UUCFItemDefinition) is a list of fragments. The Equippable fragment (UUCFItemFragment_Equippable) makes it drawable and carries its graph, its keys and its hit volumes.
item = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Unarmed")
eq = unreal.new_object(unreal.UCFItemFragment_Equippable, outer=item)
eq.set_editor_property("ActionGraph", graph)
eq.set_editor_property("InputMappingContext", imc)
 
def mapping(action_name, tag_name):
    m = unreal.UCFInputMapping()
    m.set_editor_property("InputAction", load(f"{DEMO}/Inputs/{action_name}"))
    m.set_editor_property("InputTag", tag(tag_name))
    return m
 
eq.set_editor_property("InputMappings", [
    mapping("IA_UCF_LightAttack", "UCF.Input.LightAttack"),
    mapping("IA_UCF_HeavyAttack", "UCF.Input.HeavyAttack"),
    mapping("IA_UCF_Dash", "UCF.Input.Dash"),
])
 
def hand_socket(socket_id, bone):
    s = unreal.UCFTraceSocket()
    s.set_editor_property("ID", socket_id)
    s.set_editor_property("Shape", unreal.UCFTraceShape.SPHERE)
    s.set_editor_property("SocketOrBoneName", bone)
    s.set_editor_property("Radius", 12.0)
    return s                     # SourceComponentTag left empty: the socket follows the body mesh
 
eq.set_editor_property("TraceSockets", [hand_socket("HandR", "hand_r"), hand_socket("HandL", "hand_l")])
eq.set_editor_property("AttackStopDistance", 25.0)
item.set_editor_property("Fragments", [eq])
save(item)
  • AttackStopDistance is how close in front of a target this item's attacks stop, in centimeters between the two bodies. The duplicated player's combat style stops attacks 50 cm short, which suits a blade; at that distance a punch stops out of reach, so fists take about 25. One move with a shorter reach than the rest, such as a shield bash beside a sword, sets its own StopDistance on its Play Montage node (AgentGuide/Player/TargetingStylesSteering.md).
  • A new Equippable fragment already holds the main hand in HoldPlaces (UCF.Place.Main).
Check: reload the item and print each fragment's class, ActionGraph, the three mappings, the two sockets and AttackStopDistance.

Step 7. Give it to the character

d = defaults(bp)
d.get_editor_property("EquipmentManagerComponent").set_editor_property("DefaultItem", item)
d.get_editor_property("MeleeTraceComponent").set_editor_property("DefaultDamageConfig", dmg_light)
save(bp)
DefaultItem is what the character holds when nothing else is drawn.

Step 8. Play and check

les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
les.editor_request_begin_play()
Play starts once this run returns. Check it in the next run, a few seconds later:
game = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_game_world()
unreal.SystemLibrary.execute_console_command(game, "UCF.Debug.Actions 1")
pawn = unreal.GameplayStatics.get_player_pawn(game, 0)
graph_comp = pawn.get_component_by_class(unreal.UCFActionGraphComponent)
print(graph_comp.process_action_input(tag("UCF.Input.LightAttack"), unreal.UCFTransitionTrigger.ON_STARTED))
print(graph_comp.get_action_state())
unreal.AutomationLibrary.take_high_res_screenshot(1280, 720, f"{N}_combo.png")
les.editor_request_end_play()
print(log_warnings())
Success looks like: process_action_input reports the press as entered, the overlay above the character names Light1, and the first attack plays. Ask the customer to press light attack three times: the attacks chain in order and the character returns to idle after the third. Against a demo enemy, its punch stops at the second light hit, as its poise breaks. log_warnings() returns nothing about this character.

Player Recipe 3: a dodge

A dodge is a graph node like any attack, reached on its own input, whose montage holds i-frames: the tag UCF.State.Intangible, during which enemy swings pass through.
am_dodge = ucf.create_montage_from_animation(load("/Game/.../Roll_Back"), F, f"AM_{N}_Dodge")
L = length(am_dodge)
w = ucf.add_notify_state_to_montage(am_dodge, unreal.UCFStateTagNotifyState, L * 0.05, L * 0.50)
w.set_editor_property("Tags", tags("UCF.State.Intangible"))
save(am_dodge)
 
interrupt = unreal.UCFTransitionTiming.INTERRUPT
press = unreal.UCFTransitionTrigger.ON_STARTED
ucf.add_montage_node(graph, "Dodge", am_dodge, 1.0)
ucf.add_transition(graph, "ROOT", "Dodge", "UCF.Input.Dash")
for key in ("Light1", "Light2", "Light3", "Heavy"):
    ucf.add_transition(graph, key, "Dodge", "UCF.Input.Dash", press, interrupt, 10)
print(ucf.compile_action_graph(graph))
save(graph)
  • The dodge uses UCF.Input.Dash, which the unarmed item already maps to IA_UCF_Dash.
  • INTERRUPT lets the dodge cut a swing. A running move still keeps its first 0.1 seconds (Cancel Window Start on the node) before an interrupt fires.
  • A UCF melee trace skips a target holding UCF.State.Intangible (the trace's PassThroughTags default), so no other setting is needed.
  • Multiplayer detail: for a dodge that travels far and fast, also put UCF.State.Dashing in the same State Tag Window and set GraceTag = UCF.State.Dashing on the character's CharacterMovement (a UUCFCharacterMovementComponent), so the server accepts the dash's travel instead of pulling the player back.
To give the dodge a stamina cost or a cooldown, see AgentGuide/Player/GatesCostsHooks.md.
Check: in Play, pressing the dash key mid-swing cuts to the roll, and UCF.Debug.Actions 1 names the Dodge node.

Player Recipe 4: a weapon with its own moves

A weapon is an item with a look, its own graph, its own keys and hit volumes on its mesh.

Step 1. Sockets on the weapon mesh

A blade is traced by a two-point capsule between two sockets on its mesh, by default TraceStart (above the guard) and TraceEnd (the tip). Check, and add them when missing:
sword_mesh = load("/Game/.../SM_Sword")
for name in ("TraceStart", "TraceEnd"):
    print(name, sword_mesh.find_socket(name) is not None)
 
print(ucf.add_blade_sockets(sword_mesh))
This places TraceStart near the guard and TraceEnd near the tip, and saves the mesh. It changes the customer's mesh: tell them, and ask them to check the sockets sit on the blade when the grip is not at the mesh's origin.

Step 2. Montages, windows and graph

Repeat Player Recipe 2, Steps 1 to 4, with the weapon's animations: montages AM_<Name>_Sword_*, damage configs, windows, and a graph AG_<Name>_Sword kept in the variable sword_graph. Add the dodge node from Player Recipe 3 to this graph too: a drawn weapon's graph replaces the unarmed one, so moves the player keeps with a weapon in hand must be in the weapon's graph.

Step 3. The weapon's keys

imc_sword = duplicate(f"{DEMO}/Weapons/Sword/IMC_UCF_Sword", F, f"IMC_{N}_Sword")
save(imc_sword)
IMC_UCF_Sword maps keys to IA_UCF_LightAttack, IA_UCF_HeavyAttack and IA_UCF_Guard. The dash key needs no mapping here: the controller's IMC_UCF_Default maps Space to IA_UCF_Dash whatever the player holds, and the item's IA_UCF_Dash row in Step 4 routes it to the sword's graph.

Step 4. The weapon item

sword = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Sword")
vis = unreal.new_object(unreal.UCFItemFragment_Visuals, outer=sword)
vis.set_editor_property("HeldMesh", sword_mesh)          # editor label: Mesh
eq = unreal.new_object(unreal.UCFItemFragment_Equippable, outer=sword)
eq.set_editor_property("ActionGraph", sword_graph)
eq.set_editor_property("InputMappingContext", imc_sword)
eq.set_editor_property("InputMappings", [
    mapping("IA_UCF_LightAttack", "UCF.Input.LightAttack"),
    mapping("IA_UCF_HeavyAttack", "UCF.Input.HeavyAttack"),
    mapping("IA_UCF_Dash", "UCF.Input.Dash"),
])
blade = unreal.UCFTraceSocket()
blade.set_editor_property("ID", "Blade")
blade.set_editor_property("SourceComponentTag", "UCF.ItemMesh")
blade.set_editor_property("Shape", unreal.UCFTraceShape.CAPSULE_TWO_POINT)
blade.set_editor_property("SocketOrBoneName", "TraceStart")
blade.set_editor_property("EndSocketOrBoneName", "TraceEnd")
blade.set_editor_property("Radius", 8.0)
eq.set_editor_property("TraceSockets", [blade])
sword.set_editor_property("Fragments", [vis, eq])
save(sword)
  • An item with a Visuals HeldMesh and no ItemActorClass shows that mesh in the hand on a component tagged UCF.ItemMesh, which is why the blade socket's SourceComponentTag is UCF.ItemMesh. An empty tag would trace from the body mesh instead.
  • bIsMainWeapon (editor label Main Weapon) is on by default: the sword's graph takes over while it is drawn.
  • The item has no Stowable fragment, so it disappears when put away rather than hanging on the body. Stowing needs reach animations and back sockets on the customer's skeleton; see the Equipment page.

Step 5. Give it to the character

inv = defaults(bp).get_editor_property("InventoryComponent")
items = list(inv.get_editor_property("StartingItems"))
if sword not in items:
    items.append(sword)
inv.set_editor_property("StartingItems", items)
save(bp)
DefaultItem, what the character holds when nothing else is drawn, is the demo's unarmed item on the duplicated character until Player Recipe 2, Step 7 sets the customer's own. When Player Recipe 2 was not run, clear it, so the demo's moves do not stay on the character:
defaults(bp).get_editor_property("EquipmentManagerComponent").set_editor_property("DefaultItem", None)
save(bp)
The belt on BP_UCF_PlayerController takes the item into its first free slot and draws it, since nothing else is held. The slot keys in IMC_UCF_Default (1 to 4) draw and put away each slot.
Check: in Play, the sword sits in the right hand and the light attack plays the sword combo.
If the sword is held at the wrong angle, judge a correction from a capture and set it as the Offset of the Equippable fragment's UCF.Place.Main row in HoldPlaces. Python cannot set a Hold Places row's fields one by one, so write the whole row as text:
offset = unreal.Transform(unreal.Vector(0, 0, 0), unreal.Rotator(roll=0, pitch=0, yaw=90), unreal.Vector(1, 1, 1))
row = unreal.UCFHoldPlaceSpec()
row.import_text(f'(Place=(TagName="UCF.Place.Main"),Offset={offset.export_text()})')
eq.set_editor_property("HoldPlaces", [row])     # eq: the sword's Equippable fragment from Step 4
save(sword)

Player Recipe 5: lock-on

The duplicated character already locks on: its starting ability set (AbilitySet_<Name>, the copy of AbilitySet_UCF_Default from Player Recipe 1) grants the lock-on ability on UCF.Input.LockOn, and the demo controller maps the middle mouse button (gamepad: top face button) to IA_UCF_LockOn. Tell the customer the key.
  1. What can be locked. Any actor with a UCF Targetable component (UUCFTargetableComponent) that is not on the player's team. Every character built on the UCF character base has one. For another kind of enemy, add the component to its Blueprint; AimAtSocket names where the lock aims.
  2. How locked movement feels. The combat style decides. The duplicate uses the Over Shoulder style. For the Soulslike style's strafing around a locked target:
    d = defaults(bp)
    d.get_editor_property("CombatComponent").set_editor_property("Style", load(f"{DEMO}/Combat/Styles/CombatStyle_UCF_Soulslike"))
    save(bp)
  3. Range. The style's targeting config sets the scan radius (ScanRadius, 2000 cm) and whether a lock breaks with distance (LockBreakDistance, 0 turns it off). To change them, duplicate TargetingConfig_UCF_Soulslike and point the style's Targeting fragment at the copy, which means duplicating the style as well.
Check: place an enemy (the demo's BP_UCF_EnemyCharacter works) and play. Pressing the lock key holds the camera and facing on the enemy; the ability system carries UCF.State.LockedOn. Pressing again releases.

Enemy Recipe 1: an enemy from the customer's mesh and animations

Set these first:
F = "/Game/Enemies/DarkKnight"      # the customer's folder
N = "DarkKnight"                     # the enemy's name
mesh = load("/Game/.../SKM_DarkKnight")
seq_light = load("/Game/.../Attack_01")
seq_heavy = load("/Game/.../Attack_03")
seq_hit = load("/Game/.../Hit_Front")
abp = load("/Game/.../ABP_DarkKnight")   # the customer's Animation Blueprint, or the one "No Animation Blueprint" makes

Step 1. Check the skeleton

The weapon attaches to a bone or socket named hand_r unless you say otherwise.
print(ANIM.does_bone_name_exist(seq_light, "hand_r"))
Check: prints True. If not, find the right hand bone's name with the customer and set it as the UCF.Place.Main row's Socket in the Equipment Manager's BodyPlaces (Enemy Recipe 2).

Step 2. Make a montage per animation

UCF plays montages, not bare sequences. Make one for each attack, each hit reaction and the dodge, if there is one.
am_light = ucf.create_montage_from_animation(seq_light, F, f"AM_{N}_Light")
am_heavy = ucf.create_montage_from_animation(seq_heavy, F, f"AM_{N}_Heavy")
am_hit = ucf.create_montage_from_animation(seq_hit, F, f"AM_{N}_HitFront")
The tool turns root motion on for the sequence, so an attack that steps forward moves the enemy, and saves the montage. It plays on the DefaultSlot slot.
An attack animation that stops on its strike pose, with no return to idle, settles smoothly on every screen when its montage holds the last frame and fades out: set the montage's Blend Out to the fade length (the demo player's combo uses 0.5 s) and Blend Out Trigger Time to 0.
Check: length(am_light) is above 0.

Step 3. Make the damage config

A Damage Config (UUCFDamageConfig) says what one hit is worth. Six ship under /UniversalCombatFramework/Core/Damage/ (Damage_UCF_Slashing, _Piercing, _Bludgeoning, _Fire, _Ice, _Lightning). Make your own to set the amount:
dmg_light = new_data_asset(unreal.UCFDamageConfig, F, f"Damage_{N}_Light")
dmg_light.set_editor_property("Damage", 15.0)
dmg_light.set_editor_property("DamageTags", tags("UCF.Damage.Physical.Slashing"))
dmg_heavy = new_data_asset(unreal.UCFDamageConfig, F, f"Damage_{N}_Heavy")
dmg_heavy.set_editor_property("Damage", 30.0)
dmg_heavy.set_editor_property("DamageTags", tags("UCF.Damage.Physical.Slashing"))
save(dmg_light, dmg_heavy)

Step 4. Mark the strike frames on each attack montage

Two windows on each attack:
  • UCF Approach Window (UUCFApproachWindowNotifyState) over the wind-up. It turns the enemy to its target and glides it into reach, so an attack chosen from a few meters away still lands. Its defaults (Move And Face, toward Target) are right. Set its StopDistanceOverride: the gap in cm it leaves between the two bodies, which has to be shorter than the weapon reaches past the enemy's own body. About 40 suits a sword, one-handed or two-handed, and 20 fists; only a spear or a polearm takes more. Left at -1 it uses the approach component's 150, and a sword swings short of the target. Without the window the enemy swings from where it stands and misses.
  • UCF Melee Trace Window (UUCFMeleeTraceNotifyState) over the frames where the weapon connects. Nothing takes damage without it.
Without frame data from the customer, put the approach window from 10% to 30% of the montage and the trace window from 30% for 25% of its length; tell the customer the times you picked.
for am, dmg in ((am_light, dmg_light), (am_heavy, dmg_heavy)):
    L = length(am)
    a = ucf.add_notify_state_to_montage(am, unreal.UCFApproachWindowNotifyState, L * 0.10, L * 0.20)
    a.set_editor_property("StopDistanceOverride", 40.0)   # cm between the two bodies; fit it to the weapon
    w = ucf.add_notify_state_to_montage(am, unreal.UCFMeleeTraceNotifyState, L * 0.30, L * 0.25)
    w.set_editor_property("SocketIDs", ["Blade"])   # the weapon's trace socket ID; [] sweeps every registered socket
    w.set_editor_property("DamageConfig", dmg)
    save(am)
For an unarmed enemy, use the socket IDs from "Unarmed enemies" in Enemy Recipe 2.
Check: ANIM.get_animation_notify_events(am_light) lists two notify states, UCFApproachWindowNotifyState and UCFMeleeTraceNotifyState.

Step 5. Make the enemy Blueprint

Duplicate the demo enemy. It already carries what an enemy needs beyond the base class: a Motion Warping component, its controller, the baton it starts holding, Poise and Stance rows, its defense and physical reaction sets, and the abilities that stagger it.
bp = duplicate("/UniversalCombatFramework/Demo/Characters/Enemy/BP_UCF_EnemyCharacter", F, f"BP_{N}")
d = defaults(bp)
body = d.get_editor_property("Mesh")
body.set_editor_property("SkeletalMeshAsset", mesh)
body.set_editor_property("AnimClass", abp.generated_class())
d.set_editor_property("StartingAbilities", [])
d.get_editor_property("MeleeTraceComponent").set_editor_property("DefaultDamageConfig", dmg_light)
d.get_editor_property("CharacterMovement").set_editor_property("MaxWalkSpeed", 400.0)
save(bp)
  • StartingAbilities is emptied because the demo's stun and parry recoil (GA_UCF_Stun, GA_UCF_ParryRecoil) play the demo mannequin's montages, which would make the customer's character perform them. Without them a guard break or a parry does not stagger the enemy; a flinch on the customer's own animation comes from the Reaction Set in Step 7.
  • The duplicate keeps the demo's AI controller, BP_UCF_EnemyController, and its starting weapon. Enemy Recipe 2 replaces the weapon.
  • The duplicate keeps the demo mannequin's mesh placement, which fits a character built like the UE5 mannequin (origin at the feet, facing +Y). If the customer's character floats, sinks or faces sideways, adjust the Mesh component's RelativeLocation and RelativeRotation, and CapsuleHalfHeight and CapsuleRadius on CapsuleComponent.
Check: open the Blueprint's viewport, or capture it, and confirm the mesh stands inside the capsule facing along the blue arrow.

Step 6. Make the Action Set (the moveset)

An Action Set (UActionSet) holds the enemy's attacks in Actions, an array of FActionSpec. For each action set:
  • ActionId: a short unique name. An empty ID is dropped silently.
  • ExecutionMethod: a Gameplay Ability method (UUCFAbilityExecutionMethod) whose AbilityClass is the shipped GA_UCF_MontageAbility, with a Montage Payload (UUCFMontagePayload) whose Montage is the attack montage.
  • A Distance Scorer (UUCFDistanceScorer) in CustomScoring.Scorers. A new action has no scorers and fires at any distance, so every melee attack needs one.
montage_ability = bp_class("/UniversalCombatFramework/Core/Abilities/GA_UCF_MontageAbility")
 
def montage_method(owner, montage, play_rate=1.0):
    method = unreal.new_object(unreal.UCFAbilityExecutionMethod, outer=owner)
    method.set_editor_property("AbilityClass", montage_ability)
    payload = method.get_editor_property("Payload")
    if payload is None:
        payload = unreal.new_object(unreal.UCFMontagePayload, outer=method)
        method.set_editor_property("Payload", payload)
    payload.set_editor_property("Montage", montage)
    payload.set_editor_property("PlayRate", play_rate)
    return method
 
def range_scorer(owner, cls, min_v, opt_min, opt_max, max_v):
    scorer = unreal.new_object(cls, outer=owner)
    r = scorer.get_editor_property("Range")
    for key, v in (("MinValue", min_v), ("OptimalMin", opt_min), ("OptimalMax", opt_max), ("MaxValue", max_v)):
        r.set_editor_property(key, v)
    scorer.set_editor_property("Range", r)
    return scorer
 
def action(owner, action_id, montage, scorers, cooldown=0.0, weight=1.0, risk=1.0, play_rate=1.0, chain_to=None):
    spec = unreal.ActionSpec()
    spec.set_editor_property("ActionId", action_id)
    spec.set_editor_property("ExecutionMethod", montage_method(owner, montage, play_rate))
    scoring = spec.get_editor_property("CustomScoring")
    scoring.set_editor_property("Scorers", scorers)
    spec.set_editor_property("CustomScoring", scoring)
    spec.set_editor_property("SelectionWeight", weight)
    spec.set_editor_property("RiskPenalty", risk)
    cd = spec.get_editor_property("Cooldown")
    cd.set_editor_property("Duration", cooldown)
    spec.set_editor_property("Cooldown", cd)
    if chain_to:
        link = unreal.ActionChainLink()
        link.set_editor_property("TargetActionId", chain_to)
        link.set_editor_property("BonusMultiplier", 1.5)
        spec.set_editor_property("ChainLinks", [link])
    return spec
 
aset = new_data_asset(unreal.ActionSet, F, f"ActionSet_{N}")
aset.set_editor_property("Actions", [
    action(aset, "Light", am_light, [range_scorer(aset, unreal.UCFDistanceScorer, 0, 100, 250, 450)],
           cooldown=1.5, chain_to="Heavy"),
    action(aset, "Heavy", am_heavy, [range_scorer(aset, unreal.UCFDistanceScorer, 0, 150, 300, 500)],
           cooldown=5.0, weight=0.6, risk=1.5),
])
save(aset)
Setting AbilityClass on the method makes its Montage Payload by itself; montage_method only fills it.
What the numbers mean:
  • A Range scores 1 between OptimalMin and OptimalMax and falls to 0 at MinValue and MaxValue. Distances are in centimeters.
  • SelectionWeight under 1 and RiskPenalty over 1 make an action come up less often on its own.
  • The chain link makes Heavy score 50% higher for a short window after Light completes, so the enemy combos.
  • Each new action already holds UCF.State.IsMovementBlocked in AddTags, which stops the enemy walking while it swings. Leave it.
Check: reload with load(...) and print len(aset.get_editor_property("Actions")), each action's ActionId, and that its ExecutionMethod and payload Montage are set.

Step 7. Make the Reaction Set (the flinch)

A Reaction Set (UReactionSet) holds Reactions (FReactionSpec) and the TriggerRules (FUCFReactionTriggerRule) that pick one. A set with no trigger rules reacts to nothing.
rset = new_data_asset(unreal.ReactionSet, F, f"ReactionSet_{N}")
flinch = unreal.ReactionSpec()
flinch.set_editor_property("ReactionId", "Flinch")
flinch.set_editor_property("ExecutionMethod", montage_method(rset, am_hit))
cd = flinch.get_editor_property("Cooldown")
cd.set_editor_property("Duration", 1.5)
flinch.set_editor_property("Cooldown", cd)
 
rule = unreal.UCFReactionTriggerRule()
rule.set_editor_property("RuleId", "FlinchOnHit")
rule.set_editor_property("OnStimulus", tag("UCF.Stimulus.DamageTaken"))
link = unreal.UCFReactionTriggerLink()
link.set_editor_property("ReactionId", "Flinch")
rule.set_editor_property("ReactionLinks", [link])
rule.set_editor_property("Chance", 0.6)
 
rset.set_editor_property("Reactions", [flinch])
rset.set_editor_property("TriggerRules", [rule])
save(rset)
UCF.Stimulus.DamageTaken reaches the enemy because the duplicated demo Blueprint reports each hit it takes. A Blueprint made from Enemy Character Base directly does not; its Handle Incoming Damage must call Resolve Enemy Damage, a Blueprint edit the customer makes by hand.
Check: print the reaction's ReactionId and the rule's OnStimulus.

Step 8. Make the AI Config

An Enemy AI Config (UEnemyAIConfig) ties the sets together. Two fields ship empty and matter: TargetSelector and AwarenessConfig.
awareness = new_data_asset(unreal.UCFAwarenessConfig, F, f"Awareness_{N}")   # defaults: 1500 cm sight, 180 degree cone, 1200 cm hearing
movement = new_data_asset(unreal.MovementBehaviorProfile, F, f"Movement_{N}")
movement.set_editor_property("DesiredDistance", 300.0)
 
config = new_data_asset(unreal.EnemyAIConfig, F, f"EnemyConfig_{N}")
config.set_editor_property("TargetSelector", unreal.new_object(unreal.AwarenessFilteredTargetSelector, outer=config))
config.set_editor_property("AwarenessConfig", awareness)
config.set_editor_property("DefaultActionSet", aset)
config.set_editor_property("DefaultReactionSet", rset)
config.set_editor_property("DefaultMovementProfile", movement)
save(awareness, movement, config)
 
d = defaults(bp)
d.set_editor_property("AIConfig", config)
save(bp)
  • StateTree (shown as Default State Tree) stays empty, which runs UCF's built-in brain: notice, investigate, close in, circle, attack, react, plus patrol and the walk home once the placed enemy has territory posts (AgentGuide/Enemy/AwarenessTerritory.md). The demo's /UniversalCombatFramework/Demo/AI/StateTrees/ST_UCF_Core runs patrol, investigation, the fight and the walk home as a State Tree; set it only when the customer wants to edit the brain in the State Tree editor.
  • The awareness config does the sensing, and the filtered selector turns what the enemy sensed into its target. A player the enemy detects joins the target pool on its own, so the player Blueprint needs no change.
  • Sight skips actors on the enemy's own team. Enemies default to Team Id 1; a player with no UCF Team component counts as neutral and is seen.
Check: print config.get_editor_property("TargetSelector"); it is not None.

Step 9. Put it in a level

world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
has_nav = any(isinstance(a, unreal.NavMeshBoundsVolume) for a in actors.get_all_level_actors())
enemy = actors.spawn_actor_from_class(bp.generated_class(), unreal.Vector(800, 0, 100))
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
The enemy walks on a navmesh. If has_nav is False, spawn a NavMeshBoundsVolume over the floor and scale it to cover the play area, or ask the customer to add one. Navigation builds on its own in the editor.

Step 10. Play and check

les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
les.editor_request_begin_play()
Play starts once this run returns. Check it in the next run, a few seconds later:
game = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_game_world()
unreal.SystemLibrary.execute_console_command(game, "UCF.Debug.All 1")
unreal.AutomationLibrary.take_high_res_screenshot(1280, 720, f"{N}_check.png")
Then end Play and read the warnings:
les.editor_request_end_play()
print(log_warnings())
Success looks like: walking into the enemy's view turns its awareness line to Detected; it closes to about the movement profile's distance, circles, swings its light attack within range, sometimes follows with the heavy, flinches some of the time when hit, and a hit on the player lands. log_warnings() returns nothing about this enemy.
Ask the customer to play it too: only a person can judge whether the strike windows sit on the right frames. UCF.Debug.Melee.DrawTracing 1 draws each sweep.

Enemy Recipe 2: a weapon

An enemy holds an item, the same kind of item a player draws. Its UCF Equipment Manager draws it the way the player's character draws: the item hangs in the enemy's hand, its trace sockets sweep the enemy's hits, its Guard fragment lends its block and parry rules, and it drops as an item a player can pick up when the enemy dies. The enemy's UCF Enemy Loadout (Loadout) lists what it starts holding and which moves its AI takes for each item.
To hand the enemy an item that already exists, go to Step 3 with it: the demo's baton ({DEMO}/Weapons/TwoHanded/Item_UCF_TwoHandedBaton), the demo's sword ({DEMO}/Weapons/Sword/Item_UCF_Sword), or one made by Player Recipe 4.

Step 1. Sockets on the weapon mesh

A blade is traced by a two-point capsule between two sockets on its mesh, by default named TraceStart (above the guard) and TraceEnd (the tip). Check, and add them when missing:
sword_mesh = load("/Game/.../SM_Sword")
for name in ("TraceStart", "TraceEnd"):
    print(name, sword_mesh.find_socket(name) is not None)
 
print(ucf.add_blade_sockets(sword_mesh))
This places TraceStart near the guard and TraceEnd near the tip, and saves the mesh. It changes the customer's mesh: tell them, and ask them to check the sockets sit on the blade when the grip is not at the mesh's origin.

Step 2. The weapon item

sword = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Sword")
vis = unreal.new_object(unreal.UCFItemFragment_Visuals, outer=sword)
vis.set_editor_property("HeldMesh", sword_mesh)          # editor label: Mesh
eq = unreal.new_object(unreal.UCFItemFragment_Equippable, outer=sword)
blade = unreal.UCFTraceSocket()
blade.set_editor_property("ID", "Blade")
blade.set_editor_property("SourceComponentTag", "UCF.ItemMesh")
blade.set_editor_property("Shape", unreal.UCFTraceShape.CAPSULE_TWO_POINT)
blade.set_editor_property("SocketOrBoneName", "TraceStart")
blade.set_editor_property("EndSocketOrBoneName", "TraceEnd")
blade.set_editor_property("Radius", 8.0)
eq.set_editor_property("TraceSockets", [blade])
drop = unreal.new_object(unreal.UCFItemFragment_WorldItem, outer=sword)
sword.set_editor_property("Fragments", [vis, eq, drop])
save(sword)
  • ID is what each melee trace window lists in SocketIDs ("Blade" in Enemy Recipe 1). The names must match exactly.
  • The item shows HeldMesh in the hand on a component tagged UCF.ItemMesh, which is why the blade socket's SourceComponentTag is UCF.ItemMesh.
  • The World Item fragment lets the sword drop where the enemy dies. Without it the sword is put away at death and nothing is left to pick up.
  • The enemy's AI picks its moves from its Action Set, so the item needs no action graph, keys or animation layer for it. Player Recipe 4 adds those when a player wields it too.

Step 3. Give it to the enemy

loadout = defaults(bp).get_editor_property("Loadout")
loadout.set_editor_property("StartingItems", [sword])
loadout.set_editor_property("ItemSets", [])
save(bp)
The duplicate from Enemy Recipe 1 is a UCF Enemy Character Base (AUCFEnemyCharacterBase), which carries the Loadout, the Equipment Manager and a body mesh items hang on. The enemy draws its StartingItems in order as it begins play; the sword takes the main hand, UCF.Place.Main, which the Equipment Manager's BodyPlaces puts on the hand_r socket. Clearing ItemSets drops the demo's rows for the baton, the sword and the fists, so the AI Config's sets apply.
The Equipment Manager's DefaultItem is what the enemy holds while it holds nothing else, the demo's fists, whose trace sockets and animation layer suit the demo mannequin. Clear it for a customer's own character:
defaults(bp).get_editor_property("EquipmentManagerComponent").set_editor_property("DefaultItem", None)
save(bp)
Check: in Play, the sword sits in the enemy's right hand, UCF.Debug.Melee.DrawTracing 1 draws a capsule along the blade during each strike window, and when the enemy dies the sword drops to the ground.
If the sword is held at the wrong angle, judge a correction from a capture and set it as the Offset of the Equippable fragment's UCF.Place.Main row in HoldPlaces, as Player Recipe 4 shows.

Moves per item and per role

An ItemSets row gives the AI an Action Set and a Reaction Set while the enemy holds its Item, in place of the AI Config's. A row naming a CombatRole applies only while the AI plays that role, and wins over a row naming none:
row = unreal.UCFEnemyItemSets()
row.set_editor_property("Item", sword)
row.set_editor_property("ActionSet", load(f"{F}/ActionSet_{N}"))
row.set_editor_property("ReactionSet", load(f"{F}/ReactionSet_{N}"))
loadout.set_editor_property("ItemSets", [row])
save(bp)
With no row for the item it holds, the AI fights with the AI Config's sets. A disarmed enemy holds its DefaultItem, so a row for that item gives it moves for bare hands.

Unarmed enemies

An unarmed enemy holds nothing: leave StartingItems empty and set the Equipment Manager's DefaultItem to a fists item. Make it as in Step 2 with an Equippable fragment alone, whose two TraceSockets rows sit on the body's hand bones: ID HandR and HandL, Shape Sphere, SocketOrBoneName hand_r and hand_l, SourceComponentTag empty, Radius 12. An empty SourceComponentTag traces from the body mesh. List HandR (or both) in each window's SocketIDs. The demo's Item_UCF_Unarmed is one, for the demo mannequin.

A two-handed weapon enemy

Same steps, with these values:
  • Set the Offset of the item's UCF.Place.Main row so the off hand meets the grip. The animations decide the pose.
  • Slower, heavier attacks: Damage 30 to 45, distance ranges 150 to 350, Cooldown.Duration 3 to 6, PlayRate 0.9 on the payloads.
  • StopDistanceOverride stays about 40 on each approach window. A heavier weapon does not stand farther off: at a 60 cm gap a two-handed swing of the same length falls short and never lands.
  • DesiredDistance 350 on the movement profile.

An enemy on Enemy Character Base

An enemy built on Enemy Character Base rather than UCF Enemy Character Base holds nothing until it carries what UCF Enemy Character Base adds. Reparenting it onto UCF Enemy Character Base gives all of it at once; otherwise add a UCF Equipment Manager, a UCF Anim Manager and a UCF Enemy Loadout, tag its Mesh component UCF.Montage and UCF.Attachment.Body in ComponentTags, and call Notify Ability System Ready from its Begin Play, so its draws play their reach and its trace's hits are confirmed. Set its Mesh component's collision Object Type to Physics Body (set_collision_object_type(unreal.CollisionChannel.ECC_PHYSICS_BODY)), as UCF Enemy Character Base does, or the swings of the demo player, and of a player made from it, pass through it, since that player's melee trace sweeps Physics Body objects. Turn on Use Acceleration For Paths on its Character Movement (NavMovementProperties), or it slides along its path in its idle pose. For flinches and a death fall, add a UCF Physical Reaction and a UCF Anim Effects component and the reaction abilities (GA_UCF_HitReact, GA_UCF_Stun, GA_UCF_ParryRecoil) to StartingAbilities.

Enemy Recipe 3: more attacks, combos and pacing

Add actions to the same Actions array. Useful settings:
WantSet
An attack for a rangeA Distance Scorer with its own band. Give each attack a different band.
Only when facing the targetAdd an Angle Scorer (UUCFAngleScorer); its default Range peaks at 0 to 30 degrees.
A three-hit comboChainLinks from A to B and B to C. For a link that must follow at once, set the link's Pacing to unreal.UCFChainPacing.IMMEDIATE.
A move that only follows anotherSelection = unreal.UCFActionSelection.CHAIN_ONLY
Fewer repeatsCooldown.Duration, and Cooldown.MaxConsecutiveUses (-1 is unlimited)
Not as the opening moveCooldown.InitialCooldown
A gap between any two attacksActionRecoveryTime on the AI Config (0 by default)
Several enemies take turnsAdd a Combat Token Gate (UUCFTokenGate, TokenTag = UCF.Token.Attack) to CustomScoring.Gates
Back off when crowdedAn action whose execution method runs a behavior tree with the Make Distance task, Distance Scorer 0 to 100 cm. See the Action System page.
An attack that turns and closes the gapA UCF Approach Window (UUCFApproachWindowNotifyState) over the wind-up of the montage

Enemy Recipe 4: reactions

Flinch on hit

Enemy Recipe 1, Step 7. For hits from the front and from behind, make one reaction each and gate them with an Incoming Angle Gate (UUCFGate_IncomingAngle) in the reaction's CustomScoring.Gates: HalfAngleDegrees 90 on the front reaction, and the same with bInvert on for the back one. The gate measures an arc to either side of straight ahead, so it cannot tell left from right; a side hit plays the front or back reaction.

Parry or dodge an incoming swing

An enemy can only answer a swing that announces itself. The attacker's montage needs a UCF Telegraph Window (UUCFTelegraphMarkerNotifyState) over its wind-up, with Broadcast.Shape set to a Sphere (UUCFTelegraphShape_Sphere, Radius 500 by default). A telegraph with no shape reaches nobody.
t = ucf.add_notify_state_to_montage(player_attack_montage, unreal.UCFTelegraphMarkerNotifyState, 0.0, strike_start)
b = t.get_editor_property("Broadcast")
b.set_editor_property("Shape", unreal.new_object(unreal.UCFTelegraphShape_Sphere, outer=t))
t.set_editor_property("Broadcast", b)
t.set_editor_property("bFindAttackAutomatically", True)
save(player_attack_montage)
Then add a Parry (or Dodge) reaction playing its montage, and a trigger rule with OnStimulus = UCF.Stimulus.AttackTelegraphed linking to it, Chance 0.3 to 0.5 and MinInterval 2. For i-frames on a dodge, put a UCF State Tag Window (UUCFStateTagNotifyState) holding UCF.State.Intangible over the dodge's evasive frames.

Enemy Recipe 5: a boss

All data, no Blueprint graph edits.
  1. Pawn. Duplicate BP_<Name> as BP_<Name>_Boss. Raise its health on the Vitals component:
    vit = defaults(boss_bp).get_editor_property("Vitals")
    rows = vit.get_editor_property("Vitals")
    for r in rows:
        if str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("VitalTag"))) == "UCF.Vital.Health":
            r.set_editor_property("MaxValue", 600.0)
    vit.set_editor_property("Vitals", rows)
    save(boss_bp)
    For a bigger boss, scale the Mesh and the capsule together.
  2. Role. Duplicate the AI Config as EnemyConfig_<Name>_Boss and point the boss pawn's AIConfig at it. In its RoleRegistrationParams set AllowedRoles = tags("UCF.Role.Elite"), PreferredRole = tag("UCF.Role.Elite"), Priority = 200. Set bIgnoreTargetRedistribution = True. Elite slots are unlimited by default, so the boss does not wait for a turn.
  3. Phases by health. Make ActionSet_<Name>_Boss. Give phase one actions a Health Scorer (UUCFHealthScorer) with Range 0.49, 0.5, 1.0, 1.0, and phase two actions one with Range 0.0, 0.0, 0.5, 0.51. Health is a 0 to 1 fraction, so phase one stops and phase two starts at half health. Phase two can reuse the same montages with PlayRate 1.25 and shorter cooldowns, plus a new finisher. Set it as the boss config's DefaultActionSet.
  4. Arena. Spawn the demo's boss arena trigger, /UniversalCombatFramework/Demo/Game/BP_UCF_BossArenaTrigger (on Epic's MCP its class is /UniversalCombatFramework/Demo/Game/BP_UCF_BossArenaTrigger.BP_UCF_BossArenaTrigger_C), covering the arena. It is a UCF Encounter Trigger that ends the fight as Defeated once every enemy it lists is dead or gone. Set EncounterName (text), bTriggerOnce = True, bEndWhenPlayerLeaves = False, and Enemies = [placed boss actor]. Enemies can only be set on the placed actor, not on a Blueprint. Size its box with trigger.get_editor_property("TriggerBox").set_box_extent(unreal.Vector(x, y, z)).
  5. Fight from the start. For an arena where the boss knows about the player at once, set bAlwaysAware = True on a dedicated awareness config for the boss.
What needs a person: a health bar on screen needs a widget bound to the UCF Encounter Subsystem's On Encounter Started (the demo's WBP_UCF_EncounterBar shows how). Tell the customer it is a Blueprint step.

Combo Enemy Recipe: an enemy that fights with an action graph combo

An enemy's AI picks one action at a time. An Action Graph Combo action (UUCFActionGraphExecutionMethod) plays a whole combo from an action graph, the same kind of graph a player's moves live in, feeding it inputs the way a player's presses would. The combo plays on the enemy's own body, swings its weapon and hits through its melee trace; its AI still decides when.
Build the enemy and its weapon first (Enemy Recipes 1 and 2). Then set these:
F = "/Game/Enemies/DarkKnight"     # the enemy's folder from Enemy Recipe 1
N = "DarkKnight"
bp = load(f"{F}/BP_{N}")
aset = load(f"{F}/ActionSet_{N}")
dmg = load(f"{F}/Damage_{N}_Light")
seqs = {"Combo1": load("/Game/.../Attack_01"),
        "Combo2": load("/Game/.../Attack_02"),
        "Combo3": load("/Game/.../Attack_03")}

Step 1. Give the enemy an action graph component

The enemy from Enemy Recipe 1 is a UCF Enemy Character Base (AUCFEnemyCharacterBase), whose UCF Enemy Attack Steering component already aims each move of a combo at the target its AI fights. It draws its weapon through its UCF Enemy Loadout (Enemy Recipe 2), as every enemy does, and needs a UCF Action Graph component (UUCFActionGraphComponent) as well to play the moves; the Equipment Manager hands that component the action graph of the item the enemy holds.
if bp_component(bp, "ActionGraph") is None:
    sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
    root = sds.k2_gather_subobject_data_for_blueprint(bp)[0]
    params = unreal.AddNewSubobjectParams(parent_handle=root, new_class=unreal.UCFActionGraphComponent, blueprint_context=bp)
    handle, problem = sds.add_new_subobject(params)
    if not unreal.SubobjectDataBlueprintFunctionLibrary.is_handle_valid(handle):
        raise RuntimeError(f"Could not add the action graph component: {problem}")
    sds.rename_subobject(handle, unreal.Text("ActionGraph"))
    unreal.BlueprintEditorLibrary.compile_blueprint(bp)
    save(bp)
Check: bp_component(bp, "ActionGraph") is not None.

Step 2. Make the combo's montages

One montage per move, each with three windows:
  • UCF Approach Window (UUCFApproachWindowNotifyState) over the wind-up, as in Enemy Recipe 1, Step 4: it turns the enemy toward its target and closes the gap. Its StopDistanceOverride is the gap in cm it leaves between the two bodies, about 40 for a sword, one-handed or two-handed.
  • UCF Melee Trace Window (UUCFMeleeTraceNotifyState) over the frames that connect, listing the weapon's trace socket (Blade in Enemy Recipe 2).
  • UCF Action Window (UUCFActionWindowNotifyState) where the next input may chain, on every move but the last. Without one, the next move waits for this one to end.
The animations are the enemy's own, on its mesh's skeleton (Rules); the first lines stop the step on any other.
skeleton = defaults(bp).get_editor_property("Mesh").get_editor_property("SkeletalMeshAsset").get_editor_property("Skeleton")
other = [key for key, seq in seqs.items() if seq.get_editor_property("Skeleton") != skeleton]
if other:
    raise RuntimeError(f"{other} are animations of another skeleton than the enemy's mesh")
am = {key: ucf.create_montage_from_animation(seq, F, f"AM_{N}_{key}") for key, seq in seqs.items()}
for key, m in am.items():
    L = length(m)
    a = ucf.add_notify_state_to_montage(m, unreal.UCFApproachWindowNotifyState, L * 0.05, L * 0.20)
    a.set_editor_property("StopDistanceOverride", 40.0)
    w = ucf.add_notify_state_to_montage(m, unreal.UCFMeleeTraceNotifyState, L * 0.30, L * 0.25)
    w.set_editor_property("SocketIDs", ["Blade"])
    w.set_editor_property("DamageConfig", dmg)
    if key != "Combo3":
        ucf.add_notify_state_to_montage(m, unreal.UCFActionWindowNotifyState, L * 0.55, L * 0.35)
    save(m)
Tell the customer the times you picked; only a person can judge whether the windows sit on the right frames.

Step 3. Build the action graph

graph = new_data_asset(unreal.UCFActionGraphAsset, F, f"AG_{N}_Combo")
for key in ("Combo1", "Combo2", "Combo3"):
    ucf.add_montage_node(graph, key, am[key], 1.0)
ucf.add_transition(graph, "ROOT", "Combo1", "UCF.Input.LightAttack")
ucf.add_transition(graph, "Combo1", "Combo2", "UCF.Input.LightAttack")
ucf.add_transition(graph, "Combo2", "Combo3", "UCF.Input.LightAttack")
print(ucf.compile_action_graph(graph))    # empty means no problems
print(ucf.describe_action_graph(graph))
save(graph)
The input tag only has to match between the graph and the combo's steps (Step 4); an enemy presses no keys, so the graph needs no item or key mapping.
Check: the describe output lists ROOT, the three moves and the two UCF.Input.LightAttack links between them.

Step 4. Add the combo to the Action Set

The action's execution method is the combo: the graph it walks, one variant listing the inputs in order, and Lock Target, which keeps every move of the combo aimed at the target the AI chose when the combo started. Give it a Distance Scorer like any melee attack. range_scorer comes from Enemy Recipe 1, Step 6; run that block again in a new Python session.
combo = unreal.new_object(unreal.UCFActionGraphExecutionMethod, outer=aset)
combo.set_editor_property("ActionGraph", graph)
press = unreal.UCFActionInputStep()
press.set_editor_property("Tag", tag("UCF.Input.LightAttack"))
variant = unreal.UCFActionGraphComboVariant()
variant.set_editor_property("Steps", [press, press, press])
combo.set_editor_property("Variants", [variant])
combo.set_editor_property("bLockTarget", True)
 
spec = unreal.ActionSpec()
spec.set_editor_property("ActionId", "Combo")
spec.set_editor_property("ExecutionMethod", combo)
scoring = spec.get_editor_property("CustomScoring")
scoring.set_editor_property("Scorers", [range_scorer(aset, unreal.UCFDistanceScorer, 0, 100, 250, 450)])
spec.set_editor_property("CustomScoring", scoring)
cd = spec.get_editor_property("Cooldown")
cd.set_editor_property("Duration", 4.0)
spec.set_editor_property("Cooldown", cd)
actions = list(aset.get_editor_property("Actions"))
actions.append(spec)
aset.set_editor_property("Actions", actions)
save(aset)
  • The action ends once the combo's last move has finished and the graph stands back at idle, so the AI's recovery time starts after the whole combo.
  • ActionGraph is set on the enemy for the combo's length. Left empty, the combo plays the graph the enemy already holds.
  • Several variants make the enemy pick one by Weight each time it plays the action.
  • An input no transition listens for ends the combo early; saving the Action Set names it in the message log.
Check: reload the set and print the new action's ActionId, its method's ActionGraph, the variant's three steps and bLockTarget.

Step 5. Play and check

Play as in Enemy Recipe 1, Step 10, and in the second run turn on both overlays:
game = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_game_world()
unreal.SystemLibrary.execute_console_command(game, "UCF.Debug.EnemyActions 1")
unreal.SystemLibrary.execute_console_command(game, "UCF.Debug.Actions 1")
Success looks like: within reach of the player, the enemy's action list shows Combo running, the action graph overlay steps through Combo1, Combo2 and Combo3, each move turns toward the player and closes in, and the hits land. log_warnings() returns nothing about this enemy.

No Animation Blueprint

The player needs an Animation Blueprint on its skeleton that blends idle, walk and run by speed and has a DefaultSlot Slot node, which is where every UCF montage plays. If the customer has none, ask whether one came with the animation pack under another name. Otherwise make one from the plugin's locomotion template:
anims = "/Game/.../"
abp = ucf.create_locomotion_anim_blueprint(mesh.get_editor_property("Skeleton"), F, f"ABP_{N}",
                                           load(anims + "Idle"), load(anims + "Walk_Fwd"), load(anims + "Run_Fwd"))
The new Animation Blueprint blends idle into walk by 200 cm/s and walk into run by 500 cm/s, and already carries the UCF Hit Stop and Inertialization nodes after its slot, so a landed hit freezes the pose. To match the character's own speeds, set WalkSpeed and RunSpeed on its class defaults (defaults(abp)) and save it.
An Animation Blueprint the customer already has works as it is. Hit stop (the frozen pose on a landed hit) also needs a UCF Hit Stop node after the slot with an Inertialization node after it; without it the log says so once and hits land without the freeze. Adding the node to the customer's own Animation Blueprint is a step for the customer.
An enemy's Animation Blueprint is made the same way. To match the enemy's own speeds (MaxWalkSpeed on its CharacterMovement), set WalkSpeed and RunSpeed on its class defaults (defaults(abp)) and save it.

More player tasks: the reference files

The recipes above build the common cases. For anything else, open the one file below that covers the task. Each lists its tasks first, then recipes with a check, the exact class and property names, and the common mistakes. They sit in AgentGuide/Player/ beside this file, in the plugin's Resources folder; when this file reached you on its own, open them there.
TaskFile
A property refuses a value, rows a plain write refuses, components on a Blueprint, montage sections, new gameplay tags, checking an assetAgentGuide/Player/Python.md
Other kinds of moves (a held guard, a wait, an ability), a move's settings, cancel windows, state tags, transitions back to idle, tag gates and conditions on a transition, sub graphs, editing or removing movesAgentGuide/Player/ActionGraphs.md
Stamina, attack costs, cooldowns and charges, resource and tag gates, sprint drain, slowing during a moveAgentGuide/Player/GatesCostsHooks.md
New keys and input tags, chords, abilities on keys, sprint, pausing inputAgentGuide/Player/InputAbilities.md
Item fragments, the off hand, shields, two-handed weapons, presets, stowing on the body, swing trails, worn gear (helmets, capes, rings)AgentGuide/Player/ItemsEquipment.md
Items that are not gear (keys, materials, potions), containers, inventory configs and their rules made from scratch, a keychain that collects keys by itself, weight limits, combine recipes, saving the inventory, inventory screens, using an item, storage boxes, bags on a bag bar, the belt, pickups, drops, weapon racks, loot chests, interactable objectsAgentGuide/Player/InventoryInteraction.md
Hit effects, blocks and parries, health and stamina rows, hit reactionsAgentGuide/Player/DamageDefense.md
Attacks closing on the target, combat styles, targeting configs, targetable actorsAgentGuide/Player/TargetingStylesSteering.md
Camera settings, camera shots, attack warning markersAgentGuide/Player/CameraTelegraphs.md
Finishers, counters and other two-character moves (Paired Actions)AgentGuide/Player/PairedActions.md
Montage windows, several meshes, animation layers, footsteps, HUD, button prompts, project settings, debuggingAgentGuide/Player/AnimationHUDDebug.md

More enemy tasks: the reference files

The recipes above build the common cases. For anything else, open the one file below that covers the task. Each lists its tasks first, then recipes with a check, the exact class and property names, and the common mistakes. They sit in AgentGuide/Enemy/ beside this file, in the plugin's Resources folder; when this file reached you on its own, open them there.
TaskFile
A property refuses a value, rows in arrays, components on a Blueprint, montage sections, new gameplay tags, checking an asset, project settingsAgentGuide/Enemy/Python.md
A moveset from several animations, ranges, combos and pacing, gates, cooldowns, one clip with several attacks, movesets per weapon or roleAgentGuide/Enemy/Actions.md
Flinches by direction, parry and dodge rules, what an enemy can noticeAgentGuide/Enemy/Reactions.md
Keeping distance, circling, backing off when stared at, flanking anglesAgentGuide/Enemy/Movement.md
Target selection, combat roles and limits, taking turns, teams, the brain, repeatable fightsAgentGuide/Enemy/BrainRolesTargets.md
Sight and hearing, patrols, guard posts, leashesAgentGuide/Enemy/AwarenessTerritory.md
An attack run as a behavior tree, the State Tree tasksAgentGuide/Enemy/BehaviorTrees.md
Montage windows, root-motion lunges, step-backs, tag-driven animation, walking slower on a tagAgentGuide/Enemy/Animation.md
Weapons and loadouts, damage and hit effects, enemies that block and parryAgentGuide/Enemy/WeaponsDamageDefense.md
Health, stamina and stance, death, encounters and boss bars, settings, debuggingAgentGuide/Enemy/VitalsEncountersDebug.md

Player and enemy together

For what crosses the two layers, open AgentGuide/Seam.md beside this file (in the plugin's Resources folder): an enemy playing the player's combos, one action running several, locking on to enemies, teams, enemies answering the player's swings and the player answering theirs, executing a staggered enemy, switching an existing project to UCF, and the demo's combo enemy and bosses.

Player reference

Assets you create

AssetClassMade withHolds
Player characterBlueprint of AUCFCharacterBase (duplicate of BP_UCF_Character)duplicateMesh, StartingAbilitySet, components below
Ability setUUCFAbilitySet (duplicate of AbilitySet_UCF_Default)duplicateGrantedGameplayAbilities rows: Ability, InputTag, InputAction
Game modeChild Blueprint of BP_UCF_GameModeunreal.BlueprintFactory with ParentClassDefaultPawnClass, controller BP_UCF_PlayerController
Animation BlueprintChild of ABP_UCF_LocomotionTemplateucf.create_locomotion_anim_blueprintIdleAnimation, WalkAnimation, RunAnimation, WalkSpeed, RunSpeed
Action GraphUUCFActionGraphAssetnew_data_asset, then ucf.add_* and ucf.compile_action_graphNodes and transitions; DefaultInputBufferMode
Item DefinitionUUCFItemDefinitionnew_data_assetFragments, DisplayName, Icon, SlotTags, MaxStackSize
Equippable fragmentUUCFItemFragment_Equippableunreal.new_object(..., outer=item)ActionGraph, InputMappingContext, InputMappings, TraceSockets, AttackStopDistance, HoldPlaces, bIsMainWeapon, EquipmentTags, AbilitySetsToGrant, AnimLayerClass, ItemActorClass
Visuals fragmentUUCFItemFragment_Visualsunreal.new_object(..., outer=item)HeldMesh (label Mesh)
Container DefinitionUUCFContainerDefinitionnew_data_assetLayout, SlotCount, GridSize, Rules (unreal.new_object(..., outer=definition)), bCarried, bTakesNewItems, AccessTag, bOpensBags
Inventory ConfigUUCFInventoryConfignew_data_assetContainers rows (import_text), CarryRules, CombineSets, SortOrder, bEquipAtOnce, bPutAwayAtOnce, bCombineAtOnce; set on the character's InventoryComponent.Config
Combine SetUUCFCombineSetnew_data_assetRecipes rows (two items, their counts, Results, Seconds), Combines; listed on the config's CombineSets
Damage ConfigUUCFDamageConfignew_data_assetDamage, AdditionalVitalDamage (a UCF.Vital.Poise row), DamageTags, HitEffects
Input Mapping ContextUInputMappingContext (duplicate a demo one)duplicate, map_keyKeys to Input Actions
MontageUAnimMontageucf.create_montage_from_animationNotify windows below
Character components you touch (all on the duplicated character): Mesh (SkeletalMeshAsset, AnimClass, ComponentTags), EquipmentManagerComponent (DefaultItem, BodyPlaces), InventoryComponent (StartingItems, Config), MeleeTraceComponent (DefaultDamageConfig), VitalsComponent (Vitals rows: VitalTag, MaxValue, RegenRatePerSecond), CombatComponent (Style), TargetingComponent (TargetingConfig), CharacterMovement (GraceTag).
Rows: FUCFInputMapping (InputAction, InputTag), FUCFTraceSocket (ID, SourceComponentTag, Shape, SocketOrBoneName, EndSocketOrBoneName, Radius, LocalOffset), FUCFHoldPlaceSpec (Place, Offset, SocketOverride), FUCFBodyPlace (Place, Socket).

Shipped assets you reuse

AssetPath under /UniversalCombatFramework/
Locomotion templateCore/Animation/ABP_UCF_LocomotionTemplate
Demo player, controller, game modeDemo/Characters/Player/BP_UCF_Character, Demo/Characters/Player/BP_UCF_PlayerController, Demo/Game/BP_UCF_GameMode
Input ActionsDemo/Inputs/IA_UCF_LightAttack, IA_UCF_HeavyAttack, IA_UCF_Dash, IA_UCF_Guard, IA_UCF_LockOn, IA_UCF_Move, IA_UCF_Look, IA_UCF_Sprint
Mapping contextsDemo/Inputs/IMC_UCF_Default, Demo/Weapons/Unarmed/IMC_UCF_Unarmed, Demo/Weapons/Sword/IMC_UCF_Sword
Combat styles and targetingDemo/Combat/Styles/CombatStyle_UCF_OverShoulder, _Soulslike, _Freeflow, each with a TargetingConfig_UCF_*
Ability set with lock-on (Player Recipe 1 copies it without the parry recoil and stun)Demo/Abilities/AbilitySet_UCF_Default
Damage configsDemo/Weapons/Unarmed/Damage_UCF_Unarmed, Demo/Weapons/Sword/Damage_UCF_Sword
A test enemyDemo/Characters/Enemy/BP_UCF_EnemyCharacter
Demo level and complete examplesDemo/Maps/LVL_UCF_Demo; Demo/Weapons/Sword/Item_UCF_Sword and AG_UCF_Sword
Inventory screens, one per ready inventory style, opened with I or a tap of the pad's View buttonDemo/UI/Widgets/Inventory/WBP_UCF_InventoryScreen_OpenWorldList, _SurvivalGrid, _PartyRPG (AgentGuide/Player/InventoryInteraction.md, Inventory screens)
Every demo item to try on: walk onto a pad to equip its item, again to put it away; an inventory style pad switches the inventory to that style and its starter kitDemo/Maps/LVL_UCF_Wardrobe (its hall LVL_UCF_Wardrobe_Hall also streams into LVL_UCF_Demo, reached by the Wardrobe plate in the start room), its pads Demo/Showcase/Equipment/BP_UCF_EquipPad and Demo/Showcase/Inventory/BP_UCF_InventoryStylePad
The demo content must stay in the project while anything references it. Duplicate a demo asset into the customer's folder when the customer plans to remove the demo. The demo's animation layers, reach montages and the montages of GA_UCF_Stun and GA_UCF_ParryRecoil belong to the demo mannequin's skeleton, so do not give them to another skeleton's character or items.

Montage notifies

Notify (editor name)ClassNeeded forKey properties
UCF Melee Trace WindowUUCFMeleeTraceNotifyStateAny hit to deal damageSocketIDs, DamageConfig, ExtraDamageTags
UCF Action WindowUUCFActionWindowNotifyStateWhere the next press may chain. Without one, the node's When No Window Is Authored (ChainWithoutWindow) decides: by default the next move starts when this one endsnone
UCF State Tag WindowUUCFStateTagNotifyStateTags for a stretch: UCF.State.Intangible (i-frames), UCF.State.HyperArmor (less poise damage)Tags
UCF Approach WindowUUCFApproachWindowNotifyStateGliding to the target during a wind-up
UCF Telegraph WindowUUCFTelegraphMarkerNotifyStateA warning marker over an enemy's swing
UCF Anim Effect WindowUUCFAnimEffectWindowNotifyStateSwing trails (UCF.AnimEffect.Weapon.Trail) and glowsEffect
UCF Anim EffectUUCFAnimEffectNotifyFootsteps, landings and other one-frame sounds the character's Anim Effect Bank playsEffect
UCF Equipment CommitUUCFEquipmentCommitNotifyThe swap frame of a draw or stow reach
UCF Gameplay EventUUCFGameplayEventNotifySending a gameplay event at a frameEventTag
Attack steering (an attack turning to the target and closing the gap) uses the engine's Motion Warping notify with the UCF Skew Warp modifier and Warp Target Name UCFTarget. The duplicated character has the Motion Warping component it needs.

Gameplay tags you set

TagUse
UCF.Input.LightAttack, .HeavyAttack, .Dash, .Dodge, .Guard, .LockOn, .Sprint, .Special, .Aim, .Fire, .Execute, .DropInput tags on item mappings and graph transitions
UCF.State.Intangiblei-frames: melee traces skip the holder
UCF.State.HyperArmorLess poise damage, so light hits do not flinch
UCF.State.DashingWith GraceTag, server trust for a fast dash
UCF.State.BlockingA held guard (node AppliedTags)
UCF.State.ActionsBlockedOn the character, drops every press
UCF.State.ActionRunning, UCF.State.LockedOnRead only: a move is running; a lock is held
UCF.Place.Main, UCF.Place.Off, UCF.Place.Back, .Back.Left, .Back.RightBody places and hold places
UCF.Place.Head, .Chest, .Hands, .Feet, .Shoulders, .Neck, .Ring.Left, .Ring.Right, .Top, .BottomThe demo's worn gear places; a game names its own
UCF.Vital.Health, .Stamina, .StanceVitals rows
UCF.ItemMeshSource Component Tag for a socket on a mesh-only item
There are no input tags for moving and looking; those keys are wired in the character Blueprint.

Common mistakes

SymptomCause and fix
Press does nothingThe item mapping's InputTag differs from the transition's, the item's mapping context lacks the Input Action, or the graph was not compiled after the last change (ucf.describe_action_graph says so on its first line).
Press does nothing and the log names the ability systemThe character has no Ability System Component; the duplicate has one.
Combo never chainsThe press landed before the action window and the buffer is set to Ignore, the transition's trigger is not ON_STARTED, or the press came after the move ended, later than its late input grace (the graph's LateInputGrace, or the move's own override); a move that leaves through an AUTO transition to another move grants none.
Item not visible in the handNo mesh tagged UCF.Attachment, or the body place's socket is missing on the skeleton. The log names both.
Hits pass throughNo UCF Melee Trace Window on the montage, the window names a socket ID the item does not register, the blade socket's SourceComponentTag is wrong, the target is on the player's team, or an unarmed item has no short AttackStopDistance, so punches stop out of reach. The log names an unregistered socket ID.
Weapon held crookedSet Offset on the item's HoldPlaces row, as in Player Recipe 4, Step 5.
T-pose, or montages do not playThe Animation Blueprint is for another skeleton, or has no DefaultSlot Slot node.
An attack plays stretched, twisted or not at allIts montage was made from an animation of another skeleton (Rules).
Lock-on finds nothingThe target has no UCF Targetable component, or is on the player's team; or the targeting config is unset.
Dodge does not avoid hitsThe dodge montage has no State Tag Window with UCF.State.Intangible, or it does not cover the frames of the incoming hit.
Draw or stow plays nothing on a custom skeletonReach montages from the demo belong to the mannequin. Leave the item without a Stowable fragment, or give it reach montages on the customer's skeleton.
Debug in Play: UCF.Debug.Actions 1 writes each character's graph state above its head; UCF.Logs Verbose raises every UCF log category and UCF.Logs puts them back.

Enemy reference

Assets you create

AssetClassMade withHolds
Enemy pawnBlueprint of AUCFEnemyCharacterBase (duplicate of BP_UCF_EnemyCharacter)duplicateMesh, AIConfig, StartingAbilities, components below
AI controllerAEnemyControllerBase; the demo BP_UCF_EnemyController is finealready set on the duplicateMovement, scoring, reactions, awareness, the brain
Enemy AI ConfigUEnemyAIConfignew_data_assetTargetSelector, AwarenessConfig, DefaultActionSet, DefaultReactionSet, DefaultMovementProfile, StateTree, RoleRegistrationParams, ActionRecoveryTime
Action SetUActionSetnew_data_assetActions (FActionSpec)
Reaction SetUReactionSetnew_data_assetReactions (FReactionSpec), TriggerRules (FUCFReactionTriggerRule)
Awareness ConfigUUCFAwarenessConfignew_data_assetSight, hearing, bAlwaysAware
Movement Behavior ProfileUMovementBehaviorProfilenew_data_assetDesiredDistance (cm)
Damage ConfigUUCFDamageConfignew_data_assetDamage, DamageTags, HitEffects
WeaponUUCFItemDefinitionnew_data_assetFragments: Visuals (HeldMesh), Equippable (TraceSockets, HoldPlaces), World Item
Animation BlueprintChild of ABP_UCF_LocomotionTemplateucf.create_locomotion_anim_blueprintIdleAnimation, WalkAnimation, RunAnimation, WalkSpeed, RunSpeed
MontageUAnimMontageucf.create_montage_from_animationNotify windows below
Pawn components you touch (all on the duplicated pawn): Mesh, CharacterMovement, MeleeTraceComponent (DefaultDamageConfig), Loadout (StartingItems, ItemSets), EquipmentManagerComponent (DefaultItem, BodyPlaces), Vitals (Vitals rows: VitalTag, MaxValue, RegenRatePerSecond, RegenDelaySeconds; one UCF.Vital.Health row at 100 by default).

Shipped assets you reuse

AssetPath
Locomotion template/UniversalCombatFramework/Core/Animation/ABP_UCF_LocomotionTemplate
Montage-playing ability/UniversalCombatFramework/Core/Abilities/GA_UCF_MontageAbility
Damage configs/UniversalCombatFramework/Core/Damage/Damage_UCF_Slashing and the five others
Demo enemy and controller/UniversalCombatFramework/Demo/Characters/Enemy/BP_UCF_EnemyCharacter, BP_UCF_EnemyController
Demo items an enemy holds/UniversalCombatFramework/Demo/Weapons/TwoHanded/Item_UCF_TwoHandedBaton, /UniversalCombatFramework/Demo/Weapons/Sword/Item_UCF_Sword, /UniversalCombatFramework/Demo/Weapons/Unarmed/Item_UCF_Unarmed
Demo brain/UniversalCombatFramework/Demo/AI/StateTrees/ST_UCF_Core
Boss arena trigger/UniversalCombatFramework/Demo/Game/BP_UCF_BossArenaTrigger
Demo awareness/UniversalCombatFramework/Demo/AI/Awareness_UCF_Default
Demo movement profiles/UniversalCombatFramework/Demo/AI/MovementProfiles/MovementProfile_UCF_Attacker (and _Flanker, _Waiter, _Supporter, _Elite)
Demo level/UniversalCombatFramework/Demo/Maps/LVL_UCF_Demo
The demo content must stay in the project while anything references it. Duplicate a demo asset into the customer's folder when the customer plans to remove the demo.

Montage notifies

Notify (editor name)ClassNeeded forKey properties
UCF Melee Trace WindowUUCFMeleeTraceNotifyStateAny hit to deal damageSocketIDs, DamageConfig, ExtraDamageTags
UCF Telegraph WindowUUCFTelegraphMarkerNotifyStateEnemies parrying or dodging this attackBroadcast.Shape, bFindAttackAutomatically, Tags
UCF State Tag WindowUUCFStateTagNotifyStateTags for a stretch: UCF.State.Intangible for i-framesTags
UCF Approach WindowUUCFApproachWindowNotifyStateTurning and gliding toward the target during a wind-upMode, ApproachTargetName (Target), StopDistanceOverride (cm between the bodies)
UCF Gameplay EventUUCFGameplayEventNotifySending a gameplay event at a frameEventTag
UCF Anim Effect Window, UCF Anim EffectUUCFAnimEffectWindowNotifyState, UUCFAnimEffectNotifyTrails, footsteps, foleyEffect
UCF has no combo notify: combos come from ChainLinks on the Action Set.

Gameplay tags you set

TagUse
UCF.Damage.Physical.Slashing, .Piercing, .Bludgeoning; UCF.Damage.Elemental.Fire, .Ice, .LightningDamageTags on a damage config
UCF.Stimulus.DamageTakenTrigger rule for a flinch
UCF.Stimulus.AttackTelegraphedTrigger rule for a parry or dodge
UCF.Role.Attacker, .Flanker, .Waiter, .Supporter, .EliteRole settings and per-role sets
UCF.Token.AttackCombat Token Gate
UCF.State.Intangiblei-frames in a State Tag Window
UCF.State.IsMovementBlockedAlready in each new action's AddTags
UCF.State.ReactionActiveStops two reactions overlapping (AddTags on one, BlockTags on the other)
UCF.Action.BlockActionsOn the ability system, stops all actions
UCF.Vital.Health, UCF.Vital.Stamina, UCF.Vital.StanceVitals rows

Common mistakes

SymptomCause and fix
Enemy stands still, no overlay above itThe pawn's AI controller is not a UCF one, or AIConfig is empty.
Enemy never notices the playerAwarenessConfig empty, or the player is on the enemy's team (Team Id 1).
Enemy moves but never attacksNo action passes its gates: bEnabled off, Selection not Scored, or a stuck UCF.Action.BlockActions tag. UCF.Debug.Scoring 1 prints the refusal reason.
Enemy swings from across the room or repeats one moveThe action has no Distance Scorer.
Action wins and nothing playsExecutionMethod empty, payload Montage empty, or ActionId empty.
Attacks once, then freezesThe ability never reaches End Ability. Use GA_UCF_MontageAbility, or set AbilityTimeout on the execution method.
The enemy holds nothingIts Loadout's StartingItems is empty and its Equipment Manager has no DefaultItem, or the enemy is built on Enemy Character Base without the Loadout, Equipment Manager and Anim Manager (Enemy Recipe 2).
Hits pass throughSocketIDs on the window do not match the ID of a TraceSockets row on the held item's Equippable fragment, or the window sits on the wrong frames. The log names an unregistered socket ID.
The player's swings pass through the enemyIt is built on Enemy Character Base, whose Mesh is not a Physics Body, the object type the demo player's melee trace sweeps; set its Mesh's collision Object Type to Physics Body. UCF Enemy Character Base sets it (Enemy Recipe 2).
Enemies hit each otherThey are on different teams, or the pawn's melee trace TeamFilter is NoFilter. A pawn on UCF Enemy Character Base, such as the demo duplicate, starts on Enemies Only; one on Enemy Character Base starts on NoFilter, so set it to unreal.UCFTeamFilter.ENEMIES_ONLY.
Never parriesThe attacker's montage has no UCF Telegraph Window, its Broadcast.Shape is empty, or the Reaction Set has no trigger rule.
A perfect block does not stagger itIts StartingAbilities lack the recoil, GA_UCF_ParryRecoil, which the demo enemy carries and Enemy Recipe 1 empties since it plays the mannequin's recoil. Give the enemy an ability triggered by UCF.Event.ParryRecoil playing its own recoil.
Never flinchesThe pawn does not report damage (see Enemy Recipe 1, Step 7), or the set has no rule on UCF.Stimulus.DamageTaken.
Does not move at allNo navmesh, or a leftover UCF.State.IsMovementBlocked tag.
The enemy slides along its path in its idle poseIt is built on Enemy Character Base with Use Acceleration For Paths off on its Character Movement; UCF Enemy Character Base turns it on (Enemy Recipe 2).
T-pose or no animationThe Animation Blueprint is for another skeleton, or has no DefaultSlot Slot node, so montages play nowhere.
An attack plays stretched, twisted or not at allIts montage was made from an animation of another skeleton, such as the player's (Rules).
Debug commands in Play: UCF.Debug.All 1, UCF.Debug.Awareness 1, UCF.Debug.Scoring 1, UCF.Debug.Melee.DrawTracing 1, UCF.Debug.LogActionDecisions 1, UCF.Debug.LogReactions 1, UCF.Debug.Stimulus.Draw 1. UCF.Debug.WatchPawn <name> narrows the overlays to one enemy.

Learn more

When the customer wants to understand something rather than build it, find the page in https://rigbak.com/docs/universal-combat-framework/llms.txt, which lists every docs page with a one-line summary, fetch the page's Markdown version (the page URL plus .md), answer from it, and give them the page link. The table names the main pages.
TopicPage
Overviewhttps://rigbak.com/docs/UniversalCombatFrameworkDocs
Getting startedhttps://rigbak.com/docs/universal-combat-framework/getting-started
Enemies playing action graph comboshttps://rigbak.com/docs/universal-combat-framework/action-graphs-in-action-sets
Action sequences and random optionshttps://rigbak.com/docs/universal-combat-framework/sequences-and-random-options
Combo enemy patternshttps://rigbak.com/docs/universal-combat-framework/seam-patterns
Action graphs, combos, transitionshttps://rigbak.com/docs/universal-combat-framework/player/action-graph
The graph editorhttps://rigbak.com/docs/universal-combat-framework/player/action-graph-editor
Gates, costs, cooldownshttps://rigbak.com/docs/universal-combat-framework/player/gates-costs-cooldowns
Input and key mappingshttps://rigbak.com/docs/universal-combat-framework/player/input
Items and fragmentshttps://rigbak.com/docs/universal-combat-framework/player/items
Drawing, stowing, body placeshttps://rigbak.com/docs/universal-combat-framework/player/equipment
Inventoryhttps://rigbak.com/docs/universal-combat-framework/player/inventory
Taking only some of the inventory: a belt alone, no grid, no bagshttps://rigbak.com/docs/universal-combat-framework/player/inventory-pick-what-you-need
The ready inventory styles: survival grid, party RPG, open world listhttps://rigbak.com/docs/universal-combat-framework/player/inventory-survival-grid, https://rigbak.com/docs/universal-combat-framework/player/inventory-party-rpg, https://rigbak.com/docs/universal-combat-framework/player/inventory-open-world-list
Inventory containers, grids, weight and capshttps://rigbak.com/docs/universal-combat-framework/player/inventory-containers
Bags and bankshttps://rigbak.com/docs/universal-combat-framework/player/inventory-bags
Combines (rounds into a magazine)https://rigbak.com/docs/universal-combat-framework/player/inventory-combines
Loot chestshttps://rigbak.com/docs/universal-combat-framework/player/loot-chests
Inventory screenshttps://rigbak.com/docs/universal-combat-framework/player/inventory-screens
Saving the inventoryhttps://rigbak.com/docs/universal-combat-framework/player/inventory-saving
Inventory rules, combines and item data in Blueprinthttps://rigbak.com/docs/universal-combat-framework/player/inventory-blueprint
The belt of slotshttps://rigbak.com/docs/universal-combat-framework/player/quick-bar
Pickups and dropshttps://rigbak.com/docs/universal-combat-framework/player/pickups-drops-holders
Combat styleshttps://rigbak.com/docs/universal-combat-framework/player/combat-styles
Targeting and lock-onhttps://rigbak.com/docs/universal-combat-framework/player/targeting
Attack steeringhttps://rigbak.com/docs/universal-combat-framework/player/attack-steering
Camerahttps://rigbak.com/docs/universal-combat-framework/player/camera
Paired Actions (finishers)https://rigbak.com/docs/universal-combat-framework/player/paired-actions
Full enemy walkthroughhttps://rigbak.com/docs/universal-combat-framework/enemy/step-by-step-enemy
Enemy actions, scoring, comboshttps://rigbak.com/docs/universal-combat-framework/enemy/action-system
Enemy reactions and trigger ruleshttps://rigbak.com/docs/universal-combat-framework/enemy/reaction-system
Enemy weaponshttps://rigbak.com/docs/universal-combat-framework/enemy-weapons
Sight, hearing, stealthhttps://rigbak.com/docs/universal-combat-framework/enemy/awareness-system
Enemy movement and spacinghttps://rigbak.com/docs/universal-combat-framework/enemy/movement-system
Combat roleshttps://rigbak.com/docs/universal-combat-framework/enemy/combat-roles
Recipes (bosses, packs)https://rigbak.com/docs/universal-combat-framework/enemy/patterns
Hit detection and damagehttps://rigbak.com/docs/universal-combat-framework/melee-trace-and-damage
Blocks and parrieshttps://rigbak.com/docs/universal-combat-framework/defense
Health and staminahttps://rigbak.com/docs/universal-combat-framework/vitals
Telegraphshttps://rigbak.com/docs/universal-combat-framework/telegraphs
Montages, notifies, root motionhttps://rigbak.com/docs/universal-combat-framework/animation-integration
Names in UCFhttps://rigbak.com/docs/universal-combat-framework/names-in-ucf
Switching an existing project to UCFhttps://rigbak.com/docs/universal-combat-framework/switching-to-ucf

Reference files

The guide's reference files ship beside it, in the plugin's Resources/AgentGuide/ folder. Each follows under a heading naming its file.

Actions: the moveset in full (AgentGuide/Enemy/Actions.md)

AGENTS.md, Enemy Recipe 1, Step 6, builds a two-attack Action Set with the helpers montage_method, range_scorer and action. This file covers everything else an action can say. Define those three helpers first (copy them from Step 6).
Tasks: a moveset from several animations; attacks for close, middle and long range; a combo that always follows on; a back-step or a gap closer; attacks only from the front, only at low health or only with stamina; pacing between attacks; several enemies taking turns; one long animation holding several attacks; a different moveset per weapon or per combat role; using the customer's own ability.
Recipe: a moveset from five animations
Two quick slashes that combo, an overhead slam, a thrust from farther away, and a back-step when the player is too close.
names = {"Slash1": "Attack_Slash_01", "Slash2": "Attack_Slash_02", "Slam": "Attack_Overhead", "Thrust": "Attack_Thrust", "BackStep": "Step_Back"}
am = {k: ucf.create_montage_from_animation(load(f"/Game/.../{v}"), F, f"AM_{N}_{k}") for k, v in names.items()}
 
for key in ("Slash1", "Slash2", "Slam", "Thrust"):        # the back-step deals no damage and needs no window
    m, L = am[key], length(am[key])
    a = ucf.add_notify_state_to_montage(m, unreal.UCFApproachWindowNotifyState, L * 0.10, L * 0.20)
    a.set_editor_property("StopDistanceOverride", 40.0)
    w = ucf.add_notify_state_to_montage(m, unreal.UCFMeleeTraceNotifyState, L * 0.30, L * 0.25)
    w.set_editor_property("SocketIDs", ["Blade"])
    w.set_editor_property("DamageConfig", dmg_heavy if key == "Slam" else dmg_light)
    save(m)
 
aset = new_data_asset(unreal.ActionSet, F, f"ActionSet_{N}")
slash1 = action(aset, "Slash1", am["Slash1"], [range_scorer(aset, unreal.UCFDistanceScorer, 0, 80, 250, 400)], cooldown=2.0)
link = unreal.ActionChainLink()
link.set_editor_property("TargetActionId", "Slash2")
link.set_editor_property("BonusMultiplier", 1.5)
link.set_editor_property("Pacing", unreal.UCFChainPacing.IMMEDIATE)
slash1.set_editor_property("ChainLinks", [link])
slash2 = action(aset, "Slash2", am["Slash2"], [range_scorer(aset, unreal.UCFDistanceScorer, 0, 80, 250, 400)])
slash2.set_editor_property("Selection", unreal.UCFActionSelection.CHAIN_ONLY)
slam = action(aset, "Slam", am["Slam"], [range_scorer(aset, unreal.UCFDistanceScorer, 0, 100, 250, 350)], cooldown=6.0, weight=0.7, risk=1.5)
thrust = action(aset, "Thrust", am["Thrust"], [range_scorer(aset, unreal.UCFDistanceScorer, 250, 350, 550, 700)], cooldown=4.0)
back = action(aset, "BackStep", am["BackStep"], [range_scorer(aset, unreal.UCFDistanceScorer, 0, 0, 100, 150)], cooldown=5.0, weight=0.8)
aset.set_editor_property("Actions", [slash1, slash2, slam, thrust, back])
save(aset)
  • Each band is a Distance Scorer: the action scores 1 between OptimalMin and OptimalMax and 0 outside MinValue to MaxValue (cm). Give each attack its own band; the thrust's band starts where the slashes end.
  • CHAIN_ONLY makes Slash2 play only after Slash1; IMMEDIATE pacing lets it start as soon as Slash1 ends, skipping the recovery gap.
  • The back-step's band ends at 150 cm, so it only plays with the player close. It has no approach window, so it steps back from where the enemy stands.
  • Point the AI Config's DefaultActionSet at the new set and save the config.
Check: reload the set and print each action's ActionId, its execution method's payload Montage, the band of its first scorer, and Slash1's chain link. ucf.validate_asset(aset) returns nothing. In Play with UCF.Debug.Scoring 1, the overlay lists every action's score; UCF.Debug.LogActionDecisions 1 logs each pick, and Slash2 follows Slash1.
An action's fields (unreal.ActionSpec)
FieldDoes
ActionIdUnique name in the set; chain links name it. An empty one is dropped.
bEnabledOff keeps the action in the set but never picks it.
Selection (unreal.UCFActionSelection)SCORED (picked by score), CHAIN_ONLY (only as a chain follow-up), MANUAL_ONLY (only when Blueprint or a State Tree runs it by name)
ExecutionMethodHow it runs (below).
SelectionWeight, RiskPenaltyMultiply and divide the score: below 1 and above 1 make it rarer.
CustomScoring (unreal.UCFCustomScoring)Scorers (soft factors) and Gates (hard vetoes), below.
TagScoreMultipliersTag to multiplier: while the target holds the tag, the score is multiplied.
RequiresTags, BlockTagsTags that must be, or must not be, on the target or in the world.
bRequireLineOfSightOnly with a clear line to the target.
AddTagsTags the enemy holds while it runs. UCF.State.IsMovementBlocked is there from the start; leave it on attacks.
Cooldown (unreal.ActionCooldown)Duration, InitialCooldown (wait before the first use), Randomization (0 to 0.5), InterruptRefund (0 to 1), SpawnCooldownChance, MaxConsecutiveUses (-1 unlimited)
bOverrideRecoveryTime, RecoveryTimeThis action's own pause after it ends (else the AI Config's ActionRecoveryTime).
ChainLinks (unreal.ActionChainLink)TargetActionId, BonusMultiplier (score bonus while the chain window is open), Pacing (SCORE_ONLY, IMMEDIATE)
HookA UUCFEnemyActionHook Blueprint run around the action (a Blueprint step; duplicate BP_UCF_ExampleHook).
On the AI Config: ActionRecoveryTime, InterruptRecoveryTime, ActionRecoveryTimeRandomization (seconds the enemy waits after an action before picking another).
Execution methods and payloads
Class (picker label)RunsFields
UUCFAbilityExecutionMethod (Gameplay Ability)One ability and waits for it to endAbilityClass (GA_UCF_MontageAbility plays the payload's montage), AbilityTimeout, Payload
UUCFAbilityByTagExecutionMethod (Gameplay Ability By Tag)The granted ability carrying a tagActivationTag, AbilityTimeout, Payload
UUCFAbilityFireAndForgetExecutionMethod (Gameplay Ability (Fire And Forget))Starts an ability and ends the action at onceAbilityClass, ActivationTag
UUCFBehaviorTreeExecutionMethod (Behavior Tree Sequence)Behavior trees one after anotherAgentGuide/Enemy/BehaviorTrees.md
The payload is a UUCFMontagePayload (Montage Payload): Montage, StartSection, PlayRate, and for a pose held a random while, HoldSection, MinHoldSeconds and MaxHoldSeconds (AgentGuide/Enemy/Reactions.md). Make it with the method as its outer (montage_method does). An ability the customer wrote must reach End Ability on every path, or the action never ends; AbilityTimeout is the safety limit.
One clip, several attacks. Give the montage sections, then set each payload's StartSection:
ucf.set_montage_sections(am_combo, [("Slash", 0.0), ("Stab", 1.1), ("Spin", 2.3)])
A section with no next section named ends the montage, so each action plays only its part.
Scorers and gates
Class (picker label)InFields
UUCFDistanceScorer (Distance Scorer)ScorersRange (cm)
UUCFAngleScorer (Angle Scorer)ScorersRange (degrees off facing the target; default peaks at 0 to 30)
UUCFHealthScorer (Health Scorer)ScorersRange (own health, 0 to 1)
UUCFSpeedScorer (Speed Scorer)ScorersRange (own speed, cm/s)
UUCFVitalScorer (Vital Scorer)ScorersVitalTag, bUseFraction, Range
UUCFAttributeScorer (Attribute Scorer)ScorersAttribute, NormalizeBy, ValueEval
UUCFStaminaGate (Stamina Gate)GatesMinStamina
UUCFVitalGate (Vital Gate)GatesVitalTag, MinValue, bUseFraction
UUCFTokenGate (Combat Token Gate)GatesTokenTag (UCF.Token.Attack), Cost
Every gate has bInvert. A Range (unreal.RangeEval) has MinValue, OptimalMin, OptimalMax, MaxValue, Exponent (falloff sharpness) and bClampToZero.
Phases by health: a Health Scorer with Range 0.49, 0.5, 1.0, 1.0 on phase one actions and 0.0, 0.0, 0.5, 0.51 on phase two (AGENTS.md, Enemy Recipe 5).
Taking turns: a Combat Token Gate on each attack; how many slots a target has is in AgentGuide/Enemy/BrainRolesTargets.md.
Movesets per weapon and per role
  • On the pawn's UCF Enemy Loadout (Loadout), an ItemSets row (unreal.UCFEnemyItemSets: Item, CombatRole, ActionSet, ReactionSet) wins over the AI Config while the enemy holds its Item, for every role or for the one its CombatRole names.
  • On the AI Config, RoleActionSets takes unreal.RoleActionSetConfig rows (Role, bManaged, ActionSet); roles not listed use DefaultActionSet. bManageActionSetsAutomatically (on) is the switch for both.
Mistakes
SymptomCause and fix
One attack fires at every rangeIt has no Distance Scorer.
The follow-up never playsIts ActionId differs from the link's TargetActionId, or its own band leaves it at 0 where the first attack ends.
The enemy spams one moveNo Cooldown.Duration, or every other action scores 0 at that range. UCF.Debug.Scoring 1 shows why.
An action wins and nothing playsEmpty ExecutionMethod, payload Montage or ActionId. A whole-array write does not fill the method; make it yourself.
The back-step plays at rangeIts band reaches too far; keep MaxValue near the reach of a player's swing.

Animation: montages, windows and the warp (AgentGuide/Enemy/Animation.md)

AGENTS.md, Enemy Recipe 1, Steps 2 and 4, makes montages and puts an approach window and a trace window on each attack. This file covers every window UCF reads, the skew warp for root-motion lunges, sections, tag-driven animation bools and the speed modifier.
Tasks: an attack that turns and closes the gap; a step back or to the side by a set distance; a lunge whose root motion tracks the target; i-frames on a dodge; an event at a frame; footsteps and trails; several attacks in one clip; a guard pose while a tag is held; walking slower while blocking.
Windows UCF reads
Add each with ucf.add_notify_state_to_montage(montage, cls, start_seconds, duration_seconds), set its properties on the returned window, and save the montage. ucf.add_notify_state_to_montage takes notify states only; a single-frame notify is added with unreal.AnimationLibrary.add_animation_notify_event(montage, "Combat", seconds, cls).
Window (editor name)ClassFields
UCF Melee Trace WindowUUCFMeleeTraceNotifyStateSocketIDs (weapon trace socket IDs; empty sweeps all), DamageConfig, ExtraDamageTags
UCF Approach WindowUUCFApproachWindowNotifyStateMode (unreal.UCFApproachMode: MOVE_AND_FACE, FACE_ONLY, MOVE_ONLY), ApproachTargetName (Target), StopDistanceOverride (cm left between the bodies), MaxApproachDistanceOverride; bMoveByOffset with OffsetDirection and OffsetDistance moves a set distance in the enemy's own frame instead (a back-step: direction (-1, 0, 0), 200 cm)
UCF State Tag WindowUUCFStateTagNotifyStateTags held while it runs: UCF.State.Intangible (i-frames), UCF.State.Blocking
UCF Telegraph WindowUUCFTelegraphMarkerNotifyStateBroadcast (unreal.UCFTelegraphBroadcast: Shape = UUCFTelegraphShape_Sphere Radius or UUCFTelegraphShape_Cone Radius, HalfAngleDegrees), bFindAttackAutomatically, DamageConfig (shown as Attack), Tags, Magnitude
UCF Anim Effect WindowUUCFAnimEffectWindowNotifyStateEffect (EffectTags, SocketName), answered by an anim effect handler on the pawn or on an item it holds, which its Equipment Manager passes each one on to
UCF Gameplay Event (one frame)UUCFGameplayEventNotifyEventTag
UCF Anim Effect (one frame)UUCFAnimEffectNotifyEffect
Root-motion lunges: the skew warp
An attack animated with root motion that should land on the target (rather than glide by an approach window) uses the engine's Motion Warping window with the UCF Skew Warp modifier:
w = ucf.add_notify_state_to_montage(am_lunge, unreal.AnimNotifyState_MotionWarping, L * 0.1, L * 0.3)
mod = unreal.new_object(unreal.UCFRootMotionModifier_SkewWarp, outer=w)
mod.set_editor_property("WarpTargetName", "Target")
mod.set_editor_property("StopDistanceOverride", 40.0)
w.set_editor_property("RootMotionModifier", mod)
save(am_lunge)
The demo enemy carries the Motion Warping component it needs. UCF.Debug.Warp 1 draws where each warp lands.
Sections
ucf.set_montage_sections(montage, [("Slash", 0.0), ("Stab", 1.1)]) gives a montage sections; a Montage Payload's StartSection then plays one (AgentGuide/Enemy/Actions.md).
Animation Blueprint
  • The locomotion template (ucf.create_locomotion_anim_blueprint, AGENTS.md, "No Animation Blueprint") blends idle, walk and run and plays montages on DefaultSlot.
  • Tag-driven bools: an Animation Blueprint whose parent is UUCFAnimInstanceBase has GameplayTagPropertyMap on its class defaults: each row sets a bool variable while the enemy holds a tag (a guard pose while UCF.State.Blocking). Wiring that bool into the AnimGraph is a step for the customer.
Walking slower while a tag is held
Add a UCF Speed Modifier component (UUCFSpeedModifierComponent) to the enemy Blueprint (AgentGuide/Enemy/Python.md, Components on a Blueprint) and fill SpeedScaleByTag, such as {tag("UCF.State.Blocking"): 0.5}.
Mistakes
SymptomCause and fix
Swings short of the targetNo approach window, or StopDistanceOverride left at -1 (the approach component's 150).
The lunge overshootsThe Motion Warping window has no modifier, or its WarpTargetName is not Target.
The dodge does not avoid hitsNo UCF.State.Intangible window over the evasive frames.
Nothing happens on an effect windowNeither the pawn nor the item it holds answers it: no anim effect handler on the pawn, a Blueprint step, and no Swing Trail on the item; or the item is not drawn through the pawn's Equipment Manager.
A weapon trail starts twiceThe enemy Blueprint also passes the effect on to its item: remove that pass, since the Equipment Manager passes it on already.

Awareness and territory: noticing, patrols and leashes (AgentGuide/Enemy/AwarenessTerritory.md)

Tasks: how far and how fast an enemy notices the player; a guard that notices slowly from the side; an enemy that knows about the player at once (a boss); waking nearby allies; patrolling between points; guarding one spot; giving up a chase past a distance and walking back.
Awareness
An enemy notices targets through its Awareness Config (UUCFAwarenessConfig), named on the AI Config as AwarenessConfig. Without one the enemy never notices anyone. The demo's is /UniversalCombatFramework/Demo/AI/Awareness_UCF_Default.
FieldDoes
SightRadius, LoseSightRadiusSight range in cm, and the range at which a seen target is lost
PeripheralVisionHalfAngleHalf the sight cone, in degrees (90 is a 180 degree cone)
bEnableHearing, HearingRangeHearing and its range in cm
bEnableDamageSenseBeing hit reveals the attacker
bGradualEscalation, EscalationRate, SuspicionThresholdSight fills a 0 to 1 meter, faster up close and straight ahead, before the enemy fully notices; the threshold is where it turns suspicious
ProximityRadiusInside this many cm a target stays noticed without sight
GraceLossDurationSeconds it keeps fighting after losing sight
SuspiciousDecayDurationSeconds a full meter takes to drain
ConfirmLostDelaySeconds without sight before a noticed target counts as lost
bAlwaysAwareKnows every hostile target at once, no sight needed (a boss in its arena)
bAlertAlliesOnDetect, AllyAlertRadius, AllyAlertCooldownTells nearby allies when it notices someone
A slow, side-blind guard:
aw = new_data_asset(unreal.UCFAwarenessConfig, F, f"Awareness_{N}_Guard")
aw.set_editor_property("SightRadius", 1800.0)
aw.set_editor_property("PeripheralVisionHalfAngle", 60.0)
aw.set_editor_property("bGradualEscalation", True)
aw.set_editor_property("EscalationRate", 0.5)
aw.set_editor_property("bAlertAlliesOnDetect", True)
save(aw)
config.set_editor_property("AwarenessConfig", aw)
save(config)
Check: in Play, UCF.Debug.All 1 writes the awareness state (Suspicious, Detected) above the enemy as the player walks into view.
The target selector turns what the enemy noticed into its target: unreal.AwarenessFilteredTargetSelector (MinRequiredState, InnerSelector) on the AI Config, as AGENTS.md, Enemy Recipe 1, Step 8, sets. Sight skips actors on the enemy's own team (AgentGuide/Enemy/BrainRolesTargets.md, Teams).
Territory: patrols, guard posts and leashes
Every enemy on AEnemyCharacterBase carries a UCF Territory component, TerritoryComponent. It is set on the placed enemy in the level, since posts are level actors. Posts are UCF Territory Post actors (AUCFTerritoryPost), each tuned on its Post component (UUCFTerritoryPostComponent).
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
posts = [actors.spawn_actor_from_class(unreal.UCFTerritoryPost, unreal.Vector(x, y, 50)) for x, y in ((0, 0), (1200, 0), (1200, 900))]
for p in posts:
    pc = p.get_editor_property("Post")
    pc.set_editor_property("WaitTime", 2.0)
    pc.set_editor_property("bFaceForwardOnArrival", True)
 
terr = placed_enemy.get_editor_property("TerritoryComponent")
terr.set_editor_property("Posts", posts)
terr.set_editor_property("RestingBehavior", unreal.UCFRestingBehavior.PATROL_POSTS)
terr.set_editor_property("PostOrder", unreal.UCFPostOrder.SEQUENTIAL_LOOP)
terr.set_editor_property("bLeashEnabled", True)
terr.set_editor_property("LeashAnchor", unreal.UCFLeashAnchor.POSTS_CENTERED)
terr.set_editor_property("LeashRadius", 1500.0)
terr.set_editor_property("DisengageBehavior", unreal.UCFDisengageBehavior.RETURN_TO_POST)
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
placed_enemy is the enemy actor in the level (AGENTS.md, Enemy Recipe 1, Step 9, keeps it as enemy).
UCF Territory fieldDoes
PostsThe posts this enemy owns, in route order
RestingBehaviorPATROL_POSTS (walk the route) or HOLD_GROUND (stand at the first post)
PostOrderSEQUENTIAL_LOOP, SEQUENTIAL_PING_PONG, RANDOM
PatrolStartDelay, PatrolStartVariance, ArrivalRadiusWhen it sets off, and how close counts as arrived
bLeashEnabled, LeashAnchor (SELF, POSTS_CENTERED, POSTS_UNION, ACTOR with LeashAnchorActor), LeashRadiusHow far it may be dragged from its ground
LeashBreakGraceTimeSeconds past the leash before it gives up
bOnlyFightInsideLeashIgnore targets outside the leash
DisengageBehaviorRETURN_TO_POST or SETTLE_HERE once a fight ends
Post fieldDoes
ShapePOINT, RADIUS (wander inside WanderRadius), BOX (inside WanderBoxExtent)
WaitTime, WaitTimeVarianceSeconds it waits on arrival
bFaceForwardOnArrivalTurn to the post's facing
bPassThroughWalk through without stopping
The built-in brain (the AI Config's StateTree, shown as Default State Tree, left empty) walks the posts, goes to look where it last sensed the player, and walks home after a fight. The demo brain /UniversalCombatFramework/Demo/AI/StateTrees/ST_UCF_Core runs patrol, investigation and the walk home as a State Tree the customer can open and change; set it as the AI Config's StateTree only when they want that.
Check: in Play, the enemy walks its posts; dragged past LeashRadius for LeashBreakGraceTime it turns back to its posts.
Mistakes
SymptomCause and fix
Never notices the playerAwarenessConfig empty, the player beyond SightRadius, outside the cone, or on the enemy's team.
Notices through wallsProximityRadius large, or hearing on with a loud level.
Stands still instead of patrollingPosts empty, RestingBehavior on HOLD_GROUND, no navmesh between the posts, or a StateTree without the territory tasks.
Chases foreverbLeashEnabled off, or the leash anchor is SELF with bTrackLeashAnchor on.
The patrol is lost after a restartThe territory was set on the Blueprint rather than the placed enemy, or the level was not saved.

Behavior trees and State Trees (AgentGuide/Enemy/BehaviorTrees.md)

Tasks: run one attack as a behavior tree with the plugin's tasks (close in, swing, back off); tune the shipped tree; know what each State Tree task does.
An action that runs a behavior tree
An action's ExecutionMethod can be a Behavior Tree Sequence (UUCFBehaviorTreeExecutionMethod): it runs its trees one after another on the controller, then the action ends.
FieldDoes
AbilityToGrantThe gameplay ability the trees start (GA_UCF_MontageAbility plays the payload's montage)
BehaviorTreeSequenceThe trees, in order
BehaviorTreeTimeoutSeconds before a tree is stopped
PayloadKeyNameBlackboard key the payload is written to, UCF_Payload
PayloadA UUCFMontagePayload (outer: the method), as for an ability method
The plugin's tasks, which the editor's behavior tree palette lists:
Task (class)DoesFields
Move Until Distance (UBTTask_MoveUntilDistance)Walks toward the blackboard target until within reachTargetDistance (cm), MaxChaseDistance, TimeoutSeconds, bAllowStrafe, bUsePathfinding, bAllowPartialPath
Activate Action Ability (UBTTask_ActivateActionAbility)Starts the ability the running action named and waits for it to endFallbackActivationTag, bFailWhenNoAbility
Activate Ability (UBTTask_ActivateAbility)Starts a named abilityAbilityClass, ActivationMode (unreal.AbilityActivationMode.BY_TAG, BY_EVENT), EventTag (shown as Activation Tag), bGrantAbilityIfMissing
Make Distance (UBTTask_MakeDistance)Backs away from the target without pathfindingTargetDistance (cm), MovementSpeed (0 to 1), Timeout, StuckTimeout
Blackboard keys the method writes: UCF_TargetActor, UCF_SelfActor, UCF_Distance, UCF_ActionId, UCF_Payload. The shipped blackboard BB_UCF_Basic holds UCF_TargetActor, UCF_Distance, UCF_ActionId and UCF_Payload.
Recipe: close in, swing, back off
Editor Python cannot build a behavior tree's shape. The shipped BT_UCF_AbilityAction already is this shape (a Sequence of Move Until Distance, Activate Action Ability and Make Distance, with a Wait), so duplicate it and tune its tasks:
bt = duplicate("/UniversalCombatFramework/Demo/AI/BehaviorTrees/BT_UCF_AbilityAction", F, f"BT_{N}_HeavyAttack")
pkg = bt.get_outermost().get_name()
nodes = [o for o in unreal.ObjectIterator(unreal.BTNode) if o.get_outermost().get_name() == pkg]
for n in nodes:
    kind = n.get_class().get_name()      # the plugin's task classes have no Python type of their own; match them by name
    if kind == "BTTask_MoveUntilDistance":
        n.set_editor_property("TargetDistance", 150.0)
    elif kind == "BTTask_MakeDistance":
        n.set_editor_property("TargetDistance", 450.0)
save(bt)
 
method = unreal.new_object(unreal.UCFBehaviorTreeExecutionMethod, outer=aset)
method.set_editor_property("AbilityToGrant", bp_class("/UniversalCombatFramework/Core/Abilities/GA_UCF_MontageAbility"))
method.set_editor_property("BehaviorTreeSequence", [bt])
payload = unreal.new_object(unreal.UCFMontagePayload, outer=method)
payload.set_editor_property("Montage", am_heavy)
method.set_editor_property("Payload", payload)
Use method as the action's ExecutionMethod in place of montage_method(...), then write the actions back and save the set. Keep a Distance Scorer on the action.
Check: reload the tree and print each task's TargetDistance; in Play, UCF.Debug.LogActionExecution 1 logs the tree starting and ending with the action.
A tree of another shape (a Selector, decorators, other tasks) is built by hand in the Behavior Tree editor: tell the customer which tasks in which order, from the table above.
State Trees
The brain is a State Tree when the AI Config's StateTree names one; editor Python cannot build or edit a State Tree's states. Use the shipped trees (ST_UCF_Core: notice, patrol, investigate, fight, walk home; ST_UCF_RoleBehavior: per combat role) or have the customer duplicate one and edit it in the State Tree editor. The plugin's tasks and conditions there:
TaskDoes
Build Decision ContextGathers distance, angle, health and threat each tick
Poll Action, Do ActionScores the actions and runs the chosen one
AI MovementRuns the movement profile
Poll Combat Role, Poll Focus Actor, Poll Last Known LocationRead the role, the focus target, where the target was last seen
Sync Action Set, Sync Reaction Set, Sync Movement Profile, UpdateActionSetSwap sets on a role change, or to a named Action Set
Territory Patrol, Territory Investigate, Return To Territory, Hold Out Of Combat, Monitor Combat LeashPatrol, search, walk home, stand down, watch the leash
ConditionPasses when
Awareness State At LeastThe target is noticed to a level
Target Eligible For Combat, Target Outside Leash, Pawn Outside Leash, Pawn On Its Ground, Territory Owns Ground, Resting Behavior IsTerritory and leash state
Action Executing, Action Recovering, Actions Blocked, Reaction Executing, ASC Has TagCombat state
Mistakes
SymptomCause and fix
The action never endsA tree waits forever: set BehaviorTreeTimeout, and check the ability reaches End Ability.
Activate Action Ability failsAbilityToGrant is empty, so the enemy holds no ability to start.
Move Until Distance never arrivesNo navmesh with bUsePathfinding on, or TargetDistance inside the target's capsule.

Brain, combat roles, targets, teams and turn-taking (AgentGuide/Enemy/BrainRolesTargets.md)

Tasks: which target an enemy picks when there are several players; enemies spreading across players; an enemy that only ever flanks; at most two attackers at once; enemies taking turns on one player; factions that fight each other; a fight that repeats exactly; choosing the brain.
All of it sits on the Enemy AI Config (UEnemyAIConfig), the pawn's AIConfig, plus a few Project Settings.
The AI Config
FieldDoes
TargetSelectorHow it picks a target (below). Empty picks the first registered target it may fight.
TargetFilterWhich actors it will fight at all; empty uses the built-in rule (never itself, never an ally, never an excluded team). A custom filter is a Blueprint child of UUCFTargetFilter (a Blueprint step).
bAutoRegisterForCombatRoles, RoleRegistrationParams (unreal.AIRoleRegistrationParams)Combat roles (below).
bIgnoreTargetRedistributionKeep its target when targets are shared out again.
DefaultActionSet, RoleActionSets; DefaultReactionSet, RoleReactionSets; DefaultMovementProfile, RoleMovementProfilesWhat it fights, reacts and moves with, per role.
AwarenessConfig, StimulusFiltersWhat it notices (AgentGuide/Enemy/AwarenessTerritory.md, AgentGuide/Enemy/Reactions.md).
StateTree (shown as Default State Tree)Empty runs the built-in brain: notice, investigate, close in, circle, attack, react, plus patrol and the walk home once the placed enemy's territory has posts. ST_UCF_Core runs the same phases as a State Tree the customer can edit; ST_UCF_RoleBehavior drives each combat role differently. Both under /UniversalCombatFramework/Demo/AI/StateTrees/.
DecisionContextParamsAggressionLevel (0 to 2) and line-of-sight trace settings.
ActionRecoveryTime, InterruptRecoveryTime, ActionRecoveryTimeRandomizationPause after each action (AgentGuide/Enemy/Actions.md).
bDeterministic, DefaultSeed, StartBarrierSecondsThe same picks every run, for a boss fight that repeats exactly; UCF.Determinism.Trace and UCF.Determinism.Compare check it.
Target selection
Instanced: make it with the config as outer.
Class (picker label)Picks
UAwarenessFilteredTargetSelector (Awareness Filtered Target Selector)Only targets the enemy has noticed (MinRequiredState, unreal.UCFAwarenessState), then asks its InnerSelector
UFirstTargetSelector (First Target Selector)The first registered target
UClosestTargetSelector (Closest Target Selector)The nearest
URandomTargetSelector (Random Target Selector)A random one, spreading enemies
UBalancedTargetSelector (Balanced Target Selector)The target with the fewest enemies on it
UFixedTargetSelector (Fixed Target Selector)The actor carrying the actor tag RequiredTag
Spread a pack over two players:
sel = unreal.new_object(unreal.AwarenessFilteredTargetSelector, outer=config)
sel.set_editor_property("InnerSelector", unreal.new_object(unreal.BalancedTargetSelector, outer=config))
config.set_editor_property("TargetSelector", sel)
save(config)
Combat roles
Roles share out what each enemy does in a group fight: UCF.Role.Attacker, .Flanker, .Waiter, .Supporter, .Elite. RoleRegistrationParams on the config: AllowedRoles (empty allows any), PreferredRole, Priority (0 to 1000, higher picks first), FitnessEvaluators (UDistanceRoleEvaluator IdealDistance, EffectiveRange; UCooldownRoleEvaluator CurrentRolePenaltyMultiplier; each with RoleWeights, a map of role tag to weight).
p = config.get_editor_property("RoleRegistrationParams")
p.set_editor_property("AllowedRoles", tags("UCF.Role.Flanker"))
p.set_editor_property("PreferredRole", tag("UCF.Role.Flanker"))
config.set_editor_property("RoleRegistrationParams", p)
save(config)
How many at once is a Project Setting: RoleLimits on unreal.UCFEnemySettings (unreal.RoleLimitConfig rows Role, Limit), with RoleReassignmentInterval and MinTimeInRole. A project setting changed from Python lasts until the editor closes (AgentGuide/Enemy/Python.md, Project Settings), so ask the customer to set it in Project Settings, Plugins, Universal Combat Framework Enemy, Combat Roles. Elite slots are unlimited.
Check: in Play, UCF.Debug.LogRoleAssignments 1 logs each assignment; the overlay from UCF.Debug.All 1 names each enemy's role.
Taking turns on one target
Put a Combat Token Gate (UUCFTokenGate, TokenTag UCF.Token.Attack, Cost 1) in each attack's CustomScoring.Gates (AgentGuide/Enemy/Actions.md). How many enemies may hold UCF.Token.Attack against one target is TokenBudgets in Project Settings (unreal.UCFTokenBudgetConfig rows TokenTag, Budget, ReissueDelay), or per target with a UCF Token Budget Component (UUCFTokenBudgetComponent) on the player Blueprint: add it as AgentGuide/Enemy/Python.md, Components on a Blueprint, shows, set its TokenBudgets to {tag("UCF.Token.Attack"): 1}, compile and save.
Teams
Every actor's team is its UCF Team component (UUCFTeamComponent): TeamId (a number; enemies default to 1, the player is 0), bFreeForAll, ExcludedTeamIds, AllowedHostileTeamIds, bIgnorePlayer, bIgnoreNeutrals, FightOnly (one actor and nothing else). An actor with no team component is neutral and can be fought. Enemies on AEnemyCharacterBase carry one as TeamComponent. Two factions: give each enemy Blueprint its own TeamId. The melee trace's TeamFilter decides whether a swing can hit allies. UCF.Debug.All 1 shows each actor's team.
Mistakes
SymptomCause and fix
Every enemy goes for the same playerNo selector, or a First or Closest selector; use Balanced or Random inside the awareness filter.
A role is never assignedbAutoRegisterForCombatRoles off, the role is outside AllowedRoles, or its limit is full.
Enemies fight each otherThey share no team and are on different TeamIds, or bFreeForAll is on.
Two enemies attack at once despite the token gateThe budget is above 1, or one attack lacks the gate.

Movement: spacing, circling and backing off (AgentGuide/Enemy/Movement.md)

Tasks: how far an enemy keeps from its target; circling and how often it switches direction; backing off when the player stares at it; flanking from an angle; different spacing per combat role; stopping farther or closer when an attack closes the gap.
Everything here is data. An enemy moves by its Movement Behavior Profile (UMovementBehaviorProfile), named on its AI Config as DefaultMovementProfile (AGENTS.md, Enemy Recipe 1, Step 8).
Recipe: a cautious duelist
Keeps about four meters away, circles the player, and backs off while the player looks at it.
movement = new_data_asset(unreal.MovementBehaviorProfile, F, f"Movement_{N}_Duelist")
movement.set_editor_property("DesiredDistance", 400.0)          # cm between the enemy and its target
movement.set_editor_property("DistanceTolerance", 0.15)
movement.set_editor_property("CrowdTolerance", 0.2)            # steps back once closer than 320 cm
movement.set_editor_property("bEnableStrafing", True)
movement.set_editor_property("StrafeTimeLimit", 4.0)
movement.set_editor_property("bAdjustDistanceByThreat", True)
movement.set_editor_property("ThreatDistanceScale", 0.5)        # up to 1.5 times the distance while stared at
movement.set_editor_property("bSwapStrafeOnHighThreat", True)
save(movement)
 
config = load(f"{F}/EnemyConfig_{N}")
config.set_editor_property("DefaultMovementProfile", movement)
config.set_editor_property("ActionRecoveryTime", 2.5)          # seconds between attacks, spent backing off and circling
save(config)
 
aset = config.get_editor_property("DefaultActionSet")
bands = [s for spec in aset.get_editor_property("Actions")
         for s in spec.get_editor_property("CustomScoring").get_editor_property("Scorers")
         if isinstance(s, unreal.UCFDistanceScorer)]
farthest = max(bands, key=lambda s: s.get_editor_property("Range").get_editor_property("MaxValue"))
r = farthest.get_editor_property("Range")
r.set_editor_property("MaxValue", max(r.get_editor_property("MaxValue"), 750.0))
farthest.set_editor_property("Range", r)
save(aset)
The profile only moves the enemy while no attack can start, so ActionRecoveryTime gives it that time after each attack; with none it attacks again as soon as an attack is ready and never backs off. CrowdTolerance 0.2 sends it back out past 320 cm after an attack; the default 0.45 lets it stand at 220 cm. While stared at, this enemy waits up to 400 x 1.15 x 1.5 = 690 cm out, past the 450 and 500 cm bands of the core recipe's attacks. An attack starts only where its Distance Scorer reaches ( below), so the last block stretches the band of the attack that reaches farthest to 750 cm, the farthest its approach window glides in. Without it the enemy circles at range and never attacks a player who keeps it on screen.
How long a stare takes to count is on the AI controller's Threat Detection component. The demo controller BP_UCF_EnemyController carries one; to change it, duplicate the controller into the customer's folder, set it on the pawn (AIControllerClass on the pawn's class defaults), and edit its class defaults:
ctrl = duplicate("/UniversalCombatFramework/Demo/Characters/Enemy/BP_UCF_EnemyController", F, f"BP_{N}_Controller")
threat = defaults(ctrl).get_editor_property("ThreatDetectionComponent")
threat.set_editor_property("PlayerLookAngleThreshold", 20.0)   # degrees off the enemy that count as looking at it
threat.set_editor_property("PlayerLookTimeThreshold", 1.0)     # seconds of looking before it counts
save(ctrl)
defaults(bp).set_editor_property("AIControllerClass", ctrl.generated_class())
save(bp)
Check: reload the config and print its DefaultMovementProfile and the stretched band's MaxValue. In Play, UCF.Debug.All 1 shows the enemy's movement state; it stops at about DesiredDistance, circles, opens the gap while the player keeps it centered on screen (UCF.Debug.Threat.Draw 1 draws the look cone), and still attacks from there.
The profile's fields
FieldDefaultDoes
DesiredDistance400Distance in cm the enemy keeps from its target
DistanceTolerance0.2How far past DesiredDistance still counts as close enough, as a share of it (0.05 to 0.5)
CrowdTolerance0.45How far inside DesiredDistance the enemy tolerates before stepping back, as a share of it
bEnableStrafingtrueCircle the target once at the distance
StrafePreferenceWeight1How strongly it prefers circling over standing
bAutoStrafeSwap, StrafeSwapThreshold, StrafeSwapCooldowntrue, 3, 2Switch circling direction when the other side scores that many times better
bEnableStrafeTimeLimit, StrafeTimeLimit, StrafeTimeLimitFluctuationtrue, 5, 2.5Switch direction after circling one way this long (seconds, plus or minus the fluctuation)
bRestAfterStrafeSwap, StrafeSwapRestTime, StrafeSwapRestFluctuationfalse, 0.5, 0.25Pause after a timed switch
bEnableStrafeRest, StrafeRestTimeLimit, StrafeRestDurationtrue, 10, 1.5Stop and rest after circling this long
bAdjustDistanceByThreat, ThreatDistanceScalefalse, 1Multiply the distance by 1 + threat x scale; threat climbs from 0 to 1 while the player looks at the enemy
bSwapStrafeOnHighThreatfalseSwitch circling direction once the player has stared long enough
PositioningRulesemptyExtra direction preferences, below
Angle preference. UAnglePreferenceRule in PositioningRules pulls the enemy toward an angle off the target's facing: PreferredAngle (0 in front, 90 at the side, 180 behind; default 90), AngleTolerance (30), DirectionCommitment (45), bAvoidInstead (stay away from that angle), Weight (0 to 1). Make it with unreal.new_object(unreal.AnglePreferenceRule, outer=movement) and write the list back. A flanker uses PreferredAngle 120 to 150.
Per combat role. RoleMovementProfiles on the AI Config takes unreal.RoleMovementProfileConfig rows (Role a UCF.Role.* tag, MovementProfile); roles not listed use DefaultMovementProfile. The demo ships one profile per role under /UniversalCombatFramework/Demo/AI/MovementProfiles/ (MovementProfile_UCF_Attacker, _Flanker, _Waiter, _Supporter, _Elite); duplicate one as a starting point.
Threat. UThreatDetectionComponent on the controller: PlayerLookAngleThreshold (15 degrees) and PlayerLookTimeThreshold (3 seconds). The controller's CombatControllerComponent turns it on (bEnableThreatDetection, on by default).
Getting in range to attack
The profile decides where the enemy waits between attacks; the enemy picks its next attack from there. An action can start only while the gap is inside its Distance Scorer's band (below MaxValue). The attack then closes the last gap through the UCF Approach Window on its montage (AGENTS.md, Enemy Recipe 1, Step 4): its StopDistanceOverride is the gap it leaves, and the pawn's UCF Approach component sets the rest: DefaultStopDistance, DefaultMaxApproachDistance (farthest it glides, 750 cm), SpeedLimit.
So the farthest the enemy waits, DesiredDistance x (1 + DistanceTolerance), times (1 + ThreatDistanceScale) while stared at when bAdjustDistanceByThreat is on, has to sit inside at least one attack's band.
Mistakes
SymptomCause and fix
The enemy hugs the playerDesiredDistance below about 150, or the profile is not the config's DefaultMovementProfile while bManageMovementProfilesAutomatically is on (the default).
It jitters back and forthDistanceTolerance too small for the distance; raise it toward 0.2.
It stays close after each attackAn attack is always ready, so it never has time to walk back. Set ActionRecoveryTime on the AI Config (the demo uses 2), or longer Cooldown.Duration on the attacks.
It circles but never attacksIt waits farther out than any attack's Distance Scorer reaches, often only while the player looks at it (bAdjustDistanceByThreat). Stretch the farthest attack's MaxValue past the farthest wait, as the recipe does, or lower DesiredDistance or ThreatDistanceScale.
It never backs off when stared atbAdjustDistanceByThreat off, or the controller has no Threat Detection component (the demo controller has one).
It changes direction constantlyStrafeTimeLimit short with bAutoStrafeSwap on; raise StrafeSwapThreshold or StrafeTimeLimit.
A role's profile is ignoredThe role tag on the row does not match the role the enemy holds; UCF.Debug.LogRoleAssignments 1 logs it.

Editor Python: what can be set, and how (AgentGuide/Enemy/Python.md)

Rules every other file relies on. Read this when a set_editor_property call is refused, when a value you wrote is gone after a reload, or before you add components, rows or instanced objects.
Tasks: set a property; edit a row in an array; add an instanced object (an execution method, a scorer, a selector); edit a component on a Blueprint; give a montage sections; add a gameplay tag; check an asset; save a Project Settings value; read the log.
Setting properties
  • obj.set_editor_property("Name", value) takes the C++ name (bAlwaysAware) or the Python name (always_aware). It refuses a property the editor shows read-only, and a class-defaults-only property on anything that is not a template (an asset, a class default object, or an object inside an asset).
  • Arrays and their elements come back as copies. Edit the element, put it back in the list, and write the whole list:
    actions = list(aset.get_editor_property("Actions"))
    a = actions[0]
    a.set_editor_property("SelectionWeight", 0.8)
    actions[0] = a
    aset.set_editor_property("Actions", actions)
  • Nested structs (an action's Cooldown, a scorer's Range) too: read, edit, write back to the owner, as AGENTS.md's range_scorer does.
  • A whole-array write does not run the editor's own fill-ins: a new action written this way gets no execution method, so make one (montage_method).
Instanced objects
Execution methods, payloads, scorers, gates, target selectors, positioning rules, stimulus filters, hit effects and defense rules live inside the asset holding them.
  • Make one with unreal.new_object(cls, outer=<the asset that holds it>). A payload's outer is its execution method.
  • Never give a class default object as the outer (unreal.get_default_object(...)), not even to look at a class: the next object of that class with the same name takes it as its template, and the asset holding it fails to save.
Components on a Blueprint
  • A component the C++ base creates is read from the class defaults: on the pawn, defaults(bp).get_editor_property("MeleeTraceComponent") (also Loadout, EquipmentManagerComponent, Vitals, CharacterMovement, Mesh); on the controller, ThreatDetectionComponent, MovementEvaluatorComponent, ActionEvaluationComponent, AwarenessComponent, CombatControllerComponent, UCFBrainComponent. Edit it there and save the Blueprint.
  • A component the Blueprint adds lives in its construction script; bp_component(bp, "<name start>") from AGENTS.md returns its template. Edit it, compile with unreal.BlueprintEditorLibrary.compile_blueprint(bp) and save.
  • Adding a component:
    sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
    root = sds.k2_gather_subobject_data_for_blueprint(bp)[0]
    params = unreal.AddNewSubobjectParams(parent_handle=root, new_class=unreal.UCFTerritoryComponent, blueprint_context=bp)
    handle, fail = sds.add_new_subobject(params)
Montage sections
The engine's Python cannot give a montage sections. Use the plugin's tool:
ucf.set_montage_sections(montage, [("Slash", 0.0), ("Stab", 1.1), ("Spin", 2.3)])
It replaces every section and saves the montage. Each section ends the montage, so an action whose payload names a StartSection plays only that part. A third value names the section it plays on into instead, or its own name to loop it: ("Hold", 0.4, "Hold").
Gameplay tags
A tag must exist before a property can hold it. The plugin's role, token, stimulus, state and vital tags exist already. To add one, such as a role or a token pool of the project's own:
ucf.add_gameplay_tag("UCF.Role.Guardian", "Stays beside the boss")
It writes Config/DefaultGameplayTags.ini and the tag can be used at once.
Project Settings
unreal.get_default_object(unreal.UCFEnemySettings) edits the values under Project Settings, Plugins, Universal Combat Framework Enemy (RoleLimits, TokenBudgets, DefaultTargetSelectorClass, DefaultTargetFilterClass, vital tags). Editor Python cannot write them to the project's config file before UE 5.8, so a change lasts until the editor closes: ask the customer to set the value in Project Settings, or on UE 5.8 save it with Epic's MCP ConfigSettingsToolset.
Checks
  • ucf.validate_asset(asset) runs the checks the editor's Validate Assets runs (Action Sets, Reaction Sets, damage configs) and returns one line per problem.
  • After Play, log_warnings() returns UCF's warnings; each names the asset and the fix.

Reactions: flinches, parries, dodges and counters (AgentGuide/Enemy/Reactions.md)

AGENTS.md, Enemy Recipe 1, Step 7, makes a flinch and Enemy Recipe 4 a parry. This file covers the rest of a Reaction Set.
Tasks: flinch only sometimes, or not twice in a row; different reactions for hits from the front and from behind; parry some swings and dodge others; parry only light attacks; not react to what the enemy cannot see; a counter after a parry; reactions only in one phase.
How a reaction is picked
Something happens to the enemy (it takes damage, a swing is announced near it) and arrives as a stimulus tag. Each trigger rule (unreal.UCFReactionTriggerRule) in TriggerRules that answers that tag, asked highest RulePriority first, rolls its Chance; the first that fires picks one of the reactions it links, weighted by WeightMultiplier. A set with no trigger rules reacts to nothing.
StimulusArrives when
UCF.Stimulus.DamageTakenThe enemy takes a hit (the duplicated demo Blueprint reports it).
UCF.Stimulus.AttackTelegraphedA swing near it is announced by a UCF Telegraph Window on the attacker's montage.
UCF.Stimulus.StanceBrokenThe enemy's Blueprint reports it when the stance vital empties (AgentGuide/Enemy/VitalsEncountersDebug.md); the plugin never sends it on its own.
A rule's fields
FieldDoes
RuleIdName in logs.
OnStimulusThe stimulus tag it answers.
RequireContextTags, BlockContextTagsTags the stimulus must or must not carry: the attacker's damage tags and the telegraph's Tags arrive here, so a parry rule can skip unblockable swings.
ConditionsGates that must all pass (below).
ReactionLinks (unreal.UCFReactionTriggerLink)ReactionId, WeightMultiplier.
ReactionCategoryAnswer with any reaction of this category instead of named links.
RulePriorityHigher is asked first.
Chance0 to 1.
MinIntervalSeconds before the rule may fire again.
A reaction's fields (unreal.ReactionSpec)
ReactionId, ExecutionMethod (as an action's; montage_method from AGENTS.md), Priority, SelectionWeight, Cooldown (unreal.ActionCooldown), CustomScoring (Scorers, Gates), AddTags, RequiresTags, BlockTags (tags on the enemy itself), ReactionCategory, bCancelCurrentAction (cut the attack it was making).
UCF.State.ReactionActive in one reaction's AddTags and another's BlockTags stops them overlapping.
Reaction gates
Put them in a rule's Conditions or a reaction's CustomScoring.Gates.
Class (picker label)Passes whenFields
UUCFGate_IncomingAngle (Incoming Angle Gate)The blow arrives inside an arc in frontHalfAngleDegrees, bPassWithoutDirection, bInvert (behind instead)
UUCFGate_TimeToImpact (Time To Impact Gate)Enough time is left before an announced swing landsMinSeconds, MaxSeconds
UUCFGate_StimulusMagnitude (Stimulus Magnitude Gate)The blow is worth answeringMinMagnitude, MaxMagnitude
UUCFGate_SourceDistance (Source Distance Gate)The attacker is in rangeMinDistance, MaxDistance (cm), bPassWithoutSource
UUCFHitsTakenGate (Hits Taken Gate)Enough blows got through lately, this one includedHits (2), WithinSeconds (4); reads the enemy's UCF Defense
The angle gate tells front from back only: a side hit plays the front or the back reaction.
A guard after a run of hits: a DamageTaken rule with BlockContextTags UCF.Defense.Block and UCF.Defense.Parry, a Hits Taken Gate in its Conditions and a Chance below 1, linking a reaction that raises and holds the guard. An enemy that plays montages holds it with its reaction's Montage Payload: HoldSection names the montage section that loops, MinHoldSeconds and MaxHoldSeconds how long, a random time between the two, after which the montage plays on into the section linked after it (link the sections with ucf.set_montage_sections, AgentGuide/Enemy/Animation.md). The reaction's AddTags carry UCF.State.Blocking, the tag the Defense Rule Set's Guard rule requires, plus UCF.State.IsMovementBlocked to stand still and UCF.Action.BlockActions. The demo two-handed enemy keeps one as an example, switched off: its Guard reaction holds the Hold section of AM_UCF_TwoHanded_Guard for 1.5 to 3 s and is off, and its rule DodgeOrGuardAfterHits (two blows within 4 s, chance 0.5) links only that reaction, so the rule never answers and a second blow falls to the next rule. An enemy that plays the player's action graph holds the graph's own guard instead, an Action Graph Combo step held for a random time.
Recipe: hits from the front and from behind
def angle_gate(owner, half, invert):
    g = unreal.new_object(unreal.UCFGate_IncomingAngle, outer=owner)
    g.set_editor_property("HalfAngleDegrees", half)
    g.set_editor_property("bInvert", invert)
    return g
 
def reaction(owner, rid, montage, gates, cooldown=1.0):
    r = unreal.ReactionSpec()
    r.set_editor_property("ReactionId", rid)
    r.set_editor_property("ExecutionMethod", montage_method(owner, montage))
    scoring = r.get_editor_property("CustomScoring")
    scoring.set_editor_property("Gates", gates)
    r.set_editor_property("CustomScoring", scoring)
    cd = r.get_editor_property("Cooldown")
    cd.set_editor_property("Duration", cooldown)
    r.set_editor_property("Cooldown", cd)
    return r
 
front = reaction(rset, "HitFront", am_hit_front, [angle_gate(rset, 90.0, False)])
back = reaction(rset, "HitBack", am_hit_back, [angle_gate(rset, 90.0, True)])
rule = unreal.UCFReactionTriggerRule()
rule.set_editor_property("RuleId", "FlinchOnHit")
rule.set_editor_property("OnStimulus", tag("UCF.Stimulus.DamageTaken"))
links = []
for rid in ("HitFront", "HitBack"):
    link = unreal.UCFReactionTriggerLink()
    link.set_editor_property("ReactionId", rid)
    links.append(link)
rule.set_editor_property("ReactionLinks", links)
rule.set_editor_property("Chance", 0.7)
rule.set_editor_property("MinInterval", 1.5)
rset.set_editor_property("Reactions", [front, back])
rset.set_editor_property("TriggerRules", [rule])
save(rset)
Check: ucf.validate_asset(rset) returns nothing; in Play, UCF.Debug.LogReactions 1 logs each rule that fires or is skipped, with the reason.
Parry some swings, dodge others
Two rules on UCF.Stimulus.AttackTelegraphed: the parry rule at RulePriority 10 with Chance 0.4, MinInterval 2 and a BlockContextTags of the tag the unblockable swings' telegraph carries; the dodge rule at priority 0 with Chance 0.5. A swing the parry rule skips or does not roll falls to the dodge. A Time To Impact Gate (MinSeconds 0.15) on each keeps the enemy from starting an answer it cannot finish. The attacker's montage needs a UCF Telegraph Window with a Broadcast.Shape ( AGENTS.md, Enemy Recipe 4).
For i-frames on the dodge, a UCF State Tag Window holding UCF.State.Intangible over its evasive frames. A parry that stops the hit is a defense rule: AgentGuide/Enemy/WeaponsDamageDefense.md.
Noticing
What the enemy can notice before an attack lands: StimulusFilters on the AI Config (UUCFStimulusFilter_FacingCone HalfAngleDegrees, UUCFStimulusFilter_Awareness MinimumState, UUCFStimulusFilter_LineOfSight TraceChannel, EyeHeight; each has BypassOnContextTags). Without them it notices everything in range.
Movesets per weapon and per role
An ItemSets row on the pawn's UCF Enemy Loadout names the reactions for the item the enemy holds, per role where the row names one; RoleReactionSets on the AI Config takes unreal.RoleReactionSetConfig rows per role.
Mistakes
SymptomCause and fix
Never reactsNo trigger rule, or the rule's ReactionLinks name an ID no reaction has.
Never parriesThe attacker's montage has no telegraph window or its shape is empty, or Chance rolls low; a valid low chance can miss several swings in a row.
Reacts to every hit in a comboRaise the rule's MinInterval or the reaction's Cooldown.Duration.
Back hits play the front reactionBoth reactions lack an angle gate, or both have bInvert the same way.

Vitals, death, encounters, settings and debugging (AgentGuide/Enemy/VitalsEncountersDebug.md)

Tasks: more health; a stance meter that breaks into a stun; stamina for the enemy; what happens on death; a fight that starts when the player walks in and shows a boss bar; turning off the demo hit effects; finding out why an enemy does nothing.
Vitals
The pawn's UCF Vitals component (Vitals) holds Vitals rows (unreal.UCFVitalDefinition): VitalTag, MaxValue, RegenRatePerSecond, RegenDelaySeconds, DepletedLooseTag (held while empty), DepletedResultTag (on the hit that empties it), DepletedGameplayEvent (a gameplay event sent to the enemy's own ability system once when it empties, starting a granted ability that lists the tag as a trigger; a Reaction Set never hears it). The duplicated demo enemy has health and stance rows.
A stance meter that breaks:
vit = defaults(bp).get_editor_property("Vitals")
rows = list(vit.get_editor_property("Vitals"))
names = [str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("VitalTag"))) for r in rows]
if "UCF.Vital.Stance" in names:                   # the duplicated demo enemy has one
    stance = rows[names.index("UCF.Vital.Stance")]
else:
    stance = unreal.UCFVitalDefinition()
    stance.set_editor_property("VitalTag", tag("UCF.Vital.Stance"))
    rows.append(stance)
stance.set_editor_property("MaxValue", 100.0)
stance.set_editor_property("RegenRatePerSecond", 15.0)
stance.set_editor_property("RegenDelaySeconds", 2.0)
stance.set_editor_property("DepletedLooseTag", tag("UCF.State.StanceBroken"))
vit.set_editor_property("Vitals", rows)
save(bp)
Attacks drain it through AdditionalVitalDamage on their damage configs (AgentGuide/Enemy/WeaponsDamageDefense.md). DepletedLooseTag holds UCF.State.StanceBroken on the enemy from the moment the pool empties until it starts refilling, 2 seconds here; list that tag in each action's BlockTags so a stunned enemy does not swing.
The stun animation is a reaction on UCF.Stimulus.StanceBroken (AgentGuide/Enemy/Reactions.md) playing the customer's stun montage, and the plugin never sends that stimulus. Sending it is a Blueprint step for the customer: in the enemy Blueprint, bind the Vitals component's On Vital Depleted, and when its Vital Tag is UCF.Vital.Stance, call Report Stimulus To with Receiver set to the enemy and a stimulus whose Tags hold UCF.Stimulus.StanceBroken. The call reports on the server only and does nothing on a client.
Which vital counts as health and as stamina is HealthVitalTag and StaminaVitalTag in Project Settings.
Death
With bAutoHandleDeathOnHealthDepleted on (the default) on the controller's CombatControllerComponent, an emptied health vital shuts the enemy down: brain, actions, reactions, traces, role. bDropWeaponOnDeath drops its weapon. Playing a death montage or a ragdoll is the controller's On Death event in Blueprint, a step for the customer; the demo Blueprints show it.
Encounters and boss bars
A placed UCF Encounter Trigger (AUCFEncounterTrigger) names a place or opens a fight when the player walks into its TriggerBox: EncounterName, Enemies (on the placed actor only), Payload, bTriggerOnce, StartCondition (PLAYER_ENTERS, MANUAL), bEndWhenPlayerLeaves. The demo's /UniversalCombatFramework/Demo/Game/BP_UCF_BossArenaTrigger also ends the fight as Defeated once its enemies die, so spawn that one (AGENTS.md, Enemy Recipe 5, step 4).
A boss bar is a widget bound to the UCF Encounter Subsystem's On Encounter Started event; the demo's WBP_UCF_EncounterBar is one. Adding it to the customer's HUD is a Blueprint step.
Project Settings
unreal.get_default_object(unreal.UCFEnemySettings): RoleLimits, AdditionalRoles, RoleReassignmentInterval, MinTimeInRole, TokenBudgets, DefaultTargetSelectorClass, DefaultTargetFilterClass, HealthVitalTag, StaminaVitalTag. The demo hit effects are switched off with Load Demo Hit Effects under Project Settings, Plugins. Before UE 5.8 a value set from Python lasts until the editor closes (AgentGuide/Enemy/Python.md), so ask the customer to set it in Project Settings, Plugins, Universal Combat Framework Enemy.
Debugging an enemy
Console command (in Play)Shows
UCF.Debug.All 1Every overlay above each enemy: awareness, brain, action, role, team
UCF.Debug.WatchPawn <name>Narrows the overlays to one enemy
UCF.Debug.Scoring 1Each action's score, and why a gate refused it
UCF.Debug.LogActionDecisions 1, UCF.Debug.LogActionExecution 1Each pick, and each action starting and ending
UCF.Debug.LogReactions 1Each trigger rule firing or skipped, with the reason
UCF.Debug.LogRoleAssignments 1Role assignments
UCF.Debug.Melee.DrawTracing 1Every melee sweep
UCF.Debug.Movement.DrawScoring 1, UCF.Debug.Movement.DrawAvoidance 1Movement direction scores and avoidance
UCF.Debug.Threat.Draw 1The player's look cone and the threat level
UCF.Debug.Stimulus.Draw 1Announced swings and who they reach
UCF.Debug.Warp 1Where each motion warp lands
UCF.Debug.AnimEffects 1Each footstep and other anim effect asked for, and what answered it
UCF.Logs VerboseRaises every UCF log category; UCF.Logs puts them back
After Play, log_warnings() returns UCF's warnings, each naming the asset and the fix. ucf.validate_asset(asset) checks an Action Set, Reaction Set or damage config without playing.
Mistakes
SymptomCause and fix
Never diesNo UCF.Vital.Health row, or bAutoHandleDeathOnHealthDepleted off.
The stance never breaksNo stance row on the enemy, or the attacks' damage configs drain none.
The stance empties but no stun playsNothing reports UCF.Stimulus.StanceBroken (the On Vital Depleted step above), or the Reaction Set has no rule on it.
The fight never startsThe trigger box does not cover where the player enters, StartCondition is MANUAL, or it already fired with bTriggerOnce.
A Project Settings value is gone after a restartIt was set from Python; set it in Project Settings.

Weapons, damage and defense (AgentGuide/Enemy/WeaponsDamageDefense.md)

AGENTS.md, Enemy Recipe 2, makes a weapon and Enemy Recipe 1, Step 3, a damage config. This file covers the rest: loadouts, hit volumes, what a hit is worth beyond health, effects on landing, and an enemy that blocks or parries.
Tasks: drop the weapon on death; several weapons; heavy hits that drain stamina or stance and knock the player back; sparks on metal; swings that spare other enemies; an enemy that blocks frontal hits while guarding; a parry that turns a blow aside.
Weapons and loadout
An enemy holds an item, the same item definition a player draws (unreal.UCFItemDefinition, AgentGuide/Player/ItemsEquipment.md). Its Equippable fragment carries TraceSockets (unreal.UCFTraceSocket: ID, SourceComponentTag, Shape (unreal.UCFTraceShape: SPHERE, CAPSULE, CAPSULE_TWO_POINT), SocketOrBoneName, EndSocketOrBoneName, Radius, CapsuleHalfHeight, LocalOffset), HoldPlaces (the hand and its Offset), AnimLayerClass and bIsMainWeapon; its Visuals fragment the mesh, its Guard fragment the block and parry rules it lends, its World Item fragment what lets it drop.
The pawn's UCF Enemy Loadout (Loadout): StartingItems (item definitions drawn in order as the enemy begins play) and ItemSets (unreal.UCFEnemyItemSets: Item, CombatRole, ActionSet, ReactionSet). Its UCF Equipment Manager (EquipmentManagerComponent) draws them: DefaultItem (held while nothing else is, such as fists), BodyPlaces (each place's socket). The controller's UCF Combat Controller (CombatControllerComponent) has bDropWeaponOnDeath, which drops what the enemy holds as items a player can pick up.
The Equipment Manager passes each anim effect the enemy plays on to the items it holds, so an item's Swing Trail fragment draws its trail on an anim effect window. An enemy Blueprint must not pass the effects on to its item as well, or the item hears each one twice.
Damage configs
UUCFDamageConfig: Damage, AdditionalVitalDamage (unreal.UCFVitalDamage rows VitalTag, Amount), DamageTypeClass, DamageTags, MultiHitInterval (seconds before the same swing hits one target again; -1 once), MaxTargetsPerSwingOverride (-1 uses the trace's), bUseAuthoredHitDirection, AuthoredHitDirectionLocal, HitEffects.
Hit effect (picker label)DoesFields
UUCFPredictedGameplayCueHitEffect (UCF Play Gameplay Cues)Plays cues on the attacker and the targetAttackerCues, TargetCues, SurfaceSet (UUCFImpactSurfaceSet: cue suffix per physical material or surface)
UUCFPhysicsImpulseHitEffect (UCF Apply Physics Impulse)Shoves the struck bodyHitBoneForce, HitOverallForce, HitRotationalForce, bVelocityChange
UUCFApplyGameplayEffectHitEffect (UCF Apply Gameplay Effect)Applies a gameplay effectGameplayEffect, Level
Every hit effect also has AffectedSides, SuppressOnResultTags, RequireAnyResultTags (run only on Blocked, Parried and the like), RequireAnyTargetTags, SuppressOnTargetTags, bRequireDamageApplied, bRunOnSceneryHits. Make each with the damage config as outer.
A heavy hit that drains stance and knocks back:
dmg = new_data_asset(unreal.UCFDamageConfig, F, f"Damage_{N}_Slam")
dmg.set_editor_property("Damage", 35.0)
stance = unreal.UCFVitalDamage()
stance.set_editor_property("VitalTag", tag("UCF.Vital.Stance"))
stance.set_editor_property("Amount", 40.0)
dmg.set_editor_property("AdditionalVitalDamage", [stance])
push = unreal.new_object(unreal.UCFPhysicsImpulseHitEffect, outer=dmg)
push.set_editor_property("HitOverallForce", 800.0)
dmg.set_editor_property("HitEffects", [push])
save(dmg)
The vital must exist on the target: a row on its vitals component (AgentGuide/Enemy/VitalsEncountersDebug.md).
The pawn's melee trace
MeleeTraceComponent on the pawn: DefaultDamageConfig, TeamFilter (unreal.UCFTeamFilter: NO_FILTER, ENEMIES_ONLY, FRIENDLIES_ONLY, NEUTRAL_ONLY), MaxTargetsPerSwing, HitResetInterval, PassThroughTags (UCF.State.Intangible lets i-frames work), SubStepDistance, bDrawDebug. The demo enemy's TeamFilter is ENEMIES_ONLY, so its swings spare other enemies.
Blocks and parries on the enemy
A Defense Rule Set (UUCFDefenseRuleSet) lists Responses run in order and OutcomeEffects. The pawn's UCF Defense component (Defense) runs its DefenseSet and Responses; an item it holds lends its Guard fragment's sets.
Response (picker label)DoesFields
UUCFDefenseRule_Guard (UCF Guard)Soaks a hit arriving inside an arcArcHalfAngleDegrees, DamageMultiplier (0 blocks all)
UUCFDefenseRule_Scale (UCF Scale Damage)Scales a hitDamageMultiplier
UUCFDefenseRule_Invulnerable (UCF Invulnerable)Takes nothing
Every response has RequiredTags and BlockedTags (shown as Required and Blocked Defender Tags: what the enemy must hold, such as UCF.State.Blocking), ResultTag (what the hit is called: the attacker's effects read it), RequiredAttackTags, BlockedAttackTags, and a cost (CostVitalTag, FlatCost, CostPerDamage).
Blocks from the front while guarding:
rules = new_data_asset(unreal.UCFDefenseRuleSet, F, f"DefenseRuleSet_{N}")
guard = unreal.new_object(unreal.UCFDefenseRule_Guard, outer=rules)
guard.set_editor_property("RequiredTags", tags("UCF.State.Blocking"))
guard.set_editor_property("ArcHalfAngleDegrees", 70.0)
guard.set_editor_property("DamageMultiplier", 0.0)
rules.set_editor_property("Responses", [guard])
save(rules)
defaults(bp).get_editor_property("Defense").set_editor_property("DefenseSet", rules)
save(bp)
The guard holds while the enemy carries UCF.State.Blocking: a UCF State Tag Window on a block reaction's montage, or AddTags on a block action or reaction. The demo's two-handed weapon uses DefenseRuleSet_UCF_TwoHanded and GA_UCF_TwoHanded_Block. For a parry, a second Guard response with a narrower arc, RequiredTags of the parry window's tag and its own ResultTag, placed first.
Check: reload the rule set and print each response's class, tags and arc. In Play, a frontal hit while the enemy blocks deals nothing.
Mistakes
SymptomCause and fix
Hits pass throughSocketIDs on the window differ from the ID of a TraceSockets row on the held item's Equippable fragment.
Enemies hit each otherThe trace's TeamFilter is NO_FILTER; set ENEMIES_ONLY.
A stance or stamina drain does nothingThe target has no row for that vital.
The enemy never blocksNothing gives it UCF.State.Blocking while it guards, or the rule set is on neither the pawn's Defense component nor the Guard fragment of an item it holds.

Action graphs: every card, edited from Python (AgentGuide/Player/ActionGraphs.md)

AGENTS.md, Player Recipe 2, builds a combo from montage moves and input transitions. This file covers the rest of the graph: other kinds of moves, a move's settings, transitions back to idle, tag gates and conditions on a transition, sub graphs, and editing or removing what exists.
Tasks: a move held while a button is down (a guard) and released back to idle; a move that fires an ability or waits; a heavy attack that cannot be canceled early; tags on the character while a move runs; a transition only while a tag is held or only in one stick direction; the next attack starting at once; moves that exist only while an item is drawn; renaming, editing or removing a move or a transition.
How a move is edited
ucf.get_node_settings(graph, name) returns the move's settings as an unreal.UCFActionNode; edit the copy, nested fields included, and hand it to ucf.set_node_settings(graph, name, settings):
s = ucf.get_node_settings(graph, "Heavy")
s.cancellation.cancel_window_start = 0.3        # nothing may cut the heavy for 0.3 s
ucf.set_node_settings(graph, "Heavy", s)
print(ucf.compile_action_graph(graph))
save(graph)
Every edit waits for ucf.compile_action_graph before it reaches the game; compile after the last edit and before saving. ucf.describe_action_graph(graph) then lists each move with its payload, the values changed from their defaults, its state tags, costs, gates and hooks, and each transition with its tags and conditions.
On Epic's MCP, set_node_settings cannot make a new cost, gate or hook, since the MCP has no owner to make it in. Add them on the move's card instead, the object that owns the move's payload: get_node_settings returns the payload's path, and the card's path is that path without its last part (.../AG_Knight.AG_Knight:<graph>.<card>). Call ObjectTools.set_properties on the card with {"ActionNodeData": {"Costs": ["/Script/UCFActions.UCFActionCost_Vital"]}} (or Gates, Hooks), read the card back with ObjectTools.get_properties (properties: ["ActionNodeData"]) for each new object's path, set the object's own properties there, then compile_action_graph. Everything else goes through set_node_settings.
A move's settings (unreal.UCFActionNode)
FieldHolds
NodeNameThe move's name. Write another name to rename it; transitions follow.
Execution (unreal.UCFNodeExecution)Payload: what the move does (below). InputBufferOverride (unreal.UCFInputBufferOverride: USE_GRAPH_DEFAULT, IGNORE, ACCEPT_FIRST, ACCEPT_LAST): what an early press does. bOverrideLateInputGrace with LateInputGrace (seconds, 0 off): this move's own late input grace in place of the graph's. bRetriggerFromRootOnFailedStart: a move that cannot start goes back to idle and tries the same press once more.
Cancellation (unreal.UCFNodeCancellation)CancelWindowStart (seconds, default 0.1): the earliest an Interrupt transition may cut the move. bCanBeCancelled, CancellableByInputs, IgnoredCancelInputs: whether, and by which input tags, a press may cancel the move outright.
State (unreal.UCFNodeState)AppliedTags: tags the character holds while the move runs, such as UCF.State.Blocking for a guard or UCF.State.HyperArmor.
Costs, Gates, HooksStamina costs, cooldowns and resource checks, and effects while the move runs: AgentGuide/Player/GatesCostsHooks.md.
Payloads: what a move does
ucf.add_montage_node makes a Play Montage move. ucf.add_node(graph, name, payload_class) makes any other kind; read its payload from get_node_settings(...).get_editor_property("Execution").get_editor_property("Payload"), set its fields, and write the settings back. On Epic's MCP, add_node takes the payload's class path, such as /Script/UCFActions.UCFHoldActionPayload.
Class (editor label)DoesFields
UUCFMontageActionPayload (Play Montage)Plays a montageMontage, PlayRate, SectionName (start from a section; see AgentGuide/Player/Python.md for adding sections), ChainWithoutWindow (label When No Window Is Authored; AT_COMPLETION starts the next move when this one ends, FROM_ENTRY lets the next press start it at once), BackMontage, LeftMontage, RightMontage (played in place of Montage when the stick pushes that way from the body's facing; empty plays Montage), bTurnToInputAtStart (turns the body to the stick as the move starts while rotation follows movement, then plays Montage), StopDistance (cm between the bodies this attack stops at; -1 uses a playing window's, else the weapon's, else the style's; AgentGuide/Player/TargetingStylesSteering.md), MakeRoomSeconds (-1 follows the style, 0 skips the step back for this move, above 0 turns it on), TurnSpeed (degrees per second the move turns the body to its facing; -1 follows the attack approach's AttackTurnSpeed, else the character's rotation rate; 0 at once; the demo's rolls use 1440)
UUCFHoldActionPayload (Hold)Runs until a transition leaves it, so its state tags stay on as long as the button is held. Plays no animationbOpenActionWindow (on: any input leaves at once)
UUCFDelayActionPayload (Delay)Waits, then ends so its Action Completed transition firesDelaySeconds, bOpenActionWindow
UUCFAbilityEventActionPayload (Trigger Ability / Event)Sends a gameplay event to the character, or activates its abilities by tagMode (SEND_EVENT, ACTIVATE_BY_TAG), EventTag, EventMagnitude, AbilityTags, bEndImmediately
UUCFPlayPairedActionPayload (Play Paired Action)Starts a synced two-body moveAgentGuide/Player/PairedActions.md
Recipe: a held guard with a parry window
The guard plays the customer's guard animation and holds its pose while the guard button is down; releasing it returns to idle (a transition to ROOT ends the running move). The move holds UCF.State.Blocking, and the first frames of the raise hold UCF.State.Parrying, which is what a guard rule set reads (AgentGuide/Player/DamageDefense.md).
am_guard = ucf.create_montage_from_animation(load("/Game/.../Guard"), F, f"AM_{N}_Guard", enable_root_motion=False)
L = length(am_guard)
ucf.set_montage_sections(am_guard, [("Raise", 0.0, "Hold"), ("Hold", L * 0.5, "Hold")])   # the second half loops while held
w = ucf.add_notify_state_to_montage(am_guard, unreal.UCFStateTagNotifyState, 0.0, min(0.25, L * 0.5))
w.set_editor_property("Tags", tags("UCF.State.Parrying"))
save(am_guard)
 
ucf.add_montage_node(graph, "Guard", am_guard, 1.0)
s = ucf.get_node_settings(graph, "Guard")
s.state.applied_tags = tags("UCF.State.Blocking")
s.cancellation.cancel_window_start = 0.0        # a quick tap lets go at once
ucf.set_node_settings(graph, "Guard", s)
 
ucf.add_transition(graph, "ROOT", "Guard", "UCF.Input.Guard")
ucf.add_transition(graph, "Guard", "ROOT", "UCF.Input.Guard", unreal.UCFTransitionTrigger.ON_COMPLETED, unreal.UCFTransitionTiming.INTERRUPT)
print(ucf.compile_action_graph(graph))
save(graph)
  • The item's mappings need a row for IA_UCF_Guard on UCF.Input.Guard (AGENTS.md, Player Recipe 2, Step 6). Both demo mapping contexts map it already.
  • Pick the loop point from the animation: the frame where the guard is fully up. Tell the customer the times you picked.
  • The looping guard opens no action window, so every way out of it is an INTERRUPT transition: the release above, and an attack out of the guard. A release that waits for the window never lands.
  • A guard whose pose comes from the item's animation layer reading UCF.State.Blocking, as the demo's do, needs no montage: make the move with ucf.add_node(graph, "Guard", unreal.UCFHoldActionPayload) instead, with the same tags and transitions.
Check: ucf.describe_action_graph(graph) lists Guard plays AM_..._Guard ...; state tags UCF.State.Blocking, UCF.Input.Guard, Input Pressed ... -> Guard from ROOT and UCF.Input.Guard, Input Released, Interrupt ... -> ROOT from Guard. unreal.AnimationLibrary.get_animation_notify_events(am_guard) lists the State Tag Window, and am_guard.get_num_sections() is 2.
Transitions
ucf.add_transition(graph, from_node, to_node, input_tag, fires_on, timing, priority); to_node may be ROOT.
fires_on (unreal.UCFTransitionTrigger)Editor labelFires when
ON_STARTEDInput PressedThe input is pressed (combos)
ON_COMPLETEDInput ReleasedThe input is released (letting go of a hold)
ON_CANCELLEDInput Released EarlyThe input is released before its Input Action's hold trigger finishes
AUTOAction CompletedThe move ended on its own; input tag ""
ON_FAILEDAction FailedThe move could not start (a cost, a gate); input tag ""
timing is WAIT_FOR_WINDOW (the press waits for the running move's action window) or INTERRUPT (it cuts the running move once CancelWindowStart has passed: dodges and parries). Higher priority wins between transitions on the same input; a transition with conditions wins over an equal one without.
Dodge from every move: one add_transition(graph, move, "Dodge", "UCF.Input.Dash", ON_STARTED, INTERRUPT, 10) per move, as AGENTS.md, Player Recipe 3, does, or one add_alias(graph, "Dodge", "UCF.Input.Dash", ON_STARTED, INTERRUPT, 10), which also reaches moves added later and the moves a sub graph imports. required_tags and blocked_tags on an alias route one press to different moves by the character's tags.
A dodge per direction: one Play Montage move whose Montage is the forward dodge and whose BackMontage, LeftMontage and RightMontage hold the others; the stick's push against the body's facing picks one as the move starts, and in multiplayer the player's own machine makes the pick and the server plays the same. With bTurnToInputAtStart on, a character whose rotation follows its movement turns to the push and plays Montage, so one roll goes every way; locked on or facing the camera, it plays the direction montages instead. The demo routes Dash by style this way: AG_UCF_Sword sends it to Hop under UCF.Style.OverShoulder, to Dodge Locked under UCF.State.LockedOn, and to Dodge (the turning roll) otherwise.
Transition settings
ucf.get_transition_settings(graph, from_node, to_node, input_tag, fires_on=None) returns an unreal.UCFActionTransition with InputTag, Trigger, Timing, Priority, RequiredTags, BlockedTags (tags on the character; blocked beats required) and Conditions. Edit it and write it back with ucf.set_transition_settings(graph, from_node, to_node, input_tag, settings, fires_on=None), naming the transition as it is before the edit.
t = ucf.get_transition_settings(graph, "ROOT", "BackStep", "UCF.Input.LightAttack")
cond = unreal.new_object(unreal.UCFTransitionCondition_Direction)
cond.set_editor_property("RequiredDirection", unreal.UCFInputDirection.BACK)
t.set_editor_property("Conditions", [cond])
ucf.set_transition_settings(graph, "ROOT", "BackStep", "UCF.Input.LightAttack", t)
With that condition, light attack pulled back plays BackStep and a plain transition on the same input plays the usual first attack.
Condition class (editor label)Passes whenFields
UUCFTransitionCondition_Direction (Direction)The stick points one way at the pressRequiredDirection (unreal.UCFInputDirection: NEUTRAL, FORWARD, FORWARD_RIGHT, RIGHT, BACK_RIGHT, BACK, BACK_LEFT, LEFT, FORWARD_LEFT), or bUseAngleRange with MinAngleDegrees and MaxAngleDegrees
UUCFTransitionCondition_VitalThreshold (Vital Threshold)A vital meets a levelVitalTag, Comparison, Threshold, Tolerance, bUseFraction
UUCFTransitionCondition_TargetState (Target State)The aimed-at enemy holds tagsRequiredTags, BlockedTags, bRepickAtPress
UUCFTransitionCondition_TargetDistance (Target Distance)The aimed-at enemy is near or farComparison, Distance (cm), Tolerance, bRepickAtPress
UUCFTransitionCondition_CooldownReady (Cooldown Ready)A cooldown has a chargeCooldownTag
UUCFPairedActionCondition (Paired Action Available)A synced move would play nowActions (paired action sets)
Comparison is unreal.UCFValueComparison: LESS, LESS_OR_EQUAL, NEARLY_EQUAL, GREATER_OR_EQUAL, GREATER.
Sub graphs
A sub graph folds another action graph's moves into this one, gated by tags, so a shield's moves exist only while the shield is drawn:
ucf.add_sub_graph(sword_graph, "ROOT", shield_graph, entry_required_tags=["UCF.Equipment.Shielded"])
print(ucf.compile_action_graph(sword_graph))
shield_graph's transitions leaving its ROOT leave ROOT here too, each requiring the entry tags; its other moves come along. Recompile the parent after editing the source graph. entry_blocked_tags and priority_bias (added to each entry transition's priority) are optional.
To start the folded-in moves from more moves than one, such as a shield guard pressed mid-combo, attach those moves to the same import; the moves are imported once and each attached move gets the entry transitions with the same tags and priority:
for move in ("Light1", "Light2", "Light3"):
    ucf.attach_sub_graph(sword_graph, move, shield_graph)
print(ucf.compile_action_graph(sword_graph))
An entry that should cut a running attack needs INTERRUPT timing on the source graph's ROOT transition, and a priority above the parent's own transition on the same input (priority_bias).
Removing and renaming
  • ucf.remove_transition(graph, from_node, to_node, input_tag, fires_on=None).
  • ucf.remove_node(graph, name) takes the move, every transition into and out of it and its row in every alias. ROOT stays.
  • Rename by writing another NodeName through set_node_settings.
Graph and character settings
  • On the graph asset: DefaultInputBufferMode (unreal.UCFInputBufferMode: IGNORE, ACCEPT_FIRST, ACCEPT_LAST, the default) decides what a press made before the action window does; LateInputGrace (seconds, default 0.25, 0 off): how long after a move runs to its end a press or release still follows that move's own transitions, so a combo carries on when the next press comes a moment late; a canceled move, or one that leaves through an AUTO transition to another move, grants none; HeldInputRestartWindow (seconds).
  • On the character's UCF Action Graph component (the C++ base creates it): GlobalBlockTags (default UCF.State.ActionsBlocked) drops every press while the character holds one; ActionSpeed scales how fast every move plays (1 is authored speed).
Mistakes
SymptomCause and fix
An edit has no effect in PlayThe graph was not compiled after the edit; describe_action_graph says so on its first line.
The guard never endsNo ON_COMPLETED transition from the guard to ROOT on the guard input, or that transition is WAIT_FOR_WINDOW, which waits for a window the looping guard never opens; make it INTERRUPT.
A set_node_settings call raises about an empty entryA Costs, Gates or Hooks list holds None; make each object with unreal.new_object.
A directional move never playsIts transition has the Direction condition, but the Input Action's movement is read from the character's movement input; with no stick pushed the direction is NEUTRAL.
A shield's moves play without the shieldThe sub graph has no entry_required_tags; gate it on a tag the shield's item holds while drawn (its Equippable EquipmentTags).
A shield's guard starts only from idleOnly ROOT is attached to the shield's sub graph; attach_sub_graph each combo move it should start from.

Animation, HUD, settings and debugging (AgentGuide/Player/AnimationHUDDebug.md)

Tasks: a character made of several meshes; walking differently while a weapon is drawn; hit stop in the customer's own Animation Blueprint; footstep sounds, per surface too; a weapon's own swing effects; finding out why an effect plays nothing; i-frames or hyper armor on frames; showing stamina on screen; button prompts; project-wide settings; finding out why a combo does not chain.
Montage windows
Every window is added with ucf.add_notify_state_to_montage(montage, cls, start_seconds, duration_seconds); a one-frame notify with unreal.AnimationLibrary.add_animation_notify_event(montage, "Combat", seconds, cls). Save the montage after setting properties.
Window (editor name)ClassFields
UCF Melee Trace WindowUUCFMeleeTraceNotifyStateSocketIDs, DamageConfig, ExtraDamageTags
UCF Action WindowUUCFActionWindowNotifyStatenone: where the next press may chain
UCF State Tag WindowUUCFStateTagNotifyStateTags: UCF.State.Intangible (i-frames), UCF.State.HyperArmor (less poise damage), UCF.State.Parrying, UCF.State.Dashing
UCF Approach Window, UCF Approach Or Move WindowUUCFApproachWindowNotifyState, UUCFApproachOrMoveWindowNotifyStateAgentGuide/Player/TargetingStylesSteering.md
UCF Telegraph WindowUUCFTelegraphMarkerNotifyStateAgentGuide/Player/CameraTelegraphs.md
UCF Anim Effect WindowUUCFAnimEffectWindowNotifyStateEffect (EffectTags, SocketName): trails, glows, sounds
UCF Anim Effect (one frame)UUCFAnimEffectNotifyEffect: footsteps, landings
UCF Gameplay Event (one frame)UUCFGameplayEventNotifyEventTag
UCF Equipment Commit (one frame)UUCFEquipmentCommitNotifyBlendSeconds
Several meshes and animation layers
  • Component tags on the character's skeletal meshes say what each is for: UCF.Montage (follows the action's montage), UCF.AnimLayer (takes the item's animation layer), UCF.Attachment.<Slot> (items attach to it; the duplicated player's body has UCF.Attachment.Body). Matching is by prefix. Add the tags to an extra mesh's ComponentTags.
  • Walking differently with a weapon: the Equippable fragment's AnimLayerClass, a child of the demo's ABP_UCF_ItemAnimLayersBase for the customer's skeleton with its own walk and jog sets. Its Upper Body Default sequence also holds the arms through a dodge while UCF.State.Dashing is on, so a weapon playing the bare hands' dodge montages keeps its grip. Building the layer's AnimGraph is a step for the customer.
  • Tag-driven bools: an Animation Blueprint whose parent is UUCFAnimInstanceBase has GameplayTagPropertyMap on its class defaults, setting a bool while a tag is held.
  • Hit stop in the customer's own Animation Blueprint: a UCF Hit Stop node after the DefaultSlot slot and an Inertialization node after it. That is a step for the customer; the plugin's locomotion template already has both (AGENTS.md, "No Animation Blueprint"), and without them the log warns once and hits land without the freeze.
Footsteps and effects
An animation asks the character for an effect with a UCF Anim Effect notify (one frame, UUCFAnimEffectNotify) or a UCF Anim Effect Window (UUCFAnimEffectWindowNotifyState), both carrying Effect (EffectTags, SocketName). Everything on the character that answers is asked, each once: the character's own Blueprint when it implements UCF Anim Effect Handler (IUCFAnimEffectHandler), then each component that does. The UCF Anim Effects component (UUCFAnimEffectBankComponent, AnimEffectComponent on the character base) plays the matching row of its Anim Effect Bank (UUCFAnimEffectBank: Rows with EffectTag, Sounds, Particles, bAttachToSocket; SurfaceSet), the deepest row whose tag the request sits under. The equipment manager runs each drawn item's Swing Trail and passes the request on to the drawn weapon's Blueprint.
  • Footsteps: duplicate the demo's AnimEffectBank_UCF_Default and set it as the component's Bank. The console command UCF.AnimEffects.PlantFootsteps <content path> save writes UCF.AnimEffect.Footstep.Left and .Right notifies where each foot lands, for every animation in a folder.
  • Footsteps per surface: give the bank a SurfaceSet (UUCFImpactSurfaceSet: MaterialSuffixes maps a physical material asset to a name such as Stone, SurfaceSuffixes a surface type) and a row for UCF.AnimEffect.Footstep.Stone, which then answers every footstep on that material unless a deeper row such as Footstep.Left exists. A row's tag must exist: ucf.add_gameplay_tag(tag, comment). The component looks at the ground under the socket for an effect a bank it uses has a surface row for. ucf.validate_asset(bank) warns about a surface no row ends in and notes a row that plays nothing, which silences its tag (how a layered bank mutes one).
  • A weapon Blueprint's own swing effects (a blade glow, a whoosh of its own, sparks): the Equippable fragment's ItemActorClass, a child of UCF Equippable Item, already implements UCF Anim Effect Handler, answering false. Overriding its functions Handle Anim Effect, Handle Anim Effect Begin and Handle Anim Effect End (under Interfaces in the Blueprint editor), checking the request's Effect Tags, returning true when it acted and false for the rest, is a Blueprint graph step for the customer; the demo BP_UCF_Sword lights its blade on UCF.AnimEffect.Weapon.Glow windows that way. The request's Mesh and Socket Name are the character's, so a blade effect goes on the weapon's own mesh. Windows can overlap: a heavy attack chained into another can open the next window before the last one closes, when the next montage blends in, so the graph counts open windows and switches the effect off when the count returns to zero, as the demo sword does. The character's own handlers do not pass requests on to the weapon; the equipment manager already does.
  • A ribbon behind the blade needs no graph: the Swing Trail fragment (AgentGuide/Player/ItemsEquipment.md) and a window carrying UCF.AnimEffect.Weapon.Trail over each swing. ucf.validate_asset(item) warns when no montage the item's Action Graph plays carries such a window.
  • Item sounds are item events, not anim effects: an item's draw and put-away sounds are its Stowable fragment's DrawSound and PutAwaySound, and its drop and landing sounds come from its World Item fragment.
  • In the animation editor, playing or scrubbing a clip plays the effects its notifies ask for from a preview bank: UUCFEditorSettings (Project Settings, Plugins, Universal Combat Framework Editor, Animation Preview) PreviewBank, or PreviewBanksBySkeleton for one skeleton. While the clip, an animation or a montage, carries a UCF Anim Effect, the viewport's bottom left corner names the bank; a bank the project lacks plays nothing and shows no name.
  • Nothing plays: UCF.Debug.AnimEffects 1 in Play writes each character's last requests above it with what answered (the bank, its row and surface, the Swing Trail, a Blueprint by class name), in red when nothing did. Then check, in order: the notify sits on the mesh that plays the montage; the character has a handler (the component has a Bank); a row's tag sits above the requested tag; a surface row's tag exists; the effect plays on a client or listen server, never a dedicated server; the notify's TriggerWeightThreshold and NotifyTriggerChance.
HUD and prompts
  • The demo HUD WBP_UCF_HUD shows vitals (WBP_UCF_CoreVitals), the crosshair, cooldowns and the belt. A style's Tags fragment holds UCF.UI.Show.Stamina, UCF.UI.Show.Belt and the like, which the HUD reads to show each part. Changing a widget's layout is a step for the customer.
  • Button prompts: UUCFInputDisplaySettings (Project Settings, Plugins, Universal Combat Framework Input Display) lists GlyphSets (UUCFInputGlyphSet: DeviceFamily, HardwareDeviceIdentifiers naming the pads a sheet serves, Glyphs rows Key, Icon, ShortLabel, LongLabel), top to bottom, the first sheet serving the device and covering the key winning: the PlayStation sheet (DualSense, DualSenseEdge, DualShock4), the generic gamepad sheet, then keyboard.
Project settings
unreal.get_default_object(unreal.UCFCombatSettings): DefaultHitDetectionAuthority, MaxHitStopSeconds. The demo hit effects are switched off with Load Demo Hit Effects under Project Settings, Plugins, Universal Combat Framework Demo. Editor Python cannot save a project setting to the config file before UE 5.8, so a value set this way lasts until the editor closes: ask the customer to set it in Project Settings, Plugins.
Debugging
Console command (in Play)Shows
UCF.Debug.Actions 1Each character's action graph above its head: node, window, buffered input
UCF.Debug.Vitals 1, UCF.Debug.Equipment 1, UCF.Debug.Targeting 1, UCF.Debug.Approach 1Vitals, drawn items, targets, approach state
UCF.Debug.Melee.DrawTracing 1Every melee sweep
UCF.Debug.Steering.Draw 1Where attacks aim and stop
UCF.Debug.Paired.Draw 1Paired action spots
UCF.Debug.AnimEffects 1Each character's last anim effect requests and what answered them
UCF.Logs VerboseRaises every UCF log category; UCF.Logs puts them back
Without Play: ucf.describe_action_graph(graph) and ucf.compile_action_graph(graph) for a graph, ucf.validate_asset(asset) for anything else. After Play, log_warnings() returns UCF's warnings, each naming the asset and the fix.

Camera and attack warnings (AgentGuide/Player/CameraTelegraphs.md)

Tasks: a closer over-the-shoulder camera; the camera pulling back while sprinting; a different camera with a weapon drawn; a cinematic camera shot; warning markers over enemy swings; a marker over a stunned enemy.
The camera rig
The duplicated player carries a UCF Camera Rig component (UCFCameraRig, added by the Blueprint; AgentGuide/Player/Python.md, "Components on a Blueprint", shows how to read its template). DefaultSettings (unreal.UCFCameraRigSettings) is used when neither the drawn item nor the combat style names a camera:
FieldDoes
ArmLengthDistance behind the character, cm
SocketOffsetOffset from the arm's end, cm; Y moves the camera over a shoulder
FieldOfViewDegrees
PitchOffset (label Camera Tilt)Tilts the view without moving the aim
PositionLagSpeed, RotationLagSpeed, SettingsBlendSpeedHow quickly it follows and blends
bFollowSoftTarget, SoftFollowSpeed, SoftFollowDeadzone, SoftFollowResumeDelayTurning toward the soft target while unlocked
Other rig fields: OutputMode, bCreateRigIfMissing, ShoulderSwapSeconds.
Per item: a UUCFItemFragment_CameraRig (Camera Rig) on the item, Settings, while it drives combat. Per style: a UUCFStyleFragment_CameraRig on the combat style, Settings and States (unreal.UCFCameraStateRow: Label, RequiredTags, BlockedTags, Layer), a layer that blends in while the character holds the tags.
Pull back while sprinting: a style state row with RequiredTags UCF.State.Sprinting and a Layer overriding ArmLength. Read a demo style's row first (CombatStyle_UCF_OverShoulder has a Camera Rig fragment) and copy its shape with export_text.
Check: in Play, capture the viewport before and after; a camera change only a person can judge, so describe it to the customer.
Camera shots
A Camera Shot (UUCFCameraShot, made with the UCF Camera Shot factory or new_data_asset) holds Keys (unreal.UCFCameraShotKey: TimeSeconds, Location, Rotation, FieldOfView, Interpolation), the first at 0 and the rest in increasing time. A paired action plays one through an Authored Camera Shot hook (AgentGuide/Player/PairedActions.md). ucf.validate_asset(shot) checks the key order.
Warning markers over swings
  1. The attacker's montage carries a UCF Telegraph Window (UUCFTelegraphMarkerNotifyState) over the wind-up: TelegraphType, bFindAttackAutomatically (finds the trace window it describes), DamageConfig, Tags, OriginSpace, OriginItemTag, Broadcast (its Shape). Add it with ucf.add_notify_state_to_montage.
  2. The player sees markers through a UCF Telegraph Viewer (the duplicated player has one) with a StyleSet: a Telegraph Style Set (UUCFTelegraphStyleSet: Styles rows unreal.UCFTelegraphStyle RequiredTags, BlockedTags, Priority, PresenterClass, FallbackSocket, Duration; ViewRules). Duplicate the demo's TelegraphStyle_UCF_Default and change rows; a new marker look is a presenter Blueprint (duplicate a BP_UCF_TelegraphPresenter_*).
  3. A marker over a character rather than a swing: a UCF Telegraph Subject component (UUCFTelegraphSubjectComponent) and its Show Marker call, a Blueprint step.
Mistakes
SymptomCause and fix
A camera setting does nothingThe drawn item's Camera Rig fragment or the style's wins over DefaultSettings.
No marker showsThe viewer has no StyleSet, no row's tags match the announcement, or the window is on the player's own attack.
A shot jumpsIts keys are out of time order; validate_asset says which.

Damage, hit effects, blocks, parries and vitals (AgentGuide/Player/DamageDefense.md)

AGENTS.md, Player Recipe 2, Step 2, makes damage configs. This file covers what a hit does beyond its damage, and how the player answers a hit: blocks, parries, i-frames, and the health and stamina pools.
Tasks: hits that drain stamina or stance; a knock-back; a hit stop; swings that slow when they strike armor; blocking frontal hits while guarding; a timed guard that parries; a shield that blocks; more health; a flinch when hit, or only when a few hits break poise.
Damage configs
UUCFDamageConfig: Damage, AdditionalVitalDamage (unreal.UCFVitalDamage rows VitalTag, Amount), DamageTypeClass, DamageTags (what kind of hit it is: UCF.DamageType.Blunt, .Slash), MultiHitInterval, MaxTargetsPerSwingOverride, bUseAuthoredHitDirection, HitEffects.
Hit effect (picker label)DoesFields
UUCFPredictedGameplayCueHitEffect (UCF Play Gameplay Cues)Cues on the attacker and the targetAttackerCues, TargetCues, SurfaceSet, bAllowPredicted
UUCFPhysicsImpulseHitEffect (UCF Apply Physics Impulse)Shoves the struck bodyHitBoneForce, HitOverallForce, HitRotationalForce, bVelocityChange
UUCFApplyGameplayEffectHitEffect (UCF Apply Gameplay Effect)Applies a gameplay effectGameplayEffect, Level
UUCFHitStopEffect (UCF Hit Stop)Freezes the pose for a momentHoldSeconds (cut to MaxHitStopSeconds in Project Settings, 0.3 by default), FatalHoldMultiplier, SurfaceScaling
UUCFSendGameplayEventHitEffect (UCF Send Gameplay Event)Sends an event, which a hit reaction ability answersEventTag (UCF.Event.Reaction)
UUCFRefillVitalHitEffect (UCF Refill Vital)Fills a pool to its maximum, such as broken poiseVitalTag (UCF.Vital.Poise)
UUCFImpactSlowHitEffect (UCF Impact Slow)Slows the swing when it strikes the level or armorRelativeRate, Duration, RequireAnyTargetTags
UUCFPhysicalReactionHitEffect (UCF Play Physical Reaction)Moves the struck body's bones under physicsReactionName, Force
Every hit effect also has AffectedSides, RequireAnyResultTags, SuppressOnResultTags (run only, or never, on a Blocked or Parried hit), RequireAnyTargetTags, SuppressOnTargetTags, bRequireDamageApplied. Make each with unreal.new_object(cls, outer=damage_config).
The character's MeleeTraceComponent (UUCFCombatTraceComponent): DefaultDamageConfig, TeamFilter (unreal.UCFTeamFilter, Enemies Only by default), PassThroughTags (UCF.State.Intangible), MaxTargetsPerSwing, HitDetectionAuthority.
Recipe: a shield that blocks and a timed guard that parries
The guard rules are a Defense Rule Set (UUCFDefenseRuleSet) that an item lends while drawn through its Guard fragment (UUCFItemFragment_Guard, DefenseSet). The responses run in order and the first that answers decides; the parry goes first.
rules = new_data_asset(unreal.UCFDefenseRuleSet, F, f"DefenseRuleSet_{N}_Shield")
parry = unreal.new_object(unreal.UCFDefenseRule_Guard, outer=rules)
parry.set_editor_property("RequiredTags", tags("UCF.State.Parrying"))
parry.set_editor_property("DamageMultiplier", 0.0)
parry.set_editor_property("ResultTag", tag("UCF.DamageResult.Parried"))
parry.set_editor_property("CostPerDamage", 0.0)
block = unreal.new_object(unreal.UCFDefenseRule_Guard, outer=rules)
block.set_editor_property("RequiredTags", tags("UCF.State.Blocking"))
block.set_editor_property("ArcHalfAngleDegrees", 70.0)
block.set_editor_property("DamageMultiplier", 0.2)
block.set_editor_property("ResultTag", tag("UCF.DamageResult.Blocked"))
rules.set_editor_property("Responses", [parry, block])
save(rules)
 
guard = unreal.new_object(unreal.UCFItemFragment_Guard, outer=shield)       # shield: the item from AgentGuide/Player/ItemsEquipment.md
guard.set_editor_property("DefenseSet", rules)
shield.set_editor_property("Fragments", list(shield.get_editor_property("Fragments")) + [guard])
save(shield)
  • The tags come from the guard move: UCF.State.Blocking while the guard node runs and UCF.State.Parrying over the first frames of its montage (AgentGuide/Player/ActionGraphs.md, "A held guard with a parry window"). Without them the rules never answer and hits land whole.
  • Put the guard move in the graph of the weapon held with the shield: the shield itself drives no moves.
  • A guard costs stamina when CostVitalTag names a vital (CostPerDamage per point of damage, FlatCost per hit); empty costs nothing.
  • ArcHalfAngleDegrees is half the arc in front that blocks; a hit from behind lands whole.
Check: reload the rule set and print each response's class, RequiredTags, ResultTag and DamageMultiplier. In Play, with the guard held, a frontal hit takes a fifth of its damage and the attacker's hit carries UCF.DamageResult.Blocked; inside the parry window nothing lands and it carries UCF.DamageResult.Parried.
Defense responses
Response (picker label)DoesFields
UUCFDefenseRule_Guard (UCF Guard)Soaks a hit from inside an arcArcHalfAngleDegrees (60), DamageMultiplier (0.2), cost (CostPerDamage 1 when CostVitalTag is set)
UUCFDefenseRule_Scale (UCF Scale Damage)Scales the hit and lets the next response runDamageMultiplier
UUCFDefenseRule_Invulnerable (UCF Invulnerable)Takes nothing
All have RequiredTags, BlockedTags (shown as Required and Blocked Defender Tags), ResultTag, RequiredAttackTags, BlockedAttackTags (an unblockable attack's damage tag), CostVitalTag, FlatCost, CostPerDamage, bSpendRemainderWhenUnaffordable, bContinueAfterClaim. A rule set's OutcomeEffects (hit effects) run once the hit is answered: the demo's sword set sends the attacker UCF.Event.ParryRecoil on a parry. The character's own UCF Defense component (DefenseComponent) holds DefenseSet, Responses and OutcomeEffects that do not come from an item.
Vitals
VitalsComponent on the character: Vitals rows (unreal.UCFVitalDefinition: VitalTag, MaxValue, RegenRatePerSecond, RegenDelaySeconds, DepletedLooseTag, DepletedResultTag, DepletedGameplayEvent). The duplicated player has health; stamina is in AgentGuide/Player/GatesCostsHooks.md. An emptied UCF.Vital.Stance row with DepletedGameplayEvent UCF.Event.GuardBreak is how the demo breaks a guard.
Hit reactions
A flinch is an ability that answers UCF.Event.Reaction, which a UCF Send Gameplay Event hit effect on the attacker's damage config (or a defense set's outcome effects) sends. The demo's GA_UCF_HitReact is one: it cuts the running move and holds UCF.State.ActionsBlocked for its HoldSeconds, plays no animation, and serves any character, so add it to the character's ability set.
To flinch only on the hit that breaks poise, as the demo does: a UCF.Vital.Poise row on the character's vitals with DepletedResultTag UCF.DamageResult.PoiseBroken, a poise row in each damage config's AdditionalVitalDamage, UCF.DamageResult.PoiseBroken in the event's RequireAnyResultTags with bRequireDamageApplied off, and a UUCFRefillVitalHitEffect (VitalTag UCF.Vital.Poise, the same result gate) beside it in the same outcome effects. The demo characters share these in DefenseRuleSet_UCF_Character. UCF.State.HyperArmor on the character (a State Tag Window over a swing) halves its poise damage through a UUCFDefenseRule_Scale in that set (RequiredTags UCF.State.HyperArmor, DamageMultiplier 1, VitalDamageMultipliers row UCF.Vital.Poise at 0.5, bContinueAfterClaim on), so light hits do not stop the swing and a heavy one does.
Mistakes
SymptomCause and fix
The guard blocks nothingNothing holds UCF.State.Blocking, the shield is not drawn, or the hit comes from outside ArcHalfAngleDegrees.
Every guarded hit is a parryThe parry window covers the whole guard montage; keep it to the first quarter second.
The parry never happensThe parry response is after the block in Responses, or the State Tag Window holds another tag.
The attacker never learns it was blockedResultTag is empty on the response.

Stamina, costs, cooldowns, gates and hooks (AgentGuide/Player/GatesCostsHooks.md)

Read AgentGuide/Player/ActionGraphs.md first: everything here is set on a move through ucf.get_node_settings and ucf.set_node_settings, or on Epic's MCP on the move's card, as that file's "How a move is edited" says.
Tasks: give the player stamina; make attacks cost stamina; give a move a cooldown or charges; allow a move only at a resource level or while a tag is held; make sprinting drain stamina; slow the player or let them walk out of a move; read a cooldown for the HUD.
Recipe: stamina, attack costs, a dodge cooldown and sprint drain
d = defaults(bp)
vitals = d.get_editor_property("VitalsComponent")
rows = list(vitals.get_editor_property("Vitals"))
names = [str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("VitalTag"))) for r in rows]
if "UCF.Vital.Stamina" in names:                  # the duplicated demo player has one
    row = rows[names.index("UCF.Vital.Stamina")]
else:
    row = unreal.UCFVitalDefinition()
    row.set_editor_property("VitalTag", tag("UCF.Vital.Stamina"))
    rows.append(row)
row.set_editor_property("MaxValue", 100.0)
row.set_editor_property("RegenRatePerSecond", 25.0)
row.set_editor_property("RegenDelaySeconds", 1.0)
vitals.set_editor_property("Vitals", rows)
save(bp)
 
def add_cost(graph, node, amount):
    s = ucf.get_node_settings(graph, node)
    cost = unreal.new_object(unreal.UCFActionCost_Vital)
    cost.set_editor_property("VitalTag", tag("UCF.Vital.Stamina"))
    cost.set_editor_property("Amount", float(amount))
    s.set_editor_property("Costs", list(s.get_editor_property("Costs")) + [cost])
    ucf.set_node_settings(graph, node, s)
 
for node in ("Light1", "Light2", "Light3"):
    add_cost(graph, node, 10)
add_cost(graph, "Dodge", 25)
 
s = ucf.get_node_settings(graph, "Dodge")
gate = unreal.new_object(unreal.UCFActionGate_Cooldown)
gate.set_editor_property("CooldownTag", tag("UCF.Cooldown.Ability.Dodge"))
gate.set_editor_property("Seconds", 1.0)
gate.set_editor_property("Charges", 1)
s.set_editor_property("Gates", list(s.get_editor_property("Gates")) + [gate])
ucf.set_node_settings(graph, "Dodge", s)
print(ucf.compile_action_graph(graph))
save(graph)
Sprint drain is set on the character's UCF Sprint component, which the Blueprint adds (AgentGuide/Player/Python.md, "Components on a Blueprint", shows how to read its template): StaminaVital = UCF.Vital.Stamina, StaminaDrainPerSecond = 15, MinStaminaToStart = 10. Compile and save the Blueprint.
  • A cost is checked when the press arrives and spent when the move starts. A press the player cannot pay for does not start the move; it takes the move's Action Failed transition when one is wired.
  • Do the same in every graph that has these moves: a drawn weapon's graph replaces the unarmed one.
  • The cooldown tag names the timer. Gates sharing a tag share the timer, so they must agree on Seconds and Charges (the compile warns when they differ). For a second cooldown, add its own tag first: ucf.add_gameplay_tag("UCF.Cooldown.Ability.Heavy", "Heavy attack cooldown").
Check: ucf.describe_action_graph(graph) lists costs Vital (VitalTag=..., Amount=10) on each light attack and gates Cooldown (... Seconds=1 ...) on the dodge. In Play, UCF.Debug.Vitals 1 writes the stamina above the character; it drops by the cost after each press and climbs back after a second.
Gates, costs and hooks
Class (editor label)Goes inProperties
UUCFActionCost_Vital (Vital)CostsVitalTag, Amount
UUCFActionCost_Attribute (Attribute)CostsAttribute (a Gameplay Ability System attribute), Amount
UUCFActionGate_Cooldown (Cooldown)GatesCooldownTag, Seconds, Charges (uses it can bank), EffectClass (advanced)
UUCFActionGate_Vital (Vital)GatesVitalTag, Comparison (unreal.UCFValueComparison: LESS, LESS_OR_EQUAL, NEARLY_EQUAL, GREATER_OR_EQUAL, GREATER), Threshold, Tolerance, bUseFraction (compare 0 to 1 of the max)
UUCFActionGate_Tags (Tags)GatesRequiredTags, BlockedTags, WhenClosed (unreal.UCFGateTagMode.SKIP tries the next matching transition, REFUSE drops the press)
UUCFActionHook_LocomotionModifier (Locomotion Modifier)HooksWalkSpeedFactor, AccelerationFactor, RotationRateFactor (0 freezes, 1 keeps)
UUCFActionHook_CancelOnMovement (Cancel On Movement)HooksReadMode (INPUT_INTENT, SPEED), MovementThreshold (0 to 1)
UUCFActionHook_DrainVital (Drain Vital)HooksVitalTag, DrainRatePerSecond, EndBehavior (NONE, FINISH, CANCEL the move when the vital empties)
A gate decides whether the move may start; a cost is paid when it starts; a hook runs while it runs. A gate never spends anything.
Falling through to another move. When the press should do something else while a move is shut, put a condition on the transition rather than relying on the gate: UUCFTransitionCondition_CooldownReady (CooldownTag) or UUCFTransitionCondition_VitalThreshold (VitalTag, Comparison, Threshold, bUseFraction) on the transition into the gated move, and a second transition on the same input without it. See AgentGuide/Player/ActionGraphs.md, "Transition settings".
HUD. unreal.UCFActionGate_Cooldown.get_cooldown_state(owner, cooldown_tag) reports charges ready, charges it can bank and when the next comes back. The demo HUD's WBP_UCF_AbilityCooldown reads it.
Mistakes
SymptomCause and fix
Attacks cost nothingThe character has no row for the cost's VitalTag in VitalsComponent's Vitals, or the cost sits on a move in a graph the player does not use while that item is drawn.
A press never starts the moveA cost the player cannot pay, a gate that is shut, or a cooldown still running. UCF.Debug.Actions 1 shows the graph state; log_warnings() names a cost whose vital is missing.
The compile warns about a cooldownTwo gates share a CooldownTag with different Seconds or Charges. Make them agree or give one its own tag.
Sprint never drainsStaminaVital is empty on the UCF Sprint component, or the character has no row for it.

Input, abilities and sprint (AgentGuide/Player/InputAbilities.md)

Tasks: put a move on a new key; a combined press of two buttons; an input that works with any weapon; an ability on a key that can cut a swing (a potion, a heal); sprint speed and stamina; pausing combat input.
How a press reaches a move
A key maps to an Input Action in a mapping context; a mapping row turns the Input Action into an input tag; the action graph's transitions listen for the tag. All three must agree.
  • Item mappings (while an item is drawn): the Equippable fragment's InputMappingContext, InputMappingPriority and InputMappings rows (unreal.UCFInputMapping: InputAction, InputTag, RequiredStateTags, DisplayName), as AGENTS.md, Player Recipe 2, Steps 5 and 6, builds.
  • Character mappings (always): the character's InputMappingComponent (UUCFInputMappingComponent): InputMappings, InputChords, ChordWindowSeconds, bAutoBind.
  • Keys: IMC_UCF_Default on the controller maps movement, look, slots 1 to 4, dash, lock-on, interact, drop and sprint. Item contexts map attack and guard keys.
Recipe: a kick on F
ucf.add_gameplay_tag("UCF.Input.Kick", "Kick")
ia = unreal.AssetToolsHelpers.get_asset_tools().create_asset(f"IA_{N}_Kick", F, unreal.InputAction, unreal.InputAction_Factory())
ia.set_editor_property("ValueType", unreal.InputActionValueType.BOOLEAN)
save(ia)
key = unreal.Key()
key.import_text("F")
imc.map_key(ia, key)                         # imc: the item's mapping context copy
save(imc)
m = unreal.UCFInputMapping()
m.set_editor_property("InputAction", ia)
m.set_editor_property("InputTag", tag("UCF.Input.Kick"))
eq.set_editor_property("InputMappings", list(eq.get_editor_property("InputMappings")) + [m])   # eq: the item's Equippable fragment
save(item)
ucf.add_transition(graph, "ROOT", "Kick", "UCF.Input.Kick")
Check: reload the item and print its mappings; ucf.describe_action_graph(graph) lists UCF.Input.Kick leaving ROOT. In Play, graph_comp.process_action_input(tag("UCF.Input.Kick"), unreal.UCFTransitionTrigger.ON_STARTED) enters the move (AGENTS.md, Player Recipe 2, Step 8).
Chords
unreal.UCFInputChord rows (MemberTags, two or more input tags; OutputTag, the tag sent when all are pressed inside ChordWindowSeconds; Priority) in an item's InputChords or the character's. A transition on the output tag plays the move. ChordWindowSeconds 0 turns chords off.
Abilities on keys
The character's starting ability set (StartingAbilitySet, a copy of AbilitySet_UCF_Default in AGENTS.md, Player Recipe 1) grants abilities with their keys: GrantedGameplayAbilities rows (unreal.UCFAbilitySet_GameplayAbility: Ability, AbilityLevel, InputTag, InputAction, bInterruptsActionGraph (cuts the running move, for a dodge or a potion), bForwardInputWhileActive (a second press goes into the running ability, for a hold)). The row's fields refuse set_editor_property, so write the row as text:
row = unreal.UCFAbilitySet_GameplayAbility()
row.import_text(f'(Ability="{heal_bp.generated_class().get_path_name()}",AbilityLevel=1,InputTag=(TagName="UCF.Input.Special"),InputAction="{ia_heal.get_path_name()}",bInterruptsActionGraph=True)')
abilities.set_editor_property("GrantedGameplayAbilities", list(abilities.get_editor_property("GrantedGameplayAbilities")) + [row])
save(abilities)
An item grants its own sets while drawn through AbilitySetsToGrant. A press goes to the action graph first, then to a granted ability whose row carries the same input tag.
Sprint
The sprint is the UCF Sprint Ability (UUCFSprintAbility, LatchTapSeconds) on UCF.Input.Sprint (in the copied ability set) and the UCF Sprint component (Sprint on the duplicated player, added by the Blueprint): WalkSpeed, SprintSpeed, SpeedBlendSeconds, MinInputStrength, MaxSprintAngle, BlockedTags, StopGraceSeconds, StaminaVital, StaminaDrainPerSecond, MinStaminaToStart. Stamina for it: AgentGuide/Player/GatesCostsHooks.md.
Slower while a tag is held: a UCF Speed Modifier component (UCFSpeedModifier on the duplicated player): SpeedScaleByTag, a map of tag to multiplier.
Pausing combat input
GlobalBlockTags on the character's ActionGraphComponent (default UCF.State.ActionsBlocked) drops every press while the character holds one; holding the tag (a dialogue, a cutscene) is a Blueprint step or a gameplay effect.
Mistakes
SymptomCause and fix
A press does nothingThe mapping row's tag differs from the transition's, the context lacks the Input Action, or the tag was never added.
The ability never fires mid-swingbInterruptsActionGraph off, or a transition on the same tag in the graph takes the press first.
A new tag reads emptyIt was used before ucf.add_gameplay_tag added it.

Inventory, belt, pickups, drops and interaction (AgentGuide/Player/InventoryInteraction.md)

Tasks: start with an item; an item, a container and an inventory config made from scratch; a keychain that takes every key by itself, cannot be dropped and weighs nothing; a weight limit or a cap per item kind; a belt that takes any item, or a belt laid out by item kind; saving the inventory in the game's save; a survival grid, a party RPG inventory, an open world list, or a character carrying only what its hands hold; an inventory screen, the demo's as it is, a copy changed for the game, or one of the project's own; a potion drunk from a screen or the belt; a stash; a rule, a combine or an item fragment of the project's own in Blueprint; two items combined into a third by a recipe; rounds loaded into a magazine by dropping them on it; a bag bar whose pouches hold items; an item on the floor to pick up; dropping the held weapon; a weapon rack; a loot chest every nearby player sees; only interacting with what the player looks at; a lever or a door that plays an animation.
Inventory and belt
  • Starting items: StartingItems on the character's InventoryComponent (AGENTS.md, Player Recipe 4, Step 5).
  • The belt is the UCF Quick Bar component on the player controller (BP_UCF_PlayerController; duplicate it to change it, and set the copy as the game mode's PlayerControllerClass). Fields: Slots (unreal.UCFQuickBarSlot rows: Filter, an item kind the item's SlotTags must hold, its children included), bAutoPopulateFromInventory (off by default; on, a new item also takes the first free slot that admits it, as on the demo controller; what a combine makes is no new item), bAutoDrawOnInit (with Auto Populate on, an item landing on a slot also comes to hand when its places are free; it does nothing while Auto Populate is off), bRestoreWhenPlaceFrees, bWeaponKeepsItsPlace, DefaultMaxCopiesPerDefinition (1 on the demo controller, so its belt holds one of each item; the demo sword's Belt Limit fragment of 2 lets it hold two swords), DriverReplacementOnDrop, BlockedTags (tags that switch the belt off while the character carries one; UCF.State.BeltBlocked by default). The controller's IMC_UCF_Default maps keys 1 to 4 and the D-pad's up, right, down and left to IA_UCF_SelectSlot_1 to _4.
  • Ask the customer which belt layout the game wants. Any item on any slot, as a survival game's hotbar: leave every slot's Filter empty, and a worn item drawn from the belt is put on. Slots by item kind, as the demo's souls-like diamond: slot 1 (top) UCF.Slot.Weapon, slot 2 (right) UCF.Slot.Consumable.Potion, slot 3 (bottom) UCF.Slot.OffHand, slot 4 (left) UCF.Slot.Consumable, with a Belt Limit fragment (MaxBeltCount 1) on the potion so its stacks take the right slot alone and the left slot holds other consumables; worn gear and a second weapon then stay in the inventory. Ask too whether any combat style has no belt: put UCF.State.BeltBlocked in that style's Gameplay Tags fragment (unreal.UCFStyleFragment_Tags, field Tags), as the demo Freeflow style does, and while it is active a belt press does nothing, nothing new goes on the belt and its slots keep their items. The demo HUD shows its belt only while the character carries UCF.UI.Show.Belt, which a style with a belt adds the same way.
  • Item kinds are one UCF.Slot hierarchy in each item's SlotTags, read by the belt's filters, the inventory's rules and its sort order: UCF.Slot.Weapon (.Sword, .TwoHanded), UCF.Slot.OffHand (.Shield), UCF.Slot.Consumable (.Potion), UCF.Slot.Apparel, UCF.Slot.Ingredient, UCF.Slot.Ammo (.Arrow), UCF.Slot.KeyItem, UCF.Slot.Upgrade. Add the project's own kinds under these, such as a spear kind under UCF.Slot.Weapon, so a filter on the parent takes them. An item with no SlotTags fits unfiltered slots only. A Belt Limit fragment caps copies on the belt.
Containers
An inventory with no config is one list with no limits. For slots, a grid, a bank, caps per item kind or a weight limit, set the inventory component's Config to a UCF Inventory Config (unreal.UCFInventoryConfig): defaults(bp).get_editor_property("InventoryComponent").set_editor_property("Config", config) on the character Blueprint, then save(bp). Three ready styles sit in /UniversalCombatFramework/Demo/Items/Inventory, each a recipe below; duplicate one into the project's folder and change the copy. The demo player starts on InventoryConfig_UCF_SurvivalGrid; the style pads in the wardrobe hall switch it.
  • Containers rows (unreal.UCFContainerSpec): a Container tag and a UCF Container Definition (unreal.UCFContainerDefinition: DisplayName, Icon, Layout unreal.UCFContainerLayout.LIST, SLOTS or GRID, SlotCount, GridSize (unreal.IntPoint), bAllowRotation, CapacityTag, Rules, bCarried, bTakesNewItems, AccessTag, bOpensBags). Adds try the rows in order, each followed by the bags open in it, and take the first container whose rules let the item in and that has room; a bTakesNewItems container off is filled by moves only. A List has no size and takes anything its rules allow, so give a container meant for one kind of item an Item Filter rule.
  • CarryRules, judged over every carried container together. The rules: Weight Limit (Limit, CapacityTag, bRefuseOverLimit, Thresholds of Fraction and Tag), Category Limit (Limits rows of Category, MaxUnits, CapacityTag, matched against the item's SlotTags) Item Filter (AllowedTags, BlockedTags) and Belt Only (no settings: lets in only what the belt holds, for a style with no inventory; the belt needs bAutoPopulateFromInventory on. It turns down any bag, an item with a Container fragment, since what a bag holds would be carried off the belt. In the Carry Rules it limits everything carried; on a container it limits that container alone, as the demo Simple config's Belt container beside a Worn container whose Item Filter takes apparel).
  • BeltSpace and EquippedSpace (unreal.UCFHeldItemSpace: KEEPS_ITS_PLACE, FREES_ITS_PLACE): whether an item on the belt, or drawn and off the belt, keeps its place in its container. Under FREES_ITS_PLACE, RequestMove of the whole held stack to a place in a carried container has the belt and the hand let go of it and puts it there, and CanPlace answers for that move. A screen that drops an item out of the hand onto a place sends RequestMove first and the belt's clear or RequestUnequipItem after it: a timed put-away running when the move arrives refuses the move. SortOrder: the Slot Tags RequestSort lays items out by. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce (Timing): on, an equip, a put-away or a combine asked for from the inventory lands at once with no animation and no wait, which a screen that pauses the game needs; off, the request plays the item's reach, or waits DrawTiming or StowTiming (unreal.UCFItemActionTiming: Seconds, StartSound, CommitSound, bCancelOnMove) for an item with none, or the recipe's time for a combine. The server reads these three, so no request takes a flag for them. bSwapWhenFull is explained with pickups, in the paragraph after the code below. bShowCarriedItemsOnBody (off by default): on, every stowable item carried outside a bag hangs on the body while out of hand; off, only the belt's items do and an item only in the inventory shows nowhere on the character. BeltSlots (one tag per slot, an empty tag taking any item): the belt this config gives, standing in for the belt's own Slots while the config is used, as the party RPG's four slots taking any item; left empty, the belt keeps its own.
  • An item with a Capacity Bonus fragment raises a capacity tag while owned; a container's or a limit rule's CapacityTag names it.
  • Another config at runtime, such as a game that lets the player pick an inventory style: call the inventory's SetConfig on the server, never set Config itself outside the defaults. A container both configs list, such as a stash, keeps its items; every other item outside a bag is placed again in the new layout as an add would, each staying on the belt and in hand; one that fits nowhere stays in a carried container, past its end when that is full, with a warning. To start the new config empty, call RemoveAllItems first, which empties the stash too; to keep the stash, remove only the items IsItemCarriedAndInReach answers true for, as the demo wardrobe's BP_UCF_InventoryStylePad does before it adds the style's starter kit.
Row fields are edited on the asset only, so Python fills a row with import_text:
spec = unreal.UCFContainerSpec()
spec.import_text('(Container=(TagName="UCF.Inventory.Container.Backpack"),Definition="/Game/Inventory/Container_Backpack.Container_Backpack")')
config = load("/Game/Inventory/InventoryConfig_Knight")      # the project's copy of a demo config
config.set_editor_property("Containers", list(config.get_editor_property("Containers")) + [spec])
save(config)
Adds and pickups take only what fits and a pickup leaves the rest on the ground. The world item's GetUnitsThatFit (with the picker) answers what a pickup would take, the inventory's what an add would. A pickup that takes nothing stays on the prompt with its verb saying why (No Room, Too Heavy) and a press does nothing; with the config's bSwapWhenFull on it reads Swap instead, and a press puts down the item in the way and takes the new one (GetSwapItem names what goes): an item in hand or on a belt slot that takes the new item, one of the same kind first, so a second sword replaces the sword put away rather than the shield. The demo's inventory screens draw all of this (Inventory screens, below); what follows is what any screen reads and sends. A UI reads GetItemsInContainer, GetItemsInSortOrder (a list kept in the config's SortOrder without moving anything), GetItemPlacement, GetContainerSize and CanPlace (its units out says how many a merge takes), a grid UI GetItemCells and GetPositionOfCell, a weight bar GetWeight with an empty scope, and redraws on OnLayoutChanged. The UI changes nothing itself: it asks the server through the inventory's RequestMove (move, split, merge, swap, combine, or into the bag dropped on), RequestSort and RequestUseItem, the belt's RequestAssignSlot, and the equipment manager's RequestEquipItem, RequestUnequipItem and RequestCancelSequence, and draws the change when it arrives. Clearing or refilling a belt slot whose item is in hand takes that item out of the hand at once, with no animation, once CanAssignSlot allows it. RequestEquipItem and CanEquipItem take the item and a Place, a paper doll's place (leave it empty to follow the item's Hold Places order), and RequestUnequipItem takes the item only. The config's bEquipAtOnce and bPutAwayAtOnce decide whether the requests play the draw and put-away animation or land at once. Each request has a check the UI asks first, the one the server makes: CanPlace for a move, the belt's CanAssignSlot for a drag onto or off the belt, the equipment manager's CanEquipItem and CanUnequipItem for Equip and Unequip buttons, and the inventory's IsItemCarriedAndInReach for a Use button; gray a button out while its check answers false. IsContainerInReach tells a bank or stash screen whether the player can reach it now. A timed draw announces OnEquipStepStarted and OnEquipSequenceEnded on the equipment manager, and GetPlayingStep answers how far it has got.
Check: in Play with the survival grid config on the player, GetContainerSize for UCF.Inventory.Container.Case reads 6 by 4, a sword added lands at the case's first free place (GetItemPlacement), and a hip pouch added lands in Key Items and opens six cells (GetContainerOpenedBy, then GetContainerSize of that container reads 6 by 1).
Recipe: a survival grid
A small case where items take room by size and turn to fit, key items in a list beside it, a hip pouch that adds six cells under the case, and a stash for the rest. Duplicate InventoryConfig_UCF_SurvivalGrid:
  • Containers, in this order: Case (UCF.Inventory.Container.Case: Grid, GridSize 6 by 4, bAllowRotation on, an Item Filter rule with BlockedTags UCF.Slot.KeyItem and UCF.Slot.Upgrade, CapacityTag UCF.Inventory.Capacity.CaseRows), Key Items (UCF.Inventory.Container.KeyItems: List, an Item Filter rule with AllowedTags UCF.Slot.KeyItem and UCF.Slot.Upgrade, bOpensBags on, so keys and pouches take no room in the case and a pouch opens there) and Stash (UCF.Inventory.Container.Stash: Slots, SlotCount 30, bCarried off, bTakesNewItems off, AccessTag UCF.State.AtStash; the same container asset the three demo style configs list, so a stash survives a switch of config).
  • Each item larger than one cell gets a Grid Footprint fragment (unreal.UCFItemFragment_GridFootprint, Size columns by rows: the demo sword 1 by 3, the shield 2 by 2). The hip pouch (/UniversalCombatFramework/Demo/Items/Bags/Item_UCF_HipPouch) is a bag whose Container fragment opens Container_UCF_HipPouch, a Grid 6 by 1 with the case's Item Filter; the case is listed first, so adds fill it before the pouch's cells, and what lies in those cells drops, travels and comes back with the pouch. The demo survival grid screen draws each open pouch's cells under the case (WBP_UCF_ExtraCells). For space that stays with the character, such as a case upgrade, give an item a Capacity Bonus row for UCF.Inventory.Capacity.CaseRows instead: it adds a row, and the player cannot drop it while that row holds an item.
  • CarryRules: the demo's Blueprint rule BP_UCF_InventoryRule_UniqueKeyItems (one of each key item). CombineSets: the demo's CombineSet_UCF_Demo (Combines, below). bPutAwayAtOnce on, so a screen's put-away leaves the hand at once while Equip keeps its draw animation. bShowCarriedItemsOnBody on, so every weapon in the case hangs on the body.
  • The stash is opened at a demo storage box (Storage boxes, below). A whole stack on the belt never goes into storage the character does not carry until the belt lets go of it; the demo screens' Store clears the belt slot first.
Check: in Play, a sword's CanPlace onto the case's cell (0, 3) answers REFUSED with UCF.Inventory.Refused.OutOfBounds upright and PLACE with bRotated on.
Recipe: a party RPG inventory
A backpack that never refuses for space, weight tiers that slow, pouches that open, worn gear for a paper doll and a stash. Duplicate InventoryConfig_UCF_PartyRPG:
  • Containers: Backpack (UCF.Inventory.Container.Backpack: List, bOpensBags on, so a pouch opens once picked up) and Stash (UCF.Inventory.Container.Stash: Slots, SlotCount 30, bCarried off, bTakesNewItems off, AccessTag UCF.State.AtStash).
  • CarryRules: a Weight Limit with Limit 60, bRefuseOverLimit off and Thresholds UCF.State.Encumbered at 0.7 and UCF.State.HeavilyEncumbered at 1. Every item gets a Weight fragment. The slow is the character's UCF Speed Modifier (SpeedScaleByTag: the demo character's 0.85, and 0 for UCF.State.HeavilyEncumbered and UCF.State.Overburdened, which hold it still); the demo character's UCF Sprint names UCF.State.Encumbered and UCF.State.Overburdened in its BlockedTags, so an encumbered character cannot sprint.
  • CombineSets: CombineSet_UCF_Demo. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce on, so the screen equips, puts away and combines at once. BeltSpace and EquippedSpace FREES_ITS_PLACE, so an item on the belt or in hand, worn gear included, leaves the backpack while held and its weight still counts. BeltSlots: four empty tags, a row taking any item.
  • The Stash is the same container as the survival grid's, opened at the same storage box (Storage boxes, below). The party RPG screen's paper doll is WBP_UCF_PaperDoll (Inventory screens, below); a doll of the project's own reads the equipment manager's GetInstanceInPlace for each place it shows, skips the unarmed fallback (IsDefaultItem), and redraws on OnDrawnStateChanged. Loot chests are BP_UCF_LootChest (Loot chests, below).
Check: in Play, seven of the demo shields (weight 6 each) put UCF.State.Encumbered on the character, eleven add UCF.State.HeavilyEncumbered, and the character's speed modifier's GetCurrentSpeedScale reads 0.85, then 0.
Recipe: an open world list
One list with no size, weight that slows past the limit without refusing, categories by item kind and no belt, as in Skyrim. Duplicate InventoryConfig_UCF_OpenWorldList:
  • Containers: Satchel (UCF.Inventory.Container.Satchel: List) and the demo's Stash (Container_UCF_Stash, as the survival grid lists it), which the list screen shows in a panel of its own on the right of its frame while the character stands at a storage box.
  • CarryRules: a Weight Limit with Limit 60, bRefuseOverLimit off and a threshold UCF.State.Overburdened at 1, and the demo's Blueprint rule BP_UCF_InventoryRule_Valuables (UCF.State.CarryingValuables while an item worth 100 gold or more is carried).
  • SortOrder: UCF.Slot.Weapon, UCF.Slot.OffHand, UCF.Slot.Apparel, UCF.Slot.Consumable, UCF.Slot.Ingredient; items of no listed kind sort last. The demo's list screen shows the satchel in that order (GetItemsInSortOrder), with a category column filtering by the same kinds.
  • bHasBelt off: the player has no belt while this config is used. The belt has no slots, so the 1 to 4 keys do nothing and nothing goes on it, and the HUD and the list screen show no belt, no On Belt category and no Add to belt prompt. Leave it on for a list with the belt as favorites: the screen then sends RequestAssignSlot, and its On Belt category lists the belt's items.
  • CombineSets: CombineSet_UCF_Demo. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce on, since the list screen pauses a game with no other players and a paused world runs no timers.
Check: in Play, RequestSort of UCF.Inventory.Container.Satchel lays a key, a herb, a potion, a helmet and a sword out as sword, helmet, potion, herb, key, and the player's belt GetNumSlots reads 0.
Recipe: hands only
The character carries only what its two hands hold: a pickup comes straight to hand, a second one-handed item to the other hand, and a third swaps for the item in hand. InventoryConfig_UCF_SingleItem does it for one hand; for two, make the config from scratch (Containers, above):
  • Containers: one container, Slots with SlotCount 2, bCarried on, no rules. BeltSpace and EquippedSpace stay KEEPS_ITS_PLACE (the defaults), so two held items fill it.
  • bSwapWhenFull on, so a third pickup reads Swap and puts down the item in hand that makes room, the weapon driving combat first.
  • BeltSlots: two empty tags, a belt of two slots taking any item. On the controller's belt, bAutoPopulateFromInventory and bAutoDrawOnInit on: a picked-up item lands on the first free slot and comes to hand while its Hold Places are free. For two of one item, the belt's DefaultMaxCopiesPerDefinition must allow two (0 is no limit; the demo controller's is 1), or the item needs a Belt Limit fragment of 2.
  • No HUD shows the belt: leave UCF.UI.Show.Belt out of the style's Gameplay Tags fragment. Leave the belt's keys out of the game's mapping context so no key puts an item away.
An item the hands cannot hold beside what they hold, a two-handed weapon beside a sword, stays in its slot, unheld, until something draws it.
Check: in Play, picking up two swords puts one in each hand (GetItemsInHand holds two), and a third pickup's prompt reads Swap; taking it leaves the first sword on the ground and the new one in its hand.
Recipe: a keychain
Every key the player picks up goes onto a keychain by itself and never into the pack, a key cannot be dropped, and a key weighs nothing, with a pack that holds 30 weight beside it. This is also the pattern for any items that live apart from the rest: ammunition, quest items, crafting materials. Three facts carry it:
  • A container listed first is tried first by each add, and an Item Filter rule on it lets in only the UCF.Slot.KeyItem kind, so keys land there and nothing else does. The pack, listed second, takes the rest.
  • An item with no World Item fragment cannot be dropped or lie on the ground: the drop ability refuses it and the demo screens show no Drop for it.
  • An item with no Weight fragment weighs nothing, so the weight limit does not count a key, even in a pack already full.
F = "/Game/Inventory"                                    # the customer's folder
ucf.add_gameplay_tag("UCF.Inventory.Container.Keychain", "The player's keychain")
 
def make_item(name, kind, stack=1, weight=None):
    item = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{name}")
    item.set_editor_property("DisplayName", name)
    item.set_editor_property("SlotTags", tags(kind))
    item.set_editor_property("MaxStackSize", stack)
    if weight is not None:
        w = unreal.new_object(unreal.UCFItemFragment_Weight, outer=item)
        w.set_editor_property("Weight", weight)
        item.set_editor_property("Fragments", [w])
    save(item)
    return item
 
rusty = make_item("RustyKey", "UCF.Slot.KeyItem")        # no Weight, no World Item fragment
gold = make_item("GoldKey", "UCF.Slot.KeyItem")
flint = make_item("Flint", "UCF.Slot.Ingredient", stack=10, weight=1.0)
 
keychain = new_data_asset(unreal.UCFContainerDefinition, F, "Container_Keychain")     # a List by default
only_keys = unreal.new_object(unreal.UCFInventoryRule_ItemFilter, outer=keychain)
only_keys.set_editor_property("AllowedTags", tags("UCF.Slot.KeyItem"))
keychain.set_editor_property("Rules", [only_keys])
save(keychain)
pack = new_data_asset(unreal.UCFContainerDefinition, F, "Container_Pack")
save(pack)
 
config = new_data_asset(unreal.UCFInventoryConfig, F, "InventoryConfig_Hero")
rows = []
for container_tag, definition in (("UCF.Inventory.Container.Keychain", keychain), ("UCF.Inventory.Container.Backpack", pack)):
    row = unreal.UCFContainerSpec()
    row.import_text(f'(Container=(TagName="{container_tag}"),Definition="{definition.get_path_name()}")')
    rows.append(row)
config.set_editor_property("Containers", rows)             # the keychain first
limit = unreal.new_object(unreal.UCFInventoryRule_WeightLimit, outer=config)
limit.set_editor_property("Limit", 30.0)
config.set_editor_property("CarryRules", [limit])
save(config)
 
bp = load("/Game/Player/BP_Hero")                          # the customer's player
defaults(bp).get_editor_property("InventoryComponent").set_editor_property("Config", config)
save(bp)
UCF.Slot.KeyItem exists already; the keychain's container tag is new, and UCF.Inventory.Container.Backpack is a ready one. Every further key is one more make_item(..., "UCF.Slot.KeyItem") with no weight. A key with no World Item fragment has no look on the ground either, so it reaches the player from a chest (Loot chests, below), a reward or a starting item: inv.add_item_definition(key, 1) on the server. A key that has to lie in the level carries the fragment and can be dropped again, unless the project's drop ability refuses it in its Can Drop (a Blueprint step).
Check: in Play (AGENTS.md, Player Recipe 2, Step 8, starts it and reaches the pawn), inv is the pawn's unreal.UCFInventoryComponent. With 10 Flint in the pack, inv.add_item_definition(rusty, 1) returns a stack, unreal.GameplayTagLibrary.get_tag_name(inv.get_item_placement(stack).container.tag) reads UCF.Inventory.Container.Keychain, inv.get_weight(unreal.UCFContainerId()) is the same before and after, and rusty.find_fragment_by_class(unreal.UCFItemFragment_WorldItem) is None. The flint's placement reads UCF.Inventory.Container.Backpack.
Variant: the keychain is an item the character carries. A bag opens a container of its own (Bags, below), so the keychain can be an item the player is given, and the pack, which opens bags, turns keys away so adds reach the open keychain. The keychain is a bag with no World Item fragment, so it cannot be dropped either:
holds = keychain                                           # Container_Keychain above: the Item Filter on keys
chain = make_item("Keychain", "UCF.Slot.Upgrade")
bag = unreal.new_object(unreal.UCFItemFragment_Container, outer=chain)
bag.set_editor_property("Definition", holds)               # ContainerTag keeps its default, UCF.Inventory.Container.Bag
chain.set_editor_property("Fragments", [bag])
save(chain)
 
pack = new_data_asset(unreal.UCFContainerDefinition, F, "Container_PackWithBags")
pack.set_editor_property("bOpensBags", True)
no_keys = unreal.new_object(unreal.UCFInventoryRule_ItemFilter, outer=pack)
no_keys.set_editor_property("BlockedTags", tags("UCF.Slot.KeyItem"))
pack.set_editor_property("Rules", [no_keys])
save(pack)
# The config lists the pack alone; the character starts with the keychain.
defaults(bp).get_editor_property("InventoryComponent").set_editor_property("StartingItems", [chain])
More pieces from Python
The keychain recipe shows the calls; the rest of the pieces take the same ones.
  • A container shaped as slots or a grid. layout = unreal.UCFContainerLayout.SLOTS with SlotCount, or GRID with GridSize as unreal.IntPoint(6, 4) and bAllowRotation; either grows with a CapacityTag. An item bigger than one grid cell carries a Grid Footprint fragment (Size, unreal.IntPoint(1, 3)). A container off the character, such as a bank, sets bCarried off (its items leave the weight limit, the belt and Get Item Count), and bTakesNewItems off keeps adds out of it; AccessTag locks it to a character holding that tag.
  • A cap per item kind. A Category Limit rule, on a container's Rules or the config's CarryRules, with Limits rows written as text: row = unreal.UCFCategoryLimit(); row.import_text('(Category=(TagName="UCF.Slot.Ammo.Arrow"),MaxUnits=20)'), then rule.set_editor_property("Limits", [row]).
  • A weight limit that slows instead of refusing. bRefuseOverLimit off and Thresholds rows, each '(Fraction=0.7,Tag=(TagName="UCF.State.Encumbered"))' through unreal.UCFWeightThreshold().import_text(...); the tag then sits on the character, and the character's UCF Speed Modifier or a transition's BlockedTags gives it an effect.
  • An item that grows a capacity. A Capacity Bonus fragment whose Bonuses row names the capacity tag and an Amount, written as text (unreal.UCFCapacityBonus().import_text('(CapacityTag=(TagName="UCF.Inventory.Capacity.CaseRows"),Amount=1)')); a container's, a Weight Limit's or a Category Limit's CapacityTag names the same tag. The player cannot drop, store or put back such an item while items sit in the slots or rows it gives (CanItemLeave answers UCF.Inventory.Refused.CapacityInUse); for extra space whose items go with it, make the item a bag.
  • The config's other settings. SortOrder (a list of tags: [tag("UCF.Slot.Weapon"), tag("UCF.Slot.Consumable")]), BeltSpace and EquippedSpace (unreal.UCFHeldItemSpace.FREES_ITS_PLACE), bSwapWhenFull, and the three at-once switches, all plain set_editor_property writes.
  • Which screen it opens. A config of the project's own needs a row in the screens component's InventoryScreenClasses, or it opens the open world list (Inventory screens, below).
Building on it in Blueprint
Each extension is a Blueprint class whose parent is a UCF class, created with unreal.BlueprintFactory (parent_class) and listed on the config; its graph is a Blueprint step. The demo's are in /UniversalCombatFramework/Demo/Items/Inventory/Blueprints, ready to duplicate:
  • A rule (parent unreal.UCFInventoryRule): override GetUnitsAccepted to turn items away (BP_UCF_InventoryRule_UniqueKeyItems reads the inventory's GetItemCount) or GetStatusTags to tag the character (BP_UCF_InventoryRule_Valuables). The context's Departing lists what leaves the rule's scope in the same change, a row per stack (a swap's other item, what a combine takes from both of its stacks), and ArrivingWith what comes in beside the item; count the first as gone and the second as already in, as the unique key rule counts Departing. List it on a container's Rules or the config's CarryRules. A rule keeps no state of its own.
  • A combine (parent unreal.UCFInventoryCombine): for what a Combine Set's recipe row cannot say; the demo's Load Holder and Coat Weapon (Combines, below).
  • An item fragment (parent unreal.UCFItemFragment): data an item carries, such as BP_UCF_ItemFragment_GoldValue (an integer Value). Add an instance to an item's Fragments like any fragment; a graph reads it with the item instance's FindFragmentByClass and a cast. The C++ sort reads Slot Tags only, so a Blueprint fragment orders nothing by itself.
Inventory screens
The demo ships one inventory screen per ready style, Widget Blueprints in /UniversalCombatFramework/Demo/UI/Widgets/Inventory:
ScreenOpens forShows
WBP_UCF_InventoryScreen_OpenWorldListInventoryConfig_UCF_OpenWorldList, any config with no row of its own, and an inventory with no configA category column, the satchel as one list in SortOrder, an item card with its prompts, a weight bar; a chest's items, or the Stash at a storage box, in a mirrored panel of their own on the right
WBP_UCF_InventoryScreen_SurvivalGridInventoryConfig_UCF_SurvivalGridThe case as a grid where items turn to fit, Key Items beside it
WBP_UCF_InventoryScreen_PartyRPGInventoryConfig_UCF_PartyRPGThe backpack, a panel per open pouch, the paper doll, a weight bar marking both slowdowns
BPC_UCF_InventoryScreens, a component on BP_UCF_PlayerController, opens the screen for the character's inventory config on I, or a tap of View on a pad (holding View respawns), and I, View, B or Escape closes it. While it is open the character stands: move, look and combat input stop, and a hit still lands. Every screen also shows the belt while the character holds UCF.UI.Show.Belt and the storage panel at a storage box; the grid and party screens show the chest panel at a loot chest. On the grid and party screens a mouse click selects an item and shows its details and actions (Consume and Combine sharing the first row, Equip, Unequip, Split, Drop, Add to belt, each grayed when it does not apply; Take alone for an item in a chest), a drag moves it, and right click runs its main action (Equip, Unequip or Consume; Take or Store at a chest or a storage box); a pad picks up and puts down with A, opens the actions with X, turns a carried item with Y and moves between panels with LB and RB. The list screen opens on All with the first item highlighted and its card showing: the mouse over an item, Up and Down, or the D-pad highlight it and its card follows; a click, a right click, E or pad A runs its main action (Equip, Unequip or Consume; Take or Store at a chest or a storage box), C or the right trigger combines, R or pad X drops it (takes everything at a chest), F or pad Y adds it to the belt, 1 to 4 put it on that belt slot, LB and RB step through the categories, and Left or B goes back to the categories. On every screen Combine holds the item until the next item picked, in any category or panel, is combined with it; Cancel, Back and closing the screen let it go.
Ask the customer whether the game uses a demo screen as it is, a copy changed for the game, or a screen of its own.
  • As it is. Keep BP_UCF_PlayerController, or the project's duplicate of it, as the game mode's PlayerControllerClass, or add BPC_UCF_InventoryScreens to the project's own player controller (Components panel, Add; a Blueprint step), which brings the screens, the I and Back keys and the chest's Open option with it; a player ability set duplicated from AbilitySet_UCF_Default already grants the use and drop abilities (Using and dropping from a screen, below). The component's InventoryScreenClasses maps each inventory config to its screen, and FallbackInventoryScreen serves the rest, so a config duplicated from a demo one needs a row of its own, or it opens the open world list.
  • A copy. Duplicate the screen into the project's folder, point the screens component's row at the copy, and change the copy in the Widget Blueprint editor (a Blueprint step). Data the customer changes in the editor's Class Defaults or Details panel: the list panel's CategoryRows (WBP_UCF_ListPanel, which both sides of the list screen share; each a Label, the item kinds it shows in Kinds, OtherKinds for a row taking what no other row names, or BeltOnly for a row of the belt's items), the paper doll's Places (WBP_UCF_PaperDoll: a place tag, a label, a row and a column each, following BP_UCF_Character's places, held once in the doll's class defaults, so a body with other BodyPlaces needs them edited there) and the message line's RefusalWords (WBP_UCF_InventoryMessage: the words shown for each UCF.Inventory.Refused and UCF.Equipment.Cancelled reason; a reason with no row shows the last part of its tag). A copy keeps using the blocks in Common beside the screens, so keep the demo in the project while it does.
  • A screen of the project's own. Start from a copy all the same: the blocks in Common hold every action once. WBP_UCF_ItemTile draws one item or one empty place; WBP_UCF_ContainerList, WBP_UCF_ContainerGrid and WBP_UCF_ContainerSlots draw one container each; BP_UCF_ItemMove is the carried item, for a mouse drag and a click or pad pick-up alike; BFL_UCF_InventoryScreens holds each item action as a check and a send, and the carry flow every screen calls (Pick Up, Put Down, Put Back, Send To Belt); BPI_UCF_InventoryScreen is what the screens component and the tiles call on a screen, Show Inventory among them; the panels are WBP_UCF_BeltPanel, WBP_UCF_StoragePanel, WBP_UCF_ChestPanel, WBP_UCF_BagPanel and WBP_UCF_PaperDoll. Keep the screens' contract: every action asks the check its request runs on the server (Containers, above), sends the request only when the check said yes, and redraws from the components' events once the change arrives, about a round trip later, with nothing predicted. A button that moves an item with no place picked, such as Take or Store, asks the inventory where it lands: FindTransferDestination between the player's inventory and a chest, FindMoveDestination into one container, FindAddDestination where an add would put it; each answers the place one request moves the most units into, with the server's own answer there and, on a refusal, its reason (Full, or Held when the belt or the hand holds the item and more of it would land once they let go), and the button sends RequestTransfer or RequestMove with that place. Pick Up plays the item's grab sound and Put Down and Put Back its place sound, from the equipment manager's GetInventoryMoveSound (the item's own InventoryGrabSound and InventoryPlaceSound, else its Stowable fragment's DrawSound and PutAwaySound, and none for a move into or out of the hand that the item's look sounds itself). UCFInventoryStatics.GetItemFootprint answers an item's grid cells for a drag picture, the belt's GetSlotOfItem the slot an item sits in, and the inventory's IsHeldBy whether the belt or a hand holds it.
The look. The screens, the HUD and the interaction prompts all draw from one theme asset, /UniversalCombatFramework/Demo/UI/Theme/UITheme_UCF_Default: its colors, fonts, surfaces and paddings restyle every one of them, and a copied screen keeps reading it. In a copy, blocks move freely, and the weight bar, belt panel, hint bar and item details can be deleted. A new widget takes a theme role from a row in its Widget Blueprint's ThemeRoles map (the widget's name and an E_UCF_UIRole); a renamed widget needs its key renamed too, or that part keeps its own look and the log shows a line (LogBlueprintUserMessages) each time the designer refreshes that widget. A color change is an edit to a copy of the theme in the project's folder, since a plugin update replaces the shipped one:
theme = duplicate(f"{DEMO}/UI/Theme/UITheme_UCF_Default", F, f"UITheme_{N}")
theme.set_editor_property("Accent", unreal.LinearColor(0.80, 0.25, 0.05, 1.0))
save(theme)
Every shipped widget reads its theme through the Get UI Theme function of BFL_UCF_UITheme, beside the theme asset, which returns UITheme_UCF_Default; pointing it at the copy is a Blueprint step for the customer.
A row for a duplicated config or a copied screen goes on the screens component's class defaults: duplicate BPC_UCF_InventoryScreens into the project and put the copy on the project's controller in place of the demo's (a Blueprint step), then:
comp = load("/Game/Player/BPC_InventoryScreens")
d = defaults(comp)
screens = d.get_editor_property("InventoryScreenClasses")
screens[load("/Game/Inventory/InventoryConfig_Survival")] = load(f"{DEMO}/UI/Widgets/Inventory/WBP_UCF_InventoryScreen_SurvivalGrid").generated_class()
d.set_editor_property("InventoryScreenClasses", screens)
save(comp)
Opening from the world. An interaction option whose OptionId is OpenInventory opens the screen as the interaction starts, with the interactable's UCF World Inventory beside it when the actor has one. Give it a payload that ends as it starts, as the demo's Delay of 0 s, since only a payload reports the start; a longer one keeps the interaction running behind the screen, which hides the prompt and refuses the next interact press after a close (Interaction, below, writes the option as text):
opt = unreal.UCFInteractionOption()
opt.import_text('(OptionId="OpenInventory",ActivationInputTag=(TagName="UCF.Input.Interact"),Prompt=(Verb=NSLOCTEXT("", "", "Open"),Name=NSLOCTEXT("", "", "Chest")),PayloadSpec=/Script/UCFInteraction.UCFDelayInteractionPayloadSpec(DelaySeconds=0.0))')
Check: in Play on LVL_UCF_Demo, with InventoryConfig_UCF_OpenWorldList set on the player's inventory (SetConfig; the demo player starts on InventoryConfig_UCF_Simple, which opens no screen), F at the hallway's loot chest takes its potions, ring and necklace; I then opens the open world list on its categories, All lists the ring and the necklace above the potions, Consumables lists the potions only, and I closes it again.
Storage boxes
A stash holds each player's own items: the Stash is a container of the player's inventory reached with an Access Tag (the survival grid and party RPG recipes, above). The demo's BP_UCF_StorageBox (/UniversalCombatFramework/Demo/Interactables/StorageBox) gives a character standing in its zone the Access Tag of that character's own storage, the first container its inventory does not carry, through GE_UCF_StorageAccess, applied on the server, and its Open option opens the screen with the storage panel beside the bag. One box serves every style. From the storage panel the player can equip an item or put it on the belt directly: RequestEquipItem and RequestAssignSlot move it into the carried containers first, and their checks (CanEquipItem, CanAssignSlot) answer for it; the inventory's CanTakeToHold names why one is refused, such as Too Heavy or Full. A chest's items work the same way. To open one container only, place one and set its tag:
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
box = actors.spawn_actor_from_class(EAL.load_blueprint_class(f"{DEMO}/Interactables/StorageBox/BP_UCF_StorageBox"), unreal.Vector(400, 0, 0))
box.set_editor_property("AccessTag", tag("UCF.State.AtStash"))
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
LVL_UCF_Wardrobe_Hall places one stash box between the Backpack And Weight and One List pads.
Using and dropping from a screen
Use drinks a potion or eats a herb. The screen's Use sends the inventory's RequestUseItem, and a belt slot holding an item that is not equippable does the same when pressed; on the server both send the gameplay event UCF.Event.UseItem with the item as the event's Optional Object to the character's ability system. The demo's GA_UCF_UseItem (Server Only, Ability Trigger UCF.Event.UseItem, granted by AbilitySet_UCF_Default with no input) spends one unit and applies the item's BP_UCF_ItemFragment_UseEffect (a vital tag and an amount); the screen offers Use only for an item carrying that fragment, and the demo potion, herb and mixed herb do. An ability of the project's own on the same trigger must be Server Only (NetExecutionPolicy SERVER_ONLY): the event is sent on the server, which starts no Local Predicted ability for a remote player.
Drop sends UCF.Event.DropItem with the item to the player's own character, where GA_UCF_DropFromScreen (a UCF Drop Ability with ItemSelection From Event and DropCount 0, granted by AbilitySet_UCF_Default with no input) drops the whole stack. The screen offers Drop only for an item with a World Item fragment, while the inventory's CanItemLeave says yes.
Check: in Play, with the character's health below its maximum, Use on a potion spends one (GetItemStackCount) and raises UCF.Vital.Health (the character's VitalsComponent, GetVitalValue); a potion on the belt's right slot does the same when its key is pressed.
Combines
What combining one item with another makes, such as two herbs mixed into a mixed herb, rounds loaded into a magazine one at a time or a key opening a locked box, lives in a UCF Combine Set (unreal.UCFCombineSet, a data asset: Add, UCF, Items, Combine Set) on the config's CombineSets, so several configs share one set. A drop of one item onto another, or a screen's Combine, asks each set's recipes and then its combines, in order; the first that matches the two items decides, ahead of a merge or a swap. The demo's CombineSet_UCF_Demo (/UniversalCombatFramework/Demo/Items/Inventory) holds Mix Herbs and Dip Arrows as recipes and Load Holder and Coat Weapon as Blueprint combines.
Recipes (unreal.UCFCombineRecipe, plain rows, no Blueprint): item_a and count_a, item_b and count_b, results (each a unreal.UCFCombineResult with item and count; a second result gives a byproduct back, such as an empty bottle), order_matters (off: either item dropped onto the other combines), required_tags (the character's ability system must hold them all, else the drop is refused UCF.Inventory.Refused.Locked; a workbench zone grants one as the demo storage box grants its Access Tag) and seconds (each combine's time, moving stopping it; 0 is at once). A drop makes as many whole combines as the dragged units and both stacks allow; it is refused UCF.Inventory.Refused.NotEnough while a stack holds too few for one, and with the add's reason when the results do not fit. The results of each combine are judged with the units it takes already gone, so at a weight limit a result weighing no more than what it uses passes. A row that would use up a bag still holding anything it does not also use is refused UCF.Inventory.Refused.BagNotEmpty; the bag is emptied first. The config's CombineResultPlace (unreal.UCFCombineResultPlace: ONTO_THE_TARGET, the default, ONTO_THE_SOURCE, AS_ADDED) says where the first result goes: the place of the item combined onto, or of the item picked first, once the combine uses that item's stack up, the place is not inside the other item (a bag the combine uses up) and the result fits there, else where an add would; the other results go where an add would. Nothing a combine makes goes on the belt by bAutoPopulateFromInventory, but a belt slot an ingredient emptied takes the first result when CanAssignSlot lets it in.
herb = load("/Game/Items/Item_Herb")
mixed = load("/Game/Items/Item_MixedHerb")
combine_set = new_data_asset(unreal.UCFCombineSet, "/Game/Inventory", "CombineSet_Knight")
made = unreal.UCFCombineResult()
made.set_editor_property("item", mixed)
recipe = unreal.UCFCombineRecipe()
recipe.set_editor_property("item_a", herb)
recipe.set_editor_property("item_b", herb)
recipe.set_editor_property("results", [made])
recipe.set_editor_property("seconds", 1.0)
combine_set.set_editor_property("recipes", list(combine_set.get_editor_property("recipes")) + [recipe])
save(combine_set)
config = load("/Game/Inventory/InventoryConfig_Knight")     # the project's copy of a demo config
config.set_editor_property("combine_sets", list(config.get_editor_property("combine_sets")) + [combine_set])
save(config)
Combines (unreal.UCFInventoryCombine, instanced on the set's combines) for logic a row cannot say. The combine is the project's own class, a Blueprint child overriding its three functions (a Blueprint step) or a C++ subclass in the project's module; the demo's BP_UCF_Combine_LoadHolder and BP_UCF_Combine_CoatWeapon in /UniversalCombatFramework/Demo/Items/Inventory/Blueprints are ready to copy. Load Holder fills any item carrying the demo Holder fragment (BP_UCF_ItemFragment_Holder: Holds, the item it takes; Capacity; StatTag, the stat counting what one unit holds), so a quiver is an item with that fragment holding arrows, with nothing else to set, and the demo screens show its load over its capacity, 12/20.
  • Matches(Item, Target): whether it handles Item dropped onto Target.
  • GetUnits(Query, OutReason): how many units to make, from 0 to Query.Count (Query, a UCFInventoryCombineQuery: Inventory, Item, Target, Count). Asked when the drop is judged, also by a screen previewing it, and again before each unit with the units left; it changes nothing. 0 turns the drop down; set OutReason to a tag under UCF.Inventory.Refused, such as UCF.Inventory.Refused.Full.
  • ApplyUnit(Context) (Context, a UCFInventoryCombineContext with the same four fields): makes one unit on the server, such as one more stack of a loaded stat tag on Target (AddStatTagStack) and one unit of Item consumed (the inventory's ConsumeItemInstance).
  • UnitTiming (unreal.UCFItemActionTiming): half a second per unit by default, stopped by moving; 0 makes every unit at once.
For a magazine: rounds stack, the magazine has MaxStackSize 1 and counts its rounds in a stat tag; GetUnits is the least of Query.Count, the inventory's GetItemStackCount(Item) and the room left, else 0 with Refused.Full. For a locked box: GetUnits is 1 when the key and the box share a lock tag in their SlotTags and the box lacks an unlocked stat tag, else 0 with UCF.Inventory.Refused.NotAdmitted; ApplyUnit adds the unlocked stat tag and consumes the key; UnitTiming 1.5 s.
combine_set = load("/Game/Inventory/CombineSet_Knight")
combine = unreal.new_object(EAL.load_blueprint_class("/Game/Inventory/BP_MagazineCombine"), outer=combine_set)
combine_set.set_editor_property("combines", list(combine_set.get_editor_property("combines")) + [combine])
save(combine_set)
The UI changes nothing for a combine beyond what it does for a move: CanPlace answers COMBINE (unreal.UCFPlaceResult) with the units, or REFUSED with the recipe's or combine's reason, and RequestMove starts it. A Combine button names the target by item instead: RequestCombine(Item, Target) combines Item's whole stack with Target, an item in hand with no place included, and unreal.UCFInventoryStatics.can_combine(inventory, item, target) is its check: None when the two do not combine now, else (results, reason) with the recipe's results (UCFCombineResult rows) and an empty reason (Python.md says why the yes or no is not returned; a Blueprint node has pins for the results and the reason, UCF.Inventory.Refused.NoCombine when nothing combines the two). The inventory's OnCombined reports each landing on the server and the owning player's machine, with the two items, the recipe (its Set and RecipeIndex in that set's recipes) or the Combine, and the units that landed together in its Units. The config's bCombineAtOnce lands every unit at once with no wait, as a screen that pauses the game needs, and OnCombined then fires once for all of them. While it runs, OnEquipStepStarted fires once per unit (the step's SourceItem is the target, UsedItem the dropped item, Timing.Seconds the unit's length) and OnEquipSequenceEnded reports the end, while GetPlayingStep answers how far the current unit has got and how many units have landed, for a widget opened partway; moving, RequestCancelSequence with either item, or either item leaving stops it, and the units made stay. One equipment change runs at a time, so a belt press during a load is turned down.
Check: in Play, with a stack of 10 rounds and an empty magazine of 6, the inventory's CanPlace for 10 rounds onto the magazine's place answers COMBINE with 6; RequestMove with the same arguments loads one round per half second, and after 3 seconds the magazine counts 6 and the stack 4.
Bags
A bag bar whose pouches hold items, as in an MMO: a bag in a bag bar slot opens a container of its own, and in a backpack that opens no bags it is closed, keeping what it holds out of reach. The demo pouch is /UniversalCombatFramework/Demo/Items/Bags/Item_UCF_Pouch; the demo party RPG config opens it in its backpack instead (Container_UCF_Backpack has bOpensBags on).
  • The bag bar is a config row whose definition has bOpensBags on and bTakesNewItems off, listed after the backpack, so adds fill the backpack and then the bags in bag bar order (row tag UCF.Inventory.Container.BagBar).
  • A bag is an item with MaxStackSize 1 and a Container fragment (unreal.UCFItemFragment_Container): Definition, the UCF Container Definition of what it holds (its own size, rules, bCarried, bTakesNewItems, AccessTag, bOpensBags off), and ContainerTag (UCF.Inventory.Container.Bag by default; never a tag the config's own rows use).
  • A bag's container is named by a UCF Container Id (unreal.UCFContainerId: Tag and ProvidingItem, the bag); a tag alone names one of the config's rows. GetContainers lists each open bag's id right after the bag bar, and GetContainerOpenedBy answers it for one bag, so a bag bar slot opens its bag's window with it.
pouch = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Pouch")
bag = unreal.new_object(unreal.UCFItemFragment_Container, outer=pouch)
bag.set_editor_property("Definition", load("/Game/Inventory/Container_Pouch"))
pouch.set_editor_property("MaxStackSize", 1)
pouch.set_editor_property("Fragments", [bag])
save(pouch)
A UI moves a bag onto the bag bar with RequestMove; its container opens and OnCapacityChanged fires with its id. Dropping a stack on an open bag puts it inside: CanPlace answers INTO_BAG (unreal.UCFPlaceResult), or REFUSED with the bag's reason, such as UCF.Inventory.Refused.Full. A bag on the belt or in hand stays open, also where the belt or the hand frees its place. A bag keeps what it holds wherever it goes: moved off the bag bar, into storage or a chest, or dropped, it closes with its items inside, and they come back in their places when it opens again or is picked up (a dropped bag's GetUnitsThatFit judges the bag and its items together). A bag holding items never goes inside another bag (REFUSED with UCF.Inventory.Refused.BagNotEmpty), and an item the belt or the hand holds stays with the character when its bag leaves. Game code removing or consuming a bag holding items spills them into the first free places, kept past the end of the backpack when none is free; TakeItemOut takes a bag out with its items instead, as a drop does.
Check: in Play with a backpack row and a bag bar row on the player's config and a pouch added, RequestMove of the pouch to UCF.Inventory.Container.BagBar place 0 makes GetContainerSize of its id read 8 by 1; a potion stack's CanPlace onto that bag bar place answers INTO_BAG, and after RequestMove the potions sit in the pouch's container (GetItemsInContainer).
Saving the inventory
UCF is no save system: the game's own Save Game keeps the inventory. Give the Save Game Blueprint a variable of type UCF Inventory Snapshot (unreal.UCFInventorySnapshot), then, on the server (a Blueprint step):
  • Save: the inventory's ExportSnapshot into that variable, then Save Game to Slot, while the player's controller still possesses the character.
  • Load: Load Game from Slot, then the inventory's ImportSnapshot with the variable, from the player controller's On Possess after its parent call, or later. The character's Event Possessed is too early: the belt is not bound yet, so the belt slots stay empty and a warning says so. The import replaces everything the inventory held, starting items included, also on the first possession at map start, which comes before Begin Play, and puts back each stack's place, stat data, belt slot and what was in hand or worn, in the same places; anything the belt or the hand held from outside the inventory is put away.
Keep the redirector of an item asset moved or renamed after a save, or add a CoreRedirect for it, or the import leaves that item out with a warning. An item whose saved place a changed config no longer has takes the first free place, a bag's items come back inside it, and a stack saved larger than its item's Max Stack Size comes back as several stacks.
Pickups
A UCF World Item (AUCFWorldItem, or the demo's BP_UCF_WorldItem) placed in the level is picked up with the interact key: ItemDefinition, StackCount, PhysicsMode. It shows the item's Visuals mesh (its DropMesh when set) only for an item that also has a World Item fragment, so the item needs both. To put a fresh item in the world from Blueprint, as the demo's pickup spots do when they restore a taken pickup, Spawn Actor BP_UCF_WorldItem on the server and set Item Definition, Stack Count and Physics Mode on the node; one world item class serves every item.
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
pickup = actors.spawn_actor_from_class(unreal.UCFWorldItem, unreal.Vector(300, 0, 50))
pickup.set_editor_property("ItemDefinition", load(f"{F}/Item_{N}_Sword"))
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()
The duplicated player's ability set grants the interact ability on UCF.Input.Interact (E). A picked-up item goes into the inventory, and onto the first belt slot that takes it while the belt's bAutoPopulateFromInventory is on, as the demo controller's is.
Drops
Give the item a World Item fragment (UUCFItemFragment_WorldItem: DropMontage, WorldItemActorClass, DropAnchor, DropOffset, bProjectToGround, DropRotation, bSimulatePhysics, and ImpactSound with ImpactSilentSpeed and ImpactFullSpeed for the sound it makes each time it lands or bounces, louder the harder it hits) and the item's Visuals HeldMesh (or DropMesh) shows on the ground. The duplicated player's ability set grants the UCF Drop Ability (UUCFDropAbility: ItemSelection, DropCount, bSkipUndroppable) on UCF.Input.Drop, which IMC_UCF_Default maps to G. By default it drops what a hand holds, the weapon first, read from the equipment manager whether the item is on the belt or not; worn gear is never in hand, so G never drops a ring or a helmet. A screen's Drop button reaches a second drop ability, GA_UCF_DropFromScreen, through the event UCF.Event.DropItem (Using and dropping from a screen, above).
Check: in Play, G drops the held item as a world item and the inventory loses it; E near it picks it back up.
Item holders
A UCF Item Holder component (UUCFItemHolderComponent: Places, unreal.UCFItemHolderPlace rows PlaceId, PlaceComponentTag, Filter; ClaimRadius) on a replicated actor offers Take and Put Back for each place. Duplicate the demo's BP_UCF_WeaponRack.
Loot chests
A UCF World Inventory component (UUCFWorldInventoryComponent) on a replicated actor holds items every nearby player sees: Config and StartingItems as on a character's inventory, AccessRadius (cm from the character to the actor's collision, at least the interactor's Detection Radius plus the interact ability's Server Range Tolerance; 0 reaches from any distance) and AccessTag (a tag the character's own ability system must hold, a key). Duplicate the demo's BP_UCF_LootChest (/UniversalCombatFramework/Demo/Interactables/LootChest). Its UCF Interactable has two options: Open (OpenInventory, on UCF.Input.Interact, E) opens the player's inventory screen with the chest's items beside the player's (Opening from the world, above), and Take All (on UCF.Input.Interact.Secondary, F) calls the interacting character's inventory RequestTakeAll with the chest's World Inventory, which takes everything that fits and leaves the rest.
To give a chest contents of the project's own, duplicate the demo chest, write its World Inventory component and place the copy in the level. The component is a template inside the Blueprint (Python.md, Components on a Blueprint); InventoryConfig_UCF_LootChest is the demo's thirty-slot config, or make a config as the keychain recipe does and list its container on it:
chest = duplicate(f"{DEMO}/Interactables/LootChest/BP_UCF_LootChest", F, "BP_ProjectChest")
sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
for handle in sds.k2_gather_subobject_data_for_blueprint(chest):
    obj = unreal.SubobjectDataBlueprintFunctionLibrary.get_object_for_blueprint(unreal.SubobjectDataBlueprintFunctionLibrary.get_data(handle), chest)
    if isinstance(obj, unreal.UCFWorldInventoryComponent):
        obj.set_editor_property("Config", load(f"{DEMO}/Items/Inventory/InventoryConfig_UCF_LootChest"))
        obj.set_editor_property("StartingItems", [potion, potion, rusty])      # one unit per entry; repeats join into one stack
        obj.set_editor_property("AccessRadius", 250.0)                         # cm; an AccessTag locks it to a key holder
unreal.BlueprintEditorLibrary.compile_blueprint(chest)
save(chest)
Place the copy in the level the way the storage box example does (Storage boxes, above).
The demo's chest panel, WBP_UCF_ChestPanel, reads the World Inventory like any inventory (GetItemsInContainer, OnLayoutChanged) and moves items through the player's own inventory: CanTransfer and RequestTransfer (an item in either inventory, a destination in the other) and RequestTakeAll for its Take All button. Put the loot on an actor of its own, never on a character, and leave the chest config's container Access Tags empty; the World Inventory's own AccessTag locks the chest.
Check: in Play with two players, both read the chest's items with GetItemsInContainer, and F at the chest (Take All) moves them into the interacting player's inventory.
Interaction
The character's UCF Interactor (InteractorComponent): Detection (unreal.UCFInteractionDetection: NEAREST, FOCUSED, AIM, OVERLAP), Tracking (CONTINUOUS, ON_DEMAND), DetectionRadius, FocusConeHalfAngle, RequireSight, RequiredTags, BlockedTags.
An actor becomes interactable with a UCF Interactable component (UUCFInteractableComponent): Options (unreal.UCFInteractionOption rows: OptionId, ActivationInputTag (UCF.Input.Interact), Prompt (Verb, Name, Icon), PayloadSpec, Approach (SpotComponentTag, AcceptanceRadius), Restrictions (bLockMovement, bLockFacing, bLockCamera, bEndRunningAction), bCancelByAbility, Priority). With no payload, choosing the option fires the component's On Option Interacted event, which the actor's own Blueprint answers (opening the door: a Blueprint step; the demo's BP_UCF_Door and BP_UCF_Chest show it).
PayloadSpec makes the character do something first: Play Montage (FUCFMontageInteractionPayloadSpec: Montage, PlayRate, SectionName), Delay (FUCFDelayInteractionPayloadSpec), Trigger Ability / Event (FUCFEventInteractionPayloadSpec), Run Ability (FUCFRunAbilityInteractionPayloadSpec) or Payload Asset (FUCFAssetInteractionPayloadSpec). Run Ability triggers the character's own ability (Server Initiated or Server Only, granted once) with the interactable as the event's Target; the ability reads which option started it with Get Interaction Option Id on the event's Target Data (UUCFInteractionStatics::GetInteractionOptionId in C++). Python cannot set its fields one by one; write the option as text, the payload as its struct path followed by its fields:
opt = unreal.UCFInteractionOption()
opt.import_text('(OptionId="Pull",ActivationInputTag=(TagName="UCF.Input.Interact"),Prompt=(Verb=NSLOCTEXT("", "", "Pull"),Name=NSLOCTEXT("", "", "Lever")),PayloadSpec=/Script/UCFInteraction.UCFMontageInteractionPayloadSpec(Montage="/Game/Player/AM_Knight_PullLever.AM_Knight_PullLever",PlayRate=1.0))')
Read opt.export_text() back to confirm the payload took. An Action Payload asset for the Payload Asset kind is made with unreal.UCFActionPayloadFactory: set its PayloadClass (such as unreal.UCFMontageActionPayload), then TOOLS.create_asset(name, folder, unreal.UCFActionPayload, factory).
Mistakes
SymptomCause and fix
A drop on an item merges or swaps the two instead of combining themNo recipe or combine in the Combine Sets on the inventory's config takes the pair, the set is not on the config's CombineSets, or the character's inventory uses another config.
A key lands in the pack, not on the keychainThe keychain is not listed before the pack in the config's Containers, or its Item Filter's AllowedTags does not name the kind in the key's SlotTags (UCF.Slot.KeyItem). Rules are on the container definition's Rules, not on the config row.
Everything lands on the keychainA List takes anything its rules allow; the keychain has no Item Filter rule, or the rule was never written to the container definition's Rules list.
A key can be dropped, or counts toward the weight limitThe key carries a World Item fragment (droppable) or a Weight fragment (weighs); leave both off the item definition.
A recipe's drop does nothing at the weight limitThe result weighs more than the units the combine takes, so the load would pass the limit (UCF.Inventory.Refused.TooHeavy).
A recipe using a bag does nothingThe bag holds an item the recipe does not use (UCF.Inventory.Refused.BagNotEmpty); take it out first.
A rule, fragment or row set from Python has no effectThe list was edited and not written back with set_editor_property, or a row struct (a container row, a threshold, a limit, a bonus) was filled field by field instead of with import_text (Python.md).
A combine does nothingThe character has no UCF Equipment Manager (a warning names it), or another equipment change is running.
An item lands in no slotThe belt's bAutoPopulateFromInventory is off, every slot's Filter refuses its SlotTags, the belt is full, or the character carries one of the belt's BlockedTags.
A belt press does nothing under one combat styleThat style's Gameplay Tags fragment puts on a tag the belt lists in BlockedTags, such as UCF.State.BeltBlocked on the demo Freeflow style.
A ring or a helmet lands on the belt and draws with a number keyThe belt's slots have no Filter; give each slot an item kind, as the demo's diamond does.
I opens no inventory screenThe game mode's player controller carries no BPC_UCF_InventoryScreens, or its default mapping context lacks IA_UCF_Inventory.
I opens the open world list for another styleThe screens component's InventoryScreenClasses has no row for the config the character's inventory uses, as for a duplicated config; add one.
A screen offers no Use, or Use does nothingThe item carries no BP_UCF_ItemFragment_UseEffect, the character's ability set lacks GA_UCF_UseItem, or the project's own use ability is not Server Only.
A potion on the belt does nothing when pressedNo Server Only ability answers UCF.Event.UseItem on the character.
A screen's Drop does nothingThe character's ability set lacks GA_UCF_DropFromScreen, or the item has no World Item fragment.
The storage panel never shows at a boxThe box's AccessTag differs from the container's Access Tag in the character's config, or the character's config has no container the character does not carry.
A stack on the belt cannot go into the stashA whole stack on the belt never goes into storage the character does not carry; take it off the belt with RequestAssignSlot first, as the demo screens' Store does.
The pickup shows no meshThe item has no World Item fragment, or no Visuals mesh.
G does nothingThe held item has no World Item fragment, or the character's ability set lacks the drop ability.
The prompt never showsThe interactor's Detection or DetectionRadius misses the actor, or RequireSight is blocked.
A placed actor ignores Blueprint changes to its optionsThe placed actor keeps its own copy of Options; reset it to the Blueprint's on the placed actor.
A chest shows its items on the server onlyThe chest's actor does not replicate; turn on Replicates in its Class Defaults (a warning names the class).
Take All or a transfer moves nothingThe character stands farther than the chest's AccessRadius from its collision, lacks its AccessTag, nothing fits in its inventory, or the request went to a World Inventory rather than the player's own inventory.

Items and equipment: fragments, hands, shields and stowing (AgentGuide/Player/ItemsEquipment.md)

AGENTS.md, Recipes 2 and 4, make an unarmed item and a sword. This file covers the rest of an item: every fragment, which hand it takes, an off-hand shield, items shared through a preset, hanging items on the body when put away, and worn gear.
Tasks: an item that is not gear (a key, a material, a potion) and what it weighs, whether it can be dropped and where it is kept; a shield in the left hand beside the sword; a two-handed weapon; a supporting item that adds moves only while drawn; all swords sharing one set of keys; a sword on the back when sheathed; a draw animation; a Swing Trail behind each swing; only one heavy weapon on the belt; a helmet, a cape, armor or rings the character wears.
The item and its fragments
An Item Definition (UUCFItemDefinition): Fragments, Preset (UUCFItemPreset, whose Fragments the item inherits unless it has its own of that kind), SlotTags (which belt slots take it), MaxStackSize, DisplayName, Description, Icon. Make each fragment with unreal.new_object(cls, outer=item) and write the whole Fragments list back.
Fragment (picker label)DoesFields
UUCFItemFragment_Equippable (Equippable)Makes it drawableActionGraph, bIsMainWeapon (label Main Weapon), HoldPlaces, PlacesRequired, EquipmentTags, InputMappingContext, InputMappingPriority, InputMappings, InputChords, TraceSockets, AttackStopDistance, AbilitySetsToGrant, AnimLayerClass, ItemActorClass, InstanceType, DrawTiming and StowTiming behind bOverrideDrawTiming and bOverrideStowTiming
UUCFItemFragment_Visuals (Visuals)What it looks likeHeldMesh (label Mesh), bOverridePerState, StowMesh, DropMesh
UUCFItemFragment_WornMesh (Worn Mesh)Skeletal meshes worn on the body while equipped, following its poseMeshes
UUCFItemFragment_Guard (Guard)Lends a defense rule set while drawnDefenseSet (AgentGuide/Player/DamageDefense.md)
UUCFItemFragment_Stowable (Stowable)Hangs on the body when put awayStowPlaces, StowActorClass
UUCFItemFragment_WorldItem (World Item)Lies on the ground: dropped and picked upAgentGuide/Player/InventoryInteraction.md
UUCFItemFragment_SwingTrail (Swing Trail)A ribbon behind swingsTrailSystem, StartSocket, EndSocket, TrailSeconds, Tint, TrailTags
UUCFItemFragment_Weight (Weight), UUCFItemFragment_GridFootprint (Grid Footprint), UUCFItemFragment_CapacityBonus (Capacity Bonus)How heavy one unit is, the cells it covers in a grid container, and the capacity owning it adds (AgentGuide/Player/InventoryInteraction.md, Containers)Weight; Size; Bonuses
UUCFItemFragment_Container (Container)Makes the item a bag that opens a container of its own on a bag bar (AgentGuide/Player/InventoryInteraction.md, Bags)Definition, ContainerTag
UUCFItemFragment_BeltLimit (Belt Limit)Caps its copies on the beltMaxBeltCount
An item that is not gear (a key, a material, a potion) needs no Equippable fragment. Its kind is SlotTags (UCF.Slot.KeyItem, UCF.Slot.Ingredient, UCF.Slot.Consumable; the inventory's rules and the belt read it), MaxStackSize sets how many share a stack, and each fragment adds one behavior: Weight makes it count toward a weight limit, World Item lets it lie on the ground and be dropped, Grid Footprint gives it cells in a grid, Container makes it a bag, Capacity Bonus grows a capacity. An item has only the behaviors whose fragment it carries: with no Weight fragment it weighs nothing, with no World Item fragment it cannot be dropped. AgentGuide/Player/InventoryInteraction.md, Recipe: a keychain, builds items of this kind with the container and config that keep them.
Main Weapon. bIsMainWeapon on (the default): its graph drives combat while drawn. Off with an ActionGraph: it drives only while no main weapon is drawn (a torch). Off with no graph: a supporting item (a shield), whose moves live in the graph of the weapon it is held with, or in a sub graph gated on its EquipmentTags (AgentGuide/Player/ActionGraphs.md, Sub graphs).
Hands and places
HoldPlaces rows (unreal.UCFHoldPlaceSpec: Place, Offset, SocketOverride, PlaceTags) list where an item can be held, in order; PlacesRequired is how many it takes. A new Equippable holds UCF.Place.Main. The character's EquipmentManagerComponent.BodyPlaces maps each place to a socket (UCF.Place.Main to hand_r, UCF.Place.Off to hand_l). Python cannot set a row's fields one by one, so write the row as text:
row = unreal.UCFHoldPlaceSpec()
row.import_text('(Place=(TagName="UCF.Place.Off"))')
eq.set_editor_property("HoldPlaces", [row])
A two-handed weapon lists both hands and takes both: two rows (UCF.Place.Main, UCF.Place.Off) and PlacesRequired 2.
A sword held in either hand lists both, main first, with PlacesRequired 1: a second copy takes the off hand. Turn on the off-hand row's bMoveToEarlierPlaceWhenFree (Move To Earlier Place When Free, written with import_text like the row's other fields) and, once the main-hand sword is put away or dropped, the other moves into the main hand and drives; leave it off for an item that stays in the hand it was drawn into, such as a dagger kept in the off hand. To put the second sword on a diamond belt's off-hand slot, give it the off-hand kind too (SlotTags UCF.Slot.Weapon.Sword and UCF.Slot.OffHand).
Recipe: a shield in the left hand
shield_mesh = load("/Game/.../SM_Shield")
shield = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Shield")
vis = unreal.new_object(unreal.UCFItemFragment_Visuals, outer=shield)
vis.set_editor_property("HeldMesh", shield_mesh)
eq = unreal.new_object(unreal.UCFItemFragment_Equippable, outer=shield)
eq.set_editor_property("bIsMainWeapon", False)
eq.set_editor_property("EquipmentTags", tags("UCF.Equipment.Shielded"))
row = unreal.UCFHoldPlaceSpec()
row.import_text('(Place=(TagName="UCF.Place.Off"))')
eq.set_editor_property("HoldPlaces", [row])
shield.set_editor_property("Fragments", [vis, eq])
save(shield)
 
inv = defaults(bp).get_editor_property("InventoryComponent")
items = list(inv.get_editor_property("StartingItems"))
items.append(shield)
inv.set_editor_property("StartingItems", items)
save(bp)
  • The belt takes each starting item into its own slot and draws every one that fits beside what is held, so the sword (main hand) and the shield (off hand) are both drawn at the start. The slot keys 1 to 4 draw and put away each one.
  • To draw an item the inventory holds from code at once, putting nothing away, as a loadout handed out in a level does: the equipment manager's EquipItemIfFree (server only), which draws it only while it is equippable, not drawn, carried and in reach and every place it needs is free.
  • To give a character gear from Blueprint, on the server: the inventory's Add Item Definition, then Equip Item If Free on the equipment manager with the item it returns. A null answer means a place is taken, such as by another cape; Request Equip Item puts that one away first. Remove Item Instance takes the gear off as it leaves the inventory. For a game with no inventory, belt or weapons that only dresses a character, skip the inventory: Equip Item on the equipment manager (server) takes the item definition with no inventory item, puts away whatever holds the places it needs (places are gameplay tags, as many as the body's Body Places names) and returns the drawn instance, null when the body has no place for it; Unequip Item with that instance, or the one Get Instance In Place answers, takes it off. A player's equip request, RequestEquipItem, also takes an item in the Stash or a chest, moving it into the carried containers first.
  • The shield's block and parry are its Guard fragment (AgentGuide/Player/DamageDefense.md); the guard move goes in the sword's graph (AgentGuide/Player/ActionGraphs.md).
  • UCF.Equipment.Shielded sits on the character while the shield is drawn, so a transition or sub graph can require it.
  • If the shield sits crooked, judge a correction from a capture and write it as the row's Offset, as AGENTS.md, Player Recipe 4, Step 5, does for the sword.
Check: reload the item and print its fragments' classes, bIsMainWeapon, the hold place and EquipmentTags. In Play, the shield is in the left hand and the sword in the right.
Stowing on the body
An item with no Stowable fragment disappears when put away. To hang it on the body: a UUCFItemFragment_Stowable with StowPlaces rows (unreal.UCFStowPlaceSpec: Place such as UCF.Place.Back.Left, Offset, DrawMontage, StowMontage), written with import_text as above; a UCF Stow Visual component on the character Blueprint (the duplicated demo player has one); and the place's socket on the customer's skeleton, mapped in BodyPlaces. By default only an item on the belt hangs while out of hand, and an item only in the inventory shows nowhere on the character; the inventory config's bShowCarriedItemsOnBody hangs every carried item outside a bag as well, as the demo survival grid does, so no weapon can be hidden. A draw or stow montage carries a UCF Equipment Commit notify (UUCFEquipmentCommitNotify, BlendSeconds) on the frame the hand closes on the grip; add it with unreal.AnimationLibrary.add_animation_notify_event(montage, "Combat", seconds, unreal.UCFEquipmentCommitNotify). The demo's reach montages belong to the demo mannequin; the customer's character needs its own. The item's own sounds go on the same fragment, never on the reach montage, so items sharing one reach still sound like themselves: DrawSound plays as the item arrives in the hand and PutAwaySound as it arrives in its place, whether a reach, a pickup or a screen moved it, on every machine that shows the character; an item that appears with nothing showing it before, such as a starting item, plays nothing.
Worn gear: helmets, capes, armor and rings
Worn gear is an Equippable item with bIsMainWeapon off and no ActionGraph, so it is drawn beside the weapon and leaves the moves alone. Its places are gameplay tags the project names, such as UCF.Place.Head and UCF.Place.Ring.Left, or only a top and a bottom. The character's EquipmentManagerComponent.BodyPlaces says where each place is on the body; a row needs a Socket only where a look sits. The duplicated demo player already has rows for the demo's worn places (AGENTS.md, Step 2), so the script below sets the socket on a row it finds and adds a row only for a place that is missing. Give worn gear SlotTags the belt slots' Filter does not pass, or a belt that takes new items puts it on a slot and puts it on at pickup. On a belt, its key puts it on and takes it off; it never counts as in hand, since only the equipment manager's HandPlaces (UCF.Place.Main and UCF.Place.Off by default) are hands, so the belt does not highlight its slot and the drop key never drops it. A body whose weapons are held in places of its own lists those places in HandPlaces.
LookHow
A static mesh on one bone (a helmet, a ring)Visuals HeldMesh, the body place's socket or bone, and the hold place's Offset to turn it into place
A skinned mesh on the body (a cape, gloves, armor)Worn Mesh Meshes, rigged to the character's skeleton; it follows the body's pose and comes off with the item
Nothing (a necklace that only grants a stat)No look fragment, and a body place with no socket
A ring's bonus is a tag in its EquipmentTags, held on the character while the ring is worn, that something else reads: the duplicated demo player's UCF Speed Modifier turns UCF.State.Swift into five percent more walk speed, as the demo ring and necklace use it, and another character gets a row for the tag in its UCF Speed Modifier's SpeedScaleByTag. An attribute bonus is a gameplay effect in an ability set's GrantedGameplayEffects, on the Equippable's AbilitySetsToGrant, and that effect is authored in the editor, since Python cannot set a gameplay effect's components: a Gameplay Effect Blueprint with Duration Policy Infinite, plus a modifier for an attribute or, for a tag, the Grant Tags to Target Actor component with the tag in its Add Tags. Items fill their places in the order HoldPlaces lists them, so two rings take the left hand, then the right, and a third replaces the left one; CanDraw(item, evicted) names the one it would replace. A UI keeps its own list of the places it shows, asks GetInstanceInPlace for each and skips an instance whose IsDefaultItem is true, redraws on the equipment manager's OnDrawnStateChanged, which fires once a change has settled, the item's place included, and asks RequestEquipItem with the place an item was dropped on (CanEquipItem with that place first) and RequestUnequipItem. Hiding the body under armor, morph targets and cloth are set up in the meshes.
eqm = defaults(bp).get_editor_property("EquipmentManagerComponent")
rows = list(eqm.get_editor_property("BodyPlaces"))
for place, socket in (("UCF.Place.Head", "head"), ("UCF.Place.Shoulders", "None"), ("UCF.Place.Ring.Left", "ring_01_l"), ("UCF.Place.Ring.Right", "ring_01_r")):
    row = unreal.UCFBodyPlace()
    row.import_text(f'(Place=(TagName="{place}"),Socket="{socket}")')
    found = [i for i, r in enumerate(rows) if str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("Place"))) == place]
    if found:
        rows[found[0]] = row
    else:
        rows.append(row)
eqm.set_editor_property("BodyPlaces", rows)
save(bp)
 
def worn(item, places):
    eq = unreal.new_object(unreal.UCFItemFragment_Equippable, outer=item)
    eq.set_editor_property("bIsMainWeapon", False)
    held = []
    for place in places:
        row = unreal.UCFHoldPlaceSpec()
        row.import_text(f'(Place=(TagName="{place}"))')
        held.append(row)
    eq.set_editor_property("HoldPlaces", held)
    return eq
 
helmet = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Helmet")
vis = unreal.new_object(unreal.UCFItemFragment_Visuals, outer=helmet)
vis.set_editor_property("HeldMesh", load("/Game/.../SM_Helmet"))
helmet.set_editor_property("Fragments", [worn(helmet, ["UCF.Place.Head"]), vis])
save(helmet)
 
cape = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Cape")
look = unreal.new_object(unreal.UCFItemFragment_WornMesh, outer=cape)
look.set_editor_property("Meshes", [load("/Game/.../SK_Cape")])
cape.set_editor_property("Fragments", [worn(cape, ["UCF.Place.Shoulders"]), look])
save(cape)
 
ring = new_data_asset(unreal.UCFItemDefinition, F, f"Item_{N}_Ring")
ring_eq = worn(ring, ["UCF.Place.Ring.Left", "UCF.Place.Ring.Right"])
ring_eq.set_editor_property("EquipmentTags", tags("UCF.State.Swift"))
ring_vis = unreal.new_object(unreal.UCFItemFragment_Visuals, outer=ring)
ring_vis.set_editor_property("HeldMesh", load("/Game/.../SM_Ring"))
ring.set_editor_property("Fragments", [ring_eq, ring_vis])
save(ring)
  • Add each place tag to the project's tags first; the plugin declares the demo's places.
  • A ring that sits crooked gets an Offset on each of its two rows, written into the row text as for the shield.
Check: in Play, equip each item from the inventory: the helmet sits on the head, the cape moves with the body, the first ring goes on the left hand and the second on the right, and the ring's stat comes and goes with it.
Mistakes
SymptomCause and fix
The shield replaces the swordThe shield has bIsMainWeapon on, or its hold place is UCF.Place.Main.
Putting on a helmet takes the sword's moves awayThe helmet has bIsMainWeapon on; worn gear has it off and no ActionGraph.
A worn item is refusedThe character's BodyPlaces has none of the item's hold places.
A cape or gloves stand in the reference pose or floatThe worn mesh is rigged to another skeleton than the character's mesh tagged UCF.Attachment.
The item is invisible in the handNo Visuals HeldMesh and no ItemActorClass, or the body place's socket is missing on the skeleton.
A Hold Places row is empty after a reloadIt was set field by field; write it with import_text.
The item vanishes when put awayNo Stowable fragment or UCF Stow Visual, or off the belt with bShowCarriedItemsOnBody off.

Paired Actions: finishers, counters and grabs (AgentGuide/Player/PairedActions.md)

A paired action is two characters playing synced animations together: an execution, a counter, a vault over an enemy. Tasks: a finisher from two animations; executing an enemy only while it is stunned; dealing the damage on the right frame; a cinematic camera during it; starting it from a combo.
The asset
A Paired Action (UUCFPairedActionAsset, new_data_asset) holds Participants (unreal.UCFPairedActionParticipant), one per role, and its placement and timing:
Participant fieldDoes
RoleIdThe role's name, such as Attacker or Victim. Read-only in the editor; set it with a constructor keyword: unreal.UCFPairedActionParticipant(role_id="Attacker")
Montage, StartSectionWhat this role plays
OffsetWhere it stands relative to the shared anchor
TravelModeHow it gets to its spot
bRequiredThe action fails without a body in this role
RequiredActorTags, BlockedActorTagsWho may fill it
TagsDuringActionTags held while it plays (UCF.State.ActionsBlocked from the start)
EventsWhat happens on frames: UUCFPairedActionEvent_Damage (Deal Damage: DamageConfig, DamageOverride, LeaveHealthAtLeast, bKill, ExtraDamageTags, TimeSeconds, TargetRoleId; under bKill, bRagdollOnKill drops the body limp with RagdollThrow, a FUCFPairedRagdollThrow: bUseReactionSetDefaults, Settings, Impact and ImpactFrame), UUCFPairedActionEvent_Ragdoll (Ragdoll, for a body that lives: Impact with Bone, Velocity in cm/s along ImpactFrame (X ahead, Z up) and Spread) and others
HooksBehavior riding the role: UUCFPairedActionHook_AutoCinematicView (FocusRole, ViewAngle, HeightOffset), UUCFPairedActionHook_CameraShot (Shot)
bSyncWithCurrent, SyncMarkerStart from an animation already playing, meeting at a UCF Paired Sync Marker notify (MarkerName)
Asset fields: AnchorMode, AnchorRoleId, MaxSlotDistance, MaxSlotYawDegrees, bRequireClearSlots, AbortRule, ReleaseRule, PlayRate, WarpTargetName.
pa = new_data_asset(unreal.UCFPairedActionAsset, F, f"Paired_{N}_Execute")
atk = unreal.UCFPairedActionParticipant(role_id="Attacker")
atk.set_editor_property("Montage", am_exec_attacker)
atk.set_editor_property("bRequired", True)
vic = unreal.UCFPairedActionParticipant(role_id="Victim")
vic.set_editor_property("Montage", am_exec_victim)
vic.set_editor_property("bRequired", True)
cut = unreal.new_object(unreal.UCFPairedActionEvent_Damage, outer=pa)
cut.set_editor_property("DamageConfig", dmg_heavy)
cut.set_editor_property("LeaveHealthAtLeast", 1.0)     # an earlier blow leaves the victim alive for the killing blow
cut.set_editor_property("TimeSeconds", 0.6)
cut.set_editor_property("TargetRoleId", "Victim")
hit = unreal.new_object(unreal.UCFPairedActionEvent_Damage, outer=pa)
hit.set_editor_property("DamageConfig", dmg_heavy)
hit.set_editor_property("bKill", True)                 # takes all the health left, whatever defends the victim
hit.set_editor_property("bRagdollOnKill", True)        # and drops the body limp with the throw below as it dies
throw = unreal.UCFPairedRagdollThrow()
throw.set_editor_property("Impact", unreal.UCFRagdollImpact(bone="spine_03", velocity=unreal.Vector(400, 0, 150), spread=0.9))
hit.set_editor_property("RagdollThrow", throw)
hit.set_editor_property("TimeSeconds", 1.2)
hit.set_editor_property("TargetRoleId", "Victim")
atk.set_editor_property("Events", [cut, hit])
pa.set_editor_property("Participants", [atk, vic])
pa.set_editor_property("AnchorRoleId", "Victim")        # the victim stands still and the attacker lines up on it
pa.call_method("DeriveOffsetsFromMontages")
save(pa)
print(ucf.validate_asset(pa))
DeriveOffsetsFromMontages places each role from where its montage puts it, for animations authored together; set the anchor role first. ucf.validate_asset(pa) lists what the pairing editor would warn about (a role with no montage, an anchor role that does not exist, a travel setting that loses the montage's own motion), each line naming the setting to change.
Starting it
  • From a combo: a move whose payload is UUCFPlayPairedActionPayload (Play Paired Action: Source PAIRED_ACTION with PairedAction, OwnerRoleId, TargetRoleId, PrimaryPicker; or PAIRED_ACTION_SETS with PairedActionSets), reached by a transition with a Paired Action Available condition (UUCFPairedActionCondition, Actions) or a Target State condition requiring a stun tag (AgentGuide/Player/ActionGraphs.md). For a move the stick aims, such as a vault, make the PrimaryPicker a Proximity Scan (unreal.UCFPairedTargetPicker_Scan: Radius, MaxAngleDegrees, bArcFollowsMovementInput on), and give the node an ON_FAILED transition to the move that plays when nobody stands in that direction, such as a roll.
  • A set of options: a Paired Action Set (UUCFPairedActionSet: GatherRadius, GatherArcDegrees, Options rows unreal.UCFPairedActionOption Action, OwnerRoleId, TargetRoleId, PrimaryPicker, RequiredTargetTags, TargetTeams, Priority), which one button searches. The demo sword's PairedActionSet_UCF_SwordExecute executes only the demo's Soulslike boss in its finisher stun: its one row requires UCF.Enemy.SoulslikeBoss, which a character carries in its CombatComponent CharacterTags, and UCF.State.Finishable, which that stun holds. For one action with its own montages per enemy type, put a type tag of the project's own (Enemy.Type.Heavy) in the enemy Blueprint's CombatComponent CharacterTags, add one row per type with a higher Priority, that tag in RequiredTargetTags and the type's own paired action as Action, and keep one catch-all row last with no RequiredTargetTags, which every other enemy gets.
  • From the level: a UCF Paired Action Spot or UCF Paired Action Interactable component on an actor.
Check: ucf.validate_asset(pa) is empty. In Play, UCF.Debug.Paired.Draw 1 draws each role's spot.
Mistakes
SymptomCause and fix
The roles drift apartOffsets not derived or set; run DeriveOffsetsFromMontages or set each Offset.
It plays on the wrong bodyThe option's RequiredTargetTags or TargetTeams are too loose.
The damage never landsNo Deal Damage event, or its TimeSeconds is past the action's end.
The victim survives the killA large DamageOverride meets a guard, a resistance or a health floor that holds it back. Tick bKill on the Deal Damage event: it takes whatever health is left, and its HealthVitalTag names the row to empty when the victim's health row is not UCF.Vital.Health.
The body stays standing after the kill, or stands up againThe kill has no fall: tick bRagdollOnKill on the killing Deal Damage rather than adding a separate Ragdoll event at the same moment. A body that still stands with it ticked could not fall: its UCF Physical Reaction component has no Reaction Set while RagdollThrow uses the Reaction Set's defaults, or it has no such component (the log says which).
A Deal Damage or Ragdoll never firesThe role carrying it was let go before its TimeSeconds: an event fires only while its own role is in the action. Put a killing blow that lands after the attacker is let go on the victim's own role.
The victim dies too earlyAn earlier Deal Damage event takes its last health, or has bKill ticked. Set LeaveHealthAtLeast (1 is enough) on every Deal Damage event before the killing blow, and tick bKill on the killing blow only.
A role is empty after a reloadRoleId was set with set_editor_property; build the participant with the role_id keyword.
A role skips its opening stepIts montage starts inside its Data Driven glide, which throws that root motion away, and ucf.validate_asset(pa) names the loss and the value to set. Set ApproachDurationSeconds to StartDelaySeconds minus RoleStartSeconds, or StartDelaySeconds to the glide's end (and PlayFromSeconds to the frame shown at the join, for a montage already playing then).

Editor Python: what can be set, and how (AgentGuide/Player/Python.md)

Rules every other file relies on. Read this when a set_editor_property call is refused, when a value you wrote is gone after a reload, or before you add components, rows or instanced objects.
Tasks: set a property; fill a struct row a plain field write refuses; add an instanced object (a fragment, a payload, a cost); edit a component on a Blueprint; give a montage sections; add a gameplay tag; check an asset; read the log.
Setting properties
  • obj.set_editor_property("Name", value) takes the C++ name (bIsMainWeapon) or the Python name (is_main_weapon). It refuses a property the editor shows read-only, and it refuses a class-defaults-only property on anything that is not a template (an asset, a class default object, or an object inside an asset).
  • Arrays come back as copies. Edit the list, then write the whole list back:
    rows = list(item.get_editor_property("Fragments"))
    rows.append(frag)
    item.set_editor_property("Fragments", rows)
  • A struct you make in Python is not a template, so its class-defaults-only fields refuse set_editor_property. Several of this plugin's row structs are like that, among them unreal.UCFHoldPlaceSpec (Hold Places rows), unreal.UCFStowPlaceSpec (Stow Places rows), unreal.UCFContainerSpec (an inventory config's Containers rows), unreal.UCFCapacityBonus (a Capacity Bonus fragment's Bonuses), unreal.UCFWeightThreshold (a Weight Limit's Thresholds), unreal.UCFCategoryLimit (a Category Limit's Limits) and the ability set rows unreal.UCFAbilitySet_GameplayAbility and unreal.UCFAbilitySet_GameplayEffect; an interaction option's PayloadSpec refuses a field write too. A Combine Set's rows (unreal.UCFCombineRecipe, unreal.UCFCombineResult) take field writes. Write any row that refuses as text:
    row = unreal.UCFAbilitySet_GameplayAbility()
    row.import_text('(Ability="/Game/Player/GA_Knight_Heal.GA_Knight_Heal_C",InputTag=(TagName="UCF.Input.Special"))')
    Read a shipped row with row.export_text() to see the text form of each field.
  • A struct read from an object is a copy: edit it, then write it back to the object with set_editor_property. Inside that copy, nested fields edit in place: s.state.applied_tags = tags("UCF.State.Blocking").
  • A call that answers yes or no and also fills a value (unreal.UCFInventoryStatics.can_combine, the inventory's get_item_placement and can_item_leave) hands back the filled values and not the yes or no: one value comes back alone, several as a tuple, and None stands for no. answer = unreal.UCFInventoryStatics.can_combine(inv, item, target) is None when the two do not combine, else (results, reason). A call that returns a number and fills a value gives both: units, reason = inv.get_units_that_fit(item, 1, False).
Instanced objects
Item fragments, action graph payloads, costs, gates, hooks, transition conditions, hit effects, defense rules and camera layers are objects that live inside the asset holding them.
  • Make one with unreal.new_object(cls, outer=<the asset that holds it>), set its properties, put it in the owner's list, then save the asset. The lists in this plugin: an item's Fragments, an inventory container's Rules, an inventory config's CarryRules and a Combine Set's Combines. Write the whole list back with set_editor_property: a list read from the asset is a copy, so adding to it without writing it back changes nothing and raises nothing.
  • An object made without outer= belongs to no asset: its properties refuse a write ("cannot be edited on instances").
  • Exception: for ucf.set_node_settings and ucf.set_transition_settings, make it with unreal.new_object(cls) and no outer; the call copies it into the graph.
  • Never give a class default object as the outer (unreal.get_default_object(...)), not even to look at a class. The next object of that class with the same name takes it as its template, and the asset holding it fails to save.
Components on a Blueprint
  • A component the C++ base creates (every component AUCFCharacterBase makes: EquipmentManagerComponent, InventoryComponent, ActionGraphComponent, MeleeTraceComponent, InputMappingComponent, AnimManagerComponent, VitalsComponent, DefenseComponent, TargetingComponent, TargetableComponent, TeamComponent, ApproachComponent, CombatComponent, InteractorComponent, AnimEffectComponent, AbilitySystemComponent, and the character's own CapsuleComponent, CharacterMovement and Mesh) is read from the class defaults: defaults(bp).get_editor_property("VitalsComponent"). Edit it there and save the Blueprint.
  • A component the Blueprint adds (sprint, camera rig, speed modifier, stow visuals on the demo player) lives in its construction script. Read its template:
    sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
    handles = sds.k2_gather_subobject_data_for_blueprint(bp)
    for h in handles:
        data = unreal.SubobjectDataBlueprintFunctionLibrary.get_data(h)
        obj = unreal.SubobjectDataBlueprintFunctionLibrary.get_object_for_blueprint(data, bp)
        if isinstance(obj, unreal.UCFSprintComponent):
            sprint = obj
    Edit sprint, then unreal.BlueprintEditorLibrary.compile_blueprint(bp) and save(bp).
  • Adding a component to a Blueprint:
    params = unreal.AddNewSubobjectParams(parent_handle=handles[0], new_class=unreal.UCFSpeedModifierComponent, blueprint_context=bp)
    new_handle, fail = sds.add_new_subobject(params)
    Then read it as above, set it, compile and save.
Montage sections
The engine's Python cannot give a montage sections. Use the plugin's tool:
ucf.set_montage_sections(montage, [("Light1", 0.0), ("Light2", 0.9), ("Light3", 1.8)])
It replaces every section and saves the montage. On Epic's MCP it takes three lists in place of the tuples: section names, start seconds, and next sections (empty, or one per section). Each section ends the montage, so a move whose payload names a section (SectionName on unreal.UCFMontageActionPayload) plays only that part. A third value names the section it plays on into instead, or its own name to loop it, which is how a held guard keeps its pose: [("Raise", 0.0, "Hold"), ("Hold", 0.4, "Hold")].
Gameplay tags
A tag must exist before a property can hold it (tag("UCF.Input.Kick") gives an empty tag otherwise). The plugin's input, state, vital, place and cooldown tags exist already. To add one:
ucf.add_gameplay_tag("UCF.Input.Kick", "Kick attack")
It writes Config/DefaultGameplayTags.ini and the tag can be used at once. A tag that exists is left as it is.
Checks
  • ucf.validate_asset(asset) runs the checks the editor's Validate Assets runs (item definitions, damage configs, combat styles, targeting configs, defense rule sets, paired actions, camera shots) and returns one line per problem.
  • For an action graph, ucf.compile_action_graph(graph) is the check.
  • After Play, log_warnings() returns UCF's warnings; each names the asset and the fix.

Targeting, combat styles and attack steering (AgentGuide/Player/TargetingStylesSteering.md)

AGENTS.md, Player Recipe 5, sets up lock-on. This file covers how attacks turn to and close on the target, combat styles, targeting configs and what can be targeted.
Tasks: attacks that snap to the target and close the gap; an attack that steps forward with nothing targeted; a lunge that lands on the target; souls-like strafing when locked on; lock range and target switching; making an actor targetable; snappier movement in combat.
Recipe: attacks that close on the target
The demo's unarmed combo puts a UCF Approach Or Move Window (UUCFApproachOrMoveWindowNotifyState) over each attack's wind-up: with a target it turns the player to it and glides into reach, and with none it steps forward. Put it before the attack's trace window:
for key in ("Light1", "Light2", "Light3", "Heavy"):
    m, L = am[key], length(am[key])
    a = ucf.add_notify_state_to_montage(m, unreal.UCFApproachOrMoveWindowNotifyState, L * 0.05, L * 0.25)
    a.set_editor_property("StopDistanceOverride", 25.0)   # cm left between the bodies: about 25 for fists, 50 for a blade
    a.set_editor_property("MoveDistance", 60.0)           # cm stepped forward when nothing is targeted
    save(m)
  • The target is the character's soft target or lock (the targeting config below); the duplicated player already picks one.
  • StopDistanceOverride -1 uses the item's AttackStopDistance, then the style's stop distance. A move's own StopDistance on its Play Montage node takes over from it (below). The gap must be shorter than the attack reaches past the player's body, or the swing stops short.
  • A plain UCF Approach Window (UUCFApproachWindowNotifyState) does the same without the step when nothing is targeted. Its Mode (unreal.UCFApproachMode: MOVE_AND_FACE, FACE_ONLY, MOVE_ONLY) picks turning, moving or both; bMoveByOffset with OffsetDirection and OffsetDistance moves a set distance instead (a step back: direction (-1, 0, 0)).
Check: unreal.AnimationLibrary.get_animation_notify_events(am["Light1"]) lists the window before the trace window. In Play, UCF.Debug.Steering.Draw 1 draws where each attack aims and stops; an attack started a few meters from an enemy glides to it and lands.
Root-motion attacks that travel by their own animation land on the target with the engine's Motion Warping window and the UCF Skew Warp modifier, as the demo sword does:
w = ucf.add_notify_state_to_montage(m, unreal.AnimNotifyState_MotionWarping, L * 0.1, L * 0.3)
mod = unreal.new_object(unreal.UCFRootMotionModifier_SkewWarp, outer=w)
mod.set_editor_property("WarpTargetName", "UCFTarget")
mod.set_editor_property("StopDistanceOverride", 50.0)
w.set_editor_property("RootMotionModifier", mod)
save(m)
A dash that carries the player into reach uses UUCFRootMotionModifier_GapCloser (UCF Gap Closer Warp) the same way. The duplicated player has the Motion Warping component.
Who steers, and which way attacks face
The character's UCF Attack Approach component (UUCFAttackApproachComponent, ApproachComponent on the duplicated player) aims and steers attacks. Another character takes this one beside a UCF Targeting component (AgentGuide/Player/Python.md, Components on a Blueprint), never its base UUCFApproachComponent, whose attacks neither aim nor keep their distance. The attack approach's settings: SteeringMode (unreal.UCFAttackSteering: OFF, TOWARD_TARGET, DISTANCE_ONLY), AttackFacing (unreal.UCFAttackFacing: NONE, AIM, MOVEMENT, LOCK_TARGET), AttackTurnSpeed (degrees per second an attack turns the character to that facing; -1, the default, follows the character's rotation rate, which the style's RotationRateYaw sets, and a rate of 0 or below turns it at once; 0 turns it at once; a move's own TurnSpeed takes over, as the demo's rolls set 1440; each machine reads it, so a value set while playing goes on the server and the player's machine alike), KeepDistance (ON stops attacks the stop distance short of the target and of enemies in their path), MakeRoomSeconds (how long an attack that starts closer than the stop distance takes to step back to it; 0 turns it off; a move's own MakeRoomSeconds takes over), DefaultStopDistance, DefaultMaxApproachDistance, WarpTargetName (UCFTarget). The combat style sets most of these as it applies, so change them on the style.
Which stop distance an attack keeps, top wins, -1 passing to the next:
LevelSet on
The moveStopDistance on its Play Montage node (UUCFMontageActionPayload)
A window, advancedStopDistanceOverride on the UCF Approach Window or UCF Skew Warp playing at that moment
The weaponAttackStopDistance on the drawn weapon's Equippable fragment
The styleStopDistance on its Approach fragment (DefaultStopDistance on the component)
The move's MakeRoomSeconds works the same way against the style's: -1 follows the style, 0 turns the step back off for that move, above 0 turns it on. Set the move's own values for a short move beside a long weapon, such as a shield bash with a sword drawn. With UCF.Debug.Approach 1 each attack logs its stop distance and where it came from.
Combat styles
A Combat Style (UUCFCombatStyleAsset, Fragments) on the character's CombatComponent (Style) sets rotation, targeting, steering, approach and camera together. The demo ships CombatStyle_UCF_OverShoulder (the duplicate's), CombatStyle_UCF_Soulslike and CombatStyle_UCF_Freeflow under /UniversalCombatFramework/Demo/Combat/Styles/; duplicate one to change it.
Fragment (picker label)Fields
UUCFStyleFragment_Rotation (Rotation)RotationMode, LockedRotationMode (unreal.UCFRotationMode: CAMERA_FACING, MOVEMENT_FACING, CONTROLLER_DESIRED), RotationRateYaw, LockedRotationRateYaw, AttackFacing
UUCFStyleFragment_Targeting (Targeting)Targeting (a targeting config), Steering
UUCFStyleFragment_Approach (Approach)StopDistance, MaxApproachDistance, FacingInterpSpeed, SpeedLimit, MovingTarget, bBlockMovementInput, MakeRoomSeconds
UUCFStyleFragment_Movement (Movement)Acceleration, braking and friction overrides
UUCFStyleFragment_Camera, UUCFStyleFragment_CameraRigThe lock-on camera and the rig (AgentGuide/Player/CameraTelegraphs.md)
UUCFStyleFragment_Tags, UUCFStyleFragment_InputMappingTags held while the style is active; a mapping context added while it is
Targeting configs
UUCFTargetingConfig: ScanRadius (cm), TargetTeams (Enemies Only by default), bAllowLock, LockBreakDistance (0 never breaks), LockBreakGraceSeconds, ScoreSwitchMargin, ScorePolicies and LockScorePolicies (UUCFTargetScorePolicy_Distance, _ViewAngle, _InputDirection, _AimDirection, _LineOfSight), SwitchInputAction (the stick that moves a lock), EngagedRadius, EngagedTag. Duplicate TargetingConfig_UCF_Soulslike (beside the styles) and point a duplicated style's Targeting fragment at it.
Targetable actors: a UCF Targetable component (UUCFTargetableComponent: AimAtSocket, AimAtComponentTag, AimOffset). Every character built on the UCF character base has one; add it to any other actor (AgentGuide/Player/Python.md, Components on a Blueprint).
Mistakes
SymptomCause and fix
Attacks stop short of the targetThe stop distance is longer than the attack's reach: lower the move's StopDistance, StopDistanceOverride or the item's AttackStopDistance.
Attacks play in placeNo approach window on the montage, SteeringMode OFF, or no target (an Approach Or Move Window still steps).
Attacks slide through enemiesKeepDistance off on the UCF Attack Approach component.
A swing from contact reaches into the enemyMakeRoomSeconds is 0 on the style's Approach fragment; around 0.15 steps the attack back to its stop distance first.
A short move beside a long weapon backs off and misses (a shield bash beside a sword)The move takes the weapon's AttackStopDistance: set the move's own StopDistance on its Play Montage node (the demo bash keeps 25).
Lock-on picks teammatesTargetTeams changed from Enemies Only, or both sides share a team.
The lunge overshootsThe Motion Warping window has no modifier, or its WarpTargetName is not UCFTarget.

Player and enemy together (AgentGuide/Seam.md)

What crosses the two layers: an enemy holding the player's items and playing the player's moves, enemies answering the player's swings and the reverse, lock-on, teams and executions. The player's side is in AgentGuide/Player/, the enemy's in AgentGuide/Enemy/.
Tasks: an enemy holding the player's items, with moves for each; an enemy that picks items up; an enemy that fights with the player's sword combo; a string of attacks run as one action; locking on to enemies; companions nobody hits; enemies that parry the player; the player blocking and parrying an enemy; a boss whose posture breaks; executing a staggered enemy; switching an existing project to UCF; the demo's enemies and bosses.
An enemy holding the player's items
An enemy holds items the way the player's character does: its UCF Enemy Loadout (Loadout) lists the items it starts holding, and its UCF Equipment Manager draws them, so the baton or sword in an enemy's hand is the same item a player picks up. Enemy Recipe 2 makes a weapon item and gives it to an enemy. The Loadout's ItemSets rows give the AI an Action Set and a Reaction Set for the item it holds, per combat role where a row names one, so an enemy fights with baton moves while it holds the baton and with its fists' moves once disarmed. At death, with the Combat Controller's bDropWeaponOnDeath on, each item it holds drops as an item a player can pick up, and the Loadout's On Item Dropped names each one on the server, which an arena binds to clear them at its reset.
Check: in Play, the enemy holds its item, and UCF.Debug.EnemyActions 1 lists the actions of the Action Set its row names.
An enemy that picks items up
Add a UCF Inventory component to the enemy Blueprint. The Loadout then draws what the inventory starts with in place of its StartingItems. An enemy takes a world item through the world item's Try Pick Up on the server, which adds it to the inventory, and holds it once the Equipment Manager's Equip Item If Free draws it; at death it drops what it holds out of the inventory. The demo's enemies carry no inventory.
An enemy that fights with the player's combo
The guide's Combo Enemy Recipe builds a combo graph for the enemy. To use a graph the player already has, such as the player's sword moves, give the enemy an Action Graph component (Combo Enemy Recipe, Step 1) and point the combo at that graph:
sword = load("/Game/Player/Item_Knight_Sword")      # the player's item; the demo's is /UniversalCombatFramework/Demo/Weapons/Sword/Item_UCF_Sword
graph = None
for f in sword.get_editor_property("Fragments"):
    if isinstance(f, unreal.UCFItemFragment_Equippable):
        graph = f.get_editor_property("ActionGraph")
print(ucf.describe_action_graph(graph))             # the inputs that walk the combo, such as UCF.Input.LightAttack three times
 
ids = set()
for node in ("Light1", "Light2", "Light3"):          # the combo's moves, named as describe_action_graph prints them
    montage = ucf.get_node_settings(graph, node).execution.payload.get_editor_property("Montage")
    for ev in ANIM.get_animation_notify_events(montage):
        n = ev.get_editor_property("notify_state_class")
        if isinstance(n, unreal.UCFMeleeTraceNotifyState):
            ids.update(str(i) for i in n.get_editor_property("SocketIDs"))
print(ids)
Then Combo Enemy Recipe, Step 4, with ActionGraph set to that graph and one input step per press. Check before Play:
  • Sockets. Each ID printed must be a TraceSockets row ID on the item the enemy holds (Enemy Recipe 2, Step 2). An empty list means the windows sweep every socket the item registers. With the player's own sword item in the enemy's StartingItems, every ID already matches.
  • Skeleton. The graph's montages play on the enemy's mesh, so the enemy needs the player's skeleton, or a copy of each montage made for its own (ucf.create_montage_from_animation and the same windows).
  • Gated moves. A transition that requires a tag the enemy never holds, such as a shield's equipment tag, never fires; the combo walks the others.
  • Aim. Moves with approach or skew warp windows close on the target the enemy's UCF Enemy Attack Steering component holds, which bLockTarget keeps on the enemy's target for the whole combo.
UUCFActionGraphExecutionMethod (Action Graph Combo)
ActionGraphGraph set on the enemy for the action's length; empty plays the graph the enemy already holds
Variants (unreal.UCFActionGraphComboVariant)Steps (unreal.UCFActionInputStep: Tag, Trigger, default pressed), Weight
bLockTargetKeeps every move aimed at the target the AI chose (default on)
ComboTimeoutSeconds before the action gives up; 0 keeps a 30 second safety
Check: in Play with UCF.Debug.EnemyActions 1 and UCF.Debug.Actions 1, the enemy's action list runs the combo action, the graph overlay steps through the moves in order, and hits land on the player.
Several actions as one: Action Sequence
An Action Sequence (UUCFActionSequenceExecutionMethod) runs other actions of the same Action Set as one action, in order or one picked by weight: a three-hit string, or a string sometimes cut short by a feint. Each step runs through its own action's execution method, so montage actions, behavior trees and action graph combos mix.
seq = unreal.new_object(unreal.UCFActionSequenceExecutionMethod, outer=aset)
steps = []
for action_id in ("Slash1", "Slash2", "Slam"):        # Action IDs of actions already in this set
    step = unreal.UCFActionSequenceStep()
    step.set_editor_property("ActionId", action_id)
    steps.append(step)
seq.set_editor_property("Steps", steps)
spec = unreal.ActionSpec()
spec.set_editor_property("ActionId", "String")
spec.set_editor_property("ExecutionMethod", seq)
scoring = spec.get_editor_property("CustomScoring")
scoring.set_editor_property("Scorers", [range_scorer(aset, unreal.UCFDistanceScorer, 0, 100, 250, 450)])
spec.set_editor_property("CustomScoring", scoring)
actions = list(aset.get_editor_property("Actions"))
actions.append(spec)
aset.set_editor_property("Actions", actions)
save(aset)
print(ucf.validate_asset(aset))
range_scorer comes from Enemy Recipe 1, Step 6. bPickOneAtRandom runs one step picked by each step's Weight instead of all in order; SequenceTimeout limits the whole sequence. The sequence cools down and recovers as one action; the actions it names keep their own cooldowns. A step naming another Action Sequence is refused, and a sequence cannot be a reaction.
Check: ucf.validate_asset(aset) is empty; in Play, UCF.Debug.EnemyActions 1 shows String running while its steps play one after another.
Locking on to enemies
Player Recipe 5 locks on to any actor with a targetable component. An enemy on UCF Enemy Character Base (AUCFEnemyCharacterBase, what Enemy Recipe 1 duplicates) carries a UCF Enemy Targetable component (UUCFEnemyTargetableComponent), which stops being a target once the enemy dies. An enemy built on Enemy Character Base needs one added, as Combo Enemy Recipe, Step 1 adds a component, with new_class=unreal.UCFEnemyTargetableComponent. AimAtSocket names the bone the lock aims at; empty aims at the actor.
Check: in Play, the lock-on key locks the enemy; after it dies, the lock lets go.
Teams
A pawn's team is its UCF Team component (UUCFTeamComponent: TeamId, 255 for no team; bFreeForAll). Every enemy carries one, its TeamComponent, on team 1. A character built on UCF Character Base carries one too, its TeamComponent, on no team until its TeamId is set, and takes its controller's team when the controller carries one. Every Enemies Only filter treats a pawn with no team as hostile, so the player and the enemies fight with nothing set.
  • Companions nobody hits: set the same TeamId, such as 0, on the TeamComponent of the player and of each companion (a companion built on neither base gets a UCF Team component of its own). The player's melee trace and lock-on (TargetTeams on its targeting config) and the enemies' melee traces, all on Enemies Only, then spare teammates.
  • Enemies that hit each other: their teams differ, or a melee trace's TeamFilter is NoFilter (unreal.UCFTeamFilter.ENEMIES_ONLY spares teammates).
Check: UCF.Debug.Teams 1 writes each pawn's team above its head.
Enemies answering the player's swings
An enemy parries or dodges only a swing that announces itself. Give each of the player's attack montages a telegraph window over its wind-up with a Broadcast shape: the UCF Telegraph Window (UUCFTelegraphMarkerNotifyState, which also anchors the player's markers on a drawn item), as Enemy Recipe 4 adds it. Set its shape as Enemy Recipe 4 does, with a UUCFTelegraphShape_Sphere or UUCFTelegraphShape_Cone. Then give the enemy's Reaction Set the parry and dodge rules on UCF.Stimulus.AttackTelegraphed (AgentGuide/Enemy/Reactions.md, "Parry some swings, dodge others").
A parry reaction plays a guard long enough to meet the swing. The demo's sword enemies parry with GA_UCF_SwordParry (/UniversalCombatFramework/Demo/Weapons/Sword), a child of GA_UCF_MontageAbility, which plays the montage its reaction's Montage Payload names at the payload's PlayRate from its StartSection; the parry links that section on to its ThenSection (GuardLower), since the montage leaves its sections unlinked for the player's held guard and the montage ability alone stops at the end of the section it starts. Their reaction sets play AM_UCF_Sword_Parry from GuardRaise at a PlayRate of 0.7 through it.
A guard an enemy raises after a run of hits and holds for a while comes from a DamageTaken rule with a Hits Taken Gate (AgentGuide/Enemy/Reactions.md) and is held one of two ways. An enemy that plays an action graph, such as the dual-sword boss, presses the graph's own guard through an Action Graph Combo step held for a random time (MinHoldSeconds, MaxHoldSeconds on the step), so its guard is the player's: the same hold, block, stance cost and guard break. An enemy that plays montages holds a section of its reaction's montage: the Montage Payload's HoldSection loops for a random time between MinHoldSeconds and MaxHoldSeconds, then the montage plays on, and the reaction's AddTags carry UCF.State.Blocking for the Defense Rule Set's Guard rule, as the two-handed enemy's Guard reaction does.
Check: in Play with UCF.Debug.LogReactions 1, each player swing logs the rule that fired or why it was skipped.
The player answering an enemy's swings
An enemy's hits reach the player's defense like any other hit, so the guard and parry from AgentGuide/Player/ActionGraphs.md ("A held guard with a parry window") and the rules in AgentGuide/Player/DamageDefense.md block and parry enemies with nothing more. A warning marker over an enemy's swing needs a telegraph window with a shape on the enemy's attack montage (as above) and the player's UCF Telegraph Viewer with a style set (AgentGuide/Player/CameraTelegraphs.md).
Check: in Play, a hit taken while guarding from the front deals less damage than one taken without guarding.
A parry the player lands sends the attacker UCF.Event.ParryRecoil. The demo's enemies answer it with GA_UCF_ParryRecoil in their StartingAbilities, which plays the recoil and stops the swing. A boss answers with posture instead, GA_UCF_BossPosture: no recoil, a drain of its own UCF.Vital.Stance row by the ability's DrainPerParry, so a few clean parries empty the row, whose UCF.Event.GuardBreak starts the ordinary stun (GA_UCF_Stun), a window to strike. Tune how many parries break it with DrainPerParry against the Stance row's MaxValue, and keep the row's regeneration slow enough that parries in one exchange count.
Check: in Play, parry an ordinary enemy's swing and it recoils; parry a boss's swings a few times and it is stunned.
Executing a staggered enemy
The demo sword's graph executes a target holding UCF.State.Staggered: its idle and light attack moves carry a light attack transition to an Execute move, gated on a Paired Action Available condition naming PairedActionSet_UCF_SwordExecute. An enemy is open to it while it holds the tag, which a UCF State Tag Window (UUCFStateTagNotifyState, Tags) over the enemy's stagger or stun montage gives it, as the demo's AM_UCF_Stun does:
w = ucf.add_notify_state_to_montage(am_stun, unreal.UCFStateTagNotifyState, 0.0, length(am_stun))
w.set_editor_property("Tags", tags("UCF.State.Staggered"))
save(am_stun)
The paired roles, their montages and the damage on the right frame: AgentGuide/Player/PairedActions.md. The enemy needs no paired setup of its own: the action gives it the role when it plays, and an enemy on UCF Enemy Character Base holds its AI's actions and reactions while it is stunned or executed, so its block or dodge cannot cut the execution. An enemy on plain Enemy Character Base needs the same: put UCF.Action.BlockActions and UCF.Reaction.BlockReactions on it while it holds UCF.State.PairedAction.
Check: in Play, stagger the enemy and press light attack within reach; UCF.Debug.Paired.Draw 1 draws both roles' spots and the enemy's health drops by the execution's damage.
Switching an existing project to UCF
Moving a project from the two standalone plugins is a customer step: enable UCF in place of them, then run Tools, Universal Combat Framework, Finish Switching, which moves project settings and console variables to UCF's names, renames hand-typed component tags and names, and resaves every asset that needs it. It asks before it starts. Recommend source control first; do not run it for the customer.
The demo's enemies and bosses
AssetPath
Enemy, the parent of every demo enemy/UniversalCombatFramework/Demo/Characters/Enemy/BP_UCF_EnemyCharacter
Boss, the parent of every demo boss/UniversalCombatFramework/Demo/Characters/Boss/BP_UCF_BossCharacter
Combo enemy/UniversalCombatFramework/Demo/Characters/ComboEnemy/BP_UCF_ComboEnemy
Its Action Sets, one per weaponActionSet_UCF_ComboEnemy, ActionSet_UCF_ComboEnemy_Sword, ActionSet_UCF_ComboEnemy_Unarmed in the same folder
Its AI ConfigEnemyConfig_UCF_ComboEnemy in the same folder
Dual-sword boss, open to the sword execution/UniversalCombatFramework/Demo/Characters/DualSwordBoss/BP_UCF_DualSwordBoss
Its Action Sets and Reaction SetActionSet_UCF_DualSwordBoss, ActionSet_UCF_DualSwordBoss_Phase2, ReactionSet_UCF_DualSwordBoss in the same folder
Boss posture/UniversalCombatFramework/Demo/Characters/Boss/GA_UCF_BossPosture
Sword parry, the sword enemies' and the dual-sword boss's/UniversalCombatFramework/Demo/Weapons/Sword/GA_UCF_SwordParry
The level with them all/UniversalCombatFramework/Demo/Maps/LVL_UCF_Demo
Every demo enemy draws what it holds through its Loadout, with the fists as its Equipment Manager's DefaultItem, so a disarmed enemy fights on with its fists: the enemy parent holds the baton in StartingItems, and an enemy given RandomStartingItems draws one entry picked at random each time it spawns, as the Over Shoulder crowd does. The enemy parent carries the player layer's reactions: DefenseRuleSet_UCF_Character on its Defense component, Poise and Stance rows beside Health, PhysReact_UCF_Enemy on its Physical Reaction component, and GA_UCF_HitReact, GA_UCF_Stun and GA_UCF_ParryRecoil in its StartingAbilities. The boss parent answers a parry with GA_UCF_BossPosture in place of the recoil. Duplicate one into the customer's folder to start from a working enemy; read a combo enemy's Action Set's combo actions as the Combo Enemy Recipe's Step 4 describes. The dual-sword boss is the boss parent holding two Item_UCF_Sword through its Loadout, its combos walking the main-hand sword's action graph, its rage below half health swapping in its second phase's Action Set, and its AI Config's Awareness_UCF_DualSwordBoss seeing all around it as far as its closed arena reaches, with bAutoRegisterForCombatRoles on so the role system hands it what it sees as its target, so it engages a player anywhere in the arena; its Defense component's set is DefenseRuleSet_UCF_Character, whose Finisher Health response stops its health at 150 and opens GA_UCF_FinisherStun, which its Starting Abilities grant, and its Combat component (UUCFCombatComponent) holds UCF.Enemy.SoulslikeBoss in CharacterTags, the tag the response and the sword execution's set ask for. The execution knocks one sword away as an item on the ground, and the other drops at its death.
Mistakes
SymptomCause and fix
The combo action runs and nothing playsThe enemy has no Action Graph component, or a step's input tag is one no transition from the current move listens for; saving the Action Set names it.
The combo plays but never hitsThe trace windows name socket IDs no TraceSockets row of the item the enemy holds carries.
An enemy never parries the playerThe player's attack montage has no telegraph window, or its Broadcast has no shape.
The lock holds a dead enemyThe enemy is built on Enemy Character Base without a UCF Enemy Targetable component.
The execution never startsThe enemy does not hold UCF.State.Staggered when the press comes, or the press comes from outside the paired action's reach.