343 lines
7.3 KiB
Markdown
343 lines
7.3 KiB
Markdown
# 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]
|
|
|