Core Architecture
Documentation Unreal Engine AI Architecture
The map of the plugin: which piece lives where, what decides, what replicates, and the console switch that shows each part running.
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.
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.
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 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 and runs the winner. |
| Reaction Evaluation | Picks a reaction when something happens to the enemy. |
| Movement Evaluator | Chooses where to stand and which way to move. |
| SEC Awareness | Sight, hearing and damage memory, 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 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. |
| SEC Combat Role | Replicates the assigned combat role, so a client can tint or badge the enemy. |
| SEC Vitals | Health, stamina and any other pool. An emptied health pool is what triggers death. |
| SEC Defense | How an incoming hit is answered: parry, block, invulnerability, resistances. Ships with no responses. |
| SEC Melee Trace | Swept hit detection across an attack window in the montage. |
| SEC Equipment Component | Spawns and holds 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 on the montage. |
| SEC Territory | The ground this enemy owns: posts, a wander patch, a leash. 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.
MultiplayerWhich half runs on a client
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 covers the setup, including the dedicated-server animation fix that keeps melee sockets in the right place.
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.
- 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, coloured 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, grey counting down, yellow running. |
SEC.Debug.Reactions | The reaction list with priorities and cooldowns, coloured 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.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.
AdvancedTurn a section on for one enemy, from the Details panel
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.
Going further
AdvancedWhen an enemy dies
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 drops the held weapon with a ten-second physics lifespan.
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.
AlternativeRun the AI on your own controller
EnemyControllerBase is a convenience wrapper. To keep your own AI controller class instead:- Add SEC Combat Controller to the AI controller Blueprint.
- Set Default AI Config on it, or leave it empty and let the pawn hand over its own.
- 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 covers both.AlternativeUse the combat parts without the AI
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.AdvancedThree runtime modules
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.
AdvancedWhat you still build
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.