# AI Agent Guide

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

Markdown version of https://rigbak.com/docs/universal-combat-framework/agents, a page of the Universal Combat Framework documentation. Link that page when citing it.

> 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. **Open your project**

   Open the project in the Unreal Editor and leave it open. The agent works in the running editor.
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. **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. **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.

| Route | Engine versions | What it needs |
| --- | --- | --- |
| **Python bridge** | 5.6, 5.7 and 5.8 | The 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 MCP** | 5.8 | The 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

| Ask | What 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

| File | What it is |
| --- | --- |
| `Resources/AGENTS.md` | The 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.py` | The Python bridge: sends the agent's Python to the open editor and prints what the editor printed. |
| `Resources/AgentSkills/ucf-agent/SKILL.md` | The `/ucf-agent` skill for Claude Code. |
| `Content/Python/ucf_agent_tools` | The 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](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`:

     ```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:

  ```ini
  [/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:

```python
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.

```python
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`:

| Call | Does |
| --- | --- |
| `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_transition` | Other 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 step | Epic Unreal MCP tool |
| --- | --- |
| `load`, find assets | `AssetTools.find_assets`, `AssetTools.load_asset` |
| `duplicate` | `AssetTools.duplicate` |
| `new_data_asset` | `DataAssetTools.create` |
| Blueprint with a parent class | `BlueprintTools.create` (`asset_type` is the parent class) |
| `defaults(bp)` and setting class defaults | `BlueprintTools.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 Blueprint | `ActorTools.add_component` |
| `save` | `AssetTools.save_assets` |
| Play and look | `EditorAppToolset.StartPIE`, `StopPIE`, `CaptureViewport` |
| `log_warnings` | `LogsToolset.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:

```python
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).

```python
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:

```python
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`.

```python
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.

```python
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

```python
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.

```python
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.

```python
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.

```python
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`):

| Value | Editor label | Fires when |
| --- | --- | --- |
| `ON_STARTED` | Input Pressed | The input is pressed. The default; combos use it. |
| `ON_COMPLETED` | Input Released | The input is released. |
| `ON_CANCELLED` | Input Released Early | The input is released before a hold finishes. |
| `AUTO` | Action Completed | The move finished with nothing chaining. Pass `""` as the input tag. |
| `ON_FAILED` | Action Failed | The 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:

```python
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.

```python
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

```python
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

```python
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:

```python
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.

```python
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:

```python
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

```python
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

```python
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

```python
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:

```python
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:

```python
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:

   ```python
   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:

```python
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.

```python
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.

```python
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:

```python
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.

```python
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.

```python
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.

```python
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.**

```python
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`.

```python
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

```python
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

```python
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:

```python
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:

```python
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:

```python
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

```python
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

```python
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:

```python
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:

```python
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:

| Want | Set |
| --- | --- |
| An attack for a range | A Distance Scorer with its own band. Give each attack a different band. |
| Only when facing the target | Add an **Angle Scorer** (`UUCFAngleScorer`); its default Range peaks at 0 to 30 degrees. |
| A three-hit combo | `ChainLinks` 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 another | `Selection` = `unreal.UCFActionSelection.CHAIN_ONLY` |
| Fewer repeats | `Cooldown.Duration`, and `Cooldown.MaxConsecutiveUses` (-1 is unlimited) |
| Not as the opening move | `Cooldown.InitialCooldown` |
| A gap between any two attacks | `ActionRecoveryTime` on the AI Config (0 by default) |
| Several enemies take turns | Add a **Combat Token Gate** (`UUCFTokenGate`, `TokenTag` = `UCF.Token.Attack`) to `CustomScoring.Gates` |
| Back off when crowded | An 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 gap | A **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.

```python
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:

   ```python
   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:

```python
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.

```python
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.

```python
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

```python
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.

```python
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:

```python
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:

```python
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.

| Task | File |
| --- | --- |
| A property refuses a value, rows a plain write refuses, components on a Blueprint, montage sections, new gameplay tags, checking an asset | `AgentGuide/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 moves | `AgentGuide/Player/ActionGraphs.md` |
| Stamina, attack costs, cooldowns and charges, resource and tag gates, sprint drain, slowing during a move | `AgentGuide/Player/GatesCostsHooks.md` |
| New keys and input tags, chords, abilities on keys, sprint, pausing input | `AgentGuide/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 objects | `AgentGuide/Player/InventoryInteraction.md` |
| Hit effects, blocks and parries, health and stamina rows, hit reactions | `AgentGuide/Player/DamageDefense.md` |
| Attacks closing on the target, combat styles, targeting configs, targetable actors | `AgentGuide/Player/TargetingStylesSteering.md` |
| Camera settings, camera shots, attack warning markers | `AgentGuide/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, debugging | `AgentGuide/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.

| Task | File |
| --- | --- |
| A property refuses a value, rows in arrays, components on a Blueprint, montage sections, new gameplay tags, checking an asset, project settings | `AgentGuide/Enemy/Python.md` |
| A moveset from several animations, ranges, combos and pacing, gates, cooldowns, one clip with several attacks, movesets per weapon or role | `AgentGuide/Enemy/Actions.md` |
| Flinches by direction, parry and dodge rules, what an enemy can notice | `AgentGuide/Enemy/Reactions.md` |
| Keeping distance, circling, backing off when stared at, flanking angles | `AgentGuide/Enemy/Movement.md` |
| Target selection, combat roles and limits, taking turns, teams, the brain, repeatable fights | `AgentGuide/Enemy/BrainRolesTargets.md` |
| Sight and hearing, patrols, guard posts, leashes | `AgentGuide/Enemy/AwarenessTerritory.md` |
| An attack run as a behavior tree, the State Tree tasks | `AgentGuide/Enemy/BehaviorTrees.md` |
| Montage windows, root-motion lunges, step-backs, tag-driven animation, walking slower on a tag | `AgentGuide/Enemy/Animation.md` |
| Weapons and loadouts, damage and hit effects, enemies that block and parry | `AgentGuide/Enemy/WeaponsDamageDefense.md` |
| Health, stamina and stance, death, encounters and boss bars, settings, debugging | `AgentGuide/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

| Asset | Class | Made with | Holds |
| --- | --- | --- | --- |
| Player character | Blueprint of `AUCFCharacterBase` (duplicate of `BP_UCF_Character`) | `duplicate` | Mesh, `StartingAbilitySet`, components below |
| Ability set | `UUCFAbilitySet` (duplicate of `AbilitySet_UCF_Default`) | `duplicate` | `GrantedGameplayAbilities` rows: `Ability`, `InputTag`, `InputAction` |
| Game mode | Child Blueprint of `BP_UCF_GameMode` | `unreal.BlueprintFactory` with `ParentClass` | `DefaultPawnClass`, controller `BP_UCF_PlayerController` |
| Animation Blueprint | Child of `ABP_UCF_LocomotionTemplate` | `ucf.create_locomotion_anim_blueprint` | `IdleAnimation`, `WalkAnimation`, `RunAnimation`, `WalkSpeed`, `RunSpeed` |
| Action Graph | `UUCFActionGraphAsset` | `new_data_asset`, then `ucf.add_*` and `ucf.compile_action_graph` | Nodes and transitions; `DefaultInputBufferMode` |
| Item Definition | `UUCFItemDefinition` | `new_data_asset` | `Fragments`, `DisplayName`, `Icon`, `SlotTags`, `MaxStackSize` |
| Equippable fragment | `UUCFItemFragment_Equippable` | `unreal.new_object(..., outer=item)` | `ActionGraph`, `InputMappingContext`, `InputMappings`, `TraceSockets`, `AttackStopDistance`, `HoldPlaces`, `bIsMainWeapon`, `EquipmentTags`, `AbilitySetsToGrant`, `AnimLayerClass`, `ItemActorClass` |
| Visuals fragment | `UUCFItemFragment_Visuals` | `unreal.new_object(..., outer=item)` | `HeldMesh` (label Mesh) |
| Container Definition | `UUCFContainerDefinition` | `new_data_asset` | `Layout`, `SlotCount`, `GridSize`, `Rules` (`unreal.new_object(..., outer=definition)`), `bCarried`, `bTakesNewItems`, `AccessTag`, `bOpensBags` |
| Inventory Config | `UUCFInventoryConfig` | `new_data_asset` | `Containers` rows (`import_text`), `CarryRules`, `CombineSets`, `SortOrder`, `bEquipAtOnce`, `bPutAwayAtOnce`, `bCombineAtOnce`; set on the character's `InventoryComponent.Config` |
| Combine Set | `UUCFCombineSet` | `new_data_asset` | `Recipes` rows (two items, their counts, `Results`, `Seconds`), `Combines`; listed on the config's `CombineSets` |
| Damage Config | `UUCFDamageConfig` | `new_data_asset` | `Damage`, `AdditionalVitalDamage` (a `UCF.Vital.Poise` row), `DamageTags`, `HitEffects` |
| Input Mapping Context | `UInputMappingContext` (duplicate a demo one) | `duplicate`, `map_key` | Keys to Input Actions |
| Montage | `UAnimMontage` | `ucf.create_montage_from_animation` | Notify 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

