The AI Action system controls what an NPC does at any given moment — chasing, attacking, fleeing, reloading, destroying obstacles, etc. You can configure an NPC's entire behavior by dragging Action assets in the Inspector, without writing any code.
The system consists of three parts:
| Component | Role |
|---|---|
| AIController | The decision engine, placed on the enemy prefab. It re-evaluates which Action to run at a fixed interval (default 0.25 seconds). |
| AIAction | A specific behavior, such as "move to target" or "melee attack". Each Action is a reusable asset file (ScriptableObject) that can be shared across different NPCs. |
| AIConsideration | A condition check, such as "is the target in range?" or "do I have a weapon?". An Action can only be selected when its conditions are met. |
Configuring an NPC's AI is a matter of arranging a set of Actions by priority on the AIController, and attaching the right Considerations to each one. The process is like building blocks — pick the behavior blocks, set the trigger conditions, and arrange them in priority order.
Their relationship looks like this:
AIController
└── Action List (ordered by priority)
├── Action 1 (highest priority)
│ └── Consideration A, B, C ← all must be met to execute
├── Action 2
│ └── Consideration D, E
└── Action 3 (lowest priority, fallback behavior)
└── (very loose conditions, almost always met)
The same Action asset can be reused across different NPCs (e.g. multiple zombie types can share the same MoveToTargetAction). At runtime, the system automatically creates an independent copy for each NPC, so they don't interfere with each other.
Each evaluation cycle (default every 0.25 seconds), the AIController checks the Action list from top to bottom:
Key rule: Actions higher in the Inspector list have higher priority. Place urgent behaviors (escape, pick up weapon) at the top, and fallback behaviors (move to target) at the bottom.
This means higher-priority Actions can interrupt lower-priority ones at any time. For example, a zombie that is walking toward its target will immediately switch to attacking once the target enters melee range and the attack Action's conditions are met. Conversely, if the target moves out of range and the attack conditions are no longer satisfied, the NPC automatically falls back to the lower-priority walking behavior.
| Action | Description |
|---|---|
| MoveToTargetAction | Pathfinds toward the target. Usually placed at the bottom of the list as the fallback behavior — when nothing more important needs to be done, just walk toward the target. |
| AttackAction | Automatically detects weapon type and attacks accordingly. With a ranged weapon: aims and shoots (configurable accuracy bias and arm strength). With a melee weapon: moves into range and slashes (configurable attack interval and distance). |
| AttackAction_Zombie | Zombie attack. Switch attack type via the attackType field: Melee (bare-handed punch), Explosive (self-destruct), IKFeet (foot stomp, for large zombies), GunRanged (fire a gun), Restraint (grab and hold the player). |
| ProjectileAttackAction_Zombie | Launches projectiles (e.g. acid spit) at the target. Predicts target movement direction — higher predictedTimeScale means more lead distance. |
| DashAttackAction_Zombie | Charge attack. Plays a roar animation, then rushes toward the target at boosted speed, dealing damage on collision. Used for mutants/bosses. |
| ClearObstacleAction_Zombie | Destroys obstacles blocking the path (buildings, walls, etc.). When pathfinding detects a detour, the NPC moves to the obstacle and destroys it using the configured attack type. demolishRadius controls the voxel destruction radius per hit. |
| EscapeAction | Flees from the target. Searches for a safe point away from the target and pathfinds there. Optionally enable recycleOnEscape to despawn the NPC once it is far enough away. |
| ReloadAction | Finds cover and reloads. Moves to a safe position out of the target's line of sight, then reloads the weapon once arrived. |
| MoveToItemNDPickAction | Moves to a nearby weapon and picks it up. Works together with ItemToPickCon, which is responsible for finding and locking onto the target weapon. |
| Consideration | Description |
|---|---|
| TargetInRangeCon | Checks whether the target is within (or beyond) a specified distance. Supports daytime visibility multiplier, extra tolerance while attacking, and overriding with weapon range. |
| DirectLineOfSightCon | Checks whether there is a clear line of sight to the target (no obstructions in between). |
| EmptyHandCon | Checks whether the NPC is unarmed (not holding any weapon). |
| AmmoCountCon | Checks whether the current weapon's ammo is above or below a specified amount. |
| WeaponTypeCon | Checks whether the held weapon is melee or ranged. |
| ItemToPickCon | Scans nearby for pickable weapons and selects the best one based on a priority list. Once found, it sets the weapon as the target for MoveToItemNDPickAction. |
| ArmBreakCon | Checks whether a specified arm is broken. |
| CrippledCon | Checks whether the NPC is crippled (body part disabled). |
| DetourDistanceCon | Compares pathfinding distance to straight-line distance — a large difference indicates an obstacle in the way. Used to trigger obstacle-clearing behavior. |
| ObstacleInTheWayCon | Scans pathfinding nodes to detect destructible buildings blocking the path. |
| IsOnVehicleCon | Checks whether the NPC is on a vehicle. |
| InjuryCon | Checks whether specified body parts are injured. |
Priority from top (highest) to bottom (lowest):
| # | Action | Purpose | Trigger Conditions |
|---|---|---|---|
| 1 | ClearObstacleAction_Zombie | Destroy blocking obstacles | Path blocked by building (DetourDistanceCon / ObstacleInTheWayCon) |
| 2 | AttackAction_Zombie (Melee) | Melee attack | Target within melee range (TargetInRangeCon) |
| 3 | MoveToTargetAction | Walk toward target | Fallback behavior |
Logic: Wall in the way → smash it. Target in range → attack. Otherwise → walk toward target.
Priority from top to bottom:
| # | Action | Purpose | Trigger Conditions |
|---|---|---|---|
| 1 | MoveToItemNDPickAction | Pick up weapon | Unarmed + weapon nearby (EmptyHandCon + ItemToPickCon) |
| 2 | EscapeAction | Flee the battlefield | Situation-dependent |
| 3 | ReloadAction | Find cover and reload | Ammo is zero (AmmoCountCon) |
| 4 | ClearObstacleAction | Destroy path obstacles | Path blocked (ObstacleInTheWayCon) |
| 5 | EscapeAction (keep distance variant) | Maintain distance | Target too close (TargetInRangeCon) |
| 6 | AttackAction (Ranged) | Shoot | Holding ranged weapon + target in range + has ammo |
| 7 | AttackAction (Melee) | Melee attack | Holding melee weapon + target in melee range |
| 8 | MoveToTargetAction | Walk toward target | Fallback behavior |
Logic: Top priority is to arm itself. Then handle escape and reload. Mid-priority covers obstacle clearing and distance keeping. Attack when armed and in range. If nothing else applies, walk toward the target.
And — all conditions must be met. Use Or when any single condition should activate the behavior.