metaverseDubai/NAMING_CONVENTIONS.md

# Naming Conventions - Dubai Metaverse

## Overview

Consistent naming conventions are critical for project organization, asset management, and team collaboration. All assets, files, and code must follow these conventions.

## General Rules

1. **Use PascalCase** for asset names (e.g., `SM_Building_01`)
2. **Use underscores** to separate logical groups (e.g., `SM_Building_Marina_01`)
3. **Be descriptive** but concise
4. **Use consistent prefixes** for asset types
5. **Include numbers** for multiple instances (01, 02, 03...)
6. **No spaces** in file names
7. **No special characters** except underscores and hyphens

## Asset Type Prefixes

### Static Meshes
- **Format**: `SM_AssetName_Variant_Number`
- **Example**: `SM_Building_Marina_01`, `SM_Prop_Bench_01`
- **Prefix**: `SM_`

### Skeletal Meshes
- **Format**: `SK_AssetName_Variant_Number`
- **Example**: `SK_Character_Male_01`, `SK_Vehicle_Lamborghini`
- **Prefix**: `SK_`

### Materials
- **Format**: `M_AssetName_Type`
- **Example**: `M_Building_Glass`, `M_Concrete_4K`, `M_Marina_Water`
- **Prefix**: `M_`

### Material Instances
- **Format**: `MI_AssetName_Variant`
- **Example**: `MI_Building_Glass_Blue`, `MI_Concrete_Dirty`
- **Prefix**: `MI_`

### Textures
- **Format**: `T_AssetName_MapType_Resolution`
- **Example**: `T_Building_BaseColor_4K`, `T_Concrete_Normal_2K`
- **Prefix**: `T_`
- **Map Types**: `BaseColor`, `Normal`, `Roughness`, `Metallic`, `AO`, `Emissive`, `Height`

### Blueprints
- **Format**: `BP_ClassName_Purpose`
- **Example**: `BP_PlayerController_Main`, `BP_Door_Automatic`, `BP_Vehicle_Lamborghini`
- **Prefix**: `BP_`

### Animation Blueprints
- **Format**: `ABP_CharacterName_Purpose`
- **Example**: `ABP_NPC_Walk`, `ABP_Player_Main`
- **Prefix**: `ABP_`

### Behavior Trees
- **Format**: `BT_NPCName_Behavior`
- **Example**: `BT_NPC_Wander`, `BT_NPC_Social`
- **Prefix**: `BT_`

### Particle Systems
- **Format**: `P_EffectName_Type`
- **Example**: `P_Dust_Ambient`, `P_Fountain_Water`, `P_Heat_Distortion`
- **Prefix**: `P_`

### Audio
- **Format**: `A_SoundName_Type`
- **Example**: `A_Ambient_City`, `A_Vehicle_Engine`, `A_Footstep_Concrete`
- **Prefix**: `A_`

### Sequencer Sequences
- **Format**: `SQ_SequenceName_ShotNumber`
- **Example**: `SQ_DubaiCinematic_01`, `SQ_DroneSweep_03`
- **Prefix**: `SQ_`

### Cine Cameras
- **Format**: `CineCamera_Purpose_Number`
- **Example**: `CineCamera_Drone_01`, `CineCamera_StreetLevel_02`
- **Prefix**: `CineCamera_`

### Data Assets
- **Format**: `DA_DataType_Name`
- **Example**: `DA_Quest_Main`, `DA_Dialogue_NPC_01`
- **Prefix**: `DA_`

### Widget Blueprints
- **Format**: `WBP_WidgetName_Purpose`
- **Example**: `WBP_MainMenu`, `WBP_MiniMap`, `WBP_InteractionPrompt`
- **Prefix**: `WBP_`

### PCG Graphs
- **Format**: `PCG_SystemName_Purpose`
- **Example**: `PCG_BuildingPlacement`, `PCG_RoadProps`, `PCG_Vegetation`
- **Prefix**: `PCG_`

## Category-Specific Naming

### Buildings

**Hero Landmark**:
- `SM_Hero_CayanTower_Main`
- `SM_Hero_CayanTower_Details`
- `M_Hero_CayanTower_Glass`
- `M_Hero_CayanTower_Chrome`

**Primary Buildings**:
- `SM_Building_Marina_01`
- `SM_Building_Marina_02`
- `M_Building_Glass_4K`
- `M_Building_Concrete_4K`

**Background Buildings**:
- `SM_Building_Background_01`
- `SM_Building_Background_02`

### Vehicles

- `SM_Vehicle_Lamborghini`
- `SM_Vehicle_GWagon`
- `SM_Vehicle_Ferrari`
- `BP_Vehicle_Lamborghini`
- `BP_VehicleController_Main`

### Characters (MetaHumans)

- `MH_Dubai_01`
- `MH_Dubai_02`
- `SK_Character_Male_01`
- `ABP_NPC_Walk`
- `BT_NPC_Wander`

### Materials

