d-bis/metaverseDubai
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: commit untracked UE/scaffold files (repo cleanup triage 20260707)

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Dubai Metaverse Team
2026-07-07 03:43:19 -07:00
parent b9c4978802
commit 9629838469
147 changed files with 26523 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
docs/systems/DAY_NIGHT_CYCLE.md Normal file
View File

@@ -0,0 +1,348 @@
# Day/Night Cycle System - Dubai Metaverse
## Overview
This document describes the day/night cycle system implementation for the Dubai Metaverse project.
## System Architecture
### BP_DayNightCycle Blueprint
**Purpose**: Central controller for time of day and lighting transitions
### Components
1. **Time Variable**: Float (0-24 hours)
2. **Sun Controller**: Controls directional light rotation
3. **Sky Controller**: Controls sky color and atmosphere
4. **Light Controller**: Controls light intensity and color
5. **Event System**: Triggers events at specific times
---
## Time System
### Time Format
- **Range**: 0.0 - 24.0 (hours)
- **Precision**: Float (allows smooth transitions)
- **Update**: Real-time or accelerated time
### Time Progression
- **Real-Time**: 1:1 with real time (optional)
- **Accelerated**: Faster time progression for demo
- **Manual Control**: Manual time adjustment for testing
---
## Time of Day Presets
### Sunrise (6:00-8:00)
**Duration**: 2 hours
**Lighting**:
- **Sun Intensity**: 4-6 lux (increasing)
- **Sun Color**: Warm orange/red → white
- **Sky Color**: Warm, dramatic → clear
- **Temperature**: 4000K → 5500K
**Atmosphere**:
- **Fog Density**: Medium
- **Fog Color**: Warm orange
- **Volumetric**: Enhanced
**Post-Process**:
- **Color Grading**: Warm LUT
- **Bloom**: Enhanced
- **Saturation**: High
---
### Daytime (8:00-17:00)
**Duration**: 9 hours
**Lighting**:
- **Sun Intensity**: 8-12 lux (peak at noon)
- **Sun Color**: White
- **Sky Color**: Clear blue
- **Temperature**: 6500K-7500K
**Atmosphere**:
- **Fog Density**: Low
- **Fog Color**: Neutral
- **Volumetric**: Subtle
**Post-Process**:
- **Color Grading**: Natural LUT
- **Bloom**: Moderate
- **Saturation**: Natural
**Characteristics**:
- Harsh, direct sunlight
- Strong shadows
- High contrast
- Clear visibility
---
### Sunset (17:00-19:00)
**Duration**: 2 hours
**Lighting**:
- **Sun Intensity**: 4-6 lux (decreasing)
- **Sun Color**: White → warm orange/red
- **Sky Color**: Clear → warm, dramatic
- **Temperature**: 6500K → 4000K
**Atmosphere**:
- **Fog Density**: Medium
- **Fog Color**: Warm orange
- **Volumetric**: Enhanced
**Post-Process**:
- **Color Grading**: Warm LUT
- **Bloom**: Enhanced
- **Saturation**: High
**Characteristics**:
- Warm, dramatic lighting
- Long shadows
- High contrast
- Atmospheric
---
### Night (19:00-6:00)
**Duration**: 11 hours
**Lighting**:
- **Sun Intensity**: 0-1 lux (moonlight)
- **Sun Color**: Cool blue
- **Sky Color**: Dark, starry
- **Temperature**: 8000K-10000K
**Atmosphere**:
- **Fog Density**: Low
- **Fog Color**: Cool blue/gray
- **Volumetric**: Subtle
**Post-Process**:
- **Color Grading**: Cool LUT
- **Bloom**: Enhanced (neon lights)
- **Saturation**: Reduced
**Artificial Lighting**:
- **Neon Signs**: Bright, saturated colors
- **Street Lights**: Warm, yellow
- **Building Lights**: Interior lights visible
- **Marina Lights**: Reflected in water
**Characteristics**:
- Cool, atmospheric lighting
- Soft shadows
- Low contrast
- Neon accents
---
## Implementation
### Blueprint Setup
1. **Create BP_DayNightCycle**:
- Create Blueprint class
- Add time variable
- Add event tick or timer
2. **Sun Rotation**:
- Calculate sun rotation based on time
- Rotate directional light
- Adjust sun intensity
3. **Sky Color**:
- Interpolate sky color based on time
- Use curve or lerp
- Update sky light
4. **Light Intensity**:
- Interpolate light intensity based on time
- Use curve for smooth transitions
- Update directional light
5. **Atmosphere**:
- Adjust fog density based on time
- Adjust fog color based on time
- Update exponential height fog
6. **Post-Process**:
- Switch LUTs based on time
- Adjust post-process settings
- Update post-process volume
### Curves
**Use Curves for Smooth Transitions**:
- **Sun Intensity Curve**: Float curve
- **Sun Color Curve**: Vector curve (RGB)
- **Sky Color Curve**: Vector curve (RGB)
- **Fog Density Curve**: Float curve
---
## Transitions
### Smooth Transitions
**Interpolation**:
- Use linear interpolation (lerp) for smooth transitions
- Use curves for natural transitions
- Update every frame or at intervals
**Transition Duration**:
- **Sunrise/Sunset**: 2 hours (smooth transition)
- **Day/Night**: Gradual transition
- **Avoid**: Abrupt changes
### Event Triggers
**Events at Specific Times**:
- **6:00 AM**: Sunrise start
- **8:00 AM**: Daytime start
- **5:00 PM**: Sunset start
- **7:00 PM**: Night start
**Use Cases**:
- Trigger NPC behavior changes
- Trigger audio changes
- Trigger particle effects
---
## Testing
### Manual Testing
1. **Time Control**:
- Add manual time control (slider)
- Test each time of day
- Verify transitions
2. **Visual Validation**:
- Compare to reference photos
- Verify lighting matches Dubai aesthetic
- Check transitions are smooth
3. **Performance Testing**:
- Test performance at different times
- Verify no performance issues
- Optimize if needed
### Automated Testing
- Use `scripts/lighting_validation.py` to validate:
- Time transitions
- Light intensity values
- Color values
- Performance
---
## Performance Considerations
### Optimization
1. **Update Frequency**:
- Update every frame (smooth)
- Or update at intervals (performance)
2. **Interpolation**:
- Use efficient interpolation
- Cache values when possible
3. **Light Updates**:
- Batch light updates
- Update only when needed
---
## Dubai-Specific Considerations
### Climate
- **Desert Climate**: Hot, dry, clear skies
- **Sun Intensity**: Very high during day
- **Heat Haze**: Visible during day
- **Clear Nights**: Clear, starry nights
### Lighting Characteristics
- **Daytime**: Harsh, direct sunlight
- **Sunset**: Dramatic, warm colors
- **Night**: Cool, clear with artificial lights
- **Reflections**: Strong reflections from glass
---
## Integration
### With Other Systems
1. **NPCs**: NPC behavior may change based on time
2. **Vehicles**: Vehicle lights at night
3. **Audio**: Ambient audio changes with time
4. **Particles**: Particle effects (dust, heat haze) based on time
### With Cinematics
- **Time Control**: Set specific time for cinematic shots
- **Transitions**: Use time transitions in cinematics
- **Consistency**: Maintain time consistency across shots
---
## Troubleshooting
### Common Issues
**Issue**: Transitions not smooth
- **Solution**: Use curves for interpolation
- **Solution**: Increase update frequency
**Issue**: Lighting doesn't match reference
- **Solution**: Adjust color values
- **Solution**: Adjust intensity values
**Issue**: Performance issues
- **Solution**: Reduce update frequency
- **Solution**: Optimize interpolation
---
## Documentation
### Parameters
Document all exposed parameters:
- Time variable
- Sun rotation
- Light intensity
- Color values
- Transition curves
### Usage
Document how to use the system:
- How to set time
- How to adjust transitions
- How to add new time presets
---
**Version**: 1.0
**Last Updated**: 2024-11-21

