metaverseDubai/docs/NPC_BEHAVIOR.md

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]