AI System

Purpose and Scope

The AI System in RPG Engine v6 defines how NPCs and enemies perceive the world, make decisions, and execute melee and ranged combat behaviors on top of the shared modular character framework.

This document targets gameplay programmers and technical designers and focuses on runtime behavior, core AI classes and data assets, and how AI integrates with perception, combat, quests/trading, MassAI, and the save system. Detailed Behavior Tree graphs and editor wiring are intentionally left to How‑To and Reference docs.

High-Level Architecture

At a high level, the AI System is organized around three layers.

AI character classes – BP_RPG_AI is the base class for AI characters (friends and enemies), with concrete melee/ranged variants like BP_RPG_AI_Ranged_Master, BP_RPG_AI_CC_Master, and clone AIs for scripted or special encounters.
AI logic components and data – BP_AI_Component on each AI pawn drives runtime behavior and reads configuration from AI Data assets (BP_AI_Base, BP_CC_AI_Data, BP_Ranged_AI_Data) plus experience and name settings.
Controllers and behavior assets – AI Controllers with AIPerception (Sight, Hearing, Damage, Prediction) plus Behavior Trees and Blackboards implement perception, state changes, and decision-making; attack tokens are coordinated with the player via BP_ModulesMediator and BP_PlayerComponent.

AI reuses the same character modules as the player where possible: movement, stats, firearms, melee, abilities, buffs, and effects. Differences between AI types are defined through blueprint classes, data assets, controllers, and behavior assets rather than fully separate gameplay systems.

Core AI Classes

BP_RPG_AI

BP_RPG_AI is the main base class for all AI characters in the project.

Supports two logical AI factions: friends and enemies.
Inherits from the same common character foundation as the player.
Always uses BP_AI_Component to drive AI-specific behavior.
Serves as the parent for all concrete AI blueprint classes, including active bots, dummy bots, melee enemies, ranged enemies, and clone variants.

BP_Bot_Active

BP_Bot_Active is the active AI bot class.

These bots move through the level.
They interact with the player.
They participate in perception, combat, navigation, and regular runtime AI behavior.

BP_RPG_AI_Dummy

BP_RPG_AI_Dummy is a non-moving AI class.

It is used to introduce the player to the project.
It does not perform regular movement behavior.
It is primarily a showcase/training bot rather than a combat AI.

Ranged AI family

Firearms AI is built on BP_RPG_AI_Ranged_Master.

Difficulty-based children:

BP_AI_Ranged_Easy
BP_AI_Ranged_Easy_NoLoot
BP_AI_Ranged_Medium
BP_AI_Ranged_Medium_NoLoot

The NoLoot variants differ only in post-death loot spawning behavior. Core ranged combat logic remains shared through the same AI family and firearms systems.

Melee AI family

Melee AI is built on BP_RPG_AI_CC_Master.

Difficulty-based children:

BP_AI_CC_Easy
BP_AI_CC_Easy_NoLoot
BP_AI_CC_Medium
BP_AI_CC_Medium_NoLoot
BP_AI_CC_Hard_NoLoot

These classes use the shared melee combat pipeline, while difficulty and defensive behavior are tuned through AI data assets.

Clone AI family

Special clone AI is built on BP_RPG_AI_Clone_Master.

Melee clone variants:

BP_AI_Clone_Unarmed_Easy
BP_AI_Clone_SWS_Medium – sword and shield

Ranged clone variants:

BP_AI_Clone_Ranged_Easy
BP_AI_Clone_Ranged_Medium

Clone AI uses the same general AI infrastructure while allowing special encounter setups or scripted enemy variants.

BP_AI_Component

BP_AI_Component is present on all AI characters and acts as the central runtime controller for AI logic.

Unlike the player, every AI pawn uses this component as the main entry point for AI behavior, tuning, and communication with other gameplay systems.

Main parameters

BP_AI_Component exposes the following main configuration fields:

Settings Dataset AI – AI settings Data Asset.
Behavior Tree – Behavior Tree assigned to this AI.
AI Type – enum with values Melee, Ranged, NPC.
Random Name – array of name; used as the source list for random names.
Use Random Name – bool; if true, AI gets a random name from Random Name.
Name – text; used when Use Random Name is false.

Experience configuration