223
docs/systems/FACIAL_CAPTURE.md Normal file
View File

@@ -0,0 +1,223 @@
# Facial Capture - MetaHuman Animator
## Overview
This document describes the facial capture workflow using MetaHuman Animator for the Dubai Metaverse project.
## MetaHuman Animator
### Overview
MetaHuman Animator is a tool for capturing facial animation from video or live performance and applying it to MetaHumans in Unreal Engine.
### Requirements
- **MetaHuman Animator Plugin**: Enable in Unreal Engine
- **Camera**: High-quality camera (webcam, DSLR, or phone)
- **Lighting**: Good lighting conditions
- **Calibration**: Facial calibration process
---
## Setup
### Plugin Installation
1. **Enable Plugin**:
- Edit > Plugins
- Search for "MetaHuman Animator"
- Enable plugin
- Restart editor
2. **Verify Installation**:
- Check plugin is active
- Verify MetaHuman Animator tools are available
### Camera Setup
1. **Camera Selection**:
- **Webcam**: Basic setup
- **DSLR**: Higher quality
- **Phone**: Convenient option
2. **Lighting**:
- **Even Lighting**: Avoid harsh shadows
- **Front Lighting**: Light from front
- **Avoid Backlighting**: Avoid strong backlighting
3. **Positioning**:
- **Distance**: 2-3 feet from camera
- **Angle**: Face camera directly
- **Stability**: Keep head still
---
## Calibration
### Calibration Process
1. **Start Calibration**:
- Open MetaHuman Animator
- Start calibration process
- Follow on-screen instructions
2. **Calibration Steps**:
- **Neutral Expression**: Maintain neutral expression
- **Head Movement**: Follow head movement instructions
- **Facial Expressions**: Perform requested expressions
- **Completion**: Complete calibration
3. **Calibration Validation**:
- Review calibration quality
- Re-calibrate if needed
- Save calibration
---
## Recording
### Live Performance
1. **Start Recording**:
- Begin live performance
- Speak dialogue
- Perform expressions
2. **Performance Tips**:
- **Clear Speech**: Speak clearly
- **Natural Expressions**: Use natural facial expressions
- **Head Movement**: Natural head movement
- **Eye Contact**: Look at camera
3. **Stop Recording**:
- Stop recording when complete
- Review performance
- Process if satisfied
### Video Recording
1. **Record Video**:
- Record video of performance
- Ensure good quality
- Follow recording guidelines
2. **Import Video**:
- Import video to MetaHuman Animator
- Process video
- Extract facial animation
---
## Processing
### Animation Processing
1. **Process Performance**:
- MetaHuman Animator processes performance
- Extracts facial animation
- Generates animation data
2. **Review Animation**:
- Review processed animation
- Check quality
- Refine if needed
3. **Export Animation**:
- Export animation to Unreal Engine
- Apply to MetaHuman
- Test in level
---
## Application
### Apply to MetaHuman
1. **Select MetaHuman**:
- Select MetaHuman in level
- Open MetaHuman Animator
2. **Apply Animation**:
- Apply captured animation
- Preview animation
- Adjust if needed
3. **Integration**:
- Integrate with dialogue system
- Sync with audio
- Test in context
---
## Best Practices
### Recording
1. **Quality**: Ensure good recording quality
2. **Lighting**: Use good lighting
3. **Stability**: Keep head stable
4. **Natural**: Use natural expressions
### Processing
1. **Calibration**: Ensure good calibration
2. **Review**: Review processed animation
3. **Refinement**: Refine if needed
4. **Testing**: Test in context
---
## Troubleshooting
### Common Issues
**Issue**: Calibration fails
- **Solution**: Check lighting conditions
- **Solution**: Ensure face is clearly visible
- **Solution**: Follow calibration instructions carefully
**Issue**: Animation quality poor
- **Solution**: Improve recording quality
- **Solution**: Re-calibrate
- **Solution**: Check lighting
**Issue**: Animation not applying
- **Solution**: Check MetaHuman Animator plugin
- **Solution**: Verify animation export
- **Solution**: Check MetaHuman setup
---
## Use Cases
### NPC Dialogue
- **Purpose**: Animate NPCs during dialogue
- **Implementation**: Capture dialogue performance
- **Application**: Apply to MetaHuman NPCs
### Cinematic Sequences
- **Purpose**: Animate characters in cinematics
- **Implementation**: Capture performance for cinematics
- **Application**: Apply to cinematic MetaHumans
---
## Documentation
### Performance Documentation
Document each performance:
- **Purpose**: What the performance is for
- **MetaHuman**: Which MetaHuman it's applied to
- **Context**: Where it's used
- **Quality**: Animation quality notes
---
**Version**: 1.0
**Last Updated**: 2024-11-21
**Note**: Facial capture is optional. NPCs can function without facial capture using standard animation.

302
docs/systems/LIGHTING_SETUP.md Normal file
View File

