Initial commit: Complete project foundation with all documentation, scripts, and project structure
This commit is contained in:
Dubai Metaverse Team
342
docs/NPC_BEHAVIOR.md
Normal file
342
docs/NPC_BEHAVIOR.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# 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]
|
||||
|
||||
Reference in New Issue
Block a user