metaverseDubai/docs/MATERIAL_LIBRARY.md

# Material Library - Dubai Metaverse

## Overview

This document catalogs all materials in the Dubai Metaverse project, organized by category and usage.

## Material Organization

### Folder Structure

```
Content/Assets/Materials/
├── M_BuildingLibrary/
│   ├── M_Building_Glass_4K
│   ├── M_Building_Concrete_4K
│   ├── M_Building_Metal_4K
│   └── MI_* (Material Instances)
├── M_HeroLandmark/
│   ├── M_Hero_CayanTower_Glass_8K
│   ├── M_Hero_CayanTower_Chrome_8K
│   └── MI_* (Material Instances)
├── M_Water/
│   ├── M_Water_Marina
│   └── M_Water_Foam
└── MFX/
    ├── MFX_HeatHaze
    ├── MFX_Fingerprint
    └── MFX_Weathering
```

---

## Building Materials

### Glass Materials

#### M_Building_Glass_4K
- **Type**: Opaque/Translucent
- **Usage**: Building windows, facades
- **Properties**:
  - Reflectivity: 0.7-0.9
  - Roughness: 0.05-0.1
  - Tint: Slight cool blue/green
- **Texture Resolution**: 4K
- **Instances**: 
  - `MI_Building_Glass_Blue`
  - `MI_Building_Glass_Clear`

#### M_Hero_CayanTower_Glass_8K
- **Type**: Translucent
- **Usage**: Cayan Tower facade
- **Properties**:
  - Reflectivity: 0.8-0.95
  - Roughness: 0.05-0.1
  - Tint: Cool blue/green
- **Texture Resolution**: 8K (UDIM)
- **Special**: Hero asset material

---

### Concrete Materials

#### M_Building_Concrete_4K
- **Type**: Opaque
- **Usage**: Building structures, facades
- **Properties**:
  - Reflectivity: 0.1-0.2
  - Roughness: 0.4-0.6
  - Color: Neutral gray
- **Texture Resolution**: 4K
- **Variations**:
  - Smooth concrete
  - Textured concrete
  - Weathered concrete

---

### Metal Materials

#### M_Building_Metal_4K
- **Type**: Opaque, Metallic
- **Usage**: Metal facades, structural elements
- **Properties**:
  - Reflectivity: 0.5-0.8
  - Roughness: 0.1-0.3
  - Metallic: 1.0
- **Texture Resolution**: 4K
- **Variations**:
  - Stainless steel
  - Aluminum
  - Brushed metal

#### M_Hero_CayanTower_Chrome_8K
- **Type**: Opaque, Highly Metallic
- **Usage**: Cayan Tower structural elements
- **Properties**:
  - Reflectivity: 0.9-1.0
  - Roughness: 0.01-0.05
  - Metallic: 1.0
- **Texture Resolution**: 8K (UDIM)
- **Special**: Hero asset material

---

## Water Materials

### M_Water_Marina
- **Type**: Translucent
- **Usage**: Marina water
- **Properties**:
  - Reflectivity: High
  - Roughness: Low (smooth surface)
  - Color: Slight blue/green tint
  - Animated: Wave animation
- **Features**:
  - Reflections
  - Caustics (light refraction)
  - Wave animation
  - Foam at edges

### M_Water_Foam
- **Type**: Opaque
- **Usage**: Water foam, edges
- **Properties**:
  - Emissive: Slight
  - Roughness: High
  - Color: White/light blue
- **Usage**: Applied as decal or separate mesh

---

## Effect Materials

### MFX_HeatHaze
- **Type**: Post-process effect
- **Usage**: Heat distortion above hot surfaces
- **Properties**:
  - Distortion intensity
  - Distance-based falloff
  - Subtle effect
- **Application**: Material function or post-process

### MFX_Fingerprint
- **Type**: Decal material
- **Usage**: Surface smudges, fingerprints on glass
- **Properties**:
  - Opacity: Low
  - Roughness: Slight increase
- **Application**: Decal on glass surfaces

### MFX_Weathering
- **Type**: Decal material
- **Usage**: Cracks, wear, weathering
- **Properties**:
  - Opacity: Variable
  - Color: Darker than base