@@ -0,0 +1,302 @@
# Lighting Setup - Dubai Metaverse
## Overview
This document describes the lighting setup for the Dubai Metaverse project, including Lumen global illumination, day/night cycle, and atmospheric effects.
## Lighting System: Lumen
### Lumen Overview
Lumen is Unreal Engine 5's fully dynamic global illumination and reflections system. It provides realistic lighting without pre-baking lightmaps.
### Lumen Configuration
#### Global Illumination
- **Method**: Lumen Global Illumination
- **Quality**: Epic (or High if performance issues)
- **Settings**:
- Final Gather Quality: High
- View Distance: Maximum
- Detail: High
#### Reflections
- **Method**: Lumen Reflections
- **Quality**: Epic (or High if performance issues)
- **Settings**:
- Reflection Quality: High
- Ray Tracing: Optional (if RTX GPU available)
---
## Sky and Atmosphere
### HDRI Sky Setup
1. **Create Sky Light**:
- Add Sky Light actor to level
- Configure as BP_SkyLight
2. **HDRI Setup**:
- Import Dubai-specific HDRI sky
- Assign to sky light
- Adjust intensity
3. **Sky Settings**:
- **Source Type**: SLS Captured Scene or SLS Specified Cubemap
- **Intensity**: 1.0 (adjust as needed)
- **Light Color**: White (or adjust for time of day)
### Directional Light (Sun)
1. **Create Directional Light**:
- Add Directional Light actor
- Configure as BP_DirectionalLight
2. **Sun Settings**:
- **Intensity**: 8-12 lux (daytime)
- **Light Color**: Warm white (daytime), warm orange (sunset)
- **Temperature**: 5500K-7500K (daytime), 4000K-5000K (sunset)
- **Cast Shadows**: Enabled
- **Shadow Resolution**: Virtual Shadow Maps
3. **Sun Position**:
- Controlled by day/night cycle system
- Rotates based on time of day
---
## Day/Night Cycle System
### BP_DayNightCycle Blueprint
**Purpose**: Control time of day and lighting transitions
### Time Settings
- **Sunrise**: 6:00 AM
- **Daytime Start**: 8:00 AM
- **Sunset Start**: 5:00 PM
- **Night Start**: 7:00 PM
- **Night End**: 6:00 AM
### Implementation
1. **Time Variable**: Float variable for time (0-24 hours)
2. **Sun Rotation**: Rotate directional light based on time
3. **Sky Color**: Adjust sky color based on time
4. **Light Intensity**: Adjust light intensity based on time
5. **Atmosphere**: Adjust atmosphere based on time
### Time of Day Presets
#### Sunrise (6:00-8:00)
- **Sun Intensity**: 4-6 lux
- **Sun Color**: Warm orange/red
- **Sky Color**: Warm, dramatic
- **Temperature**: 4000K-5000K
#### Daytime (8:00-17:00)
- **Sun Intensity**: 8-12 lux
- **Sun Color**: White
- **Sky Color**: Clear blue
- **Temperature**: 6500K-7500K
#### Sunset (17:00-19:00)
- **Sun Intensity**: 4-6 lux
- **Sun Color**: Warm orange/red
- **Sky Color**: Warm, dramatic
- **Temperature**: 4000K-5000K
#### Night (19:00-6:00)
- **Sun Intensity**: 0-1 lux (moonlight)
- **Sun Color**: Cool blue
- **Sky Color**: Dark, starry
- **Temperature**: 8000K-10000K
---
## Atmospheric Effects
### Volumetric Fog
1. **Create Exponential Height Fog**:
- Add Exponential Height Fog actor
- Configure as BP_Atmosphere
2. **Fog Settings**:
- **Density**: 0.02-0.05 (subtle)
- **Fog Height Falloff**: 0.2
- **Fog Inscattering Color**: Slight blue/gray
- **Fog Max Opacity**: 0.5-0.7
3. **Purpose**:
- Atmospheric perspective
- Humidity simulation
- Depth enhancement
### Heat Haze
1. **Create Heat Haze Material**:
- Material: MFX_HeatHaze
- Type: Post-process or material function
2. **Heat Haze Settings**:
- **Distortion Intensity**: Subtle
- **Distance Falloff**: Distance-based
- **Application**: Above hot surfaces (roads, buildings)
3. **Implementation**:
- Apply as post-process effect
- Or as material on surfaces
---
## Post-Process Settings
### PP_DubaiCinematic Post-Process Volume
**Purpose**: Cinematic color grading and effects
### Settings
#### Bloom
- **Intensity**: 0.5-1.0
- **Threshold**: 1.0
- **Tint**: Slight warm tint
#### Chromatic Aberration
- **Intensity**: 0.1-0.2 (subtle)
- **Start Offset**: 0.0
#### Depth of Field
- **Method**: Gaussian
- **Focal Distance**: Camera-based
- **Focal Region**: 1000-5000
- **Near Transition Region**: 500
- **Far Transition Region**: 1000
#### Color Grading
**Time-of-Day LUTs**:
- **Sunrise LUT**: Warm, dramatic
- **Daytime LUT**: Natural, slightly enhanced
- **Sunset LUT**: Warm, high saturation
- **Night LUT**: Cool, reduced saturation
**Settings**:
- **Saturation**: 1.0-1.2 (slightly enhanced)
- **Contrast**: 1.0-1.1
- **Gamma**: 1.0
---
## Lighting Calibration
### Dubai-Specific Lighting
#### Characteristics
1. **Intense Sunlight**: Harsh, direct sunlight during day
2. **Strong Shadows**: Sharp shadows with high contrast
3. **Reflective Surfaces**: Glass buildings create strong reflections
4. **Heat Haze**: Visible distortion above hot surfaces
5. **Artificial Lighting**: Neon and LED at night
#### Calibration Steps
1. **Reference Comparison**: Compare to Dubai reference photos
2. **Light Intensity**: Adjust to match reference
3. **Shadow Quality**: Ensure sharp, high-contrast shadows
4. **Reflections**: Verify glass reflections are strong
5. **Color Temperature**: Match Dubai lighting color
---
## Performance Optimization
### Lumen Quality Settings
- **Final Gather Quality**: Adjust based on performance
- **Reflection Quality**: Adjust based on performance
- **View Distance**: Optimize for performance
### Shadow Optimization
- **Virtual Shadow Maps**: Use for performance
- **Shadow Resolution**: Adjust based on performance
- **Shadow Distance**: Optimize shadow distance
### Light Optimization
- **Light Count**: Minimize dynamic lights
- **Light Complexity**: Optimize light complexity
- **Culling**: Use distance culling
---
## Validation Checklist
### Lighting Setup
- [ ] Lumen GI enabled and working
- [ ] Lumen Reflections enabled and working
- [ ] Sky light configured
- [ ] Directional light configured
- [ ] Day/night cycle working
- [ ] Atmospheric fog configured
- [ ] Post-process volume configured
### Quality Validation
- [ ] Lighting matches Dubai aesthetic
- [ ] Day/night transitions are smooth
- [ ] Shadows are realistic
- [ ] Reflections are accurate
- [ ] Performance is acceptable
---
## Troubleshooting
### Common Issues
**Issue**: Lighting too bright/dark
- **Solution**: Adjust light intensity
- **Solution**: Adjust exposure settings
**Issue**: Shadows not appearing
- **Solution**: Check shadow settings
- **Solution**: Verify Virtual Shadow Maps enabled
**Issue**: Reflections not working
- **Solution**: Check Lumen Reflections enabled
- **Solution**: Verify reflection quality settings
**Issue**: Performance issues
- **Solution**: Lower Lumen quality settings
- **Solution**: Optimize shadow settings
- **Solution**: Reduce light count
---
## Tools
### Lighting Tools
- **Unreal Editor**: Primary lighting tool
- **Lumen**: Global illumination system
- **Post-Process Volume**: Color grading and effects
### Validation Tools
- **Unreal Insights**: Performance profiling
- **Lighting Validation Script**: `scripts/lighting_validation.py`
---
**Version**: 1.0
**Last Updated**: 2024-11-21