**Building Materials**:
- `M_Building_Glass_8K`
- `M_Building_Chrome_8K`
- `M_Building_Concrete_4K`
- `M_Building_Metal_4K`

**Effect Materials**:
- `MFX_HeatHaze`
- `MFX_Fingerprint`
- `MFX_Weathering`

**Water Materials**:
- `M_Water_Marina`
- `M_Water_Foam`

### Textures

**Hero Asset Textures (8K)**:
- `T_Hero_CayanTower_BaseColor_8K`
- `T_Hero_CayanTower_Normal_8K`
- `T_Hero_CayanTower_Roughness_8K`

**Building Textures (4K)**:
- `T_Building_Glass_BaseColor_4K`
- `T_Building_Concrete_Normal_4K`

**Background Textures (2K)**:
- `T_Building_Background_BaseColor_2K`

## Folder Structure Naming

### Content Folder Structure

```
Content/
├── Maps/
│   ├── Main/
│   ├── Blockout/
│   └── Test/
├── Assets/
│   ├── Buildings/
│   │   ├── Hero/
│   │   ├── Primary/
│   │   └── Background/
│   ├── Vehicles/
│   ├── Characters/
│   ├── Props/
│   ├── Materials/
│   │   ├── M_BuildingLibrary/
│   │   ├── M_HeroLandmark/
│   │   └── MFX/
│   └── Textures/
│       ├── T_HeroLandmark/
│       ├── T_Buildings/
│       └── T_Props/
├── Blueprints/
│   ├── Gameplay/
│   ├── Vehicles/
│   ├── AI/
│   └── NPCs/
├── PCG/
├── Cinematics/
└── Audio/
```

### Folder Naming Rules

- Use **PascalCase** for folder names
- Be descriptive and organized by category
- Group related assets together
- Use consistent hierarchy

## LOD Naming

### LOD Suffixes

- **LOD0**: No suffix (highest quality)
- **LOD1**: `_LOD1`
- **LOD2**: `_LOD2`
- **LOD3**: `_LOD3`

**Example**:
- `SM_Building_Marina_01` (LOD0)
- `SM_Building_Marina_01_LOD1`
- `SM_Building_Marina_01_LOD2`
- `SM_Building_Marina_01_LOD3`

**Note**: Nanite meshes don't use LOD suffixes (Nanite handles LOD automatically)

## Variant Naming

### Color Variants

- `_Red`, `_Blue`, `_Green`, etc.
- **Example**: `MI_Building_Glass_Blue`

### Size Variants

- `_Small`, `_Medium`, `_Large`
- **Example**: `SM_Prop_Bench_Small`

### Quality Variants

- `_4K`, `_8K` (for textures)
- **Example**: `T_Building_BaseColor_4K`

## Numbering Conventions

### Sequential Numbering

- Use **zero-padded** numbers: `01`, `02`, `03`... `10`, `11`...
- **Example**: `SM_Building_Marina_01`, `SM_Building_Marina_02`

### Version Numbers

- Use **v1**, `v2`, `v3` for versions
- **Example**: `SM_Building_Marina_01_v2`

## Special Cases

### UDIM Textures

- Use UDIM naming: `T_AssetName_MapType_1001`, `T_AssetName_MapType_1002`
- **Example**: `T_Hero_CayanTower_BaseColor_1001`

### Decals

- **Format**: `D_DecalName_Type`
- **Example**: `D_Weathering_Crack`, `D_Signage_Neon`
- **Prefix**: `D_`

### Post-Process Volumes

- **Format**: `PP_VolumeName_Purpose`
- **Example**: `PP_DubaiCinematic`, `PP_Interior`
- **Prefix**: `PP_`

## Validation

### Automated Validation

Use `scripts/validate_assets.sh` to validate naming conventions:

```bash
./scripts/validate_assets.sh
```

### Manual Checklist

Before committing assets, verify:
- ✅ Prefix is correct for asset type
- ✅ Name is descriptive and clear
- ✅ Numbers are zero-padded
- ✅ No spaces or special characters
- ✅ Follows category-specific conventions
- ✅ Folder structure is correct

## Examples

### Complete Asset Set Example

**Building Asset**:
- Mesh: `SM_Building_Marina_01`
- Material: `M_Building_Marina_Glass`
- Material Instance: `MI_Building_Marina_Glass_Blue`
- Textures:
  - `T_Building_Marina_BaseColor_4K`
  - `T_Building_Marina_Normal_4K`
  - `T_Building_Marina_Roughness_4K`
  - `T_Building_Marina_Metallic_4K`
  - `T_Building_Marina_AO_4K`

**Vehicle Asset**:
- Mesh: `SM_Vehicle_Lamborghini`
- Blueprint: `BP_Vehicle_Lamborghini`
- Material: `M_Vehicle_Lamborghini_Paint`
- Textures:
  - `T_Vehicle_Lamborghini_BaseColor_4K`
  - `T_Vehicle_Lamborghini_Normal_4K`

---

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