# 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/soulslike-combat/architecture, a page of the Soulslike Enemy Combat 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 plugin plugs into one of the three.

## Config, controller, pawn

**Architecture** (Content > Plugins > SoulslikeEnemyCombat)

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/soulslike-combat/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/soulslike-combat/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 |
| --- | --- |
| **SEC 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. |
| **SEC 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/soulslike-combat/action-system) and runs the winner. |
| **Reaction Evaluation** | Picks a [reaction](https://rigbak.com/docs/soulslike-combat/reaction-system) when something happens to the enemy. |
| **Movement Evaluator** | Chooses [where to stand and which way to move](https://rigbak.com/docs/soulslike-combat/movement-system). |
| **SEC Awareness** | [Sight, hearing and damage memory](https://rigbak.com/docs/soulslike-combat/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/soulslike-combat/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. |
| **SEC Action Set Component** | Holds the moveset and replicates which action is running. |
| **SEC Reaction Set Component** | The same for [reactions](https://rigbak.com/docs/soulslike-combat/reaction-system). |
| **SEC Combat Role** | Replicates the assigned [combat role](https://rigbak.com/docs/soulslike-combat/combat-roles), so a client can tint or badge the enemy. |
| **SEC Vitals** | [Health, stamina and any other pool](https://rigbak.com/docs/soulslike-combat/vitals). An emptied health pool is what triggers death. |
| **SEC Defense** | How an incoming hit is [answered](https://rigbak.com/docs/soulslike-combat/defense-system): parry, block, invulnerability, resistances. Ships with no responses. |
| **SEC Melee Trace** | Swept [hit detection](https://rigbak.com/docs/soulslike-combat/melee-trace) across an attack window in the montage. |
| **SEC Equipment Component** | Spawns and holds [weapons](https://rigbak.com/docs/soulslike-combat/weapons). A held weapon can bring its own moveset. |
| **SEC Approach** | Turns the pawn toward its target and glides it into range across an [approach window](https://rigbak.com/docs/soulslike-combat/animation-integration) on the montage. |
| **SEC Territory** | The ground this enemy owns: [posts, a wander patch, a leash](https://rigbak.com/docs/soulslike-combat/territory). Answers nothing until posts are named, the leash is switched on, or **Resting Behavior** is set to **Hold Ground**. |
| **SEC Team** | Team ID, free-for-all, and target exclusions. |

**SEC 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 |
| --- | --- |
| **SEC Action Set Component** | The action set in force, the running action's ID, and whether an action is executing. |
| **SEC Reaction Set Component** | The same three for reactions. |
| **SEC Combat Role** | The assigned role tag. |
| **SEC 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/soulslike-combat/multiplayer) covers the setup, including the dedicated-server animation fix that keeps melee sockets in the right place.

</details>

---

## What runs the enemy

**SEC 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/soulslike-combat/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 > SoulslikeEnemyCombat)

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

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

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

`SEC.Debug.MaxDistance` (4000 cm) sets how far from the camera a pawn still draws, and `SEC.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 **SEC Combat Role** |
| Decision | **Debug Overlay Decision** on the controller's **SEC Combat Controller** |
| Awareness | **Debug Overlay Awareness** on the controller's **SEC Awareness** |
| Scoring | **Debug Overlay Scoring** on the controller's **Action Evaluation** |
| Actions | **Debug Overlay Actions** on the pawn's **SEC Action Set Component** |
| Reactions | **Debug Overlay Reactions** on the pawn's **SEC Reaction Set Component** |
| Movement | **Debug Overlay Movement** on the controller's **Movement Evaluator** |
| Territory | **Debug Overlay Territory** on the pawn's **SEC Territory** |
| Tokens | **Debug Overlay Tokens** on the target's **SEC Token Budget Component** |
| Vitals | **Debug Overlay Vitals** on the pawn's **SEC Vitals** |
| Teams | **Debug Overlay Teams** on the pawn's **SEC Team** |
| Approach | **Debug Overlay Approach** on the pawn's **SEC 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 **SEC 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, releases equipment, 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 **Soulslike Enemy Combat**.

**Drop Weapon on Death** is ticked too, which asks the held weapon to drop itself and stay for **Drop Lifetime** seconds, set on the pawn's **SEC Equipment Component**. At its default of 0 the weapon stays for good. See [Weapons](https://rigbak.com/docs/soulslike-combat/weapons#swapping-and-dropping).

**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 re-arm the enemy, so call **Equip Starting Loadout** on the pawn's **SEC Equipment Component** 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 **SEC 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: **SEC Brain**, **Movement Evaluator**, **Action Evaluation**, **Reaction Evaluation**, **SEC 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 **SEC 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/soulslike-combat/getting-started) covers both.

</details>

<details>
<summary>Use the combat parts without the AI (Alternative)</summary>

The pawn-side combat layer stands on its own, so a player character can take the same components with no AI attached:

- **SEC Melee Trace** for swept hit detection off a montage window.
- **SEC Vitals** for health, stamina and stance pools.
- **SEC Defense** for parries, blocks, invulnerability windows and resistances.
- **SEC Team** so friendly fire and target exclusions answer the same way on both sides.

`BP_SEC_PlayerCharacter` in the showcase carries the first three and takes its hits through them, with no AI controller, config asset or combat role anywhere near it.

</details>

<details>
<summary>Three runtime modules (Advanced)</summary>

The plugin ships as three runtime modules and one editor module.

| Module | Holds |
| --- | --- |
| **SECCore** | The combat layer that stands on its own: melee trace and its montage window, damage and hit effects, vitals, defense, team, the animation tag and effect windows, and the debug overlay. |
| **SECMotion** | What moves a character: the approach component, its montage window, and the SEC Skew Warp modifier. The module that carries the approach and warp types. |
| **SoulslikeEnemyCombat** | The AI on top of both. |
| **SECEditor** | The Action Set and Reaction Set canvases and the movement profile diagram. Editor only, and left out of a packaged build. |

Blueprint names and node paths do not change with the split. It matters when a C++ module of your own declares a dependency, since it needs the module holding the type it uses.

</details>

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

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

- **UI and HUD.** Health bars, lock-on markers, damage numbers. The replicated pawn components carry the data; the widgets are your call.
- **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/soulslike-combat/statetree). Next page: [Patterns & Examples](https://rigbak.com/docs/soulslike-combat/patterns)