# NPC Behavior System - Dubai Metaverse

## Overview

This document describes the NPC behavior system implementation using behavior trees and AI controllers.

## Behavior Tree System

### Overview

Behavior Trees are visual scripting systems for AI behavior. They define how NPCs make decisions and perform actions.

### Components

1. **Behavior Tree**: Visual graph defining behavior
2. **Blackboard**: Data storage for behavior
3. **Tasks**: Actions NPCs perform
4. **Decorators**: Conditions for behavior
5. **Services**: Periodic updates

---

## Behavior Trees

### BT_NPC_Wander

**Purpose**: NPCs wander around the district

#### Structure

```
Selector
├── Sequence (Move to Location)
│   ├── Decorator: Has Target Location?
│   ├── Task: Move to Location
│   └── Task: Wait at Location
└── Task: Find Random Location
```

#### Blackboard Variables

- **TargetLocation**: Vector (target location)
- **WaitTime**: Float (wait duration)
- **WanderRadius**: Float (wander area)

#### Tasks

- **FindRandomLocation**: Find random location within radius
- **MoveToLocation**: Move to target location
- **WaitAtLocation**: Wait at location for duration

#### Decorators

- **HasTargetLocation**: Check if target location exists
- **IsAtLocation**: Check if at target location

---

### BT_NPC_Social

**Purpose**: NPCs form groups and socialize

#### Structure

```
Selector
├── Sequence (Social Group)
│   ├── Decorator: In Social Group?
│   ├── Task: Maintain Group Formation
│   └── Task: Social Gestures
└── Task: Find Social Group
```

#### Blackboard Variables

- **GroupMembers**: Array (other NPCs in group)
- **GroupLocation**: Vector (group location)
- **ConversationState**: Enum (conversation state)

#### Tasks

- **FindSocialGroup**: Find nearby NPCs to group with
- **MaintainGroupFormation**: Maintain group formation
- **SocialGestures**: Perform social gestures
- **Conversation**: Simulate conversation

#### Decorators

- **InSocialGroup**: Check if in social group
- **NearOtherNPCs**: Check if near other NPCs

---

### BT_NPC_Phone

**Purpose**: NPCs use phones

#### Structure

```
Selector
├── Sequence (Use Phone)
│   ├── Decorator: Should Use Phone?
│   ├── Task: Stop Movement
│   └── Task: Use Phone Animation
└── Task: Continue Movement
```

#### Blackboard Variables

- **PhoneUsageState**: Enum (using phone, not using)
- **PhoneUsageTime**: Float (phone usage duration)
- **LastPhoneUsage**: Float (time since last usage)

#### Tasks

- **StartPhoneUsage**: Start using phone
- **UsePhoneAnimation**: Play phone usage animation
- **StopPhoneUsage**: Stop using phone
- **WalkWithPhone**: Walk while using phone (optional)

#### Decorators

- **ShouldUsePhone**: Check if should use phone
- **IsUsingPhone**: Check if currently using phone

---

## NPC Controller

### BP_NPCController

**AI controller for NPCs**

### Components

1. **Behavior Tree Component**: Reference to behavior tree
2. **Blackboard Component**: NPC state and data
3. **Perception Component**: AI perception
4. **Path Following Component**: Path following

### Settings

#### Behavior Tree

- **Behavior Tree Asset**: Assign behavior tree
- **Start Behavior**: Auto-start behavior tree

#### Blackboard

- **Blackboard Asset**: Assign blackboard
- **Initial Values**: Set initial values

#### Perception

- **Sight Config**: Configure sight perception
- **Hearing Config**: Configure hearing perception (optional)
- **Perception Range**: Set perception range

#### Movement

- **Movement Speed**: Set movement speed
- **Acceleration**: Set acceleration
- **Rotation Rate**: Set rotation rate

---

## Blackboard Variables

### Common Variables

- **TargetLocation**: Vector (target location)
- **CurrentState**: Enum (current behavior state)
- **WaitTime**: Float (wait duration)
- **LastUpdate**: Float (time since last update)

### Social Variables

- **GroupMembers**: Array (group members)
- **GroupLocation**: Vector (group location)
- **ConversationState**: Enum (conversation state)

### Phone Variables

- **PhoneUsageState**: Enum (phone usage state)
- **PhoneUsageTime**: Float (phone usage duration)

---

## Task Implementation

### Movement Tasks

#### MoveToLocation

- **Purpose**: Move NPC to target location
- **Implementation**: Use AI Move To node
- **Parameters**: Target location, acceptance radius

#### WaitAtLocation

- **Purpose**: Wait at location for duration
- **Implementation**: Wait for specified time
- **Parameters**: Wait duration

### Social Tasks

#### FindSocialGroup

- **Purpose**: Find nearby NPCs to group with
- **Implementation**: Query nearby NPCs
- **Parameters**: Search radius, max group size

#### MaintainGroupFormation

- **Purpose**: Maintain group formation
- **Implementation**: Adjust position relative to group
- **Parameters**: Formation type, spacing

### Phone Tasks

#### StartPhoneUsage

- **Purpose**: Start using phone
- **Implementation**: Set phone usage state, play animation
- **Parameters**: Phone usage duration

#### UsePhoneAnimation

- **Purpose**: Play phone usage animation
- **Implementation**: Play animation blueprint
- **Parameters**: Animation type

---

## Decorator Implementation

### Condition Decorators

#### HasTargetLocation

- **Purpose**: Check if target location exists
- **Implementation**: Check blackboard variable
- **Returns**: True if target location exists

#### IsAtLocation

- **Purpose**: Check if at target location
- **Implementation**: Check distance to target
- **Returns**: True if within acceptance radius

#### ShouldUsePhone

- **Purpose**: Check if should use phone
- **Implementation**: Check time since last usage, random chance
- **Returns**: True if should use phone

---

## Performance Optimization

### Behavior Tree Optimization

1. **Update Frequency**: Optimize behavior tree tick rate
2. **Task Efficiency**: Optimize task execution
3. **Decorator Efficiency**: Optimize decorator checks
4. **Blackboard**: Minimize blackboard updates

### Perception Optimization

1. **Perception Range**: Limit perception range
2. **Update Frequency**: Optimize perception updates
3. **Filtering**: Filter perception results

### Pathfinding Optimization

1. **Pathfinding Frequency**: Optimize pathfinding updates
2. **Path Length**: Limit path length
3. **Caching**: Cache paths when possible

---

## Testing

### Behavior Testing

1. **Wander Behavior**: Test NPCs wander correctly
2. **Social Behavior**: Test NPCs form groups
3. **Phone Behavior**: Test NPCs use phones
4. **Transitions**: Test behavior transitions

### Performance Testing

1. **NPC Count**: Test with different NPC counts
2. **Frame Rate**: Test frame rate impact
3. **Memory**: Test memory usage

---

## Troubleshooting

### Common Issues

**Issue**: NPCs not moving
- **Solution**: Check behavior tree is assigned
- **Solution**: Verify movement component

**Issue**: Behavior not executing
- **Solution**: Check behavior tree setup
- **Solution**: Verify blackboard variables

**Issue**: Performance issues
- **Solution**: Optimize behavior tree updates
- **Solution**: Reduce NPC count
- **Solution**: Optimize perception

---

## Documentation

### Behavior Documentation

Document each behavior tree:
- Purpose
- Structure
- Blackboard variables
- Tasks and decorators
- Usage

### NPC Catalog

Document NPC types:
- Appearance
- Behavior
- Placement
- Usage

---

**Version**: 1.0
**Last Updated**: [Current Date]