# Core Architecture

> The map of the plugin: which piece lives where, what decides, what replicates, and the console switch that shows each part running.

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

> An enemy is three things: a config asset, an AI controller that decides, and a pawn that acts. Everything else in the enemy layer plugs into one of the three.

## Config, controller, pawn

**Architecture** (Content > Plugins > UniversalCombatFramework)

Enemy AI Config: what this enemy is

- Which action set, reaction set and movement profile it uses
- Which combat roles it will take, and how it picks a target
- Which State Tree runs it, when one does
- What it can sense, and how long it waits between attacks

AI Controller: it decides

- Reads the config the moment it possesses the pawn
- Scores the moveset and picks the move
- Picks where to stand and which way to travel
- Runs on the server, and nothing here replicates

Pawn: it acts

- Plays the ability the chosen action names
- Traces the swing, and answers an incoming hit
- Carries health, stamina and any other pool
- Replicates what a client needs for UI

*The controller resolves the config when it possesses the pawn, then decides for it. Clients see the pawn.*

Swap the config and the enemy changes without either Blueprint being touched.

> **Warning**
>
> None of it starts until an enemy has a combat target. Call **Register Combat Target** with your player pawn once, on the server, and the loop runs. An enemy with its own perception reads from that same pool, so skipping the call leaves a fully configured enemy standing still with nothing in the log. See [Targeting](https://rigbak.com/docs/universal-combat-framework/enemy/targeting-system).

---

## The pieces

**Enemy Character Base** and **Enemy Controller Base** ship with everything below already on them, so a new enemy starts complete. [Step-by-Step Enemy](https://rigbak.com/docs/universal-combat-framework/enemy/step-by-step-enemy) builds one from those two.

### On the AI controller

Server side. This half decides and replicates nothing.

| Component | What it does |
| --- | --- |
| **UCF Combat Controller** | The hub. Resolves the config at possession, registers for a combat role, syncs the sets when the role changes, and runs the death shutdown. |
| **UCF Brain** | Runs the enemy: a State Tree when the config names one, the built-in loop when it does not. |
| **Action Evaluation** | Scores the [moveset](https://rigbak.com/docs/universal-combat-framework/enemy/action-system) and runs the winner. |
| **Reaction Evaluation** | Picks a [reaction](https://rigbak.com/docs/universal-combat-framework/enemy/reaction-system) when something happens to the enemy. |
| **Movement Evaluator** | Chooses [where to stand and which way to move](https://rigbak.com/docs/universal-combat-framework/enemy/movement-system). |
| **UCF Awareness** | [Sight, hearing and damage memory](https://rigbak.com/docs/universal-combat-framework/enemy/awareness-system), and the last-known location behind an investigation. Senses nothing until the config names an **Awareness Config**. |
| **Threat Detection** | How long the [player's camera](https://rigbak.com/docs/universal-combat-framework/enemy/threat-detection) has held this enemy, as a 0 to 1 level. Switched off on the shipped controller. |

### On the pawn

This half acts, and it is the half a client sees.

| Component | What it does |
| --- | --- |
| **Ability System Component** | Runs the abilities that actions and reactions start. |
| **UCF Action Set Component** | Holds the moveset and replicates which action is running. |
| **UCF Reaction Set Component** | The same for [reactions](https://rigbak.com/docs/universal-combat-framework/enemy/reaction-system). |
| **UCF Combat Role** | Replicates the assigned [combat role](https://rigbak.com/docs/universal-combat-framework/enemy/combat-roles), so a client can tint or badge the enemy. |
| **UCF Vitals** | [Health, stamina and any other pool](https://rigbak.com/docs/universal-combat-framework/vitals). An emptied health pool is what triggers death. |
| **UCF Defense** | How an incoming hit is [answered](https://rigbak.com/docs/universal-combat-framework/defense): parry, block, invulnerability, resistances. Ships with no responses. |
| **UCF Melee Trace** | Swept [hit detection](https://rigbak.com/docs/universal-combat-framework/melee-trace-and-damage) across an attack window in the montage. |
| **UCF Equipment Manager** and **UCF Enemy Loadout** | On **UCF Enemy Character Base**: hold the player's [items](https://rigbak.com/docs/universal-combat-framework/enemy-weapons). A held item can bring its own moveset. |
| **UCF Approach** | Turns the pawn toward its target and glides it into range across an [approach window](https://rigbak.com/docs/universal-combat-framework/animation-integration) on the montage. |
| **UCF Territory** | The ground this enemy owns: [posts, a wander patch, a leash](https://rigbak.com/docs/universal-combat-framework/enemy/territory). Answers nothing until posts are named, the leash is switched on, or **Resting Behavior** is set to **Hold Ground**. |
| **UCF Team** | Team ID, free-for-all, and target exclusions. |

**UCF Combat Controller** is the one piece a setup cannot go without. The rest arrive inherited from the two base classes, and a Blueprint child cannot remove an inherited component, so an enemy that needs less leaves the extras unconfigured or switches them off: an empty **Awareness Config** leaves an enemy that fights whatever it is handed, and **Threat Detection** ships switched off already. To carry a shorter list, start from your own controller class, covered under **Run the AI on your own controller** below.

<details>
<summary>Which half runs on a client (Multiplayer)</summary>

Everything on the AI controller is server-only: scoring, movement, perception, role assignment. A client runs none of it and needs none of it.

Four pawn components replicate what a client needs to draw UI and effects:

| Component | Replicates |
| --- | --- |
| **UCF Action Set Component** | The action set in force, the running action's ID, and whether an action is executing. |
| **UCF Reaction Set Component** | The same three for reactions. |
| **UCF Combat Role** | The assigned role tag. |
| **UCF Vitals** | Each authored pool's current value. |

Bind the delegates on those four rather than polling the controller, which a client cannot reach. [Multiplayer](https://rigbak.com/docs/universal-combat-framework/enemy/multiplayer) covers the setup, including the dedicated-server animation fix that keeps melee sockets in the right place.

</details>

---

## What runs the enemy

**UCF Brain** reads the config when the controller takes its pawn, and picks one of two paths.

- **Default State Tree** filled in: the brain builds that State Tree and runs it. Reach for this when the enemy needs graph-authored structure, such as boss phases. See [StateTree Tasks](https://rigbak.com/docs/universal-combat-framework/enemy/statetree).
- **Default State Tree** empty: the brain runs its built-in loop. Each pass gathers the fight (distance, angle, health, threat), moves the enemy, then scores the moveset and runs the winner.

Scoring, movement and reactions are the same components on both paths, so a State Tree adds structure on top rather than replacing anything.

**Architecture** (Content > Plugins > UniversalCombatFramework)

- **UCF Brain** (reads the AI Config on possession)

Default State Tree set, or empty

- **StateTree** (graph-authored)

* **Built-in loop** (no StateTree needed)

either path drives the combat loop

- **Action Evaluation** (scores actions through scorers and gates)

executes the chosen action as

- **Behavior Tree** (multi-step sequences)

* **Gameplay Ability** (single GAS action)

*One brain, chosen from the config. A StateTree adds graph structure; the built-in loop runs the same combat cycle without one.*

### Between fights, on the built-in loop

The built-in loop reads what the enemy knows and settles into one of four phases.

| Phase | The enemy |
| --- | --- |
| **Idle** | Knows of nobody and owns no ground, so it stays where it is. |
| **Resting** | Knows of nobody and owns ground, so it walks its posts or holds its one spot. |
| **Investigate** | Noticed something it cannot confirm, so it walks over and looks. It does not attack. |
| **Combat** | Has a confirmed target, so it scores and runs its actions. |

Setting **Awareness Config** on the Enemy AI Config is what unlocks Investigate, since an enemy that senses nothing never reaches Suspicious. Owning ground unlocks Resting, which comes from a post on **UCF Territory**, or from **Resting Behavior** set to **Hold Ground**, where the enemy takes the spot it starts on. Without either, the enemy sits in Idle until it is handed a target and jumps straight to Combat.

**On Brain Phase Changed** fires on each move between them, which is where an idle, alert or fighting animation set hangs off. A State Tree authors its own states instead, so this reads Idle while one is running.

---

## Debug it

One overlay covers the whole map, with a section per system. Turn the lot on, then narrow it to one enemy:

```
UCF.Debug.All 1                 // Every section at once; 0 turns them all off
UCF.Debug.WatchPawn Grunt_2     // Only this pawn draws, and it shows every section
```

Run `UCF.Debug.WatchPawn` with no argument to list the pawns the overlay has something to say about. Part of a name is enough, and running it again on a watched pawn stops watching it. `UCF.Debug.WatchClear` stops watching every pawn in the level and puts them all back under the section switches.

Twelve sections are registered:

| Switch | Draws above the pawn |
| --- | --- |
| `UCF.Debug.Role` | Name and combat role, colored by role. Reads on a client as well. |
| `UCF.Debug.Decision` | Distance and angle to the target, whether it can see it, its speed, and the threat on it. |
| `UCF.Debug.Awareness` | Awareness state, how far the meter has filled toward Detected, how old the last-known location is. |
| `UCF.Debug.Scoring` | What the last poll scored, highest first, with the reason a refused action gives instead of a score. |
| `UCF.Debug.EnemyActions` | The action list with cooldowns: green ready, gray counting down, yellow running. |
| `UCF.Debug.Reactions` | The reaction list with priorities and cooldowns, colored the same way. |
| `UCF.Debug.Movement` | The movement layer, whether it is strafing and to which side, and its heading. |
| `UCF.Debug.Territory` | What territory is doing, the post it is heading to, and how far the leash is from breaking. |
| `UCF.Debug.Tokens` | The permission slots a target hands out, drawn above the target. |
| `UCF.Debug.Vitals` | Every pool the pawn carries, one line each, as a value against its maximum. |
| `UCF.Debug.Teams` | The team the pawn fights for: its ID, Free-For-All when it is on, and what its exclusions turn aside. |
| `UCF.Debug.Approach` | How far the approach window still has to travel and whether it is gliding, plus the steering drawn in the level. |

`UCF.Debug.MaxDistance` (4000 cm) sets how far from the camera a pawn still draws, and `UCF.Debug.TextScale` (1.0) sizes the text.

> **Note**
>
> Role, Actions, Reactions, Vitals and Teams replicate, so those five read on a client. The rest are worked out on the server and draw only there. Approach draws wherever the character is steered, which is the server or a listen-server host for an enemy.

<details>
<summary>Turn a section on for one enemy, from the Details panel (Advanced)</summary>

Each section has a matching checkbox on the component it reads, so one enemy can draw without the console and without a restart:

| Section | Checkbox |
| --- | --- |
| Role | **Debug Overlay Role** on the pawn's **UCF Combat Role** |
| Decision | **Debug Overlay Decision** on the controller's **UCF Combat Controller** |
| Awareness | **Debug Overlay Awareness** on the controller's **UCF Awareness** |
| Scoring | **Debug Overlay Scoring** on the controller's **Action Evaluation** |
| Actions | **Debug Overlay Actions** on the pawn's **UCF Action Set Component** |
| Reactions | **Debug Overlay Reactions** on the pawn's **UCF Reaction Set Component** |
| Movement | **Debug Overlay Movement** on the controller's **Movement Evaluator** |
| Territory | **Debug Overlay Territory** on the pawn's **UCF Territory** |
| Tokens | **Debug Overlay Tokens** on the target's **UCF Token Budget Component** |
| Vitals | **Debug Overlay Vitals** on the pawn's **UCF Vitals** |
| Teams | **Debug Overlay Teams** on the pawn's **UCF Team** |
| Approach | **Debug Overlay Approach** on the pawn's **UCF Approach** |

A ticked checkbox saves with the Blueprint, so it survives a restart.

</details>

---

## Going further

<details>
<summary>When an enemy dies (Advanced)</summary>

**Handle Death** on **UCF Combat Controller** runs the whole shutdown in order: blocks new actions, cancels the action and reaction in flight, stops the brain, stops the melee trace, switches threat detection and perception off, clears the movement state, and gives up the combat role slot so a living enemy can take it. **On Death** fires last, at which point the pawn is safe to ragdoll.

**Auto Handle Death on Health Depleted** is ticked on the component, so an emptied health vital runs all of that on its own. Untick it when the project owns death and calls **Handle Death** itself. Which vital counts as health is set in **Project Settings** under **Universal Combat Framework Enemy**.

**Drop Weapon on Death** is ticked too, so the enemy's **UCF Enemy Loadout** drops each item it holds but its Default Item as an item a player can pick up. See [Enemy Weapons](https://rigbak.com/docs/universal-combat-framework/enemy-weapons#what-it-drops-when-it-dies).

**Handle Revive** puts a dead enemy back under AI control: it releases the action block, restarts the brain, and switches threat detection, perception and role registration back on. It does not hand the enemy its items back, so call **Equip Item** on the pawn's Equipment Manager as well. Use it for a resurrect, or when a pooled enemy is reused.

</details>

<details>
<summary>Run the AI on your own controller (Alternative)</summary>

`EnemyControllerBase` is a convenience wrapper. To keep your own AI controller class instead:

1. Add **UCF Combat Controller** to the AI controller Blueprint.
2. Set **Default AI Config** on it, or leave it empty and let the pawn hand over its own.
3. Add the ones that enemy needs: **UCF Brain**, **Movement Evaluator**, **Action Evaluation**, **Reaction Evaluation**, **UCF Awareness**, **Threat Detection**.

Everything wires itself on possession. What the wrapper adds on top is smooth focus rotation with a rotation lock, team answers routed to the pawn's **UCF Team**, threat-to-movement wiring, and the combat events forwarded as Blueprint events.

The pawn side has the same escape hatch: reparent your character to `EnemyCharacterBase`, or add the components you want to your own character. [Getting Started](https://rigbak.com/docs/universal-combat-framework/getting-started) covers both.

</details>

<details>
<summary>What you still build (Advanced)</summary>

The enemy layer covers the enemy and the fight. Three things stay yours:

- **UI and HUD.** Enemy health bars and damage numbers. The replicated pawn components carry the data; the widgets are your call. Lock-on, button prompts and a HUD widget that follows the ability system come with the player layer.
- **Level design and encounter placement.** Where enemies stand, what triggers a fight, how an arena is shaped.
- **Progression and balance.** Difficulty curves, loot, stat growth.

</details>

Previous page: [StateTree Integration](https://rigbak.com/docs/universal-combat-framework/enemy/statetree). Next page: [Determinism](https://rigbak.com/docs/universal-combat-framework/enemy/determinism)