| Asset | Path under `/UniversalCombatFramework/` |
| --- | --- |
| Locomotion template | `Core/Animation/ABP_UCF_LocomotionTemplate` |
| Demo player, controller, game mode | `Demo/Characters/Player/BP_UCF_Character`, `Demo/Characters/Player/BP_UCF_PlayerController`, `Demo/Game/BP_UCF_GameMode` |
| Input Actions | `Demo/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 contexts | `Demo/Inputs/IMC_UCF_Default`, `Demo/Weapons/Unarmed/IMC_UCF_Unarmed`, `Demo/Weapons/Sword/IMC_UCF_Sword` |
| Combat styles and targeting | `Demo/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 configs | `Demo/Weapons/Unarmed/Damage_UCF_Unarmed`, `Demo/Weapons/Sword/Damage_UCF_Sword` |
| A test enemy | `Demo/Characters/Enemy/BP_UCF_EnemyCharacter` |
| Demo level and complete examples | `Demo/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 button | `Demo/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 kit | `Demo/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) | Class | Needed for | Key properties |
| --- | --- | --- | --- |
| UCF Melee Trace Window | `UUCFMeleeTraceNotifyState` | Any hit to deal damage | `SocketIDs`, `DamageConfig`, `ExtraDamageTags` |
| UCF Action Window | `UUCFActionWindowNotifyState` | Where 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 ends | none |
| UCF State Tag Window | `UUCFStateTagNotifyState` | Tags for a stretch: `UCF.State.Intangible` (i-frames), `UCF.State.HyperArmor` (less poise damage) | `Tags` |
| UCF Approach Window | `UUCFApproachWindowNotifyState` | Gliding to the target during a wind-up |  |
| UCF Telegraph Window | `UUCFTelegraphMarkerNotifyState` | A warning marker over an enemy's swing |  |
| UCF Anim Effect Window | `UUCFAnimEffectWindowNotifyState` | Swing trails (`UCF.AnimEffect.Weapon.Trail`) and glows | `Effect` |
| UCF Anim Effect | `UUCFAnimEffectNotify` | Footsteps, landings and other one-frame sounds the character's Anim Effect Bank plays | `Effect` |
| UCF Equipment Commit | `UUCFEquipmentCommitNotify` | The swap frame of a draw or stow reach |  |
| UCF Gameplay Event | `UUCFGameplayEventNotify` | Sending a gameplay event at a frame | `EventTag` |

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

| Tag | Use |
| --- | --- |
| `UCF.Input.LightAttack`, `.HeavyAttack`, `.Dash`, `.Dodge`, `.Guard`, `.LockOn`, `.Sprint`, `.Special`, `.Aim`, `.Fire`, `.Execute`, `.Drop` | Input tags on item mappings and graph transitions |
| `UCF.State.Intangible` | i-frames: melee traces skip the holder |
| `UCF.State.HyperArmor` | Less poise damage, so light hits do not flinch |
| `UCF.State.Dashing` | With `GraceTag`, server trust for a fast dash |
| `UCF.State.Blocking` | A held guard (node `AppliedTags`) |
| `UCF.State.ActionsBlocked` | On the character, drops every press |
| `UCF.State.ActionRunning`, `UCF.State.LockedOn` | Read only: a move is running; a lock is held |
| `UCF.Place.Main`, `UCF.Place.Off`, `UCF.Place.Back`, `.Back.Left`, `.Back.Right` | Body places and hold places |
| `UCF.Place.Head`, `.Chest`, `.Hands`, `.Feet`, `.Shoulders`, `.Neck`, `.Ring.Left`, `.Ring.Right`, `.Top`, `.Bottom` | The demo's worn gear places; a game names its own |
| `UCF.Vital.Health`, `.Stamina`, `.Stance` | Vitals rows |
| `UCF.ItemMesh` | Source 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

| Symptom | Cause and fix |
| --- | --- |
| Press does nothing | The 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 system | The character has no Ability System Component; the duplicate has one. |
| Combo never chains | The 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 hand | No mesh tagged `UCF.Attachment`, or the body place's socket is missing on the skeleton. The log names both. |
| Hits pass through | No 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 crooked | Set `Offset` on the item's `HoldPlaces` row, as in Player Recipe 4, Step 5. |
| T-pose, or montages do not play | The Animation Blueprint is for another skeleton, or has no `DefaultSlot` Slot node. |
| An attack plays stretched, twisted or not at all | Its montage was made from an animation of another skeleton (Rules). |
| Lock-on finds nothing | The target has no UCF Targetable component, or is on the player's team; or the targeting config is unset. |
| Dodge does not avoid hits | The 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 skeleton | Reach 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

| Asset | Class | Made with | Holds |
| --- | --- | --- | --- |
| Enemy pawn | Blueprint of `AUCFEnemyCharacterBase` (duplicate of `BP_UCF_EnemyCharacter`) | `duplicate` | Mesh, `AIConfig`, `StartingAbilities`, components below |
| AI controller | `AEnemyControllerBase`; the demo `BP_UCF_EnemyController` is fine | already set on the duplicate | Movement, scoring, reactions, awareness, the brain |
| Enemy AI Config | `UEnemyAIConfig` | `new_data_asset` | `TargetSelector`, `AwarenessConfig`, `DefaultActionSet`, `DefaultReactionSet`, `DefaultMovementProfile`, `StateTree`, `RoleRegistrationParams`, `ActionRecoveryTime` |
| Action Set | `UActionSet` | `new_data_asset` | `Actions` (`FActionSpec`) |
| Reaction Set | `UReactionSet` | `new_data_asset` | `Reactions` (`FReactionSpec`), `TriggerRules` (`FUCFReactionTriggerRule`) |
| Awareness Config | `UUCFAwarenessConfig` | `new_data_asset` | Sight, hearing, `bAlwaysAware` |
| Movement Behavior Profile | `UMovementBehaviorProfile` | `new_data_asset` | `DesiredDistance` (cm) |
| Damage Config | `UUCFDamageConfig` | `new_data_asset` | `Damage`, `DamageTags`, `HitEffects` |
| Weapon | `UUCFItemDefinition` | `new_data_asset` | `Fragments`: Visuals (`HeldMesh`), Equippable (`TraceSockets`, `HoldPlaces`), World Item |
| Animation Blueprint | Child of `ABP_UCF_LocomotionTemplate` | `ucf.create_locomotion_anim_blueprint` | `IdleAnimation`, `WalkAnimation`, `RunAnimation`, `WalkSpeed`, `RunSpeed` |
| Montage | `UAnimMontage` | `ucf.create_montage_from_animation` | Notify 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

| Asset | Path |
| --- | --- |
| 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) | Class | Needed for | Key properties |
| --- | --- | --- | --- |
| UCF Melee Trace Window | `UUCFMeleeTraceNotifyState` | Any hit to deal damage | `SocketIDs`, `DamageConfig`, `ExtraDamageTags` |
| UCF Telegraph Window | `UUCFTelegraphMarkerNotifyState` | Enemies parrying or dodging this attack | `Broadcast.Shape`, `bFindAttackAutomatically`, `Tags` |
| UCF State Tag Window | `UUCFStateTagNotifyState` | Tags for a stretch: `UCF.State.Intangible` for i-frames | `Tags` |
| UCF Approach Window | `UUCFApproachWindowNotifyState` | Turning and gliding toward the target during a wind-up | `Mode`, `ApproachTargetName` (`Target`), `StopDistanceOverride` (cm between the bodies) |
| UCF Gameplay Event | `UUCFGameplayEventNotify` | Sending a gameplay event at a frame | `EventTag` |
| UCF Anim Effect Window, UCF Anim Effect | `UUCFAnimEffectWindowNotifyState`, `UUCFAnimEffectNotify` | Trails, footsteps, foley | `Effect` |

UCF has no combo notify: combos come from `ChainLinks` on the Action Set.

#### Gameplay tags you set

| Tag | Use |
| --- | --- |
| `UCF.Damage.Physical.Slashing`, `.Piercing`, `.Bludgeoning`; `UCF.Damage.Elemental.Fire`, `.Ice`, `.Lightning` | `DamageTags` on a damage config |
| `UCF.Stimulus.DamageTaken` | Trigger rule for a flinch |
| `UCF.Stimulus.AttackTelegraphed` | Trigger rule for a parry or dodge |
| `UCF.Role.Attacker`, `.Flanker`, `.Waiter`, `.Supporter`, `.Elite` | Role settings and per-role sets |
| `UCF.Token.Attack` | Combat Token Gate |
| `UCF.State.Intangible` | i-frames in a State Tag Window |
| `UCF.State.IsMovementBlocked` | Already in each new action's `AddTags` |
| `UCF.State.ReactionActive` | Stops two reactions overlapping (`AddTags` on one, `BlockTags` on the other) |
| `UCF.Action.BlockActions` | On the ability system, stops all actions |
| `UCF.Vital.Health`, `UCF.Vital.Stamina`, `UCF.Vital.Stance` | Vitals rows |

#### Common mistakes

| Symptom | Cause and fix |
| --- | --- |
| Enemy stands still, no overlay above it | The pawn's AI controller is not a UCF one, or `AIConfig` is empty. |
| Enemy never notices the player | `AwarenessConfig` empty, or the player is on the enemy's team (Team Id 1). |
| Enemy moves but never attacks | No 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 move | The action has no Distance Scorer. |
| Action wins and nothing plays | `ExecutionMethod` empty, payload `Montage` empty, or `ActionId` empty. |
| Attacks once, then freezes | The ability never reaches End Ability. Use `GA_UCF_MontageAbility`, or set `AbilityTimeout` on the execution method. |
| The enemy holds nothing | Its `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 through | `SocketIDs` 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 enemy | It 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 other | They 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 parries | The 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 it | Its `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 flinches | The 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 all | No navmesh, or a leftover `UCF.State.IsMovementBlocked` tag. |
| The enemy slides along its path in its idle pose | It 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 animation | The Animation Blueprint is for another skeleton, or has no `DefaultSlot` Slot node, so montages play nowhere. |
| An attack plays stretched, twisted or not at all | Its 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](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.

| Topic | Page |
| --- | --- |
| Overview | [https://rigbak.com/docs/UniversalCombatFrameworkDocs](https://rigbak.com/docs/UniversalCombatFrameworkDocs) |
| Getting started | [https://rigbak.com/docs/universal-combat-framework/getting-started](https://rigbak.com/docs/universal-combat-framework/getting-started) |
| Enemies playing action graph combos | [https://rigbak.com/docs/universal-combat-framework/action-graphs-in-action-sets](https://rigbak.com/docs/universal-combat-framework/action-graphs-in-action-sets) |
| Action sequences and random options | [https://rigbak.com/docs/universal-combat-framework/sequences-and-random-options](https://rigbak.com/docs/universal-combat-framework/sequences-and-random-options) |
| Combo enemy patterns | [https://rigbak.com/docs/universal-combat-framework/seam-patterns](https://rigbak.com/docs/universal-combat-framework/seam-patterns) |
| Action graphs, combos, transitions | [https://rigbak.com/docs/universal-combat-framework/player/action-graph](https://rigbak.com/docs/universal-combat-framework/player/action-graph) |
| The graph editor | [https://rigbak.com/docs/universal-combat-framework/player/action-graph-editor](https://rigbak.com/docs/universal-combat-framework/player/action-graph-editor) |
| Gates, costs, cooldowns | [https://rigbak.com/docs/universal-combat-framework/player/gates-costs-cooldowns](https://rigbak.com/docs/universal-combat-framework/player/gates-costs-cooldowns) |
| Input and key mappings | [https://rigbak.com/docs/universal-combat-framework/player/input](https://rigbak.com/docs/universal-combat-framework/player/input) |
| Items and fragments | [https://rigbak.com/docs/universal-combat-framework/player/items](https://rigbak.com/docs/universal-combat-framework/player/items) |
| Drawing, stowing, body places | [https://rigbak.com/docs/universal-combat-framework/player/equipment](https://rigbak.com/docs/universal-combat-framework/player/equipment) |
| Inventory | [https://rigbak.com/docs/universal-combat-framework/player/inventory](https://rigbak.com/docs/universal-combat-framework/player/inventory) |
| Taking only some of the inventory: a belt alone, no grid, no bags | [https://rigbak.com/docs/universal-combat-framework/player/inventory-pick-what-you-need](https://rigbak.com/docs/universal-combat-framework/player/inventory-pick-what-you-need) |
| The ready inventory styles: survival grid, party RPG, open world list | [https://rigbak.com/docs/universal-combat-framework/player/inventory-survival-grid](https://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-party-rpg), [https://rigbak.com/docs/universal-combat-framework/player/inventory-open-world-list](https://rigbak.com/docs/universal-combat-framework/player/inventory-open-world-list) |
| Inventory containers, grids, weight and caps | [https://rigbak.com/docs/universal-combat-framework/player/inventory-containers](https://rigbak.com/docs/universal-combat-framework/player/inventory-containers) |
| Bags and banks | [https://rigbak.com/docs/universal-combat-framework/player/inventory-bags](https://rigbak.com/docs/universal-combat-framework/player/inventory-bags) |
| Combines (rounds into a magazine) | [https://rigbak.com/docs/universal-combat-framework/player/inventory-combines](https://rigbak.com/docs/universal-combat-framework/player/inventory-combines) |
| Loot chests | [https://rigbak.com/docs/universal-combat-framework/player/loot-chests](https://rigbak.com/docs/universal-combat-framework/player/loot-chests) |
| Inventory screens | [https://rigbak.com/docs/universal-combat-framework/player/inventory-screens](https://rigbak.com/docs/universal-combat-framework/player/inventory-screens) |
| Saving the inventory | [https://rigbak.com/docs/universal-combat-framework/player/inventory-saving](https://rigbak.com/docs/universal-combat-framework/player/inventory-saving) |
| Inventory rules, combines and item data in Blueprint | [https://rigbak.com/docs/universal-combat-framework/player/inventory-blueprint](https://rigbak.com/docs/universal-combat-framework/player/inventory-blueprint) |
| The belt of slots | [https://rigbak.com/docs/universal-combat-framework/player/quick-bar](https://rigbak.com/docs/universal-combat-framework/player/quick-bar) |
| Pickups and drops | [https://rigbak.com/docs/universal-combat-framework/player/pickups-drops-holders](https://rigbak.com/docs/universal-combat-framework/player/pickups-drops-holders) |
| Combat styles | [https://rigbak.com/docs/universal-combat-framework/player/combat-styles](https://rigbak.com/docs/universal-combat-framework/player/combat-styles) |
| Targeting and lock-on | [https://rigbak.com/docs/universal-combat-framework/player/targeting](https://rigbak.com/docs/universal-combat-framework/player/targeting) |
| Attack steering | [https://rigbak.com/docs/universal-combat-framework/player/attack-steering](https://rigbak.com/docs/universal-combat-framework/player/attack-steering) |
| Camera | [https://rigbak.com/docs/universal-combat-framework/player/camera](https://rigbak.com/docs/universal-combat-framework/player/camera) |
| Paired Actions (finishers) | [https://rigbak.com/docs/universal-combat-framework/player/paired-actions](https://rigbak.com/docs/universal-combat-framework/player/paired-actions) |
| Full enemy walkthrough | [https://rigbak.com/docs/universal-combat-framework/enemy/step-by-step-enemy](https://rigbak.com/docs/universal-combat-framework/enemy/step-by-step-enemy) |
| Enemy actions, scoring, combos | [https://rigbak.com/docs/universal-combat-framework/enemy/action-system](https://rigbak.com/docs/universal-combat-framework/enemy/action-system) |
| Enemy reactions and trigger rules | [https://rigbak.com/docs/universal-combat-framework/enemy/reaction-system](https://rigbak.com/docs/universal-combat-framework/enemy/reaction-system) |
| Enemy weapons | [https://rigbak.com/docs/universal-combat-framework/enemy-weapons](https://rigbak.com/docs/universal-combat-framework/enemy-weapons) |
| Sight, hearing, stealth | [https://rigbak.com/docs/universal-combat-framework/enemy/awareness-system](https://rigbak.com/docs/universal-combat-framework/enemy/awareness-system) |
| Enemy movement and spacing | [https://rigbak.com/docs/universal-combat-framework/enemy/movement-system](https://rigbak.com/docs/universal-combat-framework/enemy/movement-system) |
| Combat roles | [https://rigbak.com/docs/universal-combat-framework/enemy/combat-roles](https://rigbak.com/docs/universal-combat-framework/enemy/combat-roles) |
| Recipes (bosses, packs) | [https://rigbak.com/docs/universal-combat-framework/enemy/patterns](https://rigbak.com/docs/universal-combat-framework/enemy/patterns) |
| Hit detection and damage | [https://rigbak.com/docs/universal-combat-framework/melee-trace-and-damage](https://rigbak.com/docs/universal-combat-framework/melee-trace-and-damage) |
| Blocks and parries | [https://rigbak.com/docs/universal-combat-framework/defense](https://rigbak.com/docs/universal-combat-framework/defense) |
| Health and stamina | [https://rigbak.com/docs/universal-combat-framework/vitals](https://rigbak.com/docs/universal-combat-framework/vitals) |
| Telegraphs | [https://rigbak.com/docs/universal-combat-framework/telegraphs](https://rigbak.com/docs/universal-combat-framework/telegraphs) |
| Montages, notifies, root motion | [https://rigbak.com/docs/universal-combat-framework/animation-integration](https://rigbak.com/docs/universal-combat-framework/animation-integration) |
| Names in UCF | [https://rigbak.com/docs/universal-combat-framework/names-in-ucf](https://rigbak.com/docs/universal-combat-framework/names-in-ucf) |
| Switching an existing project to UCF | [https://rigbak.com/docs/universal-combat-framework/switching-to-ucf](https://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.

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

| Field | Does |
| --- | --- |
| `ActionId` | Unique name in the set; chain links name it. An empty one is dropped. |
| `bEnabled` | Off 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) |
| `ExecutionMethod` | How it runs (below). |
| `SelectionWeight`, `RiskPenalty` | Multiply and divide the score: below 1 and above 1 make it rarer. |
| `CustomScoring` (`unreal.UCFCustomScoring`) | `Scorers` (soft factors) and `Gates` (hard vetoes), below. |
| `TagScoreMultipliers` | Tag to multiplier: while the target holds the tag, the score is multiplied. |
| `RequiresTags`, `BlockTags` | Tags that must be, or must not be, on the target or in the world. |
| `bRequireLineOfSight` | Only with a clear line to the target. |
| `AddTags` | Tags 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`, `RecoveryTime` | This 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`) |
| `Hook` | A `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) | Runs | Fields |
| --- | --- | --- |
| `UUCFAbilityExecutionMethod` (Gameplay Ability) | One ability and waits for it to end | `AbilityClass` (`GA_UCF_MontageAbility` plays the payload's montage), `AbilityTimeout`, `Payload` |
| `UUCFAbilityByTagExecutionMethod` (Gameplay Ability By Tag) | The granted ability carrying a tag | `ActivationTag`, `AbilityTimeout`, `Payload` |
| `UUCFAbilityFireAndForgetExecutionMethod` (Gameplay Ability (Fire And Forget)) | Starts an ability and ends the action at once | `AbilityClass`, `ActivationTag` |
| `UUCFBehaviorTreeExecutionMethod` (Behavior Tree Sequence) | Behavior trees one after another | `AgentGuide/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`:

```python
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) | In | Fields |
| --- | --- | --- |
| `UUCFDistanceScorer` (Distance Scorer) | `Scorers` | `Range` (cm) |
| `UUCFAngleScorer` (Angle Scorer) | `Scorers` | `Range` (degrees off facing the target; default peaks at 0 to 30) |
| `UUCFHealthScorer` (Health Scorer) | `Scorers` | `Range` (own health, 0 to 1) |
| `UUCFSpeedScorer` (Speed Scorer) | `Scorers` | `Range` (own speed, cm/s) |
| `UUCFVitalScorer` (Vital Scorer) | `Scorers` | `VitalTag`, `bUseFraction`, `Range` |
| `UUCFAttributeScorer` (Attribute Scorer) | `Scorers` | `Attribute`, `NormalizeBy`, `ValueEval` |
| `UUCFStaminaGate` (Stamina Gate) | `Gates` | `MinStamina` |
| `UUCFVitalGate` (Vital Gate) | `Gates` | `VitalTag`, `MinValue`, `bUseFraction` |
| `UUCFTokenGate` (Combat Token Gate) | `Gates` | `TokenTag` (`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

| Symptom | Cause and fix |
| --- | --- |
| One attack fires at every range | It has no Distance Scorer. |
| The follow-up never plays | Its `ActionId` differs from the link's `TargetActionId`, or its own band leaves it at 0 where the first attack ends. |
| The enemy spams one move | No `Cooldown.Duration`, or every other action scores 0 at that range. `UCF.Debug.Scoring 1` shows why. |
| An action wins and nothing plays | Empty `ExecutionMethod`, payload `Montage` or `ActionId`. A whole-array write does not fill the method; make it yourself. |
| The back-step plays at range | Its 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) | Class | Fields |
| --- | --- | --- |
| UCF Melee Trace Window | `UUCFMeleeTraceNotifyState` | `SocketIDs` (weapon trace socket IDs; empty sweeps all), `DamageConfig`, `ExtraDamageTags` |
| UCF Approach Window | `UUCFApproachWindowNotifyState` | `Mode` (`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 Window | `UUCFStateTagNotifyState` | `Tags` held while it runs: `UCF.State.Intangible` (i-frames), `UCF.State.Blocking` |
| UCF Telegraph Window | `UUCFTelegraphMarkerNotifyState` | `Broadcast` (`unreal.UCFTelegraphBroadcast`: `Shape` = `UUCFTelegraphShape_Sphere` `Radius` or `UUCFTelegraphShape_Cone` `Radius`, `HalfAngleDegrees`), `bFindAttackAutomatically`, `DamageConfig` (shown as Attack), `Tags`, `Magnitude` |
| UCF Anim Effect Window | `UUCFAnimEffectWindowNotifyState` | `Effect` (`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) | `UUCFGameplayEventNotify` | `EventTag` |
| UCF Anim Effect (one frame) | `UUCFAnimEffectNotify` | `Effect` |

