UE5-Modular-Game-Framework/docs/blueprints/09-ai/85_BB_AgentBoard.md

BB_AgentBoard — AI Agent Blackboard Asset

Blueprint Spec — UE 5.5–5.7

---

Parent Class

UBlackboardData (Blackboard Asset)

Dependencies

• Required By: AI_BaseAgentController — Uses this blackboard for all agent state
• Required By: BPC_AIPerceptionSystem — Writes perception data to blackboard keys
• Required By: BPC_AIMemorySystem — Reads/writes investigate and search locations
• Required By: BPC_BehaviourVariantSelector — Writes PlayerPlaystyleTag key
• Required By: Behaviour Tree (BT_Agent) — All BT nodes read/write these keys
• Engine/Plugin Requirements: AI Module, GameplayTags (for PlayerPlaystyleTag)

Purpose

Standardised blackboard asset defining all keys used by AI agents. Acts as the shared data contract between perception, memory, behaviour variant selection, and the behaviour tree. Every AI agent using this framework must use this blackboard or a derivative.

---

1. Enums

Uses E_AIAlertState from BPC_AIPerceptionSystem.

---

2. Structs

No structs defined. Blackboard keys are primitive types.

---

3. Variables — Blackboard Keys

Standard Keys

Key	Type	Description
TargetActor	Object	Current pursuit target (player or other threat)
LastKnownTargetLocation	Vector	Last known position of the target
AlertState	E_AIAlertState	Current alert level (Unaware, Curious, Suspicious, Alerted, Engaged, Searching)
PatrolTargetIndex	Integer	Index of current patrol point in the patrol path
bIsInvestigating	Bool	Whether the agent is currently investigating
InvestigateLocation	Vector	Where the agent should go to investigate
bTargetLost	Bool	Whether the agent has lost sight/hearing of the target
PlayerPlaystyleTag	GameplayTag	Current classified playstyle of the player (Aggressive, Cautious, etc.)
LastHeardLocation	Vector	Most recent sound event location

---

4. Functions

Blackboard is data-only. No functions defined at the asset level. Keys are read/written by behaviour tree nodes and perception component.

---

5. Event Dispatchers

No event dispatchers. Blackboard is a passive data store.

---

6. Overridden Events / Custom Events

None. This is a data asset, not an executable Blueprint.

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[BPC_AIPerceptionSystem sees player] --> B[Write TargetActor = Player]
    B --> C[Write LastKnownTargetLocation = Player.Location]
    A --> D[EscalateAlertState to Suspicious]
    D --> E[Write AlertState = Suspicious]
    E --> F[Behaviour Tree reads AlertState]
    F --> G[Suspicious → Start investigating]
    G --> H[Write bIsInvestigating = true]
    H --> I[Write InvestigateLocation = LastKnownTargetLocation]
    I --> J[BT MoveTo: InvestigateLocation]

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_AIPerceptionSystem	Blackboard write	TargetActor, LastKnownTargetLocation, LastHeardLocation, AlertState, bTargetLost
BPC_AIMemorySystem	Blackboard write	InvestigateLocation, bIsInvestigating
BPC_BehaviourVariantSelector	Blackboard write	PlayerPlaystyleTag
AI_BaseAgentController	Blackboard ownership	Initialises and holds the blackboard component
Behaviour Tree (BT_Agent)	Blackboard read/write	All keys — drives BT flow decisions
Patrol System (BP_PatrolPath)	Blackboard read/write	PatrolTargetIndex

---

9. Validation / Testing Checklist

• All 9 standard keys are present in the blackboard asset
• Key types match their expected usage (Object for TargetActor, Vector for locations, etc.)
• E_AIAlertState enum is properly referenced for the AlertState key
• GameplayTag type is configured for PlayerPlaystyleTag
• AI controller correctly assigns this blackboard on init
• Edge case: keys are present before perception system tries to write to them
• Edge case: behaviour tree graceful when TargetActor is None (cleared on target lost)

---

10. Reuse Notes

• This is a project-agnostic standard blackboard. Add project-specific keys in a child blackboard that inherits from this.
• All BT nodes should check key validity (Is Set) before reading to avoid errors
• Use Blackboard Key Selector pattern in BT tasks to allow designers to select which key to operate on
• New perception types (smell, damage) can write to LastHeardLocation or add new keys in a child blackboard
• PatrolTargetIndex is incremented by patrol tasks; reset to 0 on patrol path change

---

Specification based on Master Section 10.2, line 2964.