The component also references a Data Asset BP_DA_ExperienceSystem.

Important field:

Experience Points For Killing (integer) – how many experience points the player receives for killing this AI.

Runtime responsibilities

At runtime, BP_AI_Component:

reads the assigned AI Data asset,
initializes behavior-related settings,
works together with the AI Controller and Behavior Tree,
participates in attack token logic,
passes state requests through BP_ModulesMediator,
acts as the central AI-specific logic layer for the pawn.

AI Data Assets

AI behavior is configured through a hierarchy of AI Data blueprints.

BP_AI_Base

BP_AI_Base inherits from BP_Common_AI_Data_C and implements BPI_DataAI_C.

This blueprint stores generic AI behavior settings shared across different AI types.

Core parameters

Startup State (E_AI_States) – initial AI state, for example idle, patrol, aggressive, or similar runtime modes.
Hardness (E_AI_Hardness) – difficulty tier of the AI.
Attack Radius (float) – distance at which AI is allowed to attack its target.
Time To Seek After Loose Sight (float) – how long AI keeps searching after losing line of sight.
Predicate Target Location After Loose Sight (float) – parameter related to the last known target location after sight is lost.
Chance Dodge Sudden Attack (float) – chance to dodge a sudden incoming attack.

Skills and special actions

HealAroundSkill (bool) – whether AI can use area healing.
HealAroundChance (float) – chance to use area healing.
HealAroundReloadTime (float) – cooldown between heal uses.
TelekinesisPushSkill (bool) – whether AI can use telekinetic push.
TelekinesisPushChance (float) – chance to use telekinetic push.
TelekinesisPushTime (float) – timing or duration parameter for telekinetic push.
Blow Yourself Up (bool) – whether AI can self-destruct.
Blow Yourself Up Chance (float) – chance to self-destruct.
Blow Yourself Up Radius (float) – self-destruction explosion radius.
Blow Yourself Up Damage (float) – damage dealt by self-destruction.
Blow Yourself Up Damage Type (DamageType) – damage type used for the explosion.

Movement and combat tuning

Move Back By Chances (E_MoveType) – backward movement behavior selected through probability rules.
Move Side By Chances (E_MoveType) – side movement behavior selected through probability rules.
DamageMultiplier (float) – outgoing damage multiplier for the AI.

Detection and ignore rules

IgnoreList (EActorType) – actor types ignored by the AI.
DetectList (EActorType) – actor types the AI can detect.
Blow Yourself Up Ignore List (EActorType) – actor types ignored by the self-destruction explosion.

This asset defines the general behavioral profile of an AI: how aggressive it is, what it can detect, what it ignores, and which special skills it may use.

BP_CC_AI_Data

BP_CC_AI_Data extends the base AI data with melee and defensive behavior settings.

Important fields:

Defence Radius (float) – radius within which AI can enter defensive behavior.
Defence State Chance While Moving (float) – chance to switch into defense while moving.
Stop Defending Time (float) – how long AI stays in defense after the threat or movement phase ends.
Stun Chance After Damaged (float) – chance to be stunned after taking damage.
Timer After Sudden Attack AI Will Be Able To Attack (float) – delay before AI can attack again after a sudden attack.
Chance Find Target Immidiately After Being In Stun (float) – chance to immediately reacquire a target after leaving stun.
Move Back While Defence (float) – probability or weight for moving backward in defense.
Move Back While Defence By Chances (E_MoveType) – backward movement type used in defense.
Attacks Amount Per Session (int) – number of attacks AI can perform in one combat session.
Activate Move To Target State Chance (float) – chance to activate move-to-target behavior.
Chance To Block Attack (float) – probability to block incoming attacks.

This asset is used to tune close-combat enemies and define how they defend, recover, and pace their aggression.

BP_Ranged_AI_Data

BP_Ranged_AI_Data extends the base AI data with ranged-combat-specific settings.

Important fields:

Minimal Number Of Bullets Per One Attack Cycle (int) – minimum number of shots in one attack cycle.
Maximal Number Of Bullets Per One Attack Cycle (int) – maximum number of shots in one attack cycle.

This gives designers direct control over ranged attack burst length and helps differentiate easy, medium, and clone ranged enemies without changing the whole behavior logic.

Runtime Behavior