##### 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:

```python
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

| Symptom | Cause and fix |
| --- | --- |
| Swings short of the target | No approach window, or `StopDistanceOverride` left at -1 (the approach component's 150). |
| The lunge overshoots | The Motion Warping window has no modifier, or its `WarpTargetName` is not `Target`. |
| The dodge does not avoid hits | No `UCF.State.Intangible` window over the evasive frames. |
| Nothing happens on an effect window | Neither 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 twice | The 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`.

| Field | Does |
| --- | --- |
| `SightRadius`, `LoseSightRadius` | Sight range in cm, and the range at which a seen target is lost |
| `PeripheralVisionHalfAngle` | Half the sight cone, in degrees (90 is a 180 degree cone) |
| `bEnableHearing`, `HearingRange` | Hearing and its range in cm |
| `bEnableDamageSense` | Being hit reveals the attacker |
| `bGradualEscalation`, `EscalationRate`, `SuspicionThreshold` | Sight fills a 0 to 1 meter, faster up close and straight ahead, before the enemy fully notices; the threshold is where it turns suspicious |
| `ProximityRadius` | Inside this many cm a target stays noticed without sight |
| `GraceLossDuration` | Seconds it keeps fighting after losing sight |
| `SuspiciousDecayDuration` | Seconds a full meter takes to drain |
| `ConfirmLostDelay` | Seconds without sight before a noticed target counts as lost |
| `bAlwaysAware` | Knows every hostile target at once, no sight needed (a boss in its arena) |
| `bAlertAlliesOnDetect`, `AllyAlertRadius`, `AllyAlertCooldown` | Tells nearby allies when it notices someone |

