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

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/optimization/LOD_GUIDELINES.md

@@ -0,0 +1,206 @@
+# LOD Guidelines - Dubai Metaverse
+
+## Overview
+
+This document describes LOD (Level of Detail) creation and usage guidelines for the Dubai Metaverse project.
+
+## LOD System
+
+### Overview
+
+LODs reduce polygon count and detail for distant objects, improving performance while maintaining visual quality.
+
+### When to Use LODs
+
+- **Non-Nanite Assets**: Assets not using Nanite
+- **Performance**: When performance optimization is needed
+- **Distance**: For assets visible at distance
+
+### When Not to Use LODs
+
+- **Nanite Assets**: Nanite handles LOD automatically
+- **Close-Only Assets**: Assets only visible up close
+- **Simple Assets**: Very simple assets may not need LODs
+
+---
+
+## LOD Creation
+
+### LOD Levels
+
+#### LOD0
+
+- **Detail**: Full detail
+- **Polygon Count**: 100% of original
+- **Distance**: 0-50m (close)
+- **Usage**: Close-up views
+
+#### LOD1
+
+- **Detail**: High detail
+- **Polygon Count**: 50-70% of LOD0
+- **Distance**: 50-150m (medium)
+- **Usage**: Medium distance
+
+#### LOD2
+
+- **Detail**: Medium detail
+- **Polygon Count**: 30-50% of LOD0
+- **Distance**: 150-300m (far)
+- **Usage**: Far distance
+
+#### LOD3
+
+- **Detail**: Low detail
+- **Polygon Count**: 10-30% of LOD0
+- **Distance**: 300m+ (very far)
+- **Usage**: Very far distance
+
+---
+
+## LOD Generation
+
+### Automatic Generation
+
+#### Unreal Engine
+
+1. **Import Settings**:
+   - Enable "Generate LODs" on import
+   - Set LOD count
+   - Set reduction settings
+
+2. **Post-Import**:
+   - Right-click mesh > Generate LODs
+   - Configure settings
+   - Generate LODs
+
+### Manual Creation
+
+#### DCC Tools
+
+1. **Create LODs in Blender/Maya**:
+   - Create simplified versions
+   - Maintain shape and silhouette
+   - Export as separate meshes
+
+2. **Import to Unreal**:
+   - Import LOD meshes
+   - Assign as LODs
+   - Configure distances
+
+---
+
+## LOD Settings
+
+### Distance Settings
+
+#### Primary Buildings
+
+- **LOD0**: 0-100m
+- **LOD1**: 100-200m
+- **LOD2**: 200-400m
+- **LOD3**: 400m+
+
+#### Background Buildings
+
+- **LOD0**: 0-50m
+- **LOD1**: 50-150m
+- **LOD2**: 150m+
+
+#### Props
+
+- **LOD0**: 0-30m
+- **LOD1**: 30-100m
+- **LOD2**: 100m+
+
+---
+
+## LOD Quality
+
+### Visual Quality
+
+1. **Silhouette**: Maintain silhouette
+2. **Shape**: Maintain overall shape
+3. **Details**: Remove fine details progressively
+4. **Materials**: Maintain material appearance
+
+### Performance
+
+1. **Polygon Reduction**: Significant polygon reduction
+2. **Draw Calls**: Reduce draw calls
+3. **Memory**: Reduce memory usage
+
+---
+
+## LOD Validation
+
+### Quality Check
+
+- [ ] LODs maintain silhouette
+- [ ] LODs maintain overall shape
+- [ ] LOD transitions are smooth
+- [ ] Visual quality is acceptable
+- [ ] Performance improvement is significant
+
+### Testing
+
+1. **Visual Testing**: Test LOD transitions
+2. **Performance Testing**: Test performance impact
+3. **Distance Testing**: Test at various distances
+
+---
+
+## Best Practices
+
+### LOD Creation
+
+1. **Start with LOD0**: Ensure LOD0 is high quality
+2. **Progressive Reduction**: Reduce detail progressively
+3. **Maintain Shape**: Maintain overall shape and silhouette
+4. **Test Transitions**: Test LOD transitions
+
+### LOD Usage
+
+1. **Appropriate LODs**: Use appropriate LOD count
+2. **Distance Settings**: Optimize distance settings
+3. **Performance**: Balance quality and performance
+4. **Validation**: Validate LOD quality
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: LOD transitions visible
+- **Solution**: Adjust LOD distances
+- **Solution**: Improve LOD quality
+- **Solution**: Use fade transitions
+
+**Issue**: LODs too aggressive
+- **Solution**: Reduce polygon reduction
+- **Solution**: Improve LOD quality
+- **Solution**: Adjust distance settings
+
+**Issue**: Performance not improved
+- **Solution**: Verify LODs are being used
+- **Solution**: Check LOD distance settings
+- **Solution**: Profile performance
+
+---
+
+## Documentation
+
+### LOD Documentation
+
+Document LOD setup:
+- **LOD Count**: Number of LODs
+- **Distance Settings**: LOD distance settings
+- **Polygon Counts**: Polygon count per LOD
+- **Quality Notes**: Quality considerations
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2024-11-21
+