358
docs/systems/METAHUMAN_PIPELINE.md Normal file
View File

@@ -0,0 +1,358 @@
# MetaHuman Pipeline - Dubai Metaverse
## Overview
This document describes the MetaHuman creation and integration pipeline for the Dubai Metaverse project.
## MetaHuman Framework
### What are MetaHumans?
MetaHumans are Unreal Engine's high-fidelity digital humans created using the MetaHuman Creator. They provide photorealistic human characters with advanced facial animation capabilities.
### MetaHuman Creator
**Tool**: MetaHuman Creator (web-based or plugin)
**Features**:
- High-quality human models
- Extensive customization
- Realistic facial features
- Hair and clothing options
---
## MetaHuman Creation
### Step 1: Access MetaHuman Creator
1. **Epic Games Account**: Sign in to Epic Games account
2. **MetaHuman Creator**: Access via web or Unreal plugin
3. **Create New MetaHuman**: Start new MetaHuman creation
### Step 2: Base Character
1. **Preset Selection**: Choose base preset
2. **Gender**: Select gender
3. **Age**: Adjust age
4. **Ethnicity**: Select ethnicity (Dubai multicultural mix)
### Step 3: Facial Features
1. **Face Shape**: Adjust face shape
2. **Eyes**: Customize eyes
3. **Nose**: Customize nose
4. **Mouth**: Customize mouth
5. **Ears**: Customize ears
6. **Skin**: Adjust skin tone and features
### Step 4: Hair and Appearance
1. **Hair**: Select hair style and color
2. **Eyebrows**: Customize eyebrows
3. **Facial Hair**: Add facial hair (if applicable)
4. **Makeup**: Add makeup (if applicable)
### Step 5: Clothing
1. **Outfit**: Select clothing style
2. **Colors**: Adjust clothing colors
3. **Accessories**: Add accessories (optional)
### Step 6: Export
1. **Review**: Review MetaHuman
2. **Export**: Export to Unreal Engine
3. **Save**: Save MetaHuman asset
---
## Import to Unreal Engine
### Import Process
1. **MetaHuman Plugin**: Ensure MetaHuman plugin is enabled
2. **Import**: Import MetaHuman from MetaHuman Creator
3. **Validation**: Verify import is successful
4. **Placement**: Place in level
### Asset Organization
```
Content/Assets/Characters/MetaHumans/
├── MH_Dubai_01/
│ ├── SK_Character_Male_01
│ ├── [Animation assets]
│ └── [Material assets]
├── MH_Dubai_02/
└── ...
```
---
## Animation Setup
### Animation Blueprints
#### ABP_NPC_Walk
**Walking animation blueprint**
- **Locomotion**: Walking animations
- **Blend Spaces**: Speed-based blending
- **Transitions**: Smooth transitions
#### ABP_NPC_Sit
**Sitting animation blueprint**
- **Idle Sitting**: Sitting idle animations
- **Sitting Variations**: Different sitting poses
#### ABP_NPC_Phone
**Phone usage animation blueprint**
- **Phone Usage**: Using phone animations
- **Variations**: Different phone poses
#### ABP_NPC_Gestures
**Gesture animation blueprint**
- **Gestures**: Hand gestures, talking
- **Variations**: Different gesture types
### Animation Assets
- **AM_Walking**: Walking animation
- **AM_Sitting**: Sitting animation
- **AM_PhoneUsage**: Phone usage animation
- **AM_Gestures**: Gesture animations
---
## Behavior Trees
### BT_NPC_Wander
**Wandering behavior for NPCs**
#### Behavior
1. **Random Movement**: Move to random locations
2. **Wait**: Wait at locations
3. **Repeat**: Repeat wandering pattern
#### Implementation
- **Blackboard**: Store target location
- **Tasks**: Move to location, wait
- **Decorators**: Conditions for behavior
### BT_NPC_Social
**Social behavior for NPCs**
#### Behavior
1. **Group Formation**: Form groups with other NPCs
2. **Conversation**: Simulate conversation
3. **Gestures**: Use gestures during conversation
#### Implementation
- **Blackboard**: Store group members, conversation state
- **Tasks**: Group formation, conversation
- **Decorators**: Social conditions
### BT_NPC_Phone
**Phone usage behavior**
#### Behavior
1. **Phone Usage**: Use phone at intervals
2. **Walking with Phone**: Walk while using phone
3. **Stop and Use**: Stop to use phone
#### Implementation
- **Blackboard**: Store phone usage state
- **Tasks**: Phone usage, movement
- **Decorators**: Phone usage conditions
---
## NPC Controller
### BP_NPCController
**AI controller for NPCs**
### Components
1. **Behavior Tree**: Reference to behavior tree
2. **Blackboard**: NPC state and data
3. **Perception**: AI perception (sight, hearing)
4. **Movement**: AI movement component
### Settings
- **Behavior Tree**: Assign behavior tree
- **Perception**: Configure perception settings
- **Movement**: Configure movement settings
---
## ChatGPT Integration (Optional)
### BP_DialogueSystem
**ChatGPT-powered dialogue system**
### Implementation
1. **API Integration**: Integrate ChatGPT API
2. **Dialogue Generation**: Generate dynamic dialogue
3. **NPC Responses**: NPC responds to player
4. **Context Awareness**: Context-aware dialogue
### Setup
1. **API Key**: Store API key securely (not in repository)
2. **API Client**: Create API client
3. **Dialogue Handler**: Handle dialogue requests
4. **Response Processing**: Process API responses
### Usage
1. **Player Interaction**: Player interacts with NPC
2. **Dialogue Request**: Request dialogue from ChatGPT
3. **NPC Response**: NPC speaks generated dialogue
4. **Continuation**: Continue conversation
---
## MetaHuman Animator
### Facial Capture
**Purpose**: Capture facial animation for MetaHumans
### Setup
1. **MetaHuman Animator Plugin**: Enable plugin
2. **Camera Setup**: Set up camera for capture
3. **Calibration**: Calibrate facial capture
4. **Recording**: Record facial animation
### Usage
1. **Record**: Record facial performance
2. **Process**: Process facial capture
3. **Apply**: Apply to MetaHuman
4. **Refine**: Refine animation
---
## NPC Placement
### Placement Strategy
1. **Density**: Moderate NPC density
2. **Distribution**: Distribute across district
3. **Groups**: Place NPCs in social groups
4. **Activities**: Place NPCs in activity areas
### Areas
- **Marina Promenade**: Pedestrians walking
- **Cafes**: NPCs sitting, socializing
- **Roads**: NPCs walking along roads
- **Parks**: NPCs in parks, green spaces
---
## Performance Optimization
### NPC Optimization
1. **LODs**: Use LODs for distant NPCs
2. **Culling**: Cull NPCs outside view
3. **Instancing**: Use instanced meshes where possible
4. **Animation**: Optimize animation complexity
### Behavior Optimization
1. **Update Frequency**: Optimize behavior tree updates
2. **Perception**: Optimize perception checks
3. **Pathfinding**: Optimize pathfinding
---
## Testing
### NPC Testing
1. **Behavior**: Test NPC behavior
2. **Animation**: Test animations
3. **Performance**: Test performance with NPCs
4. **Interactions**: Test NPC interactions
### Dialogue Testing
1. **ChatGPT Integration**: Test API integration
2. **Dialogue Quality**: Test dialogue quality
3. **Response Time**: Test response time
4. **Context**: Test context awareness
---
## Troubleshooting
### Common Issues
**Issue**: MetaHuman not importing
- **Solution**: Check MetaHuman plugin is enabled
- **Solution**: Verify MetaHuman Creator connection
**Issue**: Animations not working
- **Solution**: Check animation blueprint setup
- **Solution**: Verify animation assets are assigned
**Issue**: Behavior tree not executing
- **Solution**: Check behavior tree assignment
- **Solution**: Verify blackboard setup
**Issue**: Performance issues
- **Solution**: Reduce NPC count
- **Solution**: Use LODs
- **Solution**: Optimize behavior trees
---
## Documentation
### MetaHuman Catalog
Document each MetaHuman:
- Name
- Appearance
- Clothing
- Behavior
- Usage
### Behavior Documentation
Document behavior trees:
- Behavior description
- Blackboard variables
- Tasks and decorators
- Usage
---
**Version**: 1.0
**Last Updated**: 2024-11-21

