@directivegames/genesys.js 3.1.24

package/docs/guides/6-ai-and-behavior-trees.md

@@ -0,0 +1,1316 @@
+## Instruction
+Use this doc to understand how AI and behavior trees work in Genesys.js. Learn how to implement sophisticated AI decision-making systems, behavior trees for NPCs, aerial movement patterns, and advanced AI debugging techniques.
+
+# AI and Behavior Trees in Genesys.js
+
+Creating intelligent, believable Non-Player Characters (NPCs) requires sophisticated decision-making systems that go beyond simple pathfinding. Genesys.js provides a powerful behavior tree system for complex AI logic, along with specialized movement components for different types of characters.
+
+This guide covers **AI behavior and decision-making systems**. For ground-based navigation and pathfinding, see the **[Navigation and Pathfinding Guide](15-navigation-and-pathfinding.md)**.
+
+---
+
+## 1. Introduction to Behavior Trees
+
+Behavior trees provide a modular, hierarchical approach to AI programming that's more flexible than traditional state machines. They allow you to create complex AI behaviors by combining simple, reusable components.
+
+The behavior tree system in Genesys.js features:
+- **Code-first approach** with full TypeScript support
+- **Organized behavior categories** (ground, aerial, combat, utility)
+- **Attached conditions system** inspired by Unreal Engine
+- **Comprehensive debugging tools**
+- **Blackboard system** for shared memory
+
+### Basic Concepts
+
+**Behavior Trees** consist of nodes that execute in a specific order:
+- **Composite Nodes**: Control execution flow (Sequence, Selector)
+- **Action Nodes**: Perform specific behaviors (Move, Attack, Wait)
+- **Condition Evaluators**: Check game state (attached to actions)
+
+**Blackboard**: Shared memory system for data exchange between nodes
+
+---
+
+## 2. Movement Components for AI
+
+Genesys.js provides specialized movement components for different types of AI characters.
+
+### Aerial Movement: AerialMovementComponent
+
+For flying enemies, drones, or floating characters, use the `AerialMovementComponent`. This component provides full 3D movement without requiring NavMesh pathfinding.
+
+```typescript
+const aerialEnemy = new ENGINE.Pawn({
+    movementComponent: new ENGINE.AerialMovementComponent({
+        maxSpeed: 15, // Movement speed in units per second
+        hoverHeight: 20, // Preferred height above ground
+        hoverVariation: 3, // Random height variation
+        rotationSpeed: 2.0, // How fast it rotates
+        maxTiltAngle: 15 // Banking angle when moving (degrees)
+    })
+});
+```
+
+The `AerialMovementComponent` provides:
+- **setTargetPosition()**: Set a 3D position to move toward
+- **setLastKnownPlayerPosition()**: Enable search behavior around a position
+- **clearTarget()**: Stop movement and hover in place
+- **getTargetPosition()**: Get current target position
+- **lookAtTarget()**: Rotate to face a target position
+- **isFacingTarget()**: Check if facing a target within angle threshold
+
+Key features:
+- **3D Movement**: Move freely in all three dimensions
+- **Hovering**: Gentle up/down floating motion with animation
+- **Banking**: Tilts when turning for realistic flight
+- **Search Behavior**: Circles around last known positions
+- **No NavMesh Required**: Works without navigation mesh
+
+### Ground-Based Movement Integration
+
+The `NpcMovementComponent` is the foundation for ground-based NPC movement. It extends `CharacterMovementComponent`, providing physics-based character movement with NavMesh pathfinding.
+
+```typescript
+const npc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 3, // How fast the NPC moves
+        turnSpeed: 5,     // How fast it turns
+        useNavigationServer: true, // Use NavMesh pathfinding
+        actorFollowingDistance: 2.0, // Stop distance when following
+        pathFollowingAccuracy: 3.0, // How close to get to waypoints
+        stopDistance: 1.0 // Distance to stop from targets
+    }),
+    camera: null // NPCs don't need cameras
+});
+```
+
+The `NpcMovementComponent` provides methods for:
+- **setPath()**: Set a path of waypoints for the NPC to follow
+- **setTargetPosition()**: Set a target position and automatically calculate the path using navigation server
+- **setTargetActor()**: Set a target actor to follow and automatically handle pathfinding
+- **followActor()**: Follow another actor at a specified distance
+- **stop()**: Stop all movement
+- **hasReachedCurrentTarget()**: Check if the NPC has reached its target
+- **getCurrentTarget()**: Get the current movement target
+
+For detailed information about NavMesh generation, pathfinding configuration, and ground-based movement debugging, see the [Navigation and Pathfinding Guide](15-navigation-and-pathfinding.md).
+
+### Architectural Design: Separation of Concerns
+
+The behavior tree system follows a clean separation of concerns where:
+
+- **Actions** focus on behavior logic and decision-making
+- **Movement Components** handle all pathfinding and navigation details
+- **Navigation Server** provides the underlying pathfinding capabilities
+
+This means ground-based actions like `MoveToPositionAction` and `FollowActorAction` simply call `setTargetPosition()` or `setTargetActor()` on the `NpcMovementComponent`, which then handles:
+- Path calculation using the Navigation Server
+- NavMesh integration and closest point finding
+- Path following and waypoint management
+- Obstacle avoidance and path recalculation
+
+This design provides several benefits:
+- **Reusability**: Pathfinding logic is centralized and reusable
+- **Simplicity**: Actions focus on "what to do" rather than "how to move"
+- **Maintainability**: Navigation improvements benefit all actions automatically
+- **Performance**: Eliminates duplicate pathfinding code across actions
+
+---
+
+## 3. Behavior Tree System
+
+The behavior tree system provides a powerful, modular approach to AI programming. It uses an **attached conditions** system inspired by Unreal Engine, with actions organized into logical categories.
+
+### Creating Behavior Trees in Code (Recommended)
+
+For full control and type safety, create behavior trees programmatically. The system organizes actions into categories:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+// Actions are organized by category:
+// - Ground actions (NavMesh-based): FollowActorAction, MoveToPositionAction, etc.
+// - Aerial actions (3D flying): AerialMoveToTargetAction, AerialSearchAction, etc.
+// - Combat actions: MeleeAttackAction, ShootAction
+// - Utility actions: WaitAction, LookAtTargetAction
+
+// Create a guard that follows the player when they get close
+const followPlayer = new ENGINE.FollowActorAction({
+  targetActorKey: 'PlayerActor',
+  followDistance: 5.0,
+  useNavigation: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 15.0 })
+  ]
+});
+
+const npc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 3,
+        turnSpeed: 5,
+        useNavigationServer: true
+    }),
+    camera: null
+});
+
+const behaviorTree = new ENGINE.BehaviorTreeComponent({
+  rootNode: followPlayer,
+  updateInterval: 0.1,
+  autoStart: true
+});
+npc.addComponents(behaviorTree);
+this.world.addActors(npc);
+
+// Initialize blackboard data - ALL actor references must go through blackboard
+const blackboard = behaviorTree.getBlackboard();
+blackboard.setValue('PlayerActor', this.playerPawn);
+```
+
+### Node Types
+
+**Composite Nodes** control execution flow:
+- `SequenceNode`: Execute children in order (AND logic)
+- `SelectorNode`: Try children until one succeeds (OR logic)
+
+**Adding Children to Composite Nodes**:
+- `addChild(node)`: Add a single child node
+- `addChildren([node1, node2, ...])`: Add multiple child nodes at once
+
+**Action Categories**:
+
+**Ground Actions** (NavMesh-based movement):
+- `MoveToPositionAction`: Move to a specific position
+- `FollowActorAction`: Follow another actor
+- `SetNextWaypointAction`: Manage waypoint cycling
+- `FleeFromTargetAction`: Flee from a target
+- `WanderAction`: Random ground movement
+
+**Aerial Actions** (3D flying movement):
+- `AerialMoveToTargetAction`: Move to target in 3D space
+- `AerialSearchAction`: Search around last known position
+- `AerialTrackTargetAction`: Continuously track target
+- `AerialWanderAction`: Random 3D movement
+
+**Combat Actions**:
+- `MeleeAttackAction`: Close-range melee attacks
+- `ShootAction`: Ranged projectile attacks
+
+**Utility Actions**:
+- `LookAtTargetAction`: Rotate to face a target
+- `WaitAction`: Wait for a specified duration
+- `CalculateTacticalPositionAction`: Calculate tactical positions relative to targets
+
+**Condition Evaluators** check game state:
+- `IsPlayerNearCondition`: Check if player is within range
+- `CanSeeTargetCondition`: Check line-of-sight to a target
+- `TargetInConeCondition`: Check if target is in field of view
+- `HpAbovePercentCondition`: Check HP above threshold
+- `TargetBelowHpPercentCondition`: Check target HP below threshold
+- `TimeLimitCondition`: Check within time limit
+- `HasLastKnownPositionCondition`: Check if position is known
+
+### Attached Conditions System
+
+Instead of conditions being separate nodes, they are **attached as properties** to any node:
+
+```typescript
+const followPlayer = new ENGINE.FollowActorAction({
+  targetActorKey: 'PlayerActor',
+  followDistance: 5.0,
+  useNavigation: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 15.0 })
+  ]
+});
+```
+
+Multiple conditions (all must succeed):
+```typescript
+const attackAction = new ENGINE.MeleeAttackAction({
+  targetActorKey: 'PlayerActor',
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 8.0 }),
+    new ENGINE.CanSeeTargetCondition({ 
+      targetActorKey: 'PlayerActor',
+      maxDistance: 10.0 
+    })
+  ]
+});
+```
+
+Inverted conditions:
+```typescript
+const moveToWaypoint = new ENGINE.MoveToPositionAction({
+  targetPositionKey: 'CurrentWaypoint',
+  acceptanceRadius: 2.0,
+  useNavigation: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ 
+      range: 15.0,
+      invert: true // Only move when player is NOT near
+    })
+  ]
+});
+```
+
+### Blackboard System
+
+The behavior tree system uses a **blackboard** for shared memory. This provides a clean, data-driven approach to AI configuration.
+
+#### Blackboard-Only Actor References
+
+**All actor references must go through blackboard keys** - direct actor references are not supported. This ensures clean separation and reusability:
+
+```typescript
+// ✅ CORRECT: Use blackboard keys
+const blackboard = behaviorTreeComponent.getBlackboard();
+blackboard.setValue('PlayerActor', this.playerPawn);
+blackboard.setValue('EnemyActor', this.enemyNpc);
+```
+
+#### Setting Up Blackboard Values
+
+```typescript
+// Set up all required blackboard values
+const blackboard = behaviorTreeComponent.getBlackboard();
+
+// Actor references (required for targeting)
+blackboard.setValue('PlayerActor', this.playerPawn);
+blackboard.setValue('EnemyActor', this.enemyNpc);
+
+// Position arrays for waypoint systems
+blackboard.setValue('PatrolWaypoints', [
+  new THREE.Vector3(-15, 1, -15),
+  new THREE.Vector3(-15, 1, 5),
+  new THREE.Vector3(5, 1, 5),
+  new THREE.Vector3(5, 1, -15)
+]);
+```
+
+---
+
+## 4. Complete Behavior Examples
+
+### Ground-Based Patrol Example
+
+Create a patrol system with player detection using attached conditions:
+
+```typescript
+// Define patrol waypoints
+const patrolWaypoints = [
+  new THREE.Vector3(-15, 1, -15),
+  new THREE.Vector3(-15, 1, 5),
+  new THREE.Vector3(5, 1, 5),
+  new THREE.Vector3(5, 1, -15)
+];
+
+// Patrol behavior - only when player is NOT near
+const setNextWaypoint = new ENGINE.SetNextWaypointAction({
+  waypointsKey: 'PatrolWaypoints',
+  currentIndexKey: 'CurrentWaypointIndex',
+  targetPositionKey: 'CurrentWaypoint',
+  loop: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ 
+      range: 12.0,
+      invert: true
+    })
+  ]
+});
+
+const moveToWaypoint = new ENGINE.MoveToPositionAction({
+  targetPositionKey: 'CurrentWaypoint',
+  useNavigation: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ 
+      range: 12.0,
+      invert: true
+    })
+  ]
+});
+
+const patrolSequence = new ENGINE.SequenceNode({
+  name: 'Patrol Sequence'
+});
+patrolSequence.addChildren([setNextWaypoint, moveToWaypoint]);
+
+// Chase behavior - only when player IS near
+const chasePlayer = new ENGINE.FollowActorAction({
+  targetActorKey: 'PlayerActor',
+  followDistance: 3.0,
+  useNavigation: true,
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 12.0 })
+  ]
+});
+
+// Main behavior: try chase first, then patrol
+const mainBehavior = new ENGINE.SelectorNode({
+  name: 'Main Behavior'
+});
+mainBehavior.addChildren([chasePlayer, patrolSequence]);
+
+// Apply to NPC
+const patrolNpc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 3,
+        turnSpeed: 5,
+        useNavigationServer: true
+    }),
+    camera: null
+});
+
+const behaviorTree = new ENGINE.BehaviorTreeComponent({
+  rootNode: mainBehavior,
+  updateInterval: 0.1,
+  autoStart: true
+});
+patrolNpc.addComponents(behaviorTree);
+this.world.addActors(patrolNpc);
+
+// Initialize blackboard data - ALL actor references must go through blackboard
+const blackboard = behaviorTree.getBlackboard();
+blackboard.setValue('PlayerActor', this.playerPawn); // Required for targeting actions/conditions
+blackboard.setValue('PatrolWaypoints', patrolWaypoints);
+blackboard.setValue('CurrentWaypointIndex', 0);
+```
+
+### Complex Combat Example
+
+Create a sophisticated combat AI with multiple behaviors:
+
+```typescript
+// Low health flee behavior
+const fleeWhenLowHealth = new ENGINE.FleeFromTargetAction({
+  targetActorKey: 'PlayerActor',
+  fleeDistance: 20.0,
+  fleeSpeedMultiplier: 1.5,
+  conditions: [
+    new ENGINE.HpAbovePercentCondition({ 
+      percentage: 30.0,
+      checkOwner: true,
+      invert: true // Flee when HP is below 30%
+    })
+  ]
+});
+
+// Melee attack when close
+const meleeAttack = new ENGINE.MeleeAttackAction({
+  targetActorKey: 'PlayerActor',
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 3.0 }),
+    new ENGINE.TargetInConeCondition({ 
+      targetActorKey: 'PlayerActor',
+      coneAngle: 90.0,
+      maxDistance: 3.0 
+    })
+  ]
+});
+
+// Ranged combat sequence
+const lookAtPlayer = new ENGINE.LookAtTargetAction({
+  targetActorKey: 'PlayerActor'
+});
+
+const shootAtPlayer = new ENGINE.ShootAction({
+  targetActorKey: 'PlayerActor',
+  shootRange: 15.0,
+  aimDuration: 0.5
+});
+
+const rangedCombatSequence = new ENGINE.SequenceNode({
+  name: 'Ranged Combat',
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 15.0 }),
+    new ENGINE.TargetInConeCondition({ 
+      targetActorKey: 'PlayerActor',
+      coneAngle: 45.0,
+      maxDistance: 15.0 
+    })
+  ]
+});
+rangedCombatSequence.addChildren([lookAtPlayer, shootAtPlayer]);
+
+// Wander when nothing else to do
+const wanderAction = new ENGINE.WanderAction({
+  wanderRadius: 8.0
+});
+
+// Main combat behavior tree
+const combatBehavior = new ENGINE.SelectorNode({
+  name: 'Combat Behavior'
+});
+combatBehavior.addChildren([
+  fleeWhenLowHealth,
+  meleeAttack,
+  rangedCombatSequence,
+  wanderAction
+]);
+
+// Create combat NPC
+const combatNpc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 4,
+        turnSpeed: 6,
+        useNavigationServer: true
+    }),
+    camera: null
+});
+
+// Add weapon for combat
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    projectileClass: ENGINE.BasicProjectile,
+    fireRate: 2.0,
+    maxAmmo: 30
+});
+combatNpc.addComponents(weapon);
+
+// Add stats for combat behavior
+const stats = new ENGINE.CharacterStatsComponent({
+    health: 100
+});
+combatNpc.addComponents(stats);
+
+// Apply behavior tree
+const behaviorTree = new ENGINE.BehaviorTreeComponent({
+  rootNode: combatBehavior,
+  updateInterval: 0.1,
+  autoStart: true
+});
+combatNpc.addComponents(behaviorTree);
+this.world.addActors(combatNpc);
+
+// Initialize blackboard
+const blackboard = behaviorTree.getBlackboard();
+blackboard.setValue('PlayerActor', this.playerPawn);
+```
+
+### Aerial Behavior Example
+
+Create a flying enemy that hunts the player from the sky:
+
+```typescript
+// Create aerial hunter behavior
+const aerialHunt = new ENGINE.SelectorNode({
+  name: 'Aerial Hunter Behavior'
+});
+
+// Track and attack when player is visible
+const attackSequence = new ENGINE.SequenceNode({
+  name: 'Attack Player',
+  conditions: [
+    new ENGINE.IsPlayerNearCondition({ range: 80.0 }),
+    new ENGINE.CanSeeTargetCondition({ 
+      targetActorKey: 'PlayerActor',
+      maxDistance: 80.0 
+    })
+  ]
+});
+attackSequence.addChildren([
+  new ENGINE.AerialTrackTargetAction({
+    targetActorKey: 'PlayerActor',
+    lastKnownPositionKey: 'LastKnownPlayerPosition',
+    updateInterval: 0.3
+  }),
+  new ENGINE.AerialMoveToTargetAction({
+    targetActorKey: 'PlayerActor',
+    acceptanceRadius: 25.0,
+    hoverAboveTarget: true,
+    hoverHeightOffset: 15.0
+  }),
+  new ENGINE.ShootAction({
+    targetActorKey: 'PlayerActor',
+    shootRange: 70.0,
+    aimDuration: 0.6
+  })
+]);
+
+// Search when player is lost
+const searchAction = new ENGINE.AerialSearchAction({
+  lastKnownPositionKey: 'LastKnownPlayerPosition',
+  searchRadius: 15.0,
+  searchDuration: 8.0,
+  conditions: [
+    new ENGINE.HasLastKnownPositionCondition({
+      positionKey: 'LastKnownPlayerPosition'
+    })
+  ]
+});
+
+// Wander when no information
+const wanderAction = new ENGINE.AerialWanderAction({
+  wanderRadius: 30.0,
+  wanderHeight: 20.0,
+  heightVariation: 8.0
+});
+
+aerialHunt.addChildren([
+  attackSequence,
+  searchAction,
+  wanderAction
+]);
+
+// Create aerial NPC
+const aerialEnemy = new ENGINE.Pawn({
+    movementComponent: new ENGINE.AerialMovementComponent({
+        maxSpeed: 15,
+        hoverHeight: 20,
+        hoverVariation: 3,
+        rotationSpeed: 2.0
+    })
+});
+
+// Add weapon for aerial combat
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    projectileClass: ENGINE.BasicProjectile,
+    fireRate: 1.5,
+    maxAmmo: 50
+});
+aerialEnemy.addComponents(weapon);
+
+const behaviorTree = new ENGINE.BehaviorTreeComponent({
+  rootNode: aerialHunt,
+  updateInterval: 0.2,
+  autoStart: true
+});
+aerialEnemy.addComponents(behaviorTree);
+this.world.addActors(aerialEnemy);
+
+// Initialize blackboard
+const blackboard = behaviorTree.getBlackboard();
+blackboard.setValue('PlayerActor', this.playerPawn);
+```
+
+---
+
+## 5. Alternative: JSON Configuration
+
+For data-driven workflows or when non-programmers need to modify AI behavior, you can use JSON configuration files. **Note**: JSON type names may differ from class names.
+
+### Loading JSON Behavior Trees
+
+```typescript
+// Load behavior tree from JSON
+const { rootNode, blackboardData } = await ENGINE.BehaviorTreeLoader.loadFromFile(ENGINE.AssetPath.fromString('@engine/assets/behavior-trees/my-guard.json'));
+
+// Apply to NPC
+const behaviorTreeComponent = new ENGINE.BehaviorTreeComponent({
+  rootNode: rootNode
+});
+npc.addComponents(behaviorTreeComponent);
+
+// Set blackboard data if provided
+if (blackboardData) {
+  const blackboard = behaviorTreeComponent.getBlackboard();
+  Object.entries(blackboardData).forEach(([key, value]) => {
+    blackboard.setValue(key, value);
+  });
+}
+```
+
+### JSON Type Mappings
+
+JSON uses specific type names that map to classes:
+
+| JSON Type | Class |
+|-----------|-------|
+| `"FollowActor"` | `FollowActorAction` |
+| `"MoveToPosition"` | `MoveToPositionAction` |
+| `"AerialMoveToTarget"` | `AerialMoveToTargetAction` |
+| `"AerialSearch"` | `AerialSearchAction` |
+| `"Shoot"` | `ShootAction` |
+| `"MeleeAttack"` | `MeleeAttackAction` |
+| `"Wait"` | `WaitAction` |
+| `"IsPlayerNear"` | `IsPlayerNearCondition` |
+| `"CanSeeTarget"` | `CanSeeTargetCondition` |
+
+### Simple Guard Behavior (JSON)
+```json
+{
+  "name": "SimpleGuardBehavior",
+  "rootNode": {
+    "type": "FollowActor",
+    "targetActorKey": "PlayerActor",
+    "followDistance": 5.0,
+    "useNavigation": true,
+    "conditions": [
+      {
+        "type": "IsPlayerNear",
+        "range": 15.0
+      }
+    ]
+  }
+}
+```
+
+### Patrol with Player Detection (JSON)
+```json
+{
+  "name": "PatrolGuardBehavior",
+  "rootNode": {
+    "type": "Selector",
+    "children": [
+      {
+        "type": "FollowActor",
+        "targetActorKey": "PlayerActor",
+        "followDistance": 3.0,
+        "useNavigation": true,
+        "conditions": [
+          {
+            "type": "IsPlayerNear",
+            "range": 12.0
+          }
+        ]
+      },
+      {
+        "type": "Sequence",
+        "children": [
+          {
+            "type": "SetNextWaypoint",
+            "waypointsKey": "PatrolWaypoints",
+            "currentIndexKey": "CurrentWaypointIndex",
+            "targetPositionKey": "CurrentWaypoint",
+            "loop": true,
+            "conditions": [
+              {
+                "type": "IsPlayerNear",
+                "range": 12.0,
+                "invert": true
+              }
+            ]
+          },
+          {
+            "type": "MoveToPosition",
+            "targetPositionKey": "CurrentWaypoint",
+            "acceptanceRadius": 2.0,
+            "useNavigation": true,
+            "conditions": [
+              {
+                "type": "IsPlayerNear",
+                "range": 12.0,
+                "invert": true
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Aerial Hunter Behavior (JSON)
+```json
+{
+  "name": "AerialHunterBehavior",
+  "description": "Flying enemy that hunts the player from the sky",
+  "rootNode": {
+    "type": "Selector",
+    "children": [
+      {
+        "type": "Sequence",
+        "name": "Attack Player",
+        "conditions": [
+          {
+            "type": "IsPlayerNear",
+            "range": 80.0
+          },
+          {
+            "type": "CanSeeTarget",
+            "targetActorKey": "PlayerActor",
+            "maxDistance": 80.0
+          }
+        ],
+        "children": [
+          {
+            "type": "AerialTrackTarget",
+            "targetActorKey": "PlayerActor",
+            "lastKnownPositionKey": "LastKnownPlayerPosition",
+            "updateInterval": 0.3
+          },
+          {
+            "type": "AerialMoveToTarget",
+            "targetActorKey": "PlayerActor",
+            "acceptanceRadius": 25.0,
+            "hoverAboveTarget": true,
+            "hoverHeightOffset": 15.0
+          },
+          {
+            "type": "Shoot",
+            "targetActorKey": "PlayerActor",
+            "maxRange": 70.0,
+            "aimTime": 0.6,
+            "leadTarget": true
+          }
+        ]
+      },
+      {
+        "type": "AerialSearch",
+        "lastKnownPositionKey": "LastKnownPlayerPosition",
+        "searchRadius": 15.0,
+        "searchDuration": 8.0,
+        "conditions": [
+          {
+            "type": "IsPlayerNear",
+            "range": 80.0,
+            "invert": true
+          }
+        ]
+      },
+      {
+        "type": "AerialWander",
+        "wanderRadius": 30.0,
+        "wanderHeight": 20.0,
+        "heightVariation": 8.0
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 6. Animation Integration
+
+Both AI systems automatically integrate with the animation system. Movement actions set animation parameters:
+
+- `speed`: Movement speed (0-1)
+- `forward`: Forward movement amount
+- `right`: Right movement amount
+
+This ensures NPCs play appropriate walking/running animations based on their behavior.
+
+---
+
+## 7. Combat Integration
+
+NPCs can be equipped with weapons for combat scenarios:
+
+```typescript
+// Add weapon to NPC
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    projectileClass: ENGINE.BasicProjectile,
+    fireRate: 2.0,
+    maxAmmo: 30
+});
+npc.addComponents(weapon);
+
+// Add stats for combat behavior
+const stats = new ENGINE.CharacterStatsComponent({
+    health: 100
+});
+npc.addComponents(stats);
+```
+
+Combat actions (`ShootAction`, `MeleeAttackAction`) automatically integrate with weapon components to handle combat scenarios.
+
+---
+
+## 8. Debugging Behavior Trees
+
+Effective debugging is crucial for developing reliable AI behaviors. Genesys.js provides comprehensive debugging tools to help you understand what your behavior trees are doing and identify issues.
+
+### Debug Information Methods
+
+The `BehaviorTreeComponent` provides several methods to inspect the current state of your AI:
+
+```typescript
+const behaviorTree = npc.getComponent(ENGINE.BehaviorTreeComponent);
+
+// Get comprehensive debug information
+const debugInfo = behaviorTree.getDebugInfo();
+console.log('Behavior Tree Debug Info:', debugInfo);
+
+// Get current execution status
+const currentStatus = behaviorTree.getCurrentStatus();
+console.log('Current Status:', currentStatus); // Success, Failure, or Running
+
+// Check if the tree is actively running
+const isRunning = behaviorTree.isRunningBehaviorTree();
+console.log('Is Running:', isRunning);
+
+// Get human-readable description of current behavior
+const description = behaviorTree.getCurrentBehaviorDescription();
+console.log('Current Behavior:', description);
+```
+
+### Execution Path Tracking
+
+Understanding the execution flow through your behavior tree is essential for debugging:
+
+```typescript
+// Get the full execution path from root to current leaf
+const executionPath = behaviorTree.getCurrentExecutionPath();
+console.log('Execution Path:');
+executionPath.forEach((node, index) => {
+  const indent = '  '.repeat(index);
+  console.log(`${indent}${node.name} (${node.getStatus()})`);
+});
+
+// Get the currently executing composite node (Sequence/Selector)
+const currentSequence = behaviorTree.getCurrentSequence();
+if (currentSequence) {
+  console.log(`Currently in: ${currentSequence.name}`);
+}
+
+// Get the currently executing action
+const currentAction = behaviorTree.getCurrentAction();
+if (currentAction) {
+  console.log(`Currently executing: ${currentAction.name}`);
+}
+```
+
+### Blackboard Inspection
+
+The blackboard contains all the shared data your behavior tree uses:
+
+```typescript
+const blackboard = behaviorTree.getBlackboard();
+
+// Get formatted debug information about all blackboard values
+const blackboardDebug = blackboard.getDebugInfo();
+console.log('Blackboard Contents:', blackboardDebug);
+
+// Check specific values
+const playerPosition = blackboard.getValue('PlayerPosition');
+const distanceToPlayer = blackboard.getValue('DistanceToPlayer');
+console.log(`Player at: ${playerPosition}, Distance: ${distanceToPlayer}`);
+
+// List all available keys
+const allKeys = blackboard.getKeys();
+console.log('Available blackboard keys:', allKeys);
+```
+
+### Real-Time Debug Monitoring
+
+Set up continuous monitoring to track AI behavior over time:
+
+```typescript
+class MyGame extends ENGINE.BaseGameLoop {
+  private debugTimer: number = 0;
+  private debugInterval: number = 2.0; // Debug every 2 seconds
+
+  protected override onTick(deltaTime: number): void {
+    super.onTick(deltaTime);
+    
+    // Debug monitoring
+    this.debugTimer += deltaTime;
+    if (this.debugTimer >= this.debugInterval) {
+      this.debugAI();
+      this.debugTimer = 0;
+    }
+  }
+
+  private debugAI(): void {
+    // Find all NPCs with behavior trees
+    const npcs = this.world.getAllActorsOfType(ENGINE.ThirdPersonCharacterPawn)
+      .filter(npc => npc.getComponent(ENGINE.BehaviorTreeComponent));
+
+    console.log('\n=== AI Debug Report ===');
+    npcs.forEach((npc, index) => {
+      const behaviorTree = npc.getComponent(ENGINE.BehaviorTreeComponent)!;
+      const description = behaviorTree.getCurrentBehaviorDescription();
+      const status = behaviorTree.getCurrentStatus();
+      
+      console.log(`NPC ${index + 1}: ${description} (${status})`);
+      
+      // Show blackboard values
+      const blackboard = behaviorTree.getBlackboard();
+      const distanceToPlayer = blackboard.getValue('DistanceToPlayer');
+      if (distanceToPlayer !== undefined) {
+        console.log(`  Distance to player: ${distanceToPlayer.toFixed(1)}`);
+      }
+    });
+    console.log('========================\n');
+  }
+}
+```
+
+### Node-Level Debugging
+
+Individual nodes provide their own debug information:
+
+```typescript
+// Get debug info from any node
+const nodeDebugInfo = someNode.getDebugInfo();
+console.log('Node Debug Info:', {
+  name: nodeDebugInfo.name,
+  description: nodeDebugInfo.description,
+  status: nodeDebugInfo.status,
+  isExecuting: nodeDebugInfo.isExecuting
+});
+
+// For composite nodes, get child information
+if (someNode instanceof ENGINE.CompositeNode) {
+  const compositeDebug = someNode.getDebugInfo();
+  console.log(`Current child index: ${compositeDebug.currentChildIndex}`);
+  console.log('Children:', compositeDebug.children);
+}
+```
+
+### Debug Output Examples
+
+Here's what typical debug output looks like:
+
+```typescript
+// Comprehensive debug info structure
+{
+  isRunning: true,
+  currentStatus: "Running",
+  updateInterval: 0.1,
+  blackboard: {
+    "PlayerPosition": "Vector3(10.50, 1.00, -5.25)",
+    "DistanceToPlayer": 12.3,
+    "CurrentWaypoint": "Vector3(0.00, 1.00, 0.00)",
+    "PatrolWaypoints": [Array of waypoints],
+    "PlayerActor": "ThirdPersonCharacterPawn(Player)"
+  },
+  rootNode: {
+    name: "PatrolBehavior",
+    description: "Main patrol behavior",
+    status: "Running",
+    isExecuting: true,
+    children: [...]
+  },
+  executionPath: [
+    { name: "PatrolBehavior", status: "Running" },
+    { name: "PatrolSequence", status: "Running" },
+    { name: "MoveToPosition", status: "Running" }
+  ]
+}
+```
+
+### Common Debugging Scenarios
+
+#### 1. Action Not Executing
+```typescript
+// Check if conditions are failing
+const currentAction = behaviorTree.getCurrentAction();
+if (!currentAction) {
+  console.log('No action executing - check conditions');
+  
+  // Inspect the execution path to see where it stops
+  const path = behaviorTree.getCurrentExecutionPath();
+  console.log('Execution stopped at:', path[path.length - 1]?.name);
+}
+```
+
+#### 2. Blackboard Issues
+```typescript
+// Verify required blackboard values are set
+const blackboard = behaviorTree.getBlackboard();
+const requiredKeys = ['PlayerActor', 'PatrolWaypoints', 'CurrentWaypoint'];
+
+requiredKeys.forEach(key => {
+  if (!blackboard.hasValue(key)) {
+    console.error(`Missing required blackboard key: ${key}`);
+  } else {
+    console.log(`✓ ${key}:`, blackboard.getValue(key));
+  }
+});
+```
+
+#### 3. Performance Issues
+```typescript
+// Monitor update frequency and execution time
+class DebugBehaviorTreeComponent extends ENGINE.BehaviorTreeComponent {
+  private lastExecutionTime: number = 0;
+  
+  protected override async updateBehaviorTree(): Promise<void> {
+    const startTime = performance.now();
+    await super.updateBehaviorTree();
+    const executionTime = performance.now() - startTime;
+    
+    if (executionTime > 5) { // Warn if execution takes more than 5ms
+      console.warn(`Slow behavior tree execution: ${executionTime.toFixed(2)}ms`);
+    }
+  }
+}
+```
+
+---
+
+## 9. Creating Custom Actions and Conditions
+
+The behavior tree system is fully extensible. You can create your own custom actions and conditions in your game project.
+
+### Creating Custom Actions
+
+```typescript
+// src/ai/actions/MyCustomAction.ts
+import * as ENGINE from 'genesys.js';
+
+export interface MyCustomActionOptions extends ENGINE.BehaviorActionOptions {
+  customParameter?: string;
+  customValue?: number;
+}
+
+@ENGINE.EngineClass('MyCustomAction')
+export class MyCustomAction extends ENGINE.BehaviorAction {
+  private customParameter: string;
+  private customValue: number;
+
+  constructor(options: MyCustomActionOptions = {}) {
+    super({ name: 'MyCustomAction', ...options });
+    this.customParameter = options.customParameter ?? 'default';
+    this.customValue = options.customValue ?? 1.0;
+  }
+
+  protected override async onUpdate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+    const owner = this.getOwner(blackboard);
+    if (!owner) return ENGINE.BehaviorStatus.Failure;
+
+    // Your custom logic here
+    console.log(`Custom action executing: ${this.customParameter}, ${this.customValue}`);
+    
+    return ENGINE.BehaviorStatus.Success;
+  }
+}
+```
+
+### ⚠️ Important: Avoid Indefinitely Running Actions
+
+**Critical Best Practice**: Custom actions should **always** have a completion condition and should not run indefinitely. Actions that return `BehaviorStatus.Running` forever will block the behavior tree from re-evaluating other branches and conditions.
+
+**❌ Bad Example** (Indefinitely running action):
+```typescript
+// DON'T DO THIS - This action will run forever
+protected override async onUpdate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+  // This action never completes!
+  return ENGINE.BehaviorStatus.Running;
+}
+```
+
+**✅ Good Examples** (Actions with completion conditions):
+```typescript
+// Timer-based completion
+protected override async onUpdate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+  const currentTime = Date.now() / 1000;
+  const elapsedTime = currentTime - this.startTime;
+  
+  if (elapsedTime >= this.maxDuration) {
+    return ENGINE.BehaviorStatus.Success; // Complete after timeout
+  }
+  
+  // Do work...
+  return ENGINE.BehaviorStatus.Running;
+}
+
+// Condition-based completion
+protected override async onUpdate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+  const owner = this.getOwner(blackboard);
+  
+  // Check if goal is achieved
+  if (this.hasAchievedGoal(owner)) {
+    return ENGINE.BehaviorStatus.Success;
+  }
+  
+  // Continue working toward goal
+  return ENGINE.BehaviorStatus.Running;
+}
+
+// Immediate completion for utility actions
+protected override async onUpdate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+  // Perform immediate action (like setting a value)
+  blackboard.setValue('SomeKey', 'SomeValue');
+  
+  // Complete immediately
+  return ENGINE.BehaviorStatus.Success;
+}
+```
+
+**Why This Matters**: The behavior tree system expects actions to eventually complete so it can:
+- Re-evaluate conditions on other branches
+- Allow higher-priority behaviors to interrupt
+- Reset and restart the tree when needed
+- Provide responsive AI that can adapt to changing game state
+
+### Creating Custom Conditions
+
+```typescript
+// src/ai/conditions/MyCustomCondition.ts
+import * as ENGINE from 'genesys.js';
+
+export interface MyCustomConditionOptions extends ENGINE.ConditionEvaluatorOptions {
+  threshold?: number;
+  targetActorKey?: string;
+}
+
+@ENGINE.EngineClass('MyCustomCondition')
+export class MyCustomCondition extends ENGINE.ConditionEvaluator {
+  private threshold: number;
+  private targetActorKey: string;
+
+  constructor(options: MyCustomConditionOptions = {}) {
+    super({ name: 'MyCustomCondition', ...options });
+    this.threshold = options.threshold ?? 10.0;
+    this.targetActorKey = options.targetActorKey ?? 'PlayerActor';
+  }
+
+  protected override async onEvaluate(blackboard: ENGINE.Blackboard): Promise<ENGINE.BehaviorStatus> {
+    const owner = this.getOwner(blackboard);
+    const target = blackboard.getValue<any>(this.targetActorKey);
+    
+    if (!owner || !target) return ENGINE.BehaviorStatus.Failure;
+
+    // Your custom condition logic here
+    // Return Success if condition is met, Failure otherwise
+    return ENGINE.BehaviorStatus.Success;
+  }
+}
+```
+
+### Using Custom Behaviors in Code
+
+```typescript
+// Use your custom behaviors directly in behavior trees
+const customBehavior = new ENGINE.SelectorNode({
+  name: 'Custom Behavior'
+});
+customBehavior.addChildren([
+  new MyCustomAction({
+    customParameter: 'myValue',
+    customValue: 42,
+    conditions: [
+      new MyCustomCondition({ threshold: 15.0 })
+    ]
+  }),
+  new ENGINE.WanderAction({ wanderRadius: 10.0 })
+]);
+
+// Apply to NPC
+const behaviorTree = new ENGINE.BehaviorTreeComponent({
+  rootNode: customBehavior,
+  updateInterval: 0.1,
+  autoStart: true
+});
+npc.addComponents(behaviorTree);
+this.world.addActors(npc);
+```
+
+### Registering for JSON Support (Optional)
+
+If you want to use your custom behaviors in JSON files, register them:
+
+```typescript
+// src/ai/registerCustomBehaviors.ts
+import * as ENGINE from 'genesys.js';
+import { MyCustomAction } from './actions/MyCustomAction.js';
+import { MyCustomCondition } from './conditions/MyCustomCondition.js';
+
+export function registerCustomBehaviors(): void {
+  // Register custom actions
+  ENGINE.BehaviorTreeLoader.registerNodeType('MyCustomAction', MyCustomAction as any);
+  
+  // Register custom conditions
+  ENGINE.BehaviorTreeLoader.registerConditionType('MyCustomCondition', MyCustomCondition as any);
+  
+  console.log('Custom behavior tree types registered');
+}
+
+// Initialize in your game
+export class MyGame extends ENGINE.BaseGameLoop {
+  constructor(container: HTMLElement) {
+    super(container);
+    
+    // Register custom types BEFORE loading JSON behavior trees
+    registerCustomBehaviors();
+  }
+}
+```
+
+---
+
+## 10. Built-in Actions and Conditions
+
+### Actions by Category
+
+All actions use **blackboard keys** for actor references.
+
+#### Ground Actions (NavMesh-based)
+| Action | Description | Key Properties |
+|--------|-------------|----------------|
+| `MoveToPositionAction` | Move to a specific position | `targetPositionKey`, `useNavigation` |
+| `FollowActorAction` | Follow another actor | `targetActorKey`, `followDistance`, `useNavigation` |
+| `SetNextWaypointAction` | Cycle through patrol points | `waypointsKey`, `targetPositionKey`, `loop` |
+| `FleeFromTargetAction` | Flee from a target actor | `targetActorKey`, `fleeDistance`, `fleeSpeedMultiplier` |
+| `WanderAction` | Random ground movement | `wanderRadius` |
+
+#### Aerial Actions (3D flying)
+| Action | Description | Key Properties |
+|--------|-------------|----------------|
+| `AerialMoveToTargetAction` | Move to target in 3D space | `targetActorKey`, `hoverAboveTarget`, `hoverHeightOffset` |
+| `AerialSearchAction` | Search around last known position | `lastKnownPositionKey`, `searchRadius`, `searchDuration` |
+| `AerialTrackTargetAction` | Continuously track target position | `targetActorKey`, `lastKnownPositionKey`, `updateInterval` |
+| `AerialWanderAction` | Random 3D movement in sky | `wanderRadius`, `wanderHeight`, `heightVariation` |
+
+#### Combat Actions
+| Action | Description | Key Properties |
+|--------|-------------|----------------|
+| `MeleeAttackAction` | Attack target at close range | `targetActorKey` |
+| `ShootAction` | Fire projectile weapon at target | `targetActorKey`, `shootRange`, `aimDuration` |
+
+#### Utility Actions
+| Action | Description | Key Properties |
+|--------|-------------|----------------|
+| `LookAtTargetAction` | Rotate to face a target | `targetActorKey` |
+| `WaitAction` | Wait for a specified duration | `duration` |
+| `CalculateTacticalPositionAction` | Calculate tactical positions relative to targets | `targetActorKey`, `outputPositionKey`, `distance` |
+
+### Conditions
+
+All conditions use **blackboard keys** for actor references and support **invert** functionality.
+
+| Condition | Description | Key Properties |
+|-----------|-------------|----------------|
+| `IsPlayerNearCondition` | Check player distance | `range` |
+| `CanSeeTargetCondition` | Line-of-sight check | `targetActorKey`, `maxDistance` |
+| `TargetInConeCondition` | Check target in field of view | `targetActorKey`, `coneAngle`, `maxDistance` |
+| `HpAbovePercentCondition` | Check HP above threshold | `percentage`, `checkOwner` |
+| `TargetBelowHpPercentCondition` | Check target HP below threshold | `targetActorKey`, `percentage` |
+| `TimeLimitCondition` | Check within time limit | `timeLimit` |
+| `HasLastKnownPositionCondition` | Check if position is known | `positionKey` |
+
+---
+
+## 11. Best Practices
+
+1. **Prefer code-based behavior trees**: Use TypeScript/JavaScript for full type safety and IDE support
+2. **Use JSON for data-driven workflows**: Reserve JSON for when designers need to modify AI without code changes
+3. **Choose appropriate movement component**: Use `NpcMovementComponent` for ground-based NPCs, `AerialMovementComponent` for flying enemies
+4. **Use appropriate update intervals**: Balance AI responsiveness with performance
+5. **Start simple**: Begin with basic behaviors and build complexity gradually
+6. **Test incrementally**: Test each AI component individually before combining
+7. **Use modular design**: Prefer composing behaviors from simple actions
+8. **Set up blackboard properly**: Initialize all required actor references and values before starting behavior trees
+9. **Debug visually**: Use comprehensive debugging methods to understand AI behavior
+10. **Attach conditions wisely**: Use attached conditions to control when actions execute
+11. **Reuse condition evaluators**: Create reusable condition evaluators for common checks
+12. **Consistent naming**: Use consistent blackboard key names across behavior trees
+13. **Document blackboard schema**: Define expected blackboard values in behavior tree comments
+14. **Avoid indefinitely running custom actions**: Ensure all custom actions have completion conditions to prevent blocking the behavior tree
+15. **Use debugging tools extensively**: Leverage the comprehensive debugging methods to understand AI behavior and identify issues quickly
+16. **Monitor performance**: Track behavior tree execution times and optimize slow-running actions or conditions
+17. **Organize by action categories**: Use the organized action structure (ground, aerial, combat, utility) for better code organization
+
+---
+
+## Next Steps
+
+Now that you understand AI and behavior trees, you can combine them with navigation for complete AI systems. See the **[Navigation and Pathfinding Guide](15-navigation-and-pathfinding.md)** to learn about:
+
+- NavMesh generation and configuration
+- Ground-based pathfinding for NPCs
+- Performance optimization for navigation
+- Troubleshooting navigation issues
+
+This AI system provides sophisticated decision-making capabilities for your Genesys.js projects.
+
+---
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/npc/behavior-tree/BehaviorTreeComponent.ts}>
+<file path={src/components/movement/AerialMovementComponent.ts}>