**A slow, side-blind guard:**

```python
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`).

```python
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 field | Does |
| --- | --- |
| `Posts` | The posts this enemy owns, in route order |
| `RestingBehavior` | `PATROL_POSTS` (walk the route) or `HOLD_GROUND` (stand at the first post) |
| `PostOrder` | `SEQUENTIAL_LOOP`, `SEQUENTIAL_PING_PONG`, `RANDOM` |
| `PatrolStartDelay`, `PatrolStartVariance`, `ArrivalRadius` | When it sets off, and how close counts as arrived |
| `bLeashEnabled`, `LeashAnchor` (`SELF`, `POSTS_CENTERED`, `POSTS_UNION`, `ACTOR` with `LeashAnchorActor`), `LeashRadius` | How far it may be dragged from its ground |
| `LeashBreakGraceTime` | Seconds past the leash before it gives up |
| `bOnlyFightInsideLeash` | Ignore targets outside the leash |
| `DisengageBehavior` | `RETURN_TO_POST` or `SETTLE_HERE` once a fight ends |

| Post field | Does |
| --- | --- |
| `Shape` | `POINT`, `RADIUS` (wander inside `WanderRadius`), `BOX` (inside `WanderBoxExtent`) |
| `WaitTime`, `WaitTimeVariance` | Seconds it waits on arrival |
| `bFaceForwardOnArrival` | Turn to the post's facing |
| `bPassThrough` | Walk 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

| Symptom | Cause and fix |
| --- | --- |
| Never notices the player | `AwarenessConfig` empty, the player beyond `SightRadius`, outside the cone, or on the enemy's team. |
| Notices through walls | `ProximityRadius` large, or hearing on with a loud level. |
| Stands still instead of patrolling | `Posts` empty, `RestingBehavior` on `HOLD_GROUND`, no navmesh between the posts, or a `StateTree` without the territory tasks. |
| Chases forever | `bLeashEnabled` off, or the leash anchor is `SELF` with `bTrackLeashAnchor` on. |
| The patrol is lost after a restart | The 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.

| Field | Does |
| --- | --- |
| `AbilityToGrant` | The gameplay ability the trees start (`GA_UCF_MontageAbility` plays the payload's montage) |
| `BehaviorTreeSequence` | The trees, in order |
| `BehaviorTreeTimeout` | Seconds before a tree is stopped |
| `PayloadKeyName` | Blackboard key the payload is written to, `UCF_Payload` |
| `Payload` | A `UUCFMontagePayload` (outer: the method), as for an ability method |

The plugin's tasks, which the editor's behavior tree palette lists:

| Task (class) | Does | Fields |
| --- | --- | --- |
| Move Until Distance (`UBTTask_MoveUntilDistance`) | Walks toward the blackboard target until within reach | `TargetDistance` (cm), `MaxChaseDistance`, `TimeoutSeconds`, `bAllowStrafe`, `bUsePathfinding`, `bAllowPartialPath` |
| Activate Action Ability (`UBTTask_ActivateActionAbility`) | Starts the ability the running action named and waits for it to end | `FallbackActivationTag`, `bFailWhenNoAbility` |
| Activate Ability (`UBTTask_ActivateAbility`) | Starts a named ability | `AbilityClass`, `ActivationMode` (`unreal.AbilityActivationMode.BY_TAG`, `BY_EVENT`), `EventTag` (shown as Activation Tag), `bGrantAbilityIfMissing` |
| Make Distance (`UBTTask_MakeDistance`) | Backs away from the target without pathfinding | `TargetDistance` (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:

```python
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:

