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