metaverseDubai/scripts/API_REFERENCE.md

# Scripts API Reference - Dubai Metaverse

## Overview

This document provides API reference for all automation scripts in the Dubai Metaverse project.

## Setup Scripts

### setup_project.sh

**Purpose**: Initialize project structure and configuration

**Usage**:
```bash
./scripts/setup/setup_project.sh
```

**Functions**:
- Initializes Git repository
- Sets up Git LFS
- Creates directory structure
- Validates prerequisites

**Exit Codes**:
- `0`: Success
- `1`: Error

### setup_ue5_project.sh

**Purpose**: Validate and configure Unreal Engine project

**Usage**:
```bash
./scripts/setup/setup_ue5_project.sh
```

**Functions**:
- Validates project structure
- Checks UE5 installation
- Verifies project settings

### create_ue5_project.sh

**Purpose**: Create Dubai Metaverse Unreal Engine project

**Usage**:
```bash
./scripts/setup/create_ue5_project.sh [PROJECT_NAME]
```

**Arguments**:
- `PROJECT_NAME` (optional): Project name (default: DubaiMetaverse)

**Functions**:
- Creates .uproject file
- Sets up Source directory structure
- Copies configuration files
- Generates project files
- Verifies Content directory

**Exit Codes**:
- `0`: Success
- `1`: Error
- `2`: Invalid arguments
- `3`: Missing dependencies

### verify_ue5_installation.sh

**Purpose**: Verify Unreal Engine 5.4 installation

**Usage**:
```bash
./scripts/setup/verify_ue5_installation.sh
```

**Functions**:
- Checks UnrealEditor binary exists
- Verifies version (5.4.x)
- Checks required plugins
- Reports installation size

**Exit Codes**:
- `0`: Installation verified
- `1`: Installation issues found

### setup_blockout.sh

**Purpose**: Display blockout level setup guide

**Usage**:
```bash
./scripts/setup/setup_blockout.sh
```

**Functions**:
- Displays blockout setup instructions
- Provides checklist
- Links to detailed documentation

## Installation Scripts

### install_ue5_5.4.1_auto.sh

**Purpose**: Automated installation of Unreal Engine 5.4.1

**Usage**:
```bash
./scripts/install_ue5_5.4.1_auto.sh
```

**Options**: None (fully automated)

**Functions**:
- Installs system dependencies
- Clones UE5.4.1 repository
- Builds Unreal Engine
- Creates launch script

**Exit Codes**:
- `0`: Success
- `1`: Error

**Output**: 
- Unreal Engine installed to `~/UnrealEngine/`
- Launch script: `~/launch_ue5.sh`

### install_ue5_wsl.sh

**Purpose**: Install Unreal Engine 5.4 on WSL/Ubuntu

**Usage**:
```bash
./scripts/install_ue5_wsl.sh
```

**Similar to**: `install_ue5_5.4.1_auto.sh` but for 5.4 branch

## Validation Scripts

### validate_project.sh

**Purpose**: Validate project structure and configuration

**Usage**:
```bash
./scripts/validation/validate_project.sh
```

**Functions**:
- Checks directory structure
- Validates configuration files
- Verifies documentation
- Checks script standards

**Exit Codes**:
- `0`: All validations pass
- `1`: Validation failures found

### validate_assets.sh

**Purpose**: Validate asset naming and structure

**Usage**:
```bash
./scripts/validation/validate_assets.sh [directory]
```

**Arguments**:
- `directory` (optional): Directory to validate (default: Content/)

**Functions**:
- Validates naming conventions
- Checks folder structure
- Verifies asset organization

## Data Processing Scripts

### import_osm_data.py

**Purpose**: Import OpenStreetMap data for Dubai Marina

**Usage**:
```bash
python3 scripts/data/import_osm_data.py --output data/processed/dubai_marina_buildings.geojson
```

**Options**:
- `--output`: Output file path (required)
- `--area`: Bounding box coordinates (optional)
- `--verbose`: Enable verbose output

**Returns**: GeoJSON file with building footprints

**Dependencies**: `overpy`, `geojson`

### gis_to_unreal.py

**Purpose**: Convert GIS elevation data to Unreal terrain format

**Usage**:
```bash
python3 scripts/data/gis_to_unreal.py data/elevation/dubai_marina_dem.tif --output data/processed/terrain_heightmap.raw
```

**Options**:
- `--output`: Output file path (required)
- `--resolution`: Heightmap resolution (optional)
- `--scale`: Height scale factor (optional)

**Returns**: Raw heightmap file for Unreal Engine

**Dependencies**: `rasterio`, `numpy`

## Build Scripts

### package_build.sh

**Purpose**: Package project for distribution

**Usage**:
```bash
./scripts/build/package_build.sh [options]
```