| Task | Does |
| --- | --- |
| Build Decision Context | Gathers distance, angle, health and threat each tick |
| Poll Action, Do Action | Scores the actions and runs the chosen one |
| AI Movement | Runs the movement profile |
| Poll Combat Role, Poll Focus Actor, Poll Last Known Location | Read the role, the focus target, where the target was last seen |
| Sync Action Set, Sync Reaction Set, Sync Movement Profile, UpdateActionSet | Swap sets on a role change, or to a named Action Set |
| Territory Patrol, Territory Investigate, Return To Territory, Hold Out Of Combat, Monitor Combat Leash | Patrol, search, walk home, stand down, watch the leash |

| Condition | Passes when |
| --- | --- |
| Awareness State At Least | The 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 Is | Territory and leash state |
| Action Executing, Action Recovering, Actions Blocked, Reaction Executing, ASC Has Tag | Combat state |

##### Mistakes

| Symptom | Cause and fix |
| --- | --- |
| The action never ends | A tree waits forever: set `BehaviorTreeTimeout`, and check the ability reaches End Ability. |
| Activate Action Ability fails | `AbilityToGrant` is empty, so the enemy holds no ability to start. |
| Move Until Distance never arrives | No 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

| Field | Does |
| --- | --- |
| `TargetSelector` | How it picks a target (below). Empty picks the first registered target it may fight. |
| `TargetFilter` | Which 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). |
| `bIgnoreTargetRedistribution` | Keep its target when targets are shared out again. |
| `DefaultActionSet`, `RoleActionSets`; `DefaultReactionSet`, `RoleReactionSets`; `DefaultMovementProfile`, `RoleMovementProfiles` | What it fights, reacts and moves with, per role. |
| `AwarenessConfig`, `StimulusFilters` | What 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/`. |
| `DecisionContextParams` | `AggressionLevel` (0 to 2) and line-of-sight trace settings. |
| `ActionRecoveryTime`, `InterruptRecoveryTime`, `ActionRecoveryTimeRandomization` | Pause after each action (`AgentGuide/Enemy/Actions.md`). |
| `bDeterministic`, `DefaultSeed`, `StartBarrierSeconds` | The 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:**

```python
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).

```python
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

| Symptom | Cause and fix |
| --- | --- |
| Every enemy goes for the same player | No selector, or a First or Closest selector; use Balanced or Random inside the awareness filter. |
| A role is never assigned | `bAutoRegisterForCombatRoles` off, the role is outside `AllowedRoles`, or its limit is full. |
| Enemies fight each other | They share no team and are on different `TeamId`s, or `bFreeForAll` is on. |
| Two enemies attack at once despite the token gate | The 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.

```python
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:

```python
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

| Field | Default | Does |
| --- | --- | --- |
| `DesiredDistance` | 400 | Distance in cm the enemy keeps from its target |
| `DistanceTolerance` | 0.2 | How far past `DesiredDistance` still counts as close enough, as a share of it (0.05 to 0.5) |
| `CrowdTolerance` | 0.45 | How far inside `DesiredDistance` the enemy tolerates before stepping back, as a share of it |
| `bEnableStrafing` | true | Circle the target once at the distance |
| `StrafePreferenceWeight` | 1 | How strongly it prefers circling over standing |
| `bAutoStrafeSwap`, `StrafeSwapThreshold`, `StrafeSwapCooldown` | true, 3, 2 | Switch circling direction when the other side scores that many times better |
| `bEnableStrafeTimeLimit`, `StrafeTimeLimit`, `StrafeTimeLimitFluctuation` | true, 5, 2.5 | Switch direction after circling one way this long (seconds, plus or minus the fluctuation) |
| `bRestAfterStrafeSwap`, `StrafeSwapRestTime`, `StrafeSwapRestFluctuation` | false, 0.5, 0.25 | Pause after a timed switch |
| `bEnableStrafeRest`, `StrafeRestTimeLimit`, `StrafeRestDuration` | true, 10, 1.5 | Stop and rest after circling this long |
| `bAdjustDistanceByThreat`, `ThreatDistanceScale` | false, 1 | Multiply the distance by 1 + threat x scale; threat climbs from 0 to 1 while the player looks at the enemy |
| `bSwapStrafeOnHighThreat` | false | Switch circling direction once the player has stared long enough |
| `PositioningRules` | empty | Extra 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

| Symptom | Cause and fix |
| --- | --- |
| The enemy hugs the player | `DesiredDistance` below about 150, or the profile is not the config's `DefaultMovementProfile` while `bManageMovementProfilesAutomatically` is on (the default). |
| It jitters back and forth | `DistanceTolerance` too small for the distance; raise it toward 0.2. |
| It stays close after each attack | An 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 attacks | It 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 at | `bAdjustDistanceByThreat` off, or the controller has no Threat Detection component (the demo controller has one). |
| It changes direction constantly | `StrafeTimeLimit` short with `bAutoStrafeSwap` on; raise `StrafeSwapThreshold` or `StrafeTimeLimit`. |
| A role's profile is ignored | The 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:

  ```python
  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:**

  ```python
  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:

```python
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:

```python
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.**

| Stimulus | Arrives when |
| --- | --- |
| `UCF.Stimulus.DamageTaken` | The enemy takes a hit (the duplicated demo Blueprint reports it). |
| `UCF.Stimulus.AttackTelegraphed` | A swing near it is announced by a UCF Telegraph Window on the attacker's montage. |
| `UCF.Stimulus.StanceBroken` | The 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

| Field | Does |
| --- | --- |
| `RuleId` | Name in logs. |
| `OnStimulus` | The stimulus tag it answers. |
| `RequireContextTags`, `BlockContextTags` | Tags 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. |
| `Conditions` | Gates that must all pass (below). |
| `ReactionLinks` (`unreal.UCFReactionTriggerLink`) | `ReactionId`, `WeightMultiplier`. |
| `ReactionCategory` | Answer with any reaction of this category instead of named links. |
| `RulePriority` | Higher is asked first. |
| `Chance` | 0 to 1. |
| `MinInterval` | Seconds 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 when | Fields |
| --- | --- | --- |
| `UUCFGate_IncomingAngle` (Incoming Angle Gate) | The blow arrives inside an arc in front | `HalfAngleDegrees`, `bPassWithoutDirection`, `bInvert` (behind instead) |
| `UUCFGate_TimeToImpact` (Time To Impact Gate) | Enough time is left before an announced swing lands | `MinSeconds`, `MaxSeconds` |
| `UUCFGate_StimulusMagnitude` (Stimulus Magnitude Gate) | The blow is worth answering | `MinMagnitude`, `MaxMagnitude` |
| `UUCFGate_SourceDistance` (Source Distance Gate) | The attacker is in range | `MinDistance`, `MaxDistance` (cm), `bPassWithoutSource` |
| `UUCFHitsTakenGate` (Hits Taken Gate) | Enough blows got through lately, this one included | `Hits` (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

```python
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

| Symptom | Cause and fix |
| --- | --- |
| Never reacts | No trigger rule, or the rule's `ReactionLinks` name an ID no reaction has. |
| Never parries | The 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 combo | Raise the rule's `MinInterval` or the reaction's `Cooldown.Duration`. |
| Back hits play the front reaction | Both 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:**

```python
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 1` | Every overlay above each enemy: awareness, brain, action, role, team |
| `UCF.Debug.WatchPawn <name>` | Narrows the overlays to one enemy |
| `UCF.Debug.Scoring 1` | Each action's score, and why a gate refused it |
| `UCF.Debug.LogActionDecisions 1`, `UCF.Debug.LogActionExecution 1` | Each pick, and each action starting and ending |
| `UCF.Debug.LogReactions 1` | Each trigger rule firing or skipped, with the reason |
| `UCF.Debug.LogRoleAssignments 1` | Role assignments |
| `UCF.Debug.Melee.DrawTracing 1` | Every melee sweep |
| `UCF.Debug.Movement.DrawScoring 1`, `UCF.Debug.Movement.DrawAvoidance 1` | Movement direction scores and avoidance |
| `UCF.Debug.Threat.Draw 1` | The player's look cone and the threat level |
| `UCF.Debug.Stimulus.Draw 1` | Announced swings and who they reach |
| `UCF.Debug.Warp 1` | Where each motion warp lands |
| `UCF.Debug.AnimEffects 1` | Each footstep and other anim effect asked for, and what answered it |
| `UCF.Logs Verbose` | Raises 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

| Symptom | Cause and fix |
| --- | --- |
| Never dies | No `UCF.Vital.Health` row, or `bAutoHandleDeathOnHealthDepleted` off. |
| The stance never breaks | No stance row on the enemy, or the attacks' damage configs drain none. |
| The stance empties but no stun plays | Nothing reports `UCF.Stimulus.StanceBroken` (the On Vital Depleted step above), or the Reaction Set has no rule on it. |
| The fight never starts | The 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 restart | It 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) | Does | Fields |
| --- | --- | --- |
| `UUCFPredictedGameplayCueHitEffect` (UCF Play Gameplay Cues) | Plays cues on the attacker and the target | `AttackerCues`, `TargetCues`, `SurfaceSet` (`UUCFImpactSurfaceSet`: cue suffix per physical material or surface) |
| `UUCFPhysicsImpulseHitEffect` (UCF Apply Physics Impulse) | Shoves the struck body | `HitBoneForce`, `HitOverallForce`, `HitRotationalForce`, `bVelocityChange` |
| `UUCFApplyGameplayEffectHitEffect` (UCF Apply Gameplay Effect) | Applies a gameplay effect | `GameplayEffect`, `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:**

```python
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) | Does | Fields |
| --- | --- | --- |
| `UUCFDefenseRule_Guard` (UCF Guard) | Soaks a hit arriving inside an arc | `ArcHalfAngleDegrees`, `DamageMultiplier` (0 blocks all) |
| `UUCFDefenseRule_Scale` (UCF Scale Damage) | Scales a hit | `DamageMultiplier` |
| `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:**

```python
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

| Symptom | Cause and fix |
| --- | --- |
| Hits pass through | `SocketIDs` on the window differ from the `ID` of a `TraceSockets` row on the held item's Equippable fragment. |
| Enemies hit each other | The trace's `TeamFilter` is `NO_FILTER`; set `ENEMIES_ONLY`. |
| A stance or stamina drain does nothing | The target has no row for that vital. |
| The enemy never blocks | Nothing 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)`:

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

| Field | Holds |
| --- | --- |
| `NodeName` | The 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`, `Hooks` | Stamina 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) | Does | Fields |
| --- | --- | --- |
| `UUCFMontageActionPayload` (Play Montage) | Plays a montage | `Montage`, `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 animation | `bOpenActionWindow` (on: any input leaves at once) |
| `UUCFDelayActionPayload` (Delay) | Waits, then ends so its Action Completed transition fires | `DelaySeconds`, `bOpenActionWindow` |
| `UUCFAbilityEventActionPayload` (Trigger Ability / Event) | Sends a gameplay event to the character, or activates its abilities by tag | `Mode` (`SEND_EVENT`, `ACTIVATE_BY_TAG`), `EventTag`, `EventMagnitude`, `AbilityTags`, `bEndImmediately` |
| `UUCFPlayPairedActionPayload` (Play Paired Action) | Starts a synced two-body move | `AgentGuide/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`).

```python
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 label | Fires when |
| --- | --- | --- |
| `ON_STARTED` | Input Pressed | The input is pressed (combos) |
| `ON_COMPLETED` | Input Released | The input is released (letting go of a hold) |
| `ON_CANCELLED` | Input Released Early | The input is released before its Input Action's hold trigger finishes |
| `AUTO` | Action Completed | The move ended on its own; input tag `""` |
| `ON_FAILED` | Action Failed | The 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.