342
docs/systems/NPC_BEHAVIOR.md Normal file
View 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**: 2024-11-21

285
docs/systems/NPC_DIALOGUE.md Normal file
View File

@@ -0,0 +1,285 @@
# NPC Dialogue System - Dubai Metaverse
## Overview
This document describes the ChatGPT-powered dynamic dialogue system for NPCs in the Dubai Metaverse project (optional feature).
## System Architecture
### Overview
The dialogue system integrates ChatGPT API to generate dynamic, context-aware dialogue for NPCs, allowing for natural conversations with players.
### Components
1. **BP_DialogueSystem**: Main dialogue system blueprint
2. **API Integration**: ChatGPT API client
3. **Dialogue Handler**: Handles dialogue requests and responses
4. **NPC Integration**: Integrates with NPC behavior system
---
## ChatGPT API Integration
### API Setup
1. **API Key**: Obtain ChatGPT API key from OpenAI
2. **Secure Storage**: Store API key securely (environment variable, not in repository)
3. **API Client**: Create API client in blueprint or C++
4. **Configuration**: Configure API endpoint and settings
### API Configuration
- **Model**: GPT-3.5-turbo or GPT-4
- **Temperature**: 0.7-0.9 (creative but coherent)
- **Max Tokens**: 100-200 (concise responses)
- **System Prompt**: Define NPC personality and context
---
## Dialogue System Blueprint
### BP_DialogueSystem
**Main dialogue system controller**
### Functions
#### RequestDialogue
- **Purpose**: Request dialogue from ChatGPT
- **Input**: Player message, NPC context
- **Output**: Generated dialogue response
- **Implementation**: API call to ChatGPT
#### ProcessResponse
- **Purpose**: Process API response
- **Input**: API response
- **Output**: Formatted dialogue
- **Implementation**: Parse and format response
#### GetNPCContext
- **Purpose**: Get NPC context for dialogue
- **Input**: NPC reference
- **Output**: NPC context (name, location, personality)
- **Implementation**: Gather NPC information
---
## NPC Context
### Context Information
#### NPC Identity
- **Name**: NPC name
- **Role**: NPC role (tourist, resident, business person)
- **Personality**: Personality traits
- **Background**: Background information
#### Location Context
- **Current Location**: Where NPC is located
- **District**: Dubai Marina
- **Landmarks**: Nearby landmarks
- **Activities**: Current activities
#### Conversation Context
- **Previous Messages**: Conversation history
- **Topic**: Current conversation topic
- **Mood**: NPC mood/emotional state
---
## System Prompts
### NPC Personality Prompts
#### Example: Tourist NPC
```
You are a tourist visiting Dubai Marina. You are friendly, curious, and excited about Dubai.
You speak in a casual, enthusiastic manner. Keep responses brief (1-2 sentences).
You know about Dubai Marina, Cayan Tower, and the luxury lifestyle in Dubai.
```
#### Example: Resident NPC
```
You are a resident of Dubai Marina. You are knowledgeable about the area, professional,
and helpful. You speak in a friendly but professional manner. Keep responses brief (1-2 sentences).
You know about local restaurants, shops, and the Marina lifestyle.
```
#### Example: Business Person NPC
```
You are a business person in Dubai. You are professional, busy, and focused.
You speak in a professional, concise manner. Keep responses brief (1-2 sentences).
You know about business in Dubai, the financial district, and professional services.
```
---
## Dialogue Flow
### Player Interaction
1. **Player Approaches NPC**: Player interacts with NPC
2. **Dialogue UI**: Dialogue UI appears
3. **Player Input**: Player types or selects message
4. **Dialogue Request**: System requests dialogue from ChatGPT
5. **NPC Response**: NPC speaks generated dialogue
6. **Continuation**: Conversation continues
### Implementation
1. **Interaction System**: Use interaction system to trigger dialogue
2. **UI Widget**: Create dialogue UI widget
3. **API Call**: Make API call to ChatGPT
4. **Response Processing**: Process and display response
5. **Audio**: Play NPC voice (optional, text-to-speech)
---
## API Integration Script
### npc_dialogue_api.py
**Python script for API integration (optional)**
### Functions
- **send_dialogue_request**: Send request to ChatGPT API
- **process_response**: Process API response
- **format_dialogue**: Format dialogue for display
### Usage
- **Standalone**: Run as standalone service
- **Integration**: Integrate with Unreal via HTTP requests
- **Caching**: Cache responses for performance
---
## Performance Considerations
### Optimization
1. **Caching**: Cache common responses
2. **Rate Limiting**: Limit API calls per NPC
3. **Response Time**: Optimize for quick responses
4. **Fallback**: Fallback to pre-written dialogue if API fails
### Cost Management
1. **API Costs**: Monitor API usage and costs
2. **Token Limits**: Limit tokens per request
3. **Request Frequency**: Limit request frequency
4. **Caching**: Cache responses to reduce API calls
---
## Security
### API Key Security
- **Never Commit**: Never commit API keys to repository
- **Environment Variables**: Use environment variables
- **Secure Storage**: Store keys securely
- **Access Control**: Limit access to API keys
### Input Validation
- **Sanitize Input**: Sanitize player input
- **Length Limits**: Limit input length
- **Content Filtering**: Filter inappropriate content
---
## Testing
### Dialogue Testing
1. **Quality**: Test dialogue quality
2. **Context**: Test context awareness
3. **Personality**: Test NPC personality consistency
4. **Response Time**: Test response time
### Integration Testing
1. **NPC Integration**: Test with NPC system
2. **UI Integration**: Test with dialogue UI
3. **Performance**: Test performance impact
4. **Error Handling**: Test error handling
---
## Fallback System
### Pre-Written Dialogue
**Fallback if API unavailable**
- **Greetings**: Pre-written greetings
- **Common Responses**: Common response templates
- **Topics**: Pre-written dialogue for common topics
### Implementation
1. **Dialogue Database**: Store pre-written dialogue
2. **Topic Matching**: Match player input to topics
3. **Response Selection**: Select appropriate response
4. **Fallback Trigger**: Trigger fallback if API fails
---
## Troubleshooting
### Common Issues
**Issue**: API not responding
- **Solution**: Check API key and connection
- **Solution**: Implement fallback system
- **Solution**: Check rate limits
**Issue**: Dialogue quality poor
- **Solution**: Refine system prompts
- **Solution**: Adjust temperature settings
- **Solution**: Improve context information
**Issue**: Response time too slow
- **Solution**: Implement caching
- **Solution**: Optimize API calls
- **Solution**: Use faster API model
---
## Documentation
### API Documentation
Document API integration:
- API setup
- Configuration
- Usage
- Error handling
### Dialogue Documentation
Document dialogue system:
- NPC personalities
- Context information
- System prompts
- Usage examples
---
**Version**: 1.0
**Last Updated**: 2024-11-21
**Note**: This is an optional feature. The project can function without ChatGPT integration using pre-written dialogue or no dialogue system.

