Update tooltips and comments: fix outdated references, clarify personality modulation

- BTTask_Attack.h: remove reference to non-existent GetBehaviorOptimalAttackRange, document PersonalityProfile ranges
- AIController.h: update TeamId comment to reflect actual MakeTeamId encoding (nibble-based)
- CoverShootCycle.h: clarify that Peek/Cover durations are base values modulated by personality traits
- FindCover.h: clarify ManualPointBonus is additive score
- CombatComponent.h: clarify AttackRange/AttackCooldown are for ExecuteAttack, not BTTask_Attack

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Unreal/PS_AI_Agent/Plugins/PS_AI_Behavior/Source/PS_AI_Behavior/Public/BT/PS_AI_Behavior_BTTask_Attack.h

@@ -13,9 +13,11 @@ class UEnvQuery;
 /**
  * BT Task: Move toward the threat actor and delegate combat to the Pawn.
  *
- * Queries IPS_AI_Behavior_Interface for CombatType and OptimalAttackRange:
+ * Queries IPS_AI_Behavior_Interface for CombatType (Melee/Ranged).
- * - Melee: rush toward target, stop at optimal range.
+ * Attack ranges come from PersonalityProfile (MinAttackRange/MaxAttackRange),
- * - Ranged: maintain optimal distance — back away if too close, advance if too far.
+ * with fallback to AttackMoveRadius if no profile is available.
+ * - Melee: rush toward target, continuous pursuit within MinRange.
+ * - Ranged: maintain distance — back away if closer than MinRange, advance if farther than MaxRange.
  *
  * Calls IPS_AI_Behavior_Interface::BehaviorStartAttack() on enter and
  * BehaviorStopAttack() on abort. The Pawn handles the actual combat
@@ -32,7 +34,7 @@ class PS_AI_BEHAVIOR_API UPS_AI_Behavior_BTTask_Attack : public UBTTaskNode
 public:
 	UPS_AI_Behavior_BTTask_Attack();
 
-	/** Fallback move radius if the Pawn doesn't implement GetBehaviorOptimalAttackRange(). */
+	/** Fallback attack range (cm) used when PersonalityProfile is unavailable. */
 	UPROPERTY(EditAnywhere, Category = "Attack", meta = (ClampMin = "50.0"))
 	float AttackMoveRadius = 300.0f;
 

Unreal/PS_AI_Agent/Plugins/PS_AI_Behavior/Source/PS_AI_Behavior/Public/BT/PS_AI_Behavior_BTTask_CoverShootCycle.h

@@ -43,19 +43,19 @@ public:
 
 	// ─── Timing ─────────────────────────────────────────────────────────
 
-	/** Minimum time (seconds) spent peeking/shooting. */
+	/** Base minimum time (seconds) spent peeking/shooting. Modulated at runtime: Aggressivity increases, Caution decreases. */
 	UPROPERTY(EditAnywhere, Category = "Cover Shoot|Timing", meta = (ClampMin = "0.5"))
 	float PeekDurationMin = 2.0f;
 
-	/** Maximum time (seconds) spent peeking/shooting. */
+	/** Base maximum time (seconds) spent peeking/shooting. Modulated at runtime: Aggressivity increases, Caution decreases. */
 	UPROPERTY(EditAnywhere, Category = "Cover Shoot|Timing", meta = (ClampMin = "0.5"))
 	float PeekDurationMax = 5.0f;
 
-	/** Minimum time (seconds) spent ducked behind cover. */
+	/** Base minimum time (seconds) spent ducked behind cover. Modulated at runtime: Caution increases, Aggressivity decreases. */
 	UPROPERTY(EditAnywhere, Category = "Cover Shoot|Timing", meta = (ClampMin = "0.5"))
 	float CoverDurationMin = 1.0f;
 
-	/** Maximum time (seconds) spent ducked behind cover. */
+	/** Base maximum time (seconds) spent ducked behind cover. Modulated at runtime: Caution increases, Aggressivity decreases. */
 	UPROPERTY(EditAnywhere, Category = "Cover Shoot|Timing", meta = (ClampMin = "0.5"))
 	float CoverDurationMax = 3.0f;
 
