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:

./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:

./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:

./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:

./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:

./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:

./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:

./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:

./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:

./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:

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:

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:

./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:

./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:

./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:

./scripts/enhance_scripts.sh

Functions:

• Validates script syntax
• Checks for common issues
• Suggests improvements

generate_docs.sh

Purpose: Generate/validate documentation

Usage:

./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:

./scripts/master_setup.sh

Functions:

• Runs project setup
• Validates installation
• Configures environment

Python Scripts

pcg_validation.py

Purpose: Validate PCG graph outputs

Usage:

python3 scripts/pcg_validation.py [options]

Status: Placeholder for Phase 2

texture_validation.py

Purpose: Validate texture resolution and format

Usage:

python3 scripts/texture_validation.py [options]

Status: Placeholder for Phase 2

lighting_validation.py

Purpose: Validate lighting setup and performance

Usage:

python3 scripts/lighting_validation.py [options]

Status: Placeholder for Phase 3

performance_audit.py

Purpose: Audit performance metrics

Usage:

python3 scripts/performance_audit.py [options]

Status: Placeholder for Phase 4

render_cinematic.py

Purpose: Automate Movie Render Queue rendering

Usage:

python3 scripts/render_cinematic.py [options]

Status: Placeholder for Phase 4

automated_tests.py

Purpose: Run automated test suite

Usage:

python3 scripts/automated_tests.py [options]

Status: Placeholder for Phase 5

npc_dialogue_api.py

Purpose: ChatGPT API integration for NPC dialogue

Usage:

python3 scripts/npc_dialogue_api.py [options]

Status: Optional feature

Common Patterns

Logging

All scripts use consistent logging:

log "INFO" "Message"
log "WARNING" "Warning message"
log "ERROR" "Error message"
log "SUCCESS" "Success message"

Error Handling

Standard error handling:

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 - Script development standards
• Scripts README - General scripts documentation

---

Last Updated: 2024