docs/optimization/PERFORMANCE_OPTIMIZATION.md

@@ -0,0 +1,309 @@
+# Performance Optimization - Dubai Metaverse
+
+## Overview
+
+This document describes performance optimization strategies and techniques for the Dubai Metaverse project.
+
+## Performance Targets
+
+### Frame Rate
+
+- **Target**: 60-90 FPS at 1440p/4K
+- **Minimum**: 60 FPS
+- **Measurement**: Unreal Insights, Stat FPS
+
+### Memory
+
+- **GPU Memory**: <12GB VRAM
+- **System RAM**: <16GB
+- **Measurement**: Unreal Insights, Stat Memory
+
+---
+
+## Optimization Strategies
+
+### Nanite Optimization
+
+#### Usage
+
+- **Enable Nanite**: Enable for all static meshes
+- **Target**: 100% of static meshes use Nanite
+- **Benefit**: High-poly geometry without performance penalty
+
+#### Optimization
+
+1. **Clustering**: Optimize Nanite clustering
+2. **Streaming**: Use texture streaming
+3. **Distance Culling**: Cull distant Nanite meshes
+
+---
+
+### LOD System
+
+#### Non-Nanite Assets
+
+- **LOD Generation**: Generate LODs for non-Nanite assets
+- **LOD Count**: LOD0-3 for primary, LOD0-2 for background
+- **LOD Distance**: Optimize LOD transition distances
+
+#### LOD Settings
+
+- **LOD0**: Full detail (close)
+- **LOD1**: Reduced detail (medium)
+- **LOD2**: Simplified (far)
+- **LOD3**: Minimal (very far)
+
+---
+
+### World Partition Optimization
+
+#### Streaming
+
+- **Cell Size**: Optimize cell size (128m default)
+- **Loading Range**: Optimize loading range per cell
+- **Streaming Budget**: Set streaming budget
+
+#### Data Layers
+
+- **Organization**: Organize by system (buildings, props, etc.)
+- **Streaming**: Optimize data layer streaming
+- **Culling**: Use distance culling
+
+---
+
+### Material Optimization
+
+#### Shader Complexity
+
+- **Instructions**: Minimize shader instructions
+- **Texture Sampling**: Optimize texture sampling
+- **Parameters**: Limit exposed parameters
+
+#### Shared Materials
+
+- **Use Shared Materials**: Use shared materials where possible
+- **Material Instances**: Use instances for variations
+- **Material Count**: Minimize unique material count
+
+---
+
+### Lighting Optimization
+
+#### Lumen Quality
+
+- **Final Gather Quality**: Adjust based on performance
+- **Reflection Quality**: Adjust based on performance
+- **View Distance**: Optimize view distance
+
+#### Shadow Optimization
+
+- **Virtual Shadow Maps**: Use for performance
+- **Shadow Resolution**: Adjust based on performance
+- **Shadow Distance**: Optimize shadow distance
+
+#### Light Count
+
+- **Minimize Dynamic Lights**: Use static lights where possible
+- **Light Complexity**: Optimize light complexity
+- **Culling**: Use distance culling
+
+---
+
+### Texture Optimization
+
+#### Resolution
+
+- **Hero Assets**: 8K (necessary for quality)
+- **Primary Buildings**: 4K
+- **Background**: 2K
+- **Props**: 1K-2K based on size
+
+#### Streaming
+
+- **Texture Streaming**: Enable texture streaming
+- **Virtual Textures**: Use for large textures (optional)
+- **Mip Maps**: Generate mip maps
+
+#### Compression
+
+- **Format**: Use appropriate compression
+- **Base Color**: BC7 (DXT5)
+- **Normal**: BC5
+- **Other**: BC7
+
+---
+
+### Particle Optimization
+
+#### Spawn Rate
+
+- **Optimize Spawn Rate**: Reduce if needed
+- **Lifetime**: Optimize particle lifetime
+- **LODs**: Use LODs for particles
+
+#### GPU Particles
+
+- **Use GPU Particles**: For better performance
+- **Limit Count**: Limit particle count
+- **Optimize Shaders**: Optimize particle shaders
+
+---
+
+### NPC Optimization
+
+#### Count
+
+- **NPC Density**: Optimize NPC count
+- **Distance Culling**: Cull distant NPCs
+- **LODs**: Use LODs for NPCs
+
+#### Behavior
+
+- **Update Frequency**: Optimize behavior tree updates
+- **Perception**: Optimize perception checks
+- **Pathfinding**: Optimize pathfinding
+
+---
+
+## Performance Profiling
+
+### Unreal Insights
+
+#### Setup
+
+1. **Enable Insights**: Enable Unreal Insights
+2. **Start Session**: Start profiling session
+3. **Play**: Play in editor or packaged build
+4. **Stop**: Stop profiling
+5. **Analyze**: Analyze results
+
+#### Metrics
+
+- **Frame Time**: Frame time breakdown
+- **Draw Calls**: Draw call count
+- **GPU Time**: GPU time breakdown
+- **Memory**: Memory usage
+
+---
+
+### Stat Commands
+
+#### Frame Rate
+
+- **Stat FPS**: Display FPS
+- **Stat Unit**: Display frame time breakdown
+
+#### Rendering
+
+- **Stat RHI**: Display rendering stats
+- **Stat SceneRendering**: Display scene rendering stats
+
+#### Memory
+
+- **Stat Memory**: Display memory usage
+- **Stat Streaming**: Display streaming stats
+
+---
+
+## Optimization Checklist
+
+### Pre-Optimization
+
+- [ ] Profile baseline performance
+- [ ] Identify bottlenecks
+- [ ] Set optimization priorities
+
+### Optimization
+
+- [ ] Enable Nanite for all static meshes
+- [ ] Generate LODs for non-Nanite assets
+- [ ] Optimize World Partition streaming
+- [ ] Optimize material complexity
+- [ ] Optimize texture resolution and streaming
+- [ ] Optimize lighting settings
+- [ ] Optimize particle systems
+- [ ] Optimize NPC count and behavior
+
+### Post-Optimization
+
+- [ ] Profile optimized performance
+- [ ] Validate performance targets met
+- [ ] Test on target hardware
+- [ ] Document optimization changes
+
+---
+
+## Performance Testing
+
+### Test Scenarios
+
+1. **Empty Level**: Baseline performance
+2. **Full District**: Complete district loaded
+3. **Cinematic Camera**: Camera movement
+4. **Vehicle Driving**: Vehicle physics
+5. **NPC Crowd**: Multiple NPCs
+
+### Test Hardware
+
+- **Minimum Spec**: RTX 3060 / RX 6600 XT
+- **Recommended Spec**: RTX 3070 / RX 6800 XT
+- **High-End Spec**: RTX 4080 / RX 7900 XTX
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Low frame rate
+- **Solution**: Profile to identify bottlenecks
+- **Solution**: Optimize identified areas
+- **Solution**: Reduce quality settings if needed
+
+**Issue**: High memory usage
+- **Solution**: Optimize texture resolution
+- **Solution**: Enable texture streaming
+- **Solution**: Reduce asset count
+
+**Issue**: Stuttering
+- **Solution**: Optimize streaming
+- **Solution**: Reduce asset loading
+- **Solution**: Optimize World Partition
+
+---
+
+## Performance Budget
+
+### Per System
+
+- **Rendering**: 60% of frame time
+- **Lighting (Lumen)**: 20% of frame time
+- **Physics**: 5% of frame time
+- **AI/NPCs**: 5% of frame time
+- **Other**: 10% of frame time
+
+### Optimization Priority
+
+1. **Rendering**: Highest priority
+2. **Lighting**: High priority
+3. **Physics**: Medium priority
+4. **AI/NPCs**: Medium priority
+5. **Other**: Low priority
+
+---
+
+## Documentation
+
+### Optimization Documentation
+
+Document optimization changes:
+- **Changes Made**: What was optimized
+- **Performance Impact**: Performance improvement
+- **Settings**: Optimization settings
+- **Notes**: Additional notes
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2024-11-21
+