@@ -72,7 +72,7 @@ public:
 
 	// ─── Advancement ────────────────────────────────────────────────────
 
-	/** Number of peek/duck cycles before advancing to a closer cover. */
+	/** Number of peek/duck cycles before attempting to advance to a closer cover point. Modulated by Aggressivity. */
 	UPROPERTY(EditAnywhere, Category = "Cover Shoot|Advancement", meta = (ClampMin = "1", ClampMax = "10"))
 	int32 MaxCyclesBeforeAdvance = 3;
 

Unreal/PS_AI_Agent/Plugins/PS_AI_Behavior/Source/PS_AI_Behavior/Public/BT/PS_AI_Behavior_BTTask_FindCover.h

@@ -51,8 +51,9 @@ public:
 	EPS_AI_Behavior_CoverPointType CoverPointType = EPS_AI_Behavior_CoverPointType::Cover;
 
 	/**
-	 * Bonus score added to manual CoverPoints over procedural candidates.
+	 * Score bonus added to manual CoverPoints (additive, 0-1 range).
-	 * Higher = manual points are strongly preferred.
+	 * A manual point with score 0.5 + bonus 0.3 = 0.8 total.
+	 * Higher = manual points strongly preferred over procedural candidates.
 	 */
 	UPROPERTY(EditAnywhere, Category = "Cover|Manual Points", meta = (ClampMin = "0.0", ClampMax = "1.0"))
 	float ManualPointBonus = 0.3f;

Unreal/PS_AI_Agent/Plugins/PS_AI_Behavior/Source/PS_AI_Behavior/Public/PS_AI_Behavior_AIController.h

@@ -33,15 +33,15 @@ public:
 
 	/**
 	 * Team ID — determines perception affiliation (Enemy/Friendly/Neutral).
-	 * Auto-assigned from NPCType at possession if left at 255 (NoTeam):
+	 * Auto-assigned from NPCType + Faction at possession via MakeTeamId():
-	 *   - Civilian = Team 1
+	 *   - Encoding: high nibble = NPCType, low nibble = Faction
-	 *   - Enemy    = Team 2
+	 *   - Civilian F0 = 0x00, Enemy F0 = 0x10, Protector F0 = 0x20
-	 *   - Neutral  = 255 (NoTeam → perceived as Neutral by everyone)
+	 *   - Same NPCType + same Faction → Friendly
-	 *
+	 *   - Same NPCType + different Faction → Hostile (rival gangs)
-	 * Two NPCs with the SAME Team ID → Friendly (ignored by perception).
+	 *   - Civilian ↔ Protector → always Friendly
-	 * Two NPCs with DIFFERENT Team IDs → Enemy (detected by perception).
+	 *   - Everything else → Hostile
-	 * A NPC with Team ID 255 → Neutral to everyone.
 	 *
+	 * Disguised enemies (hostile=false) use DisguisedTeamId (0x01).
 	 * You can override this in Blueprint or per-instance in the editor.
 	 */
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Team")

Unreal/PS_AI_Agent/Plugins/PS_AI_Behavior/Source/PS_AI_Behavior/Public/PS_AI_Behavior_CombatComponent.h

@@ -27,11 +27,11 @@ public:
 
 	// ─── Configuration ──────────────────────────────────────────────────
 
-	/** Maximum distance at which the NPC can attack (cm). */
+	/** Maximum distance at which ExecuteAttack() succeeds (cm). Independent from PersonalityProfile ranges used by BTTask_Attack. */
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Combat", meta = (ClampMin = "50.0"))
 	float AttackRange = 200.0f;
 
-	/** Cooldown between attacks (seconds). */
+	/** Minimum time between consecutive ExecuteAttack() calls (seconds). */
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Combat", meta = (ClampMin = "0.1"))
 	float AttackCooldown = 1.5f;