metaverseDubai/UE5_WSL_INSTALL.md

# Unreal Engine 5.4 Installation - WSL/Ubuntu CLI Guide

## Overview

This guide provides command-line instructions for installing Unreal Engine 5.4 on Ubuntu within Windows Subsystem for Linux (WSL) or native Ubuntu.

## Prerequisites

### WSL Setup (If Using WSL)

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

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

### System Requirements

- **OS**: Ubuntu 20.04 LTS or later (22.04 LTS recommended)
- **CPU**: 8+ cores recommended
- **RAM**: 32GB+ recommended (16GB minimum)
- **Storage**: 100GB+ free space (SSD recommended)
- **GPU**: NVIDIA GPU with Vulkan support (for WSL, drivers on Windows host)

---

## Step 1: Install System Dependencies

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

### Install Build Tools and Dependencies
```bash
sudo apt install -y \
  build-essential \
  clang \
  cmake \
  ninja-build \
  mono-devel \
  python3 \
  python3-pip \
  git \
  git-lfs \
  curl \
  wget \
  unzip
```

### Install Graphics and UI Dependencies
```bash
sudo apt install -y \
  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
```

### Install Additional Tools
```bash
sudo apt install -y \
  dotnet-sdk-6.0 \
  libc++-dev \
  libc++abi-dev
```

---

## Step 2: Link Epic Games and GitHub Accounts

### Required Before Cloning

1. **Create Epic Games Account** (if needed):
   - Visit: https://www.epicgames.com
   - Create account and sign in

2. **Link GitHub Account**:
   - Go to: https://www.unrealengine.com/en-US/ue-on-github
   - Sign in with Epic Games account
   - Link your GitHub account
   - Accept Unreal Engine license agreement

**Note**: This step is required to access the Unreal Engine source code repository.

---

## Step 3: Clone Unreal Engine Source

### Set Up Git
```bash
# Configure Git (if not already done)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Install Git LFS
git lfs install
```

### Clone Repository
```bash
# Navigate to desired installation directory
cd ~
mkdir -p UnrealEngine
cd UnrealEngine

# Clone Unreal Engine 5.4 (release branch)
# Note: This requires GitHub account linked to Epic Games account
git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 .

# Or clone specific 5.4 tag:
# git clone --depth=1 --branch 5.4 https://github.com/EpicGames/UnrealEngine.git .
```

**Note**: The repository is large (~10GB+). Cloning may take 30-60 minutes depending on connection speed.

---

## Step 4: Build Unreal Engine

### Run Setup Script
```bash
cd ~/UnrealEngine
./Setup.sh
```

This script:
- Downloads required dependencies
- Sets up build files
- May take 30-60 minutes

### Generate Project Files
```bash
./GenerateProjectFiles.sh
```

This generates:
- Makefiles for building
- Project files for IDEs (optional)

### Compile Unreal Engine
```bash
# Build Unreal Engine (this will take 2-4+ hours depending on CPU)
make UnrealEditor

# Or build with multiple cores (faster):
make -j$(nproc) UnrealEditor
```

**Build Time**: 
- 8-core CPU: ~2-3 hours
- 16-core CPU: ~1-2 hours
- 32-core CPU: ~45-90 minutes

**Note**: The build process is CPU-intensive. Close other applications for faster compilation.

---

## Step 5: Verify Installation

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

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

### Test Launch (Requires X Server for WSL)
```bash
# For WSL: You need an X server running on Windows
# Install X server: VcXsrv, Xming, or WSLg (Windows 11)

# Launch Unreal Editor
~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor
```

---

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

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

WSLg provides built-in graphics support on Windows 11:

1. **Verify WSLg**:
   ```bash
   echo $DISPLAY
   # Should show something like :0
   ```

2. **If WSLg not working**, update WSL:
   ```powershell
   # From Windows PowerShell
   wsl --update
   ```

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

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

2. **Configure X Server**:
   - Start X Server
   - Allow connections from WSL
   - Note the display number (usually :0)

3. **Set DISPLAY in WSL**:
   ```bash
   # Add to ~/.bashrc or ~/.zshrc
   export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0.0
   
   # Or for WSL2:
   export DISPLAY=$(ip route list default | awk '{print $3}'):0.0
   
   # Reload shell
   source ~/.bashrc
   ```

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

---

## Step 7: Create Project

### Create Project Directory
```bash
cd /home/intlc/projects/metaverseDubai
mkdir -p DubaiMetaverse
cd DubaiMetaverse
```

### Create Project File
```bash
# 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": "ModelingToolsEditorMode",
			"Enabled": true
		},
		{
			"Name": "ProceduralContentGeneration",
			"Enabled": true
		},
		{
			"Name": "VirtualProduction",
			"Enabled": true
		},
		{
			"Name": "MovieRenderQueue",
			"Enabled": true
		}
	]
}
EOF
```

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

### Launch Project
```bash
# Launch Unreal Editor with project
~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor "$PWD/DubaiMetaverse.uproject"
```

---

## Alternative: Pre-built Binary (If Available)

### Check for Pre-built Linux Binaries

Epic Games may provide pre-built Linux binaries. Check:
- Epic Games Launcher (if available for Linux)
- Unreal Engine downloads page
- Community builds

**Note**: Pre-built binaries may not be available for all versions. Building from source is the most reliable method for Linux.

---

## Performance Considerations for WSL

### WSL2 Configuration

1. **Allocate More Resources** (`.wslconfig` on Windows):
   ```ini
   [wsl2]
   memory=32GB
   processors=8
   swap=8GB
   localhostForwarding=true
   ```

   Location: `C:\Users\<YourUser>\.wslconfig`

2. **GPU Passthrough**:
   - WSL2 supports GPU passthrough on Windows 11
   - Install NVIDIA drivers on Windows (not in WSL)
   - WSL will use Windows drivers automatically

3. **File System Performance**:
   - Store project on WSL file system (`/home/...`)
   - Avoid Windows file system (`/mnt/c/...`) for project files
   - Better performance on native Linux file system

---

## Troubleshooting

### Build Fails

**Issue**: Compilation errors
```bash
# Clean and rebuild
cd ~/UnrealEngine
make clean
./Setup.sh
./GenerateProjectFiles.sh
make -j$(nproc) UnrealEditor
```

### X Server Connection Issues

**Issue**: Cannot connect to X server
```bash
# Check DISPLAY variable
echo $DISPLAY

# Test X connection
xhost +local:

# Verify X server is running on Windows
```

### Out of Memory During Build

**Issue**: Build fails due to memory
```bash
# Reduce parallel jobs
make -j4 UnrealEditor  # Use 4 cores instead of all

# Or increase swap
sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

### Missing Dependencies

**Issue**: Build errors about missing libraries
```bash
# Install missing dependencies
sudo apt update
sudo apt install -f

# Check specific error messages and install required packages
```

---

## Quick Installation Script

Create a script to automate installation:

```bash
#!/bin/bash
# save as: install_ue5_wsl.sh

set -e

echo "Installing Unreal Engine 5.4 on Ubuntu/WSL..."

# Install dependencies
sudo apt update && 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

# Setup Git LFS
git lfs install

# Clone UE5 (requires GitHub linked to Epic account)
cd ~
if [ ! -d "UnrealEngine" ]; then
    git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 UnrealEngine
fi

# Build
cd ~/UnrealEngine
./Setup.sh
./GenerateProjectFiles.sh
make -j$(nproc) UnrealEditor

echo "Installation complete!"
echo "Unreal Editor: ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"
```

---

## Verification Checklist

After installation, verify:

- [ ] UnrealEditor binary exists
- [ ] Can launch Unreal Editor
- [ ] X server working (for WSL)
- [ ] Can create new project
- [ ] Project opens in editor
- [ ] Engine features work (Nanite, Lumen)

---

## Next Steps

After successful installation:

1. ✅ Follow [PROJECT_SETTINGS.md](PROJECT_SETTINGS.md) for configuration
2. ✅ Create project in `/home/intlc/projects/metaverseDubai/DubaiMetaverse`
3. ✅ Copy config templates from `Config/*.template` to project `Config/`
4. ✅ Begin Phase 1, Week 2: Geospatial acquisition

---

## 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

---

**Version**: 1.0
**Last Updated**: [Current Date]
**Platform**: Ubuntu/WSL