docs/optimization/PERFORMANCE_TARGETS.md

@@ -0,0 +1,212 @@
+# Performance Targets - Dubai Metaverse
+
+## Overview
+
+This document defines performance targets and optimization goals for the Dubai Metaverse project.
+
+## Frame Rate Targets
+
+### Desktop (1440p)
+
+- **Target**: 60-90 FPS
+- **Minimum**: 60 FPS
+- **Ideal**: 90 FPS
+- **Hardware**: RTX 3070 / RX 6800 XT or better
+
+### Desktop (4K)
+
+- **Target**: 60 FPS
+- **Minimum**: 60 FPS
+- **Ideal**: 60+ FPS
+- **Hardware**: RTX 4080 / RX 7900 XTX or better
+
+### Cinematic Rendering
+
+- **Target**: Offline rendering (no FPS target)
+- **Output**: 8K EXR (7680x4320)
+- **Method**: Movie Render Queue
+- **Time**: Quality over speed
+
+### VR (If Implemented)
+
+- **Target**: 90 FPS
+- **Minimum**: 90 FPS (required for VR)
+- **Hardware**: RTX 4080 or better
+
+---
+
+## Memory Targets
+
+### GPU Memory (VRAM)
+
+- **Target**: <12GB usage
+- **Maximum**: 16GB (for high-end GPUs)
+- **Optimization**: Texture streaming, virtual textures
+
+### System RAM
+
+- **Target**: <16GB usage
+- **Maximum**: 32GB (for development)
+- **Optimization**: World Partition streaming
+
+### Storage
+
+- **Target**: <50GB packaged build
+- **Optimization**: Asset compression, unused asset removal
+
+---
+
+## Performance Metrics
+
+### Frame Time
+
+- **Target**: <16.67ms (60 FPS)
+- **Ideal**: <11.11ms (90 FPS)
+- **Measurement**: Unreal Insights
+
+### Draw Calls
+
+- **Target**: <5000 draw calls per frame
+- **Optimization**: Instancing, batching
+
+### Triangle Count
+
+- **Target**: <5M triangles per frame (with Nanite)
+- **Optimization**: Nanite, LOD system
+
+---
+
+## Optimization Strategies
+
+### Nanite
+
+- **Usage**: All static meshes where possible
+- **Benefit**: High-poly geometry without performance penalty
+- **Target**: 100% of static meshes use Nanite
+
+### LOD System
+
+- **Usage**: Non-Nanite assets, background buildings
+- **LODs**: LOD0-3 for primary, LOD0-2 for background
+- **Target**: All non-Nanite assets have LODs
+
+### World Partition
+
+- **Usage**: Entire Dubai district
+- **Cell Size**: 128m x 128m (default)
+- **Streaming**: Optimized per cell
+- **Target**: Smooth streaming, no hitches
+
+### Material Optimization
+
+- **Shared Materials**: Use material instances
+- **Texture Streaming**: Enable texture streaming
+- **Virtual Textures**: Use for large textures (optional)
+- **Target**: Minimize material complexity
+
+### Lighting Optimization
+
+- **Lumen Quality**: Adjust based on performance
+- **Shadow Quality**: Virtual Shadow Maps
+- **Light Count**: Minimize dynamic lights
+- **Target**: Maintain visual quality while optimizing
+
+---
+
+## Performance Testing
+
+### Tools
+
+- **Unreal Insights**: Profiling and analysis
+- **GPU Profiler**: GPU performance analysis
+- **Stat Commands**: Real-time performance stats
+
+### Test Scenarios
+
+1. **Empty Level**: Baseline performance
+2. **Full District**: Complete district loaded
+3. **Cinematic Camera**: Camera movement performance
+4. **Vehicle Driving**: Vehicle physics performance
+5. **NPC Crowd**: Multiple NPCs performance
+
+### Test Hardware
+
+- **Minimum Spec**: RTX 3060 / RX 6600 XT
+- **Recommended Spec**: RTX 3070 / RX 6800 XT
+- **High-End Spec**: RTX 4080 / RX 7900 XTX
+
+---
+
+## Performance Checklist
+
+### Optimization Checklist
+
+- [ ] All static meshes use Nanite (where applicable)
+- [ ] LODs generated for non-Nanite assets
+- [ ] World Partition streaming optimized
+- [ ] Material complexity minimized
+- [ ] Texture streaming enabled
+- [ ] Draw calls optimized (<5000)
+- [ ] Frame time meets targets (<16.67ms for 60 FPS)
+- [ ] Memory usage within targets
+- [ ] No performance hitches or stuttering
+- [ ] Performance tested on target hardware
+
+---
+
+## Performance Targets by Phase
+
+### Phase 2 (Environment Production)
+
+- **Target**: 30+ FPS in editor
+- **Focus**: Asset optimization, LOD generation
+
+### Phase 3 (World Systems)
+
+- **Target**: 45+ FPS in editor
+- **Focus**: Lighting optimization, system integration
+
+### Phase 4 (Gameplay + Interaction)
+
+- **Target**: 60+ FPS in editor
+- **Focus**: Final optimization pass
+
+### Phase 5 (Final Polish)
+
+- **Target**: 60-90 FPS in packaged build
+- **Focus**: Final performance validation
+
+---
+
+## Performance Budget
+
+### Per System
+
+- **Rendering**: 60% of frame time
+- **Lighting (Lumen)**: 20% of frame time
+- **Physics**: 5% of frame time
+- **AI/NPCs**: 5% of frame time
+- **Other**: 10% of frame time
+
+### Optimization Priority
+
+1. **Rendering**: Highest priority (biggest impact)
+2. **Lighting**: High priority (Lumen can be expensive)
+3. **Physics**: Medium priority
+4. **AI/NPCs**: Medium priority
+5. **Other**: Low priority
+
+---
+
+## Notes
+
+- Performance targets are guidelines, not strict requirements
+- Visual quality should not be sacrificed unnecessarily
+- Test on target hardware regularly
+- Optimize incrementally throughout development
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2024-11-21
+