- **Application**: Decals on buildings, surfaces

---

## Material Instances

### Purpose

Material instances allow variation without duplicating base materials, improving performance and maintainability.

### Naming Convention

- **Format**: `MI_BaseMaterial_Variant`
- **Examples**:
  - `MI_Building_Glass_Blue`
  - `MI_Building_Concrete_Dirty`
  - `MI_Building_Metal_Brushed`

### Common Variations

#### Glass Variations
- `MI_Building_Glass_Blue` - Blue tint
- `MI_Building_Glass_Clear` - Clear
- `MI_Building_Glass_Tinted` - Dark tint

#### Concrete Variations
- `MI_Building_Concrete_Smooth` - Smooth finish
- `MI_Building_Concrete_Textured` - Textured
- `MI_Building_Concrete_Weathered` - Weathered

#### Metal Variations
- `MI_Building_Metal_Stainless` - Stainless steel
- `MI_Building_Metal_Aluminum` - Aluminum
- `MI_Building_Metal_Brushed` - Brushed finish

---

## Material Usage Guidelines

### When to Use Shared Materials

- **Same Material Type**: Buildings with same material type
- **Performance**: Reduce material count
- **Consistency**: Maintain visual consistency

### When to Create Unique Materials

- **Hero Assets**: Unique materials for hero assets
- **Special Effects**: Special effect materials
- **Unique Requirements**: Materials with unique requirements

### Material Instance Best Practices

1. **Use Instances**: Use instances for variations
2. **Expose Parameters**: Expose parameters for flexibility
3. **Document**: Document material usage
4. **Organize**: Organize instances logically

---

## Texture Requirements

### Resolution Standards

- **Hero Assets**: 8K (8192x8192) - UDIM workflow
- **Primary Buildings**: 4K (4096x4096)
- **Background**: 2K (2048x2048)

### Texture Sets

All materials require:
- Base Color
- Normal
- Roughness
- Metallic
- AO (Ambient Occlusion)

Optional:
- Emissive (for neon, lights)
- Height (for parallax/displacement)

---

## Performance Considerations

### Material Complexity

- **Shader Complexity**: Minimize shader instructions
- **Texture Sampling**: Optimize texture sampling
- **Parameters**: Limit exposed parameters

### Optimization

- **Shared Materials**: Use shared materials
- **Instances**: Use material instances
- **Texture Streaming**: Enable texture streaming
- **Virtual Textures**: Use for large textures (optional)

---

## Material Catalog

### Building Materials

| Material Name | Type | Resolution | Usage |
|---------------|------|------------|-------|
| M_Building_Glass_4K | Glass | 4K | Primary buildings |
| M_Building_Concrete_4K | Concrete | 4K | Primary buildings |
| M_Building_Metal_4K | Metal | 4K | Primary buildings |
| M_Hero_CayanTower_Glass_8K | Glass | 8K | Hero asset |
| M_Hero_CayanTower_Chrome_8K | Metal | 8K | Hero asset |

### Water Materials

| Material Name | Type | Usage |
|---------------|------|-------|
| M_Water_Marina | Water | Marina water |
| M_Water_Foam | Foam | Water foam |

### Effect Materials

| Material Name | Type | Usage |
|---------------|------|-------|
| MFX_HeatHaze | Effect | Heat distortion |
| MFX_Fingerprint | Decal | Surface smudges |
| MFX_Weathering | Decal | Weathering effects |

---

## Material Creation Workflow

1. **Create Base Material**: Create material with textures
2. **Configure Properties**: Set material properties
3. **Expose Parameters**: Expose parameters for instances
4. **Test**: Test material in level
5. **Create Instances**: Create material instances for variations
6. **Document**: Document material usage

---

## Troubleshooting

### Common Issues

**Issue**: Material too shiny/rough
- **Solution**: Adjust roughness values
- **Solution**: Check metallic values

**Issue**: Material not displaying correctly
- **Solution**: Check texture assignment
- **Solution**: Verify sRGB settings

**Issue**: Performance issues
- **Solution**: Optimize shader complexity
- **Solution**: Use material instances
- **Solution**: Enable texture streaming

---

**Version**: 1.0
**Last Updated**: [Current Date]