Installation

This plugin is designed to provide Unreal Engine developers with advanced machine learning tools inspired by Unity’s ML-Agents Toolkit. You can install the plugin directly from FAB, Unreal Engine’s marketplace, or by cloning the repository for full control over the entire plugin, including ue-agents, ue-agents-envs, and all other components. Cloning the repository is also a great opportunity for developers to contribute to the project by adding new features or improving existing ones.

Prerequisites

  1. Unreal Engine:

    • Ensure you have Unreal Engine version 5.2 or later installed.

    • Download Unreal Engine from the official website: Unreal Engine Download.

  2. Python:

    • Install Python >= 3.10.11 (64-bit) to avoid compatibility issues.

    • Download Python from the official website: Python Download.

  3. PyTorch:

    • On Windows, install the CUDA-enabled version of PyTorch before proceeding with the plugin installation. Activate your virtual environment and run the following command:

      pip install torch~=2.4.1 --index-url https://download.pytorch.org/whl/cu124

    Note

    On Windows, you may also need Microsoft’s Visual C++ Redistributable if you don’t have it already. See the PyTorch installation guide for more installation options and versions.

For those who wants to develop in C++, please follow the very good documentation from Unreal Engine. You need to install and configure one of the following IDEs:

Note

In case you are interested by other aspects of Unreal Engine, you can find more information in the Development Setup

Important

You can either install the plugin from the FAB Marketplace or clone the repository to access the full source code. If you choose the second option, you will need to build the plugin from source. Instructions are in the GitHub advanced installation section.

  1. Navigate to the FAB Marketplace and search for UnrealMLAgents.

  2. Click Add to My Library.

  3. Open Epic Games Launcher and go to the Unreal Engine -> Library tab.

  4. Refresh the Fab Library and then Install to Engine.

The plugin is now ready to enhance your Unreal Engine environments with advanced machine learning capabilities.

For developers who want to modify or extend the plugin and its Python packages, follow these steps:

  1. Clone the repository:

    git clone git@github.com:AlanLaboratory/UnrealMLAgents.git

  2. Download the pre-built third-party binary libraries from here.

  3. Extract the downloaded libraries to the Source/ThirdParty directory.

To build the plugin from source, follow these steps:

$ cd C:/Program Files/Epic Games/UE_5.X/Engine/Build/Batchfiles
$ RunUAT.bat BuildPlugin -plugin="<path to this repo>\UnrealMLAgents.uplugin" -package="<somewhere/UnrealMLAgents>" -TargetPlatforms=Win64

After building the plugin, you can copy the UnrealMLAgents folder to the Unreal Engine Plugins/Marketplace directory.

$ cp -r UnrealMLAgents C:/Program Files/Epic Games/UE_5.X/Engine/Plugins/Marketplace

The plugin is now ready to use in your Unreal Engine projects.

Installing Python Dependencies with pip

Same for the Python packages, you can install them from PyPI or clone the repository to access the full source code. If you are not familiar with Python, we recommend installing the packages from PyPI. Last point, we recommand using a virtual environment to avoid conflicts with other Python packages. If you are not familiar with virtual environments, you can find more information in the Python Environment Guide.

Note

If you have already installed pytorch at the beginning, you shoudld already have a virtual environment.

If you are not modifying the plugin or its Python packages, you can install the required Python dependencies directly from PyPI:

  1. Ensure Python 3.10 is installed on your system.

  2. Run the following command to install the package:

    pip install ueagents

    This will automatically install ueagents_envs as a dependency.

Note

Installing the ueagents Python package involves installing other dependencies it relies on. To avoid issues with conflicting versions, consider using a virtual environment. For detailed steps, refer to the Virtual Environment Guide.

For this section, you first need to clone the repository to access the full source code. See above for more information on cloning the repository.

  1. Navigate into MLearning directory within the previously cloned repository.

  2. Install the Python packages in editable mode using the -e flag:

    cd MLearning/ue-agents-envs
pip install -e .

cd ../ue-agents
pip install -e .

Note

Running pip with the -e flag will let you make changes to the Python files directly and have those reflected when you run ue-agents-learn. It is important to install these packages in this order as the ue-agents package depends on ue-agents-envs, and installing it in the other order will download ue-agents-envs from PyPI.

Next Steps

With the plugin and Python packages installed, you can start building and training intelligent agents in your Unreal projects. Check out the Getting Started guide for detailed tutorials and examples.

Help

If you run into any problems regarding ML-Agents, refer to our Discord Server. If you can’t find a solution, please submit an issue and include relevant information such as:

  • Your operating system and version.

  • The Python version you are using.

  • Exact error messages (whenever possible).