# 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

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

## Installation Steps

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

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

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

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 (we'll add our own)
5. **Project Name**: `DubaiMetaverse`
6. **Location**: Choose project location (outside of engine installation)
7. **Create**: Click "Create Project"

### 2. Initial Project Configuration

After project creation, configure initial settings:

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

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

### 3. Install Required Plugins

See [PLUGINS.md](PLUGINS.md) for detailed plugin installation instructions.

**Essential Plugins**:
- Procedural Content Generation Framework
- Virtual Production Tools
- Movie Render Queue
- OpenXR (optional, for VR)

## Project Structure Setup

### 1. Create Folder Structure

Create the following folder structure in Content Browser:

```
Content/
├── Maps/
│   ├── Main/
│   └── Blockout/
├── Assets/
│   ├── Buildings/
│   │   ├── Hero/
│   │   ├── Primary/
│   │   └── Background/
│   ├── Vehicles/
│   ├── Characters/
│   ├── Props/
│   └── Materials/
├── Blueprints/
│   ├── Gameplay/
│   ├── Vehicles/
│   └── NPCs/
├── PCG/
├── Cinematics/
└── Audio/
```

### 2. Configure Editor Settings

1. **Edit > Editor Preferences**:
   - **Viewport**: Configure viewport settings
   - **Content Browser**: Set up content browser preferences
   - **Performance**: Configure performance settings

2. **Edit > Project Settings > Engine > Rendering**:
   - Configure rendering settings (see PROJECT_SETTINGS.md)

## First Steps After Setup

### 1. Verify Engine Features

1. **Nanite**: Create a test Nanite mesh to verify it works
2. **Lumen**: Check that Lumen GI is active
3. **World Partition**: Verify World Partition is enabled

### 2. Test Performance

1. **Create Test Level**: Create a simple test level
2. **Profile**: Use Unreal Insights to profile performance
3. **Verify**: Ensure performance is acceptable

### 3. Configure Version Control

See [VERSION_CONTROL.md](VERSION_CONTROL.md) for Git LFS setup.

## Troubleshooting

### Common Issues

#### Engine Won't Launch

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

#### Project Won't Open

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

#### Performance Issues

- **Solution**: Update GPU drivers
- **Solution**: Disable unnecessary plugins
- **Solution**: Lower viewport quality settings
- **Solution**: Check system meets requirements

#### Nanite/Lumen Not Working

- **Solution**: Verify features are enabled in project settings
- **Solution**: Check GPU supports required features
- **Solution**: Update to latest engine version

### Getting Help

- **Epic Games Forums**: [forums.unrealengine.com](https://forums.unrealengine.com)
- **Unreal Engine Documentation**: [docs.unrealengine.com](https://docs.unrealengine.com)
- **Discord**: Unreal Engine community Discord
- **Support**: Epic Games support

## Next Steps

After completing setup:

1. ✅ Review [PROJECT_SETTINGS.md](PROJECT_SETTINGS.md) for engine configuration
2. ✅ Install plugins (see [PLUGINS.md](PLUGINS.md))
3. ✅ Set up version control (see [VERSION_CONTROL.md](VERSION_CONTROL.md))
4. ✅ Review [PIPELINE.md](PIPELINE.md) for development workflow
5. ✅ Begin Phase 1, Week 2: Geospatial acquisition and blockout

---

**Version**: 1.0
**Last Updated**: [Current Date]