AI Controller, Perception, and decision flow

Behavior Tree plus Blackboard is not the only decision source for AI.

AI Controllers also directly change AI state in response to perception and damage-related events.

The AI Controller owns the perception setup and the AI senses are implemented through AIPerception:

Sight
Hearing
Damage
Prediction

When perception updates, PerceptionUpdatedDelegate triggers On Perception Updated and passes the list of actors that disturbed the AI.

The controller then:

filters who disturbed the AI,
determines how the disturbance happened,
updates internal AI logic,
changes AI state where needed,
pushes the result into runtime behavior and behavior tree flow.

This means the runtime AI flow is a combination of:

AI Controller perception events,
BP_AI_Component logic,
Behavior Tree,
Blackboard,
State System.

AI types

At runtime, AI behavior is also shaped by AI Type in BP_AI_Component:

Melee
Ranged
NPC

This is a high-level classification that helps route behavior, tuning, and behavior tree selection.

Friends and enemies

All AI belongs to one of two major groups:

friends,
enemies.

This affects who AI detects, who it ignores, and how it behaves in combat or support scenarios. The exact filtering is controlled through actor-type detection settings and runtime logic.

Combat and Attack Tokens

Combat systems integration

AI does not use a separate combat system.

Instead, it plugs into the same shared gameplay modules as the player:

BP_FirearmsComponent for ranged combat,
BP_MeleeComponent for close combat,
ability/effects/buff systems for special actions like healing, telekinesis, or self-destruction,
stats and state systems for damage, stun, and combat restrictions.

BP_AI_Component and the AI Controller decide when to request actions. The actual combat execution is then handled by the existing combat modules.

Attack token system

The attack token system is real and actively used.

The number of free attack tokens is stored in BP_PlayerComponent.
Functions that try to take or return a token are located in BP_AI_Component.
These functions are called through the player mediator.

This means AI coordinates attacks against the player through the mediator/player-component path rather than through a separate global manager.

In practice, this allows melee and other aggressive AI to avoid all attacking at the same time. If a token is unavailable, AI can remain in a waiting, repositioning, or supporting behavior instead of entering a full direct attack state.

Integration

State System

AI changes states only through:

BP_ModulesMediator
BPI_ModulesMediator

AI does not modify runtime state tags directly.

This keeps AI fully aligned with the global state architecture and ensures that combat, effects, animation logic, and restrictions remain consistent with the rest of the project.

Quests and trading

Quest NPCs and vendors are regular AI-based characters with additional components.

This means it is correct to describe them as normal AI pawns extended with quest or trade functionality rather than as a separate category of actor.

Examples:

Quest-giving AI uses BP_QuestComponentNPC.
Vendor AI uses trading-related components and dialogue outcomes.

Combat AI usually does not carry those components, while quest and vendor NPCs do.

Save system

There is a shared save container for all living AI.

The main structure is S_AI_SaveData.

Fields:

Pawn – pawn class.
Health – float.
BT – Behavior Tree.
NPC ItemsForSale Data – S_ItemForSale structure:
- Item – BP_ItemData
- Quantity – integer

This allows the save system to restore living AI, their current health, their assigned behavior tree, and vendor inventory data where applicable.

MassAI

The project also uses MassAI.

There are bots BP_MassAI_Crowd with a MassAgent component.

In the Entity Config, the parent field points to the Data Asset MassCrowdPuppetConfig.

MassAI is used for crowd-style AI and should be documented as a separate but connected branch of the overall AI architecture: standard combat and quest AI uses BP_RPG_AI, while crowd population uses the MassAI stack.

Scope and Limitations

This document covers:

the AI class hierarchy,
BP_AI_Component,
AI data assets,
perception and controller logic,
attack tokens,
integration with combat, state, save/load, quests, trading, and MassAI.

This document does not cover:

full Behavior Tree node-by-node breakdowns,
Blackboard key reference,
exact editor setup for creating a new enemy,
detailed field-by-field reference for every AI Data asset and enum.

Those topics should be covered in:

How‑To: how-to-add-ai-enemy-type.md, how-to-add-quest-npc.md, how-to-add-vendor-npc.md
Reference: AI-related sections in components, interfaces, gameplay tags, and Data Assets reference docs