271
docs/systems/PARTICLE_FX.md Normal file
View File

@@ -0,0 +1,271 @@
# Particle Effects - Dubai Metaverse
## Overview
This document catalogs all particle effects for the Dubai Metaverse project.
## Particle Systems
### P_Dust
**Purpose**: Ambient dust particles in the air
#### Properties
- **Type**: GPU Particles
- **Spawn Rate**: Low to medium
- **Lifetime**: Long (10-30 seconds)
- **Size**: Small (0.1-0.5 units)
- **Color**: Beige/brown (dust color)
- **Movement**: Slow drift, wind-affected
#### Implementation
1. **Emitter Setup**:
- Spawn rate: 5-10 particles/second
- Lifetime: 15-25 seconds
- Initial velocity: Low, random
2. **Visual**:
- Texture: Dust particle texture
- Size: Small, random variation
- Color: Beige/brown, slight variation
- Opacity: Low (0.3-0.5)
3. **Behavior**:
- Wind-affected
- Gravity: Slight downward
- Collision: None (or ground collision)
#### Placement
- **Areas**: Open areas, roads, construction sites
- **Density**: Low to medium
- **Distance**: Visible at medium distance
---
### P_HeatDistortion
**Purpose**: Heat distortion effect above hot surfaces
#### Properties
- **Type**: Post-process or material effect
- **Intensity**: Subtle
- **Distance**: Above hot surfaces (roads, buildings)
- **Falloff**: Distance-based
#### Implementation
1. **Material Function**:
- Create material function
- Use distortion node
- Apply to surfaces or post-process
2. **Settings**:
- Distortion intensity: 0.1-0.3
- Distance falloff: Exponential
- Affected by time of day (stronger during day)
#### Placement
- **Surfaces**: Roads, building roofs, hot surfaces
- **Time**: Stronger during day, weaker at night
---
### P_SandBlowing
**Purpose**: Sand particles blowing in wind
#### Properties
- **Type**: GPU Particles
- **Spawn Rate**: Medium
- **Lifetime**: Short (3-10 seconds)
- **Size**: Small to medium (0.2-1.0 units)
- **Color**: Sand color (beige/tan)
- **Movement**: Fast, wind-affected
#### Implementation
1. **Emitter Setup**:
- Spawn rate: 10-20 particles/second
- Lifetime: 5-8 seconds
- Initial velocity: High, wind direction
2. **Visual**:
- Texture: Sand particle texture
- Size: Small to medium
- Color: Sand color
- Opacity: Medium (0.5-0.7)
3. **Behavior**:
- Strong wind effect
- Gravity: Downward
- Collision: Ground collision
#### Placement
- **Areas**: Desert areas, open spaces, windy areas
- **Conditions**: Windy conditions, sandstorms (optional)
---
### P_Fountain
**Purpose**: Water fountain particle effects
#### Properties
- **Type**: GPU Particles
- **Spawn Rate**: High
- **Lifetime**: Short (1-3 seconds)
- **Size**: Small to medium (0.1-0.8 units)
- **Color**: Water color (white/blue)
- **Movement**: Upward spray, gravity-affected
#### Implementation
1. **Emitter Setup**:
- Spawn rate: 50-100 particles/second
- Lifetime: 1-2 seconds
- Initial velocity: Upward, high
2. **Visual**:
- Texture: Water droplet texture
- Size: Small, random variation
- Color: White/light blue
- Opacity: High (0.7-1.0)
3. **Behavior**:
- Gravity: Strong downward
- Collision: Ground/water collision
- Splash: Splash effect on impact
#### Placement
- **Locations**: Fountains, water features
- **Density**: High near fountain, lower at distance
---
## Particle System Organization
### Folder Structure
```
Content/Assets/FX/
├── P_Dust.uasset
├── P_HeatDistortion.uasset
├── P_SandBlowing.uasset
├── P_Fountain.uasset
└── Textures/
├── T_Dust_Particle
├── T_Sand_Particle
└── T_Water_Droplet
```
### Naming Convention
- **Format**: `P_EffectName_Type`
- **Examples**:
- `P_Dust_Ambient`
- `P_Fountain_Water`
---
## Performance Optimization
### Particle Optimization
1. **Spawn Rate**: Optimize spawn rates
2. **Lifetime**: Optimize particle lifetime
3. **LODs**: Use LODs for particles
4. **Culling**: Cull particles outside view
### GPU Particles
- **Use GPU Particles**: For better performance
- **Limit Count**: Limit particle count
- **Optimize Shaders**: Optimize particle shaders
---
## Integration
### With Lighting
- **Lighting**: Particles respond to lighting
- **Shadows**: Particles cast/receive shadows (optional)
- **Time of Day**: Particle appearance changes with time
### With Weather
- **Wind**: Particles affected by wind
- **Weather Conditions**: Particle intensity varies with weather
### With Audio
- **Audio Cues**: Trigger audio with particles (optional)
- **Synchronization**: Sync particles with audio
---
## Testing
### Visual Testing
1. **Appearance**: Verify particles look correct
2. **Behavior**: Verify particle behavior is realistic
3. **Performance**: Test performance with particles
### Performance Testing
1. **Frame Rate**: Test frame rate impact
2. **Memory**: Test memory usage
3. **Optimization**: Test optimization settings
---
## Troubleshooting
### Common Issues
**Issue**: Particles not spawning
- **Solution**: Check spawn rate settings
- **Solution**: Verify emitter is active
**Issue**: Particles too bright/dark
- **Solution**: Adjust color and opacity
- **Solution**: Check lighting settings
**Issue**: Performance issues
- **Solution**: Reduce spawn rate
- **Solution**: Use LODs
- **Solution**: Optimize particle shaders
---
## Best Practices
### Particle Design
1. **Subtlety**: Keep effects subtle and realistic
2. **Performance**: Balance quality and performance
3. **Variation**: Add variation for natural look
4. **Integration**: Integrate with other systems
### Workflow
1. **Prototype**: Prototype effects quickly
2. **Iterate**: Iterate based on feedback
3. **Optimize**: Optimize for performance
4. **Document**: Document particle settings
---
**Version**: 1.0
**Last Updated**: 2024-11-21