docs/optimization/STREAMING_SETUP.md

@@ -0,0 +1,146 @@
+# World Partition Streaming Setup - Dubai Metaverse
+
+## Overview
+
+This document describes the World Partition streaming configuration for the Dubai Metaverse project.
+
+## World Partition
+
+### Overview
+
+World Partition is Unreal Engine 5's system for streaming large worlds efficiently. It divides the world into cells and streams them based on distance.
+
+### Configuration
+
+#### Enable World Partition
+
+1. **Project Settings**:
+   - Edit > Project Settings > World Partition
+   - Enable World Partition
+
+2. **Level Setup**:
+   - Convert level to World Partition
+   - Configure cell size and settings
+
+---
+
+## Cell Configuration
+
+### Cell Size
+
+- **Default**: 128m x 128m
+- **Adjustment**: Can be adjusted based on world size
+- **Consideration**: Balance between streaming efficiency and cell granularity
+
+### Cell Organization
+
+#### Data Layers
+
+Organize content by system:
+
+- **Buildings**: Building data layer
+- **Props**: Prop data layer
+- **Vegetation**: Vegetation data layer
+- **Lighting**: Lighting data layer
+- **Vehicles**: Vehicle data layer
+- **NPCs**: NPC data layer
+
+---
+
+## Streaming Volumes
+
+### Loading Volumes
+
+**Define areas where content loads**
+
+#### Setup
+
+1. **Create Volume**:
+   - Place > Volumes > World Partition Streaming Volume
+
+2. **Configure**:
+   - Set loading range
+   - Assign data layers
+   - Set priority
+
+3. **Placement**:
+   - Place around important areas
+   - Overlap volumes for smooth transitions
+
+---
+
+## Streaming Settings
+
+### Loading Range
+
+- **Default**: 2-3 cells (256-384m)
+- **Adjustment**: Adjust based on performance
+- **Optimization**: Balance loading distance and performance
+
+### Streaming Budget
+
+- **Memory Budget**: Set memory budget
+- **Streaming Budget**: Set streaming budget
+- **Optimization**: Optimize for target hardware
+
+---
+
+## Performance Optimization
+
+### Streaming Optimization
+
+1. **Cell Size**: Optimize cell size
+2. **Loading Range**: Optimize loading range
+3. **Data Layers**: Optimize data layer organization
+4. **Streaming Budget**: Set appropriate budgets
+
+### Distance Culling
+
+1. **Cull Distance**: Set cull distances for assets
+2. **LODs**: Use LODs for distance-based detail
+3. **Streaming**: Use streaming for large assets
+
+---
+
+## Testing
+
+### Streaming Testing
+
+1. **Load Testing**: Test loading performance
+2. **Streaming**: Test streaming transitions
+3. **Performance**: Test performance impact
+4. **Visual**: Test visual quality
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Streaming hitches
+- **Solution**: Optimize loading range
+- **Solution**: Reduce streaming budget
+- **Solution**: Optimize asset sizes
+
+**Issue**: Content not loading
+- **Solution**: Check streaming volumes
+- **Solution**: Verify data layer assignment
+- **Solution**: Check loading range
+
+---
+
+## Documentation
+
+### Streaming Documentation
+
+Document streaming setup:
+- **Cell Size**: Cell size configuration
+- **Data Layers**: Data layer organization
+- **Streaming Volumes**: Streaming volume placement
+- **Settings**: Streaming settings
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2024-11-21
+