# 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**: [Current Date]