```python
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 when | Fields |
| --- | --- | --- |
| `UUCFTransitionCondition_Direction` (Direction) | The stick points one way at the press | `RequiredDirection` (`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 level | `VitalTag`, `Comparison`, `Threshold`, `Tolerance`, `bUseFraction` |
| `UUCFTransitionCondition_TargetState` (Target State) | The aimed-at enemy holds tags | `RequiredTags`, `BlockedTags`, `bRepickAtPress` |
| `UUCFTransitionCondition_TargetDistance` (Target Distance) | The aimed-at enemy is near or far | `Comparison`, `Distance` (cm), `Tolerance`, `bRepickAtPress` |
| `UUCFTransitionCondition_CooldownReady` (Cooldown Ready) | A cooldown has a charge | `CooldownTag` |
| `UUCFPairedActionCondition` (Paired Action Available) | A synced move would play now | `Actions` (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:

```python
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:

```python
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

| Symptom | Cause and fix |
| --- | --- |
| An edit has no effect in Play | The graph was not compiled after the edit; `describe_action_graph` says so on its first line. |
| The guard never ends | No `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 entry | A `Costs`, `Gates` or `Hooks` list holds `None`; make each object with `unreal.new_object`. |
| A directional move never plays | Its 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 shield | The 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 idle | Only `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) | Class | Fields |
| --- | --- | --- |
| UCF Melee Trace Window | `UUCFMeleeTraceNotifyState` | `SocketIDs`, `DamageConfig`, `ExtraDamageTags` |
| UCF Action Window | `UUCFActionWindowNotifyState` | none: where the next press may chain |
| UCF State Tag Window | `UUCFStateTagNotifyState` | `Tags`: `UCF.State.Intangible` (i-frames), `UCF.State.HyperArmor` (less poise damage), `UCF.State.Parrying`, `UCF.State.Dashing` |
| UCF Approach Window, UCF Approach Or Move Window | `UUCFApproachWindowNotifyState`, `UUCFApproachOrMoveWindowNotifyState` | `AgentGuide/Player/TargetingStylesSteering.md` |
| UCF Telegraph Window | `UUCFTelegraphMarkerNotifyState` | `AgentGuide/Player/CameraTelegraphs.md` |
| UCF Anim Effect Window | `UUCFAnimEffectWindowNotifyState` | `Effect` (`EffectTags`, `SocketName`): trails, glows, sounds |
| UCF Anim Effect (one frame) | `UUCFAnimEffectNotify` | `Effect`: footsteps, landings |
| UCF Gameplay Event (one frame) | `UUCFGameplayEventNotify` | `EventTag` |
| UCF Equipment Commit (one frame) | `UUCFEquipmentCommitNotify` | `BlendSeconds` |

##### 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 1` | Each 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 1` | Vitals, drawn items, targets, approach state |
| `UCF.Debug.Melee.DrawTracing 1` | Every melee sweep |
| `UCF.Debug.Steering.Draw 1` | Where attacks aim and stop |
| `UCF.Debug.Paired.Draw 1` | Paired action spots |
| `UCF.Debug.AnimEffects 1` | Each character's last anim effect requests and what answered them |
| `UCF.Logs Verbose` | Raises 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:

| Field | Does |
| --- | --- |
| `ArmLength` | Distance behind the character, cm |
| `SocketOffset` | Offset from the arm's end, cm; Y moves the camera over a shoulder |
| `FieldOfView` | Degrees |
| `PitchOffset` (label Camera Tilt) | Tilts the view without moving the aim |
| `PositionLagSpeed`, `RotationLagSpeed`, `SettingsBlendSpeed` | How quickly it follows and blends |
| `bFollowSoftTarget`, `SoftFollowSpeed`, `SoftFollowDeadzone`, `SoftFollowResumeDelay` | Turning 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

| Symptom | Cause and fix |
| --- | --- |
| A camera setting does nothing | The drawn item's Camera Rig fragment or the style's wins over `DefaultSettings`. |
| No marker shows | The viewer has no `StyleSet`, no row's tags match the announcement, or the window is on the player's own attack. |
| A shot jumps | Its 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) | Does | Fields |
| --- | --- | --- |
| `UUCFPredictedGameplayCueHitEffect` (UCF Play Gameplay Cues) | Cues on the attacker and the target | `AttackerCues`, `TargetCues`, `SurfaceSet`, `bAllowPredicted` |
| `UUCFPhysicsImpulseHitEffect` (UCF Apply Physics Impulse) | Shoves the struck body | `HitBoneForce`, `HitOverallForce`, `HitRotationalForce`, `bVelocityChange` |
| `UUCFApplyGameplayEffectHitEffect` (UCF Apply Gameplay Effect) | Applies a gameplay effect | `GameplayEffect`, `Level` |
| `UUCFHitStopEffect` (UCF Hit Stop) | Freezes the pose for a moment | `HoldSeconds` (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 answers | `EventTag` (`UCF.Event.Reaction`) |
| `UUCFRefillVitalHitEffect` (UCF Refill Vital) | Fills a pool to its maximum, such as broken poise | `VitalTag` (`UCF.Vital.Poise`) |
| `UUCFImpactSlowHitEffect` (UCF Impact Slow) | Slows the swing when it strikes the level or armor | `RelativeRate`, `Duration`, `RequireAnyTargetTags` |
| `UUCFPhysicalReactionHitEffect` (UCF Play Physical Reaction) | Moves the struck body's bones under physics | `ReactionName`, `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.

```python
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) | Does | Fields |
| --- | --- | --- |
| `UUCFDefenseRule_Guard` (UCF Guard) | Soaks a hit from inside an arc | `ArcHalfAngleDegrees` (60), `DamageMultiplier` (0.2), cost (`CostPerDamage` 1 when `CostVitalTag` is set) |
| `UUCFDefenseRule_Scale` (UCF Scale Damage) | Scales the hit and lets the next response run | `DamageMultiplier` |
| `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

| Symptom | Cause and fix |
| --- | --- |
| The guard blocks nothing | Nothing holds `UCF.State.Blocking`, the shield is not drawn, or the hit comes from outside `ArcHalfAngleDegrees`. |
| Every guarded hit is a parry | The parry window covers the whole guard montage; keep it to the first quarter second. |
| The parry never happens | The parry response is after the block in `Responses`, or the State Tag Window holds another tag. |
| The attacker never learns it was blocked | `ResultTag` 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

```python
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 in | Properties |
| --- | --- | --- |
| `UUCFActionCost_Vital` (Vital) | `Costs` | `VitalTag`, `Amount` |
| `UUCFActionCost_Attribute` (Attribute) | `Costs` | `Attribute` (a Gameplay Ability System attribute), `Amount` |
| `UUCFActionGate_Cooldown` (Cooldown) | `Gates` | `CooldownTag`, `Seconds`, `Charges` (uses it can bank), `EffectClass` (advanced) |
| `UUCFActionGate_Vital` (Vital) | `Gates` | `VitalTag`, `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) | `Gates` | `RequiredTags`, `BlockedTags`, `WhenClosed` (`unreal.UCFGateTagMode.SKIP` tries the next matching transition, `REFUSE` drops the press) |
| `UUCFActionHook_LocomotionModifier` (Locomotion Modifier) | `Hooks` | `WalkSpeedFactor`, `AccelerationFactor`, `RotationRateFactor` (0 freezes, 1 keeps) |
| `UUCFActionHook_CancelOnMovement` (Cancel On Movement) | `Hooks` | `ReadMode` (`INPUT_INTENT`, `SPEED`), `MovementThreshold` (0 to 1) |
| `UUCFActionHook_DrainVital` (Drain Vital) | `Hooks` | `VitalTag`, `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

| Symptom | Cause and fix |
| --- | --- |
| Attacks cost nothing | The 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 move | A 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 cooldown | Two gates share a `CooldownTag` with different `Seconds` or `Charges`. Make them agree or give one its own tag. |
| Sprint never drains | `StaminaVital` 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

```python
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:

```python
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

| Symptom | Cause and fix |
| --- | --- |
| A press does nothing | The 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-swing | `bInterruptsActionGraph` off, or a transition on the same tag in the graph takes the press first. |
| A new tag reads empty | It 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`:

