metaverseDubai/docs/WATER_SYSTEM.md

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]