Initial commit: Complete project foundation with all documentation, scripts, and project structure
This commit is contained in:
Dubai Metaverse Team
348
docs/DAY_NIGHT_CYCLE.md
Normal file
348
docs/DAY_NIGHT_CYCLE.md
Normal 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**: [Current Date]
|
||||
|
||||
Reference in New Issue
Block a user