```python
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.

```python
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:

```python
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`:

| Screen | Opens for | Shows |
| --- | --- | --- |
| `WBP_UCF_InventoryScreen_OpenWorldList` | `InventoryConfig_UCF_OpenWorldList`, any config with no row of its own, and an inventory with no config | A 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_SurvivalGrid` | `InventoryConfig_UCF_SurvivalGrid` | The case as a grid where items turn to fit, Key Items beside it |
| `WBP_UCF_InventoryScreen_PartyRPG` | `InventoryConfig_UCF_PartyRPG` | The 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:

```python
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:

```python
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):

```python
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:

```python
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.

```python
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.

```python
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.

```python
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.

```python
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:

```python
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:

```python
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

| Symptom | Cause and fix |
| --- | --- |
| A drop on an item merges or swaps the two instead of combining them | No 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 keychain | The 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 keychain | A 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 limit | The 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 limit | The 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 nothing | The 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 effect | The 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 nothing | The character has no UCF Equipment Manager (a warning names it), or another equipment change is running. |
| An item lands in no slot | The 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 style | That 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 key | The belt's slots have no `Filter`; give each slot an item kind, as the demo's diamond does. |
| I opens no inventory screen | The 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 style | The 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 nothing | The 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 pressed | No Server Only ability answers `UCF.Event.UseItem` on the character. |
| A screen's Drop does nothing | The character's ability set lacks `GA_UCF_DropFromScreen`, or the item has no World Item fragment. |
| The storage panel never shows at a box | The 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 stash | A 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 mesh | The item has no World Item fragment, or no Visuals mesh. |
| G does nothing | The held item has no World Item fragment, or the character's ability set lacks the drop ability. |
| The prompt never shows | The interactor's `Detection` or `DetectionRadius` misses the actor, or `RequireSight` is blocked. |
| A placed actor ignores Blueprint changes to its options | The 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 only | The chest's actor does not replicate; turn on Replicates in its Class Defaults (a warning names the class). |
| Take All or a transfer moves nothing | The 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) | Does | Fields |
| --- | --- | --- |
| `UUCFItemFragment_Equippable` (Equippable) | Makes it drawable | `ActionGraph`, `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 like | `HeldMesh` (label Mesh), `bOverridePerState`, `StowMesh`, `DropMesh` |
| `UUCFItemFragment_WornMesh` (Worn Mesh) | Skeletal meshes worn on the body while equipped, following its pose | `Meshes` |
| `UUCFItemFragment_Guard` (Guard) | Lends a defense rule set while drawn | `DefenseSet` (`AgentGuide/Player/DamageDefense.md`) |
| `UUCFItemFragment_Stowable` (Stowable) | Hangs on the body when put away | `StowPlaces`, `StowActorClass` |
| `UUCFItemFragment_WorldItem` (World Item) | Lies on the ground: dropped and picked up | `AgentGuide/Player/InventoryInteraction.md` |
| `UUCFItemFragment_SwingTrail` (Swing Trail) | A ribbon behind swings | `TrailSystem`, `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 belt | `MaxBeltCount` |

**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:

```python
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

```python
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`.

| Look | How |
| --- | --- |
| 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.

```python
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

| Symptom | Cause and fix |
| --- | --- |
| The shield replaces the sword | The shield has `bIsMainWeapon` on, or its hold place is `UCF.Place.Main`. |
| Putting on a helmet takes the sword's moves away | The helmet has `bIsMainWeapon` on; worn gear has it off and no `ActionGraph`. |
| A worn item is refused | The character's `BodyPlaces` has none of the item's hold places. |
| A cape or gloves stand in the reference pose or float | The worn mesh is rigged to another skeleton than the character's mesh tagged `UCF.Attachment`. |
| The item is invisible in the hand | No Visuals `HeldMesh` and no `ItemActorClass`, or the body place's socket is missing on the skeleton. |
| A Hold Places row is empty after a reload | It was set field by field; write it with `import_text`. |
| The item vanishes when put away | No 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 field | Does |
| --- | --- |
| `RoleId` | The 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`, `StartSection` | What this role plays |
| `Offset` | Where it stands relative to the shared anchor |
| `TravelMode` | How it gets to its spot |
| `bRequired` | The action fails without a body in this role |
| `RequiredActorTags`, `BlockedActorTags` | Who may fill it |
| `TagsDuringAction` | Tags held while it plays (`UCF.State.ActionsBlocked` from the start) |
| `Events` | What 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 |
| `Hooks` | Behavior riding the role: `UUCFPairedActionHook_AutoCinematicView` (`FocusRole`, `ViewAngle`, `HeightOffset`), `UUCFPairedActionHook_CameraShot` (`Shot`) |
| `bSyncWithCurrent`, `SyncMarker` | Start 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`.

```python
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

| Symptom | Cause and fix |
| --- | --- |
| The roles drift apart | Offsets not derived or set; run `DeriveOffsetsFromMontages` or set each `Offset`. |
| It plays on the wrong body | The option's `RequiredTargetTags` or `TargetTeams` are too loose. |
| The damage never lands | No Deal Damage event, or its `TimeSeconds` is past the action's end. |
| The victim survives the kill | A 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 again | The 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 fires | The 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 early | An 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 reload | `RoleId` was set with `set_editor_property`; build the participant with the `role_id` keyword. |
| A role skips its opening step | Its 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:

  ```python
  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:

  ```python
  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:

  ```python
  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:

  ```python
  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:

```python
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:

```python
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:

```python
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:

```python
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:

| Level | Set on |
| --- | --- |
| The move | `StopDistance` on its Play Montage node (`UUCFMontageActionPayload`) |
| A window, advanced | `StopDistanceOverride` on the UCF Approach Window or UCF Skew Warp playing at that moment |
| The weapon | `AttackStopDistance` on the drawn weapon's Equippable fragment |
| The style | `StopDistance` 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_CameraRig` | The lock-on camera and the rig (`AgentGuide/Player/CameraTelegraphs.md`) |
| `UUCFStyleFragment_Tags`, `UUCFStyleFragment_InputMapping` | Tags 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

| Symptom | Cause and fix |
| --- | --- |
| Attacks stop short of the target | The stop distance is longer than the attack's reach: lower the move's `StopDistance`, `StopDistanceOverride` or the item's `AttackStopDistance`. |
| Attacks play in place | No approach window on the montage, `SteeringMode` `OFF`, or no target (an Approach Or Move Window still steps). |
| Attacks slide through enemies | `KeepDistance` off on the UCF Attack Approach component. |
| A swing from contact reaches into the enemy | `MakeRoomSeconds` 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 teammates | `TargetTeams` changed from Enemies Only, or both sides share a team. |
| The lunge overshoots | The 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:

```python
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) |  |
| --- | --- |
| `ActionGraph` | Graph 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` |
| `bLockTarget` | Keeps every move aimed at the target the AI chose (default on) |
| `ComboTimeout` | Seconds 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.

```python
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:

```python
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

| Asset | Path |
| --- | --- |
| 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 weapon | `ActionSet_UCF_ComboEnemy`, `ActionSet_UCF_ComboEnemy_Sword`, `ActionSet_UCF_ComboEnemy_Unarmed` in the same folder |
| Its AI Config | `EnemyConfig_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 Set | `ActionSet_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

| Symptom | Cause and fix |
| --- | --- |
| The combo action runs and nothing plays | The 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 hits | The trace windows name socket IDs no `TraceSockets` row of the item the enemy holds carries. |
| An enemy never parries the player | The player's attack montage has no telegraph window, or its `Broadcast` has no shape. |
| The lock holds a dead enemy | The enemy is built on Enemy Character Base without a UCF Enemy Targetable component. |
| The execution never starts | The enemy does not hold `UCF.State.Staggered` when the press comes, or the press comes from outside the paired action's reach. |

---

Previous page: [One Core, Two Layers](https://rigbak.com/docs/universal-combat-framework/one-core). Next page: [Enemy Weapons](https://rigbak.com/docs/universal-combat-framework/enemy-weapons)
