metaverseDubai/docs/setup/UE5_INSTALLATION.md

# Unreal Engine 5.4 Installation Guide

## Table of Contents

- [Overview](#overview)
- [Platform Options](#platform-options)
- [System Requirements](#system-requirements)
- [Windows Installation (Epic Games Launcher)](#windows-installation-epic-games-launcher)
- [Linux/Ubuntu/WSL Installation (Source Build)](#linuxubuntuwsl-installation-source-build)
- [Project Creation](#project-creation)
- [Disk Space Optimization](#disk-space-optimization)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)

---

## Overview

This guide covers installation of Unreal Engine 5.4 for the Dubai Metaverse project. Choose your platform:

- **Windows**: Epic Games Launcher (Recommended - Easiest)
- **Linux/Ubuntu/WSL**: Source build from GitHub (Advanced)

**Official Repository**: https://github.com/EpicGames/UnrealEngine

---

## Platform Options

### Windows (Epic Games Launcher)
- ✅ Easiest installation method
- ✅ Automatic updates
- ✅ Pre-built binaries
- ✅ No compilation required

### Linux/Ubuntu/WSL (Source Build)
- ✅ Full control over build configuration
- ✅ Optimized for your system
- ✅ Can customize build options
- ⚠️ Requires compilation (2-6+ hours)
- ⚠️ Requires GitHub account linked to Epic Games

---

## System Requirements

### Windows (Epic Games Launcher)

#### Minimum Requirements
- **OS**: Windows 10 64-bit (version 1909 or later) or Windows 11
- **CPU**: Quad-core Intel or AMD processor, 2.5 GHz or faster
- **RAM**: 8 GB (16 GB recommended)
- **GPU**: DirectX 11 or 12 compatible graphics card
- **Storage**: 100 GB free space (SSD recommended)
- **Internet**: Broadband connection for Epic Games Launcher

#### Recommended Requirements
- **OS**: Windows 11 64-bit
- **CPU**: 8-core Intel i7-9700K / AMD Ryzen 7 3700X or better
- **RAM**: 32 GB or more
- **GPU**: NVIDIA RTX 3070 / AMD RX 6800 XT or better (8GB+ VRAM)
- **Storage**: 500 GB+ NVMe SSD
- **Internet**: High-speed connection

### Linux/Ubuntu/WSL (Source Build)

#### Minimum Requirements
- **OS**: Ubuntu 20.04 LTS or later (22.04 LTS recommended)
- **CPU**: 8-core processor (more cores = faster build)
- **RAM**: 32 GB (16 GB minimum, 64 GB recommended)
- **GPU**: NVIDIA GPU with Vulkan support
- **Storage**: 100 GB+ free space (SSD recommended)
- **Build Time**: 2-4+ hours depending on CPU

#### WSL-Specific Requirements
- **WSL Version**: WSL2 (WSLg for Windows 11 recommended)
- **Windows GPU Drivers**: NVIDIA drivers installed on Windows host (not in WSL)
- **X Server**: WSLg (Windows 11) or VcXsrv/Xming (Windows 10)

---

## Windows Installation (Epic Games Launcher)

### Step 1: Install Epic Games Launcher

1. **Download**: Visit [Epic Games](https://www.epicgames.com/store/en-US/download)
2. **Install**: Run the installer and follow the prompts
3. **Sign In**: Create an account or sign in to existing account
4. **Verify**: Ensure launcher is up to date

### Step 2: Install Unreal Engine 5.4

1. **Open Launcher**: Launch Epic Games Launcher
2. **Unreal Engine Tab**: Click on "Unreal Engine" tab
3. **Library**: Go to "Library" section
4. **Add Version**: Click "+" button to add engine version
5. **Select Version**: Choose "5.4" from the dropdown
6. **Install**: Click "Install" and select installation location
7. **Wait**: Wait for download and installation to complete (may take 1-2 hours)

**Installation Location**: 
- Default: `C:\Program Files\Epic Games\UE_5.4\`
- Recommended: Install on SSD for better performance

### Step 3: Verify Installation

1. **Launch**: Launch Unreal Engine 5.4 from Epic Games Launcher
2. **Create Project**: Create a test project to verify installation
3. **Check Version**: Verify version number in Help > About Unreal Editor

---

## Linux/Ubuntu/WSL Installation (Source Build)

### Prerequisites

#### 1. Link GitHub to Epic Games Account (REQUIRED)

**This step is mandatory before cloning the repository:**

1. Visit: https://www.unrealengine.com/en-US/ue-on-github
2. Sign in with your Epic Games account
3. Link your GitHub account
4. Accept the Unreal Engine license agreement

**Verify access:**
```bash
git ls-remote https://github.com/EpicGames/UnrealEngine.git
```

If this fails, complete the GitHub/Epic Games linking step above.

#### 2. WSL Setup (If Using WSL)

1. **Install/Update WSL** (from Windows PowerShell as Administrator):
   ```powershell
   wsl --install
   wsl --update
   ```

2. **Launch Ubuntu**:
   ```bash
   wsl
   ```

### Installation Methods

#### Method A: Automated Installation (Recommended)

**For UE 5.4.1 (Optimized - 4 cores, ~80-100GB disk):**
```bash
cd /home/intlc/projects/metaverseDubai
./scripts/install_ue5_5.4.1_auto.sh
```

**For UE 5.4 (Standard):**
```bash
cd /home/intlc/projects/metaverseDubai
./scripts/install_ue5_wsl.sh
```

The automated script will:
- Install all dependencies
- Clone the repository
- Build Unreal Engine
- Create launch script

**Expected Time**: 4-6+ hours (with 4 cores) or 2-4 hours (with all cores)

#### Method B: Manual Installation

##### Step 1: Install System Dependencies

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Add .NET backports repository (for Ubuntu 24.04)
sudo add-apt-repository -y ppa:dotnet/backports
sudo apt update

# Install build tools and dependencies
sudo apt install -y \
  build-essential \
  clang \
  cmake \
  ninja-build \
  mono-devel \
  python3 \
  python3-pip \
  git \
  git-lfs \
  curl \
  wget \
  unzip \
  libvulkan-dev \
  libxcb-xinput-dev \
  libgtk-3-dev \
  libxrandr-dev \
  libxinerama-dev \
  libxi-dev \
  libsdl2-dev \
  libssl-dev \
  libicu-dev \
  libxml2-dev \
  libxcursor-dev \
  libxcb-icccm4-dev \
  libxcb-image0-dev \
  libxcb-keysyms1-dev \
  libxcb-render-util0-dev \
  libxcb-xkb-dev \
  libxkbcommon-dev \
  libxkbcommon-x11-dev \
  mesa-common-dev \
  libgl1-mesa-dev \
  libc++-dev \
  libc++abi-dev

# Install .NET SDK (try 6.0, fallback to 8.0)
sudo apt install -y dotnet-sdk-6.0 || sudo apt install -y dotnet-sdk-8.0

# Setup Git LFS
git lfs install
```

##### Step 2: Clone Unreal Engine Repository

**Check Available Versions:**
```bash
# List all 5.4.x tags
git ls-remote --tags https://github.com/EpicGames/UnrealEngine.git | grep "5.4" | tail -10

# List branches
git ls-remote --heads https://github.com/EpicGames/UnrealEngine.git | grep -E "(5.4|release)"
```

**Clone Repository:**

For **5.4 branch** (latest 5.4.x):
```bash
cd ~
git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 UnrealEngine
```

For **specific tag** (e.g., 5.4.1):
```bash
cd ~
git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git UnrealEngine
cd UnrealEngine
git fetch --depth=1 origin tag 5.4.1
git checkout 5.4.1
```

**Note**: Cloning may take 30-60 minutes depending on connection speed.

##### Step 3: Build Unreal Engine

```bash
cd ~/UnrealEngine

# Run Setup script (downloads dependencies, 30-60 minutes)
./Setup.sh

# Generate project files
./GenerateProjectFiles.sh -game -engine

# Build Unreal Editor
# Standard build (uses all cores):
make -j$(nproc) UnrealEditor

# Optimized build (4 cores, saves memory):
make -j4 UnrealEditor
```

**Build Time**:
- 4 cores: 4-6+ hours
- 8 cores: 2-3 hours
- 16 cores: 1-2 hours
- 32 cores: 45-90 minutes

##### Step 4: Verify Installation

```bash
# Check binary exists
ls -lh ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor

# Check version
~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor -version
```

##### Step 5: WSL Graphics Setup (WSL Only)

**Option A: WSLg (Windows 11 - Recommended)**

WSLg provides built-in graphics support:
```bash
# Verify WSLg
echo $DISPLAY
# Should show something like :0

# If not working, update WSL
# From Windows PowerShell:
wsl --update
```

**Option B: X Server (Windows 10 or if WSLg unavailable)**

1. **Install X Server on Windows**:
   - **VcXsrv**: https://sourceforge.net/projects/vcxsrv/
   - **Xming**: https://sourceforge.net/projects/xming/

2. **Configure DISPLAY in WSL**:
   ```bash
   # Add to ~/.bashrc or ~/.zshrc
   export DISPLAY=$(ip route list default | awk '{print $3}'):0.0
   source ~/.bashrc
   ```

3. **Test X Server**:
   ```bash
   sudo apt install x11-apps
   xeyes  # Should open a window
   ```

---

## Project Creation

### Windows

1. **Launch UE5.4**: Open Epic Games Launcher and launch Unreal Engine 5.4
2. **New Project**: Click "New Project" or "Games" tab
3. **Template**: Select "Blank" or "Third Person" template
4. **Settings**:
   - **Blueprint**: Start with Blueprint (C++ can be added later)
   - **Target Platform**: Desktop
   - **Quality Preset**: Maximum
   - **Raytracing**: Optional (requires RTX GPU)
   - **Starter Content**: No Starter Content
5. **Project Name**: `DubaiMetaverse`
6. **Location**: Choose project location
7. **Create**: Click "Create Project"

### Linux/WSL

```bash
# Create project directory
cd /home/intlc/projects/metaverseDubai
mkdir -p DubaiMetaverse
cd DubaiMetaverse

# Create .uproject file
cat > DubaiMetaverse.uproject << 'EOF'
{
	"FileVersion": 3,
	"EngineAssociation": "5.4",
	"Category": "",
	"Description": "Dubai Metaverse - High-End Interactive Demo District",
	"Modules": [
		{
			"Name": "DubaiMetaverse",
			"Type": "Runtime",
			"LoadingPhase": "Default"
		}
	],
	"Plugins": [
		{
			"Name": "ProceduralContentGeneration",
			"Enabled": true
		},
		{
			"Name": "VirtualProduction",
			"Enabled": true
		},
		{
			"Name": "MovieRenderQueue",
			"Enabled": true
		}
	]
}
EOF

# Generate project files
~/UnrealEngine/Engine/Binaries/Linux/UnrealVersionSelector-Linux.sh \
  -projectfiles \
  -project="$PWD/DubaiMetaverse.uproject" \
  -game \
  -rocket \
  -progress

# Launch project
~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor "$PWD/DubaiMetaverse.uproject"
```

### Initial Project Configuration

After project creation:

1. **Edit > Project Settings**:
   - **Project Name**: Dubai Metaverse
   - **Company Name**: [Your Company]
   - **Copyright Notice**: [Copyright Info]

2. **Engine Settings** (see [docs/setup/PROJECT_SETTINGS.md](../../docs/setup/PROJECT_SETTINGS.md)):
   - Enable Nanite
   - Enable Lumen
   - Enable Virtual Shadow Maps
   - Enable World Partition

3. **Install Required Plugins** (see [docs/setup/PLUGINS.md](../../docs/setup/PLUGINS.md)):
   - Procedural Content Generation Framework
   - Virtual Production Tools
   - Movie Render Queue

---

## Disk Space Optimization

For Linux/WSL installations, you can optimize disk space usage:

### Optimization Strategies

1. **Shallow Git Clone**: `--depth=1` saves ~5GB
2. **Development Editor Only**: Saves ~50-70GB (skips Shipping builds)
3. **Limited CPU Cores**: `-j4` reduces memory usage
4. **Clean Intermediate Files**: Saves ~20-30GB after build

### Optimized Build Configuration

**Disk Space**: ~80-100GB (vs ~150GB+ full build)

**Build Command**:
```bash
# Build with 4 cores (optimized)
make -j4 UnrealEditor

# Clean intermediate files after build
find Engine/Intermediate -type f -name "*.o" -delete
find Engine/Intermediate -type f -name "*.obj" -delete
find Engine/Intermediate -type f -name "*.d" -delete
find Engine/Intermediate -type f -name "*.pch" -delete
```

**See**: [UE5_DISK_SPACE_OPTIMIZATION.md](../../UE5_DISK_SPACE_OPTIMIZATION.md) for detailed optimization guide.

---

## Troubleshooting

### GitHub Access Denied

**Error**: `fatal: could not read Username for 'https://github.com'`

**Solution**: 
1. Ensure GitHub account is linked to Epic Games
2. Visit: https://www.unrealengine.com/en-US/ue-on-github
3. Try using SSH instead of HTTPS (requires SSH key setup)

### Build Fails Due to Low RAM

**Symptoms**: Build process killed, out of memory errors

**Solutions**:
- Reduce parallel jobs: `make -j2 UnrealEditor` (instead of `-j4`)
- Close other applications
- Add swap space
- Edit script: Change `NUM_CORES=4` to `NUM_CORES=2`

### Tag Not Found

**Solution**: The script will automatically fall back to the `5.4` branch, which contains the latest 5.4.x updates.

### WSL Graphics Issues

**Windows 11**: WSLg should work automatically

**Windows 10**: Install VcXsrv or Xming X server
- Download: https://sourceforge.net/projects/vcxsrv/
- Launch with: "Disable access control" enabled

### Build Fails

**Solution**: Clean and rebuild
```bash
cd ~/UnrealEngine
make clean
./Setup.sh
./GenerateProjectFiles.sh
make -j4 UnrealEditor
```

### X Server Connection Issues

**Solution**:
```bash
# Check DISPLAY variable
echo $DISPLAY

# Test X connection
xhost +local:

# Verify X server is running on Windows
```

### Missing Dependencies

**Solution**:
```bash
sudo apt update
sudo apt install -f
# Check specific error messages and install required packages
```

### Engine Won't Launch (Windows)

**Solutions**:
- Update graphics drivers
- Verify DirectX is installed
- Check Windows updates

### Project Won't Open

**Solutions**:
- Verify project file (.uproject) is valid
- Check project is compatible with UE5.4
- Try regenerating project files (right-click .uproject > Generate Visual Studio files)

---

## Next Steps

After successful installation:

1. ✅ Verify installation: `~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor -version` (Linux) or launch from Epic Games Launcher (Windows)
2. ✅ Review [docs/setup/PROJECT_SETTINGS.md](../../docs/setup/PROJECT_SETTINGS.md) for engine configuration
3. ✅ Install plugins (see [docs/setup/PLUGINS.md](../../docs/setup/PLUGINS.md))
4. ✅ Set up version control (see [docs/setup/VERSION_CONTROL.md](../../docs/setup/VERSION_CONTROL.md))
5. ✅ Review [docs/PIPELINE.md](../../docs/PIPELINE.md) for development workflow
6. ✅ Begin Phase 1, Week 2: Geospatial acquisition and blockout

---

## Resources

- **Unreal Engine on GitHub**: https://github.com/EpicGames/UnrealEngine
- **UE on GitHub Setup**: https://www.unrealengine.com/en-US/ue-on-github
- **WSL Documentation**: https://docs.microsoft.com/en-us/windows/wsl/
- **WSLg Documentation**: https://github.com/microsoft/wslg
- **Epic Games Forums**: https://forums.unrealengine.com
- **Unreal Engine Documentation**: https://docs.unrealengine.com

---

**Version**: 1.0 (Consolidated)  
**Last Updated**: 2024  
**Platforms**: Windows, Linux, Ubuntu, WSL