304
docs/systems/VEHICLE_SYSTEM.md Normal file
View File

@@ -0,0 +1,304 @@
# Vehicle System - Dubai Metaverse
## Overview
This document describes the vehicle system implementation using Chaos Physics for the Dubai Metaverse project.
## Chaos Vehicle System
### Overview
Chaos Vehicle is Unreal Engine 5's physics-based vehicle simulation system. It provides realistic vehicle physics and handling.
### Setup
1. **Enable Chaos Physics**:
- Project Settings > Physics > Chaos Physics
- Enable Chaos Vehicle
2. **Vehicle Blueprint**:
- Create vehicle blueprint
- Add Chaos Vehicle components
- Configure physics settings
---
## Vehicle Assets
### Dubai Supercars
#### Lamborghini
- **Model**: SM_Vehicle_Lamborghini
- **Blueprint**: BP_Vehicle_Lamborghini
- **Type**: Supercar
- **Characteristics**:
- High speed
- High acceleration
- Sporty handling
#### G-Wagon
- **Model**: SM_Vehicle_GWagon
- **Blueprint**: BP_Vehicle_GWagon
- **Type**: Luxury SUV
- **Characteristics**:
- High ground clearance
- Stable handling
- Luxury aesthetic
#### Ferrari
- **Model**: SM_Vehicle_Ferrari
- **Blueprint**: BP_Vehicle_Ferrari
- **Type**: Supercar
- **Characteristics**:
- High speed
- High acceleration
- Sporty handling
---
## Vehicle Blueprint Setup
### BP_VehicleBase
**Base class for all vehicles**
### Components
1. **Chaos Vehicle Movement Component**:
- Main vehicle physics component
- Handles acceleration, braking, steering
- Configures vehicle dynamics
2. **Mesh Component**:
- Vehicle static mesh
- Visual representation
3. **Camera Component** (optional):
- Third-person camera
- First-person camera (if needed)
4. **Audio Component**:
- Engine sounds
- Tire sounds
- Other vehicle sounds
### Physics Settings
#### Engine
- **Max RPM**: 6000-8000
- **Torque**: High for supercars
- **Gear Ratios**: Configure for vehicle type
#### Transmission
- **Type**: Automatic or Manual
- **Gear Count**: 6-8 gears
- **Shift Points**: Configure shift points
#### Suspension
- **Spring Rate**: Adjust for vehicle type
- **Damping**: Adjust for handling
- **Travel**: Suspension travel distance
#### Tires
- **Friction**: Tire friction coefficient
- **Pressure**: Tire pressure
- **Radius**: Tire radius
---
## Vehicle Controller
### BP_VehicleController
**Purpose**: Handle player input and vehicle control
### Input Mapping
- **Throttle**: W key / Gamepad trigger
- **Brake**: S key / Gamepad trigger
- **Steering**: A/D keys / Gamepad stick
- **Handbrake**: Space key / Gamepad button
### Implementation
1. **Input Handling**:
- Capture player input
- Convert to vehicle commands
- Send to vehicle movement component
2. **Camera Control**:
- Third-person camera follow
- Camera smoothing
- Camera offset
3. **UI**:
- Speedometer (optional)
- Gear indicator (optional)
---
## AI Traffic System
### PCG_Traffic Graph
**Purpose**: Generate AI traffic on roads
### Implementation
1. **Spline System**:
- Create road splines
- Define traffic paths
- Set traffic direction
2. **Vehicle Spawning**:
- Spawn vehicles at intersections
- Spawn vehicles at entry points
- Vary vehicle types
3. **AI Movement**:
- Follow spline paths
- Maintain speed
- Avoid collisions
### AI Vehicle Controller
1. **Spline Following**:
- Follow road splines
- Maintain lane position
- Adjust speed
2. **Traffic Behavior**:
- Stop at intersections (optional)
- Yield to other vehicles
- Maintain safe distance
---
## Vehicle Materials
### Paint Materials
- **M_Vehicle_Paint**: Base paint material
- **Variations**: Different colors per vehicle
- **Properties**:
- High reflectivity
- Low roughness
- Metallic (for some colors)
### Material Instances
- **MI_Vehicle_Lamborghini_Yellow**: Yellow paint
- **MI_Vehicle_Lamborghini_Orange**: Orange paint
- **MI_Vehicle_GWagon_Black**: Black paint
- **MI_Vehicle_Ferrari_Red**: Red paint
---
## Vehicle Audio
### Engine Sounds
- **A_Vehicle_Engine_Lamborghini**: Lamborghini engine
- **A_Vehicle_Engine_GWagon**: G-Wagon engine
- **A_Vehicle_Engine_Ferrari**: Ferrari engine
### Implementation
1. **Audio Component**:
- Attach to vehicle
- Play engine sound
- Adjust pitch based on RPM
2. **Tire Sounds**:
- Tire screech on hard braking
- Tire squeal on sharp turns
---
## Performance Optimization
### Vehicle Optimization
1. **LODs**: Use LODs for distant vehicles
2. **Culling**: Cull vehicles outside view
3. **Instancing**: Use instanced meshes for traffic
### Physics Optimization
1. **Update Frequency**: Optimize physics update rate
2. **Collision**: Optimize collision shapes
3. **Simulation**: Limit physics simulation distance
---
## Testing
### Vehicle Testing
1. **Handling**: Test vehicle handling
2. **Physics**: Verify physics are realistic
3. **Performance**: Test performance with vehicles
4. **Audio**: Test vehicle audio
### Traffic Testing
1. **Spawn Rate**: Test vehicle spawn rate
2. **AI Behavior**: Test AI traffic behavior
3. **Performance**: Test performance with traffic
4. **Collisions**: Test collision avoidance
---
## Troubleshooting
### Common Issues
**Issue**: Vehicle handling too sensitive/loose
- **Solution**: Adjust suspension settings
- **Solution**: Adjust tire friction
**Issue**: Vehicle not accelerating
- **Solution**: Check engine torque settings
- **Solution**: Check transmission settings
**Issue**: AI traffic not moving
- **Solution**: Check AI controller setup
- **Solution**: Verify spline paths
**Issue**: Performance issues
- **Solution**: Reduce vehicle count
- **Solution**: Optimize vehicle meshes
- **Solution**: Use LODs
---
## Documentation
### Vehicle Specifications
Document each vehicle:
- Model name
- Blueprint name
- Physics settings
- Material settings
- Audio settings
### Controls
Document vehicle controls:
- Input mapping
- Camera controls
- Special features
---
**Version**: 1.0
**Last Updated**: 2024-11-21

