# PS_AI_Agent — Notes pour Claude

## Plugins dans ce repo

### PS_AI_ConvAgent
- **Module**: `PS_AI_ConvAgent` / `PS_AI_ConvAgentEditor`
- **API macro**: `PS_AI_CONVAGENT_API`
- **Class prefix**: `PS_AI_ConvAgent_` (e.g. `UPS_AI_ConvAgent_PostureComponent`)
- **ElevenLabs-specific**: suffix `_ElevenLabs` (e.g. `UPS_AI_ConvAgent_ElevenLabsComponent`)
- **UI display**: `"PS AI ConvAgent"` (categories, DisplayName)
- **CoreRedirects**: DefaultEngine.ini handles both ElevenLabs* and PS_AI_Agent_* → PS_AI_ConvAgent_*

### PS_AI_Behavior
- **Module**: `PS_AI_Behavior` / `PS_AI_BehaviorEditor`
- **API macro**: `PS_AI_BEHAVIOR_API`
- **Class prefix**: `PS_AI_Behavior_` (e.g. `UPS_AI_Behavior_PersonalityComponent`)
- **UI display**: `"PS AI Behavior"` (categories, DisplayName)
- **Interface**: `IPS_AI_Behavior_Interface` — implements on host project Pawns

## PS_AI_Behavior — Architecture

### Core Design
- **Interface-driven**: `IPS_AI_Behavior_Interface` on Pawns decouples plugin from host project
- **Personality profiles**: DataAsset with 5 trait axes, thresholds, target priority, speed per state
- **NPCType enum**: Civilian, Enemy, Protector, Any (unified — no separate SplineCategory)
- **TeamIds**: Civilian=1, Enemy=2, Protector=3, auto-assigned in OnPossess
- **Hostile switch**: Enemy with IsBehaviorHostile=false → TeamId=1 (disguised), flips to 2 at runtime

### Blackboard
- Key `BehaviorState` = Enum type, path: `/Script/PS_AI_Behavior.EPS_AI_Behavior_State`
- Values: Idle(0), Patrol(1), Alerted(2), Combat(3), Fleeing(4), TakingCover(5), Dead(6)
- BB asset created manually in editor (runtime fallback exists but prefer asset)
- SetValueAsEnum / GetValueAsEnum (not Int)

### BT Pattern
- Services on Selector: UpdateThreat + EvaluateReaction
- Decorator Observer Aborts = Both on Combat/Flee branches
- Spline branch as fallback (lowest priority, no condition decorator)
- Attack task stays InProgress permanently, Decorator pulls out on state change

### Spline System
- SplinePath actors placed in level, SplineCategory = NPCType
- SplineNetwork WorldSubsystem auto-detects junctions
- SplineFollowerComponent on Pawns: uses Pawn's real velocity, debug green sphere
- Junction switching: 70% probability, direction filter (dot > -0.5)

### Perception
- Senses configured in BeginPlay (NOT constructor — NewObject crashes in CDO)
- RequestStimuliListenerUpdate() after ConfigureSenses
- Detect ALL affiliations, filter by Hostile attitude in CalculateThreatLevel
- Target priority from PersonalityProfile (combat targeting)

### Known Gotchas (UE 5.5)
- BB Enum picker doesn't list plugin enums — use string path
- NTFS junctions (not symlinks) for UE5 cross-project plugin linking
- SVN doesn't traverse junctions — robocopy for initial import
- Live Coding fails on header changes — full rebuild required
- BlueprintNativeEvent: UHT auto-generates _Implementation defaults, don't duplicate in .cpp
- FGenericTeamId::NoTeam comparison: always recalculate TeamId (BP CDOs may reset to 0)

### Testing Status (2026-03-26)
- ✅ Patrol, Spline following, Perception, Threat, Flee, Combat delegation, Hostile switch
- 🔲 Cover Points, EQS, Editor tools (SplineEdMode, CoverPoint placement)

## Posture System — Diagonal Tilt Bug (à corriger)

### Problème
Le tilt diagonal (ear-to-shoulder) est PLUS VISIBLE avec la neck bone chain qu'avec le mono-bone.

### Piste de fix
Faire le swing-twist **PER-BONE** : pour chaque bone de la chaîne, composer le FractionalRot avec le bone's own rotation, swing-twist autour du bone's own tilt axis.

### Fichiers concernés
- `AnimNode_PS_AI_ConvAgent_Posture.cpp` — Evaluate_AnyThread, section multi-bone chain

## Architecture Posture (ConvAgent)
- **PS_AI_ConvAgent_PostureComponent** (game thread) : cascade Eyes→Head→Body
- **AnimNode_PS_AI_ConvAgent_Posture** (anim thread) : applique rotation sur bone(s) + injecte curves
- Pipeline 100% FQuat, Thread safety via FCriticalSection
- ARKit eye curves normalisées par range fixe (40°/35°)