**Options**:
- `-c, --config CONFIG`: Build configuration (Development/Shipping) [default: Shipping]
- `-p, --platform PLAT`: Platform (Windows/Linux) [default: Windows]
- `-o, --output DIR`: Output directory [default: Builds/]
- `-d, --dry-run`: Perform dry run
- `-v, --verbose`: Enable verbose output
- `-h, --help`: Show help

**Functions**:
- Cleans build artifacts
- Validates assets
- Packages project
- Creates distribution build

**Exit Codes**:
- `0`: Success
- `1`: Error
- `2`: Invalid arguments

### setup_pixel_streaming.sh

**Purpose**: Set up Pixel Streaming for cloud access

**Usage**:
```bash
./scripts/build/setup_pixel_streaming.sh [options]
```

**Options**:
- `-p, --port PORT`: Streaming port [default: 8888]
- `-s, --signaling PORT`: Signaling server port [default: 8888]
- `-d, --dry-run`: Perform dry run
- `-v, --verbose`: Enable verbose output
- `-h, --help`: Show help

**Functions**:
- Enables Pixel Streaming plugin
- Configures project settings
- Sets up signaling server
- Creates startup script

**Exit Codes**:
- `0`: Success
- `1`: Error

## Monitoring Scripts

### monitor_ue5_install.sh

**Purpose**: Monitor UE5 installation progress

**Usage**:
```bash
./scripts/monitor_ue5_install.sh
```

**Functions**:
- Checks installation status
- Shows build progress
- Displays disk usage
- Lists active processes

## Utility Scripts

### enhance_scripts.sh

**Purpose**: Check and enhance script syntax

**Usage**:
```bash
./scripts/enhance_scripts.sh
```

**Functions**:
- Validates script syntax
- Checks for common issues
- Suggests improvements

### generate_docs.sh

**Purpose**: Generate/validate documentation

**Usage**:
```bash
./scripts/generate_docs.sh
```

**Functions**:
- Validates documentation structure
- Checks for broken links
- Generates documentation index

### master_setup.sh

**Purpose**: Run all setup scripts in sequence

**Usage**:
```bash
./scripts/master_setup.sh
```

**Functions**:
- Runs project setup
- Validates installation
- Configures environment

## Python Scripts

### pcg_validation.py

**Purpose**: Validate PCG graph outputs

**Usage**:
```bash
python3 scripts/pcg_validation.py [options]
```

**Status**: Placeholder for Phase 2

### texture_validation.py

**Purpose**: Validate texture resolution and format

**Usage**:
```bash
python3 scripts/texture_validation.py [options]
```

**Status**: Placeholder for Phase 2

### lighting_validation.py

**Purpose**: Validate lighting setup and performance

**Usage**:
```bash
python3 scripts/lighting_validation.py [options]
```

**Status**: Placeholder for Phase 3

### performance_audit.py

**Purpose**: Audit performance metrics

**Usage**:
```bash
python3 scripts/performance_audit.py [options]
```

**Status**: Placeholder for Phase 4

### render_cinematic.py

**Purpose**: Automate Movie Render Queue rendering

**Usage**:
```bash
python3 scripts/render_cinematic.py [options]
```

**Status**: Placeholder for Phase 4

### automated_tests.py

**Purpose**: Run automated test suite

**Usage**:
```bash
python3 scripts/automated_tests.py [options]
```

**Status**: Placeholder for Phase 5

### npc_dialogue_api.py

**Purpose**: ChatGPT API integration for NPC dialogue

**Usage**:
```bash
python3 scripts/npc_dialogue_api.py [options]
```

**Status**: Optional feature

## Common Patterns

### Logging

All scripts use consistent logging:
```bash
log "INFO" "Message"
log "WARNING" "Warning message"
log "ERROR" "Error message"
log "SUCCESS" "Success message"
```

### Error Handling

Standard error handling:
```bash
error_exit "Error message"  # Exits with code 1
warning "Warning message"   # Logs warning, continues
```

### Exit Codes

Standard exit codes:
- `0`: Success
- `1`: General error
- `2`: Invalid arguments
- `3`: Missing dependencies

## Environment Variables

### UE_ROOT
Unreal Engine installation directory
- Default: `~/UnrealEngine` or `/opt/UnrealEngine`
- Used by: Build and packaging scripts

### PROJECT_ROOT
Project root directory
- Default: Parent of scripts directory
- Used by: All scripts

### LOG_FILE
Log file path
- Default: `$PROJECT_ROOT/logs/script_name.log`
- Used by: All scripts

## Dependencies

### System Dependencies
- `bash` 4.0+
- `python3` 3.8+
- `git` 2.0+
- `git-lfs` 2.0+

### Python Dependencies
See `requirements.txt`:
- `overpy` - OpenStreetMap data
- `geojson` - GeoJSON handling
- `rasterio` - GIS data processing
- `numpy` - Numerical operations

## See Also

- [Script Standards](STANDARDS.md) - Script development standards
- [Scripts README](README.md) - General scripts documentation

---

**Last Updated**: 2024