add blueprints

docs/blueprints/09-ai/85_BB_AgentBoard.md

@@ -0,0 +1,123 @@
+# BB_AgentBoard — AI Agent Blackboard Asset
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UBlackboardData` (Blackboard Asset)
+
+### Dependencies
+- **Required By:** [`AI_BaseAgentController`](AI_BaseAgentController.md) — Uses this blackboard for all agent state
+- **Required By:** [`BPC_AIPerceptionSystem`](BPC_AIPerceptionSystem.md) — Writes perception data to blackboard keys
+- **Required By:** [`BPC_AIMemorySystem`](BPC_AIMemorySystem.md) — Reads/writes investigate and search locations
+- **Required By:** [`BPC_BehaviourVariantSelector`](BPC_BehaviourVariantSelector.md) — 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`](BPC_AIPerceptionSystem.md).*
+
+---
+
+## 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
+
+```mermaid
+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`](BPC_AIPerceptionSystem.md) | Blackboard write | `TargetActor`, `LastKnownTargetLocation`, `LastHeardLocation`, `AlertState`, `bTargetLost` |
+| [`BPC_AIMemorySystem`](BPC_AIMemorySystem.md) | Blackboard write | `InvestigateLocation`, `bIsInvestigating` |
+| [`BPC_BehaviourVariantSelector`](BPC_BehaviourVariantSelector.md) | Blackboard write | `PlayerPlaystyleTag` |
+| [`AI_BaseAgentController`](AI_BaseAgentController.md) | 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.*