290
docs/systems/WATER_SYSTEM.md Normal file
View File

@@ -0,0 +1,290 @@
# Water System - Dubai Metaverse
## Overview
This document describes the Marina water system implementation for the Dubai Metaverse project.
## Marina Water Requirements
### Visual Requirements
- **Realistic Water**: Photorealistic water appearance
- **Reflections**: Strong reflections of buildings and sky
- **Caustics**: Light refraction (caustics) on surfaces
- **Waves**: Animated wave surface
- **Foam**: Foam at edges and around objects
### Technical Requirements
- **Performance**: Maintain 60-90 FPS
- **Quality**: High visual quality
- **Scale**: Large water area (Marina channel)
---
## Water Material
### M_Water_Marina
**Primary water material for Marina**
### Material Properties
#### Base Properties
- **Blend Mode**: Translucent
- **Shading Model**: Default Lit
- **Two-Sided**: Enabled
#### Reflection
- **Reflectivity**: High (0.8-0.95)
- **Reflection Method**: Lumen Reflections
- **Reflection Quality**: High
#### Surface Properties
- **Roughness**: Low (0.05-0.1) for smooth surface
- **Metallic**: Low (0.0-0.1)
- **Color**: Slight blue/green tint
#### Animation
- **Wave Animation**: Animated normal map
- **Wave Speed**: Configurable
- **Wave Intensity**: Configurable
- **Wave Direction**: Configurable
### Texture Requirements
#### Base Color
- **Resolution**: 4K
- **Content**: Water color, depth variation
- **Tint**: Blue/green
#### Normal Map
- **Resolution**: 4K
- **Content**: Wave patterns, surface detail
- **Animation**: Animated for wave movement
#### Roughness
- **Resolution**: 4K
- **Content**: Surface roughness (low for smooth water)
#### Additional Maps
- **Caustics**: Caustics texture (optional)
- **Foam Mask**: Foam areas (optional)
---
## Water Shader Implementation
### Wave Animation
1. **Normal Map Animation**:
- Use panner node to animate normal map
- Combine multiple wave layers
- Adjust speed and intensity
2. **Vertex Animation** (optional):
- Animate vertex positions
- Use world position offset
- Adjust wave height
### Reflections
1. **Lumen Reflections**:
- Enable Lumen Reflections
- High reflection quality
- Verify reflections are accurate
2. **Planar Reflections** (optional):
- Use planar reflection actor
- For specific reflection needs
- Performance consideration
### Caustics
1. **Caustics Texture**:
- Create or use caustics texture
- Project onto surfaces below water
- Animate for movement
2. **Implementation**:
- Use material function
- Project onto geometry
- Adjust intensity
---
## Water System Blueprint
### BP_WaterSystem
**Purpose**: Control water system behavior**
### Components
1. **Water Mesh**:
- Large plane or custom mesh
- Covers Marina area
- Assigned water material
2. **Water Controller**:
- Controls wave animation
- Controls water level
- Controls water effects
3. **Foam System**:
- Foam at edges
- Foam around objects
- Foam material
### Settings
- **Wave Speed**: Animation speed
- **Wave Intensity**: Wave strength
- **Water Level**: Water height
- **Foam Intensity**: Foam amount
---
## Foam System
### M_Water_Foam
**Foam material for water edges**
### Properties
- **Blend Mode**: Translucent or Additive
- **Color**: White/light blue
- **Opacity**: Variable
- **Emissive**: Slight emissive
### Implementation
1. **Foam Mask**:
- Create foam mask texture
- Or use distance-based mask
- Define foam areas
2. **Foam Placement**:
- Place at water edges
- Place around objects
- Use decals or separate mesh
---
## Performance Optimization
### Water Optimization
1. **Material Complexity**:
- Optimize shader instructions
- Use efficient nodes
- Minimize texture sampling
2. **Mesh Optimization**:
- Use efficient mesh
- Optimize vertex count
- Use LODs if needed
3. **Reflection Optimization**:
- Optimize Lumen Reflections
- Limit reflection distance
- Use lower quality if needed
### Streaming
- **World Partition**: Use World Partition for large water areas
- **Distance Culling**: Cull water outside view
- **LODs**: Use LODs for distant water
---
## Integration
### With Lighting
- **Reflections**: Water reflects sky and buildings
- **Caustics**: Caustics on surfaces below
- **Time of Day**: Water appearance changes with time
### With Buildings
- **Reflections**: Buildings reflect in water
- **Interaction**: Water interacts with building bases
- **Foam**: Foam around building foundations
### With Vehicles
- **Wake Effects**: Vehicle wake (optional)
- **Splashes**: Water splashes (optional)
---
## Testing
### Visual Testing
1. **Reflections**: Verify reflections are accurate
2. **Waves**: Verify wave animation is smooth
3. **Caustics**: Verify caustics are visible
4. **Foam**: Verify foam placement is correct
### Performance Testing
1. **Frame Rate**: Test frame rate with water
2. **Memory**: Test memory usage
3. **Optimization**: Test optimization settings
---
## Troubleshooting
### Common Issues
**Issue**: Water not reflecting
- **Solution**: Check Lumen Reflections enabled
- **Solution**: Verify reflection quality settings
**Issue**: Waves not animating
- **Solution**: Check material animation nodes
- **Solution**: Verify time-based nodes
**Issue**: Performance issues
- **Solution**: Optimize material complexity
- **Solution**: Reduce reflection quality
- **Solution**: Use LODs
**Issue**: Water too transparent/opaque
- **Solution**: Adjust opacity settings
- **Solution**: Adjust color and tint
---
## Reference
### Dubai Marina Water
- **Color**: Clear blue/green
- **Reflections**: Strong reflections
- **Waves**: Gentle waves
- **Clarity**: Clear, visible depth
### Material References
- Study real water materials
- Reference Dubai Marina photos
- Match visual appearance
---
**Version**: 1.0
**Last Updated**: 2024-11-21