# PCG Workflow - Dubai Metaverse

## Overview

This document describes the Procedural Content Generation (PCG) workflow for the Dubai Metaverse project, including building placement, road props, and vegetation.

## PCG Framework Basics

### What is PCG?

Procedural Content Generation Framework is Unreal Engine 5's built-in system for procedurally placing and generating content in levels. It uses graph-based workflows to define rules for content placement.

### Key Concepts

- **PCG Graph**: Visual graph defining placement rules
- **Input**: Splines, volumes, points, or other data
- **Output**: Placed actors, meshes, or other content
- **Rules**: Logic defining how content is placed

---

## Building Placement PCG

### Graph: PCG_BuildingPlacement

**Purpose**: Procedurally place buildings in the Dubai Marina district

### Input Data

- **Building Footprints**: From OpenStreetMap data or manual placement
- **Spline Points**: Road network splines
- **Volume**: District boundary volume

### Placement Rules

1. **Distance from Roads**: Buildings placed 5-10m from road edges
2. **Building Spacing**: Minimum 2m spacing between buildings
3. **Building Types**: 
   - Residential towers: Near Marina
   - Commercial: Along main roads
   - Background: Fill remaining areas
4. **Orientation**: Buildings face roads or Marina

### Output

- **Static Mesh Actors**: Building meshes placed in level
- **Material Instances**: Assigned based on building type
- **LODs**: Automatically assigned based on distance

### Implementation Steps

1. **Create PCG Graph**:
   - Create new PCG graph asset: `PCG_BuildingPlacement.pcg`
   - Add input node (spline or points)

2. **Define Rules**:
   - Add "Surface Sampler" node to sample building locations
   - Add "Point Filter" to filter valid placement points
   - Add "Spawn Actor" node to place building meshes

3. **Configure Parameters**:
   - Building density
   - Building types
   - Placement constraints

4. **Test and Iterate**:
   - Execute graph
   - Review placement
   - Adjust rules as needed

---

## Road Props PCG

### Graph: PCG_RoadProps

**Purpose**: Place road props (lamp posts, barriers, signs) along roads

### Input Data

- **Road Splines**: Road network splines
- **Prop Types**: Lamp posts, barriers, signs, etc.

### Placement Rules

1. **Lamp Posts**: 
   - Spacing: 20-30m along roads
   - Placement: Road edges, alternating sides
   - Height: Match road level

2. **Barriers**:
   - Placement: Road medians, pedestrian areas
   - Spacing: Continuous or 2-5m gaps

3. **Signs**:
   - Placement: Road intersections, important locations
   - Orientation: Face traffic direction

### Output

- **Static Mesh Actors**: Prop meshes placed along roads
- **Variations**: Random prop variations for variety

### Implementation Steps

1. **Create PCG Graph**: `PCG_RoadProps.pcg`
2. **Add Spline Sampler**: Sample points along road splines
3. **Add Spawn Actor**: Place prop meshes at sampled points
4. **Add Variation**: Random prop selection and rotation

---

## Vegetation PCG

### Graph: PCG_Vegetation

**Purpose**: Place trees, shrubs, and vegetation in the district

### Input Data

- **Terrain**: Landscape/terrain data
- **Exclusion Zones**: Areas where vegetation shouldn't be placed (roads, buildings)

### Placement Rules

1. **Palm Trees**:
   - Placement: Marina promenade, parks, green spaces
   - Spacing: 5-10m between trees
   - Clustering: Group in natural clusters

2. **Shrubs**:
   - Placement: Around buildings, along paths
   - Density: Medium to high
   - Randomization: Vary size and rotation

3. **Grass**:
   - Placement: Open areas, parks
   - Density: High
   - Use foliage system for performance

### Output

- **Static Mesh Actors**: Tree and shrub meshes
- **Foliage Instances**: Grass and small vegetation
- **Variations**: Random size, rotation, and type

### Implementation Steps

1. **Create PCG Graph**: `PCG_Vegetation.pcg`
2. **Add Surface Sampler**: Sample terrain surface
3. **Add Exclusion Filter**: Exclude roads and buildings
4. **Add Spawn Actor**: Place vegetation meshes
5. **Add Variation**: Randomize size and rotation

---

## Traffic PCG

### Graph: PCG_Traffic

**Purpose**: Generate AI traffic on roads

### Input Data

- **Road Splines**: Road network for traffic paths
- **Vehicle Types**: Car, SUV, supercar variants

### Placement Rules

1. **Vehicle Spawning**:
   - Spawn points: Road intersections, entry points
   - Density: Moderate (not too crowded)
   - Types: Mix of vehicle types

2. **Traffic Flow**:
   - Direction: Follow road direction
   - Speed: Vary by vehicle type
   - Behavior: Use Chaos Vehicle AI

### Output

- **Vehicle Actors**: Spawned vehicles on roads
- **AI Controllers**: Vehicle AI for movement
- **Traffic Flow**: Realistic traffic patterns

### Implementation Steps

1. **Create PCG Graph**: `PCG_Traffic.pcg`
2. **Add Spline Sampler**: Sample road splines
3. **Add Spawn Actor**: Spawn vehicle blueprints
4. **Configure AI**: Set up vehicle AI controllers

---

## PCG Graph Organization

### Folder Structure

```
Content/PCG/
├── PCG_BuildingPlacement.pcg
├── PCG_RoadProps.pcg
├── PCG_Vegetation.pcg
├── PCG_Traffic.pcg
└── SubGraphs/
    ├── PCG_BuildingRules.pcg
    └── PCG_PropRules.pcg
```

### Naming Convention

- **Format**: `PCG_SystemName_Purpose.pcg`
- **Examples**: 
  - `PCG_BuildingPlacement.pcg`
  - `PCG_RoadProps_LampPosts.pcg`

---

## Best Practices

### Performance

1. **Baking**: Bake PCG output to static meshes for performance
2. **LODs**: Use LOD system for distant content
3. **Culling**: Use distance culling for props
4. **Instancing**: Use instanced static meshes where possible

### Quality

1. **Variation**: Add randomization for natural look
2. **Rules**: Define clear placement rules
3. **Validation**: Validate output quality
4. **Iteration**: Iterate on rules until satisfied

### Workflow

1. **Start Simple**: Begin with basic placement rules
2. **Iterate**: Refine rules based on output
3. **Test**: Test in level regularly
4. **Document**: Document rules and parameters

---

## Troubleshooting

### Common Issues

**Issue**: Buildings overlapping
- **Solution**: Add minimum distance filter

**Issue**: Props not placing correctly
- **Solution**: Check spline direction and sampling

**Issue**: Performance issues
- **Solution**: Bake to static meshes, use LODs

**Issue**: Vegetation in wrong areas
- **Solution**: Add exclusion zones/filters

---

## Validation

### PCG Output Validation

Use `scripts/pcg_validation.py` to validate:
- Placement rules are followed
- No overlapping content
- Performance is acceptable
- Visual quality meets standards

---

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