diff --git a/README.md b/README.md index eaade91..2b48674 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,8 @@ This project aims to create a **studio-grade, cinematic, 8K-ready, interactive D - [Project Plan](PROJECT_PLAN.md) - Complete 90-day roadmap - [Pipeline Documentation](PIPELINE.md) - Development workflows and toolchain - [Naming Conventions](NAMING_CONVENTIONS.md) - Asset naming standards -- [UE5 Setup Guide](UE5_SETUP.md) - Installation and configuration +- [UE5 Setup Guide](UE5_SETUP.md) - Windows installation (Epic Games Launcher) +- [UE5 WSL Installation](UE5_WSL_INSTALL.md) - Linux/Ubuntu/WSL CLI installation - [Project Settings](PROJECT_SETTINGS.md) - Engine configuration details - [Plugins Guide](PLUGINS.md) - Required plugins and setup - [Version Control](VERSION_CONTROL.md) - Git LFS setup and workflows @@ -60,7 +61,9 @@ This project aims to create a **studio-grade, cinematic, 8K-ready, interactive D ### Prerequisites -1. **Unreal Engine 5.4** - See [UE5_SETUP.md](UE5_SETUP.md) for installation +1. **Unreal Engine 5.4** + - **Windows**: See [UE5_SETUP.md](UE5_SETUP.md) for Epic Games Launcher installation + - **Linux/WSL**: See [UE5_WSL_INSTALL.md](UE5_WSL_INSTALL.md) for CLI source build 2. **Git LFS** - Required for large file version control 3. **Python 3.8+** - For automation scripts 4. **Houdini** (Optional) - For procedural generation diff --git a/UE5_SETUP.md b/UE5_SETUP.md index 8f73883..5583955 100644 --- a/UE5_SETUP.md +++ b/UE5_SETUP.md @@ -1,8 +1,16 @@ # Unreal Engine 5.4 Setup Guide +## Platform Options + +This guide covers installation for: +- **Windows** (Epic Games Launcher - Recommended) +- **Linux/Ubuntu/WSL** (Source build - See [UE5_WSL_INSTALL.md](UE5_WSL_INSTALL.md) for CLI instructions) + ## System Requirements -### Minimum 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 @@ -11,7 +19,7 @@ - **Storage**: 100 GB free space (SSD recommended) - **Internet**: Broadband connection for Epic Games Launcher -### Recommended Requirements +#### Recommended Requirements - **OS**: Windows 11 64-bit - **CPU**: 8-core Intel i7-9700K / AMD Ryzen 7 3700X or better @@ -20,16 +28,35 @@ - **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) + ## Installation Steps -### 1. Install Epic Games Launcher +### Option A: Windows Installation (Epic Games Launcher) + +#### 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 -### 2. Install Unreal Engine 5.4 +#### 2. Install Unreal Engine 5.4 1. **Open Launcher**: Launch Epic Games Launcher 2. **Unreal Engine Tab**: Click on "Unreal Engine" tab @@ -43,12 +70,62 @@ - Default: `C:\Program Files\Epic Games\UE_5.4\` - Recommended: Install on SSD for better performance -### 3. Verify Installation +#### 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 +--- + +### Option B: Linux/Ubuntu/WSL Installation (CLI - Source Build) + +**For detailed CLI instructions, see: [UE5_WSL_INSTALL.md](UE5_WSL_INSTALL.md)** + +#### Quick Start (Automated) + +```bash +# Run automated installation script +chmod +x scripts/install_ue5_wsl.sh +./scripts/install_ue5_wsl.sh +``` + +#### Manual Installation (Step-by-Step) + +1. **Install Dependencies**: + ```bash + sudo apt update && sudo apt install -y \ + build-essential clang cmake ninja-build mono-devel python3 \ + git git-lfs libvulkan-dev libxcb-xinput-dev libgtk-3-dev \ + libxrandr-dev libxinerama-dev libxi-dev libsdl2-dev \ + libssl-dev libicu-dev libxml2-dev + ``` + +2. **Link GitHub to Epic Games**: + - Visit: https://www.unrealengine.com/en-US/ue-on-github + - Link GitHub account and accept license + +3. **Clone Repository**: + ```bash + cd ~ + git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 UnrealEngine + ``` + +4. **Build**: + ```bash + cd ~/UnrealEngine + ./Setup.sh + ./GenerateProjectFiles.sh + make -j$(nproc) UnrealEditor + ``` + +5. **Launch**: + ```bash + ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor + ``` + +**See [UE5_WSL_INSTALL.md](UE5_WSL_INSTALL.md) for complete WSL/Ubuntu installation guide.** + ## Project Creation ### 1. Create New Project diff --git a/UE5_WSL_INSTALL.md b/UE5_WSL_INSTALL.md new file mode 100644 index 0000000..ffdf013 --- /dev/null +++ b/UE5_WSL_INSTALL.md @@ -0,0 +1,491 @@ +# 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\\.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 + diff --git a/scripts/install_ue5_wsl.sh b/scripts/install_ue5_wsl.sh new file mode 100755 index 0000000..6c2c2a7 --- /dev/null +++ b/scripts/install_ue5_wsl.sh @@ -0,0 +1,159 @@ +#!/bin/bash + +# Dubai Metaverse - Unreal Engine 5.4 WSL/Ubuntu Installation Script +# Automated installation script for UE5.4 on Ubuntu/WSL + +set -e + +echo "==========================================" +echo "Dubai Metaverse - UE5.4 WSL Installation" +echo "==========================================" +echo "" +echo "This script will install Unreal Engine 5.4 from source on Ubuntu/WSL" +echo "Prerequisites:" +echo " 1. GitHub account linked to Epic Games account" +echo " 2. Sufficient disk space (100GB+)" +echo " 3. Sufficient RAM (32GB+ recommended)" +echo "" +read -p "Continue? (y/n) " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + exit 1 +fi + +# Colors +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' + +print_step() { + echo -e "${GREEN}[STEP]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# Step 1: Update system +print_step "Updating system packages..." +sudo apt update && sudo apt upgrade -y + +# Step 2: Install dependencies +print_step "Installing build 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 + +# Step 3: Setup Git LFS +print_step "Setting up Git LFS..." +git lfs install + +# Step 4: Check GitHub/Epic Games account +print_step "Checking GitHub access..." +if ! git ls-remote https://github.com/EpicGames/UnrealEngine.git &>/dev/null; then + print_error "Cannot access Unreal Engine repository" + echo "" + echo "Please ensure:" + echo " 1. Your GitHub account is linked to Epic Games account" + echo " 2. You have accepted the Unreal Engine license" + echo " 3. Visit: https://www.unrealengine.com/en-US/ue-on-github" + echo "" + exit 1 +fi + +# Step 5: Clone repository +print_step "Cloning Unreal Engine 5.4 repository..." +echo "This may take 30-60 minutes depending on connection speed..." +cd ~ +if [ -d "UnrealEngine" ]; then + print_warning "UnrealEngine directory already exists" + read -p "Remove and re-clone? (y/n) " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + rm -rf UnrealEngine + else + echo "Using existing directory" + fi +fi + +if [ ! -d "UnrealEngine" ]; then + git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 UnrealEngine +fi + +# Step 6: Run Setup +print_step "Running Setup.sh (this may take 30-60 minutes)..." +cd ~/UnrealEngine +./Setup.sh + +# Step 7: Generate project files +print_step "Generating project files..." +./GenerateProjectFiles.sh + +# Step 8: Build Unreal Engine +print_step "Building Unreal Engine..." +echo "This will take 2-4+ hours depending on CPU..." +echo "Using $(nproc) parallel jobs" +make -j$(nproc) UnrealEditor + +# Step 9: Verify installation +print_step "Verifying installation..." +if [ -f "Engine/Binaries/Linux/UnrealEditor" ]; then + echo -e "${GREEN}✓${NC} Unreal Editor built successfully!" + echo "" + echo "Installation location: ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" + echo "" + echo "To launch:" + echo " ~/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" + echo "" + echo "For WSL graphics, ensure X server is running (WSLg on Windows 11, or VcXsrv/Xming on Windows 10)" +else + print_error "Build failed - UnrealEditor binary not found" + exit 1 +fi + +echo "" +echo "==========================================" +echo "Installation Complete!" +echo "==========================================" +echo "" +echo "Next steps:" +echo "1. Set up X server for graphics (if using WSL)" +echo "2. Create project: Follow UE5_WSL_INSTALL.md" +echo "3. Configure project settings" +echo "" +