1. Installation

1.1. Installing Using the Epic Games Launcher

  • In the Marketplace section of the Epic Games Launcher, find the AGX Dynamics for Unreal plugin and select Install To Engine.

  • Use your license to enable AGX Dynamics for Unreal, see Licensing for details.

To be able to use the AGX Dynamics for Unreal plugin in an Unreal Engine project, it needs to be enabled for that project. This can be done by selecting Top Menu Bar > Edit > Plugins > AGX Dynamics for Unreal and checking the Enabled checkbox. Restart Unreal Editor for the changes to take effect. The plugin is now ready to be used.

1.2. Install or Build Using a .zip File Release

The AGX Dynamics for Unreal .zip comes in two main forms:

  • Prebuilt plugin

  • Source code

The prebuilt plugin can be installed either directly to a particular project or as an Unreal Engine plugin. Installing the plugin as an Unreal Engine plugin (recommended) means that it can be activated for any project, but must be explicitly activated for each project. Installing the plugin directly to a project means that it will be available for that project only and is automatically activated. This is supported only for C++ projects, not pure Blueprint projects.

Building AGX Dynamics for Unreal from source is also possible by using the source code .zip file.

See sections below for detailed instructions for each of these scenarios.

1.2.1. Installing a Prebuilt Plugin as an Engine Plugin

This section describe how to install a ready-to-use prebuilt plugin as an engine plugin, making it available for activation in all projects.

  • Download the plugin package for your platform.

  • Unpack the downloaded package to the Engine/Plugins directory in you Unreal Engine installation. The final result should be ../Engine/Plugins/Marketplace/AGXUnreal.

  • Use your license to enable AGX Dynamics for Unreal, see Licensing for details.

The plugin can now be activated for a particular Unreal Engine project by opening the project in Unreal Editor and selecting Top Menu Bar > Edit > Plugins > AGX Dynamics for Unreal and checking the Enabled checkbox. Restart Unreal Editor for the changes to take effect. The plugin is now ready to be used.

On Linux it may be necessary to configure the plugin for the current runtime environment. This is done by running the Unreal Build Tool for the project in which AGX Dynamics for Unreal has been activated. In the following, replace <PROJECT_ROOT> with the path to the project’s root directory and <PROJECT_NAME> with the name of the project.

<UE_ROOT>/Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=<PROJECT_ROOT>/<PROJECT_NAME>.uproject -TargetType=Editor

1.2.2. Installing a Prebuilt Plugin to an Existing Project

This section describe how to install a ready-to-use prebuilt plugin to an existing Unreal Engine project. This installation method is only supported for C++ projects, not Blueprint-only projects.

  • Download the plugin package for your platform.

  • Create a directory named Plugins in your Unreal Engine project unless one already exists.

  • Unpack the package to the Plugins directory created in the previous step. The final result should be ../MyProject/Plugins/Marketplace/AGXUnreal.

  • Use your license to enable AGX Dynamics for Unreal, see Licensing for details.

The next time the project is opened with Unreal Editor or from the Unreal Launcher a notification about the newly installed plugin will be shown and the plugin is ready to be used.

On Linux it may be necessary to configure the plugin for the current runtime environment. This is done by running the Unreal Build Tool for the project to which AGX Dynamics for Unreal has been installed. In the following, replace <PROJECT_ROOT> with the path to the project’s root directory and <PROJECT_NAME> with the name of the project.

<UE_ROOT>/Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=<PROJECT_ROOT>/<PROJECT_NAME>.uproject -TargetType=Editor

1.2.3. Building and Packaging from Source

This section is for users who wish to use AGX Dynamics for Unreal with their local installation of AGX Dynamics, use the plugin on a platform for which prebuilt binaries aren’t available, or build the plugin against a custom Unreal Engine.

The Source package does not contain any prebuilt binaries for any platform, only the plugin source code and configuration files. It also does not contain AGX Dynamics, the physics engine that AGX Dynamics for Unreal integrate into Unreal Engine. AGX Dynamics must therefore be installed separately.

Creating a local version of AGX Dynamics for Unreal consists of three steps: building, packaging, and installation. These are described in the following subsections.

1.2.3.1. Requirements

  • Unreal Engine 5.4-5.6.

  • AGX Dynamics 2.40.1.3

  • Visual Studio 2022 (Windows only).

  • .NET Framework SDK 4.6.0 or higher (Windows only).

1.2.3.2. Building

The source for the AGX Dynamics for Unreal plugin is distributed as a .zip file. It should be placed within an existing Unreal Editor C++ project, here assumed to be named MyProject. When MyProject is built the plugin source is also built along with it.

Download the source .zip file and unpack into your Unreal Engine project inside a Plugins directory, such that the result is MyProject/Plugins/AGXUnreal. Follow the OS-specific instructions below.

In the following, <AGX> should be replaced with the installation directory of AGX Dynamics. <MyProject> should be replaced with the actual name of the project. <UE_ROOT> should be replaced with the root directory of your Unreal Engine installation.

1.2.3.2.1. Linux
  • Select the AGX Dynamics installation to use:
<AGX>$ source <AGX>/setup_env.bash
  • Generate build project files from the Unreal Engine project file:
<UE_ROOT>$ ./GenerateProjectFiles.sh <MyProject>/MyProject.uproject -game
  • Build the project:
<MyProject>$ make MyProject

If make completed successfully then the plugin has been built and is ready to be used within the MyProject project. You can open the project and start experimenting with simulations, for example by testing one of the example levels, by opening the project as follows:

<UE_ROOT>/Engine/Binaries/Linux$ ./UE4Editor <MyProject>/MyProject.uproject

Remember that the plugin, when built this way, depends on the AGX Dynamics installation so Unreal Editor must always be opened from a terminal in which setup_env.bash has been sourced. If opened without setup_env you will get an error message saying

Plugin 'AGXUnreal' failed to load because module 'AGXUnrealBarrier' could not be loaded.

If you want to export the plugin for use in other Unreal Engine projects then continue under “Packaging” below.

1.2.3.2.2. Windows
  • Generate project files.

    Right-click the MyProject.uproject file and select Generate Visual Studio Project Files.

  • Open a Command Prompt, cmd.exe from the directory containing the newly generated MyProject.sln file.

  • Setup environment for AGX Dynamics.

<MyProject> call "<AGX>\setup_env.bat"

  • From the same Command Prompt, open Visual Studio.

<MyProject> devenv MyProject.sln

  • From the Solution Explorer, right-click on the project MyProject and select Build.

  • Launch the Unreal Editor by running the project from Visual Studio.

If you want to export the plugin for use in other Unreal Engine projects then continue under “Packaging” below.

1.2.3.3. Building Against other Unreal Engine Versions

To build the AGX Dynamics for Unreal plugin from source against an Unreal Engine version other than the current default version: 5.4-5.6, the EngineVersion in the file AGXUnreal/AGXUnreal.uplugin should be manually changed to the version used. Once complete, the instructions in Building and Packaging from Source can be followed.

1.2.3.4. Packaging

By packaging the AGX Dynamics for Unreal plugin we can use it in projects outside of the MyProject project that was used to build it.

1.2.3.4.1. From the Unreal Editor

Once the plugin has been built and Unreal Editor is open, the plugin can be packaged by selecting Top Menu Bar > Edit > Plugins and then Package... under the entry for AGX Dynamics for Unreal located in the Project/Physics category. The rest of this text assumes that the plugin is packaged to PackagedPlugins/AGXUnreal, but any target directory will work.

1.2.3.4.2. From the command line

As an alternative to packaging from within Unreal Editor, it is also possible to use Unreal Automation Tool directly from the command line.

1.2.3.4.3. Linux
<MyProject>$ <UE_ROOT>/Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin=<MyProject>/Plugins/AGXUnreal/AGXUnreal.uplugin -Package=<MyProject>/PackagedPlugin/AGXUnreal -Rocket
1.2.3.4.4. Windows
<MyProject> "<UE_ROOT>\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin -Plugin="<MyProject>\Plugins\AGXUnreal\AGXUnreal.uplugin" -Package="<MyProject>/PackagedPlugin/AGXUnreal" -TargetPlatforms=Win64 -Rocket

1.2.3.5. Installation

After building and packaging a package almost identical to the prebuilt packages has been produced and the instructions for any of the two Installing a prebuilt package subsections above can be used to install the plugin either to a project or as an engine plugin. The only difference is that the provided prebuilt packages have been compressed into a single Zip file while the package generated by Unreal Editor or Unreal Automation Tool are not, so the unpack step in the installation instructions should be skipped.

1.2.3.6. Extra Runtime Checks

AGX Dynamics for Unreal contains extra runtime checks that are disabled by default. To enable these checks either set the bEnableAGXCheck variable in AGXUnrealBarrier.Build.cs to true or set the AGXUNREAL_CHECK environment variable to true when generating project files and building the plugin.

1.3. AGX Dynamics

By default the plugin packaging process will produce a stand-alone plugin that does not depend on a system installation of AGX Dynamics; AGX Dynamics will be bundled in the plugin package. This means that it is only necessary to run AGX Dynamic’s setup_env when building the plugin the first time, not when using or rebuilding it.

However, by running setup_env and launching Unreal Editor from the same console/terminal it is possible to override the AGX Dynamics bundle inside the plugin and instead use an external one. This technique is also applicable for AGX Dynamics for Unreal plugins that has been packaged without a built-in AGX Dynamics bundle.

The built-in AGX Dynamics installation, if available, is split in two parts. Library binaries loaded by Unreal Engine are stored in AGXUnreal/Binaries/<platform> and resources used during building as well as AGX Dynamic’s internal operation during runtime are stored in AGXUnreal/Binaries/ThirdParty/agx.

1.4. Troubleshooting

1.4.1. The following modules are missing or built with a different engine version

This error may occur the first time the plugin is used on Linux. The full error message is

LogInit: Warning: Incompatible or missing module: AGXUnrealBarrier
LogInit: Warning: Incompatible or missing module: AGXUnreal
LogInit: Warning: Incompatible or missing module: AGXUnrealEditor
LogInit: Warning: Incompatible or missing module: AGXUnrealTests

The following modules are missing or built with a different engine version:
    AGXUnrealBarrier
    AGXUnreal
    AGXUnrealEditor
    AGXUnrealTests
Engine modules cannot be compiled at runtime. Please build through your IDE.

This problem is solved by building the plugin against the Unreal Engine installation on the local machine. If you are familiar with building Unreal Engine projects then build using that method. If not, then run the following in a terminal. Replace <PROJECT_ROOT> with the path to the project’s root directory and <PROJECT_NAME> with the name of the project.

<UE_ROOT>/Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=<PROJECT_ROOT>/<PROJECT_NAME>.uproject -TargetType=Editor

where <UE_ROOT> is the root of your Unreal Engine installation, <PROJECT_ROOT> is the root directory of your Unreal Engine project and <PROJECT_NAME> is the name of you project.

1.5. Build errors on Windows when making changes in Barrier module

Sometimes when making changes to source code in the Barrier module, lots of seemingly unrelated build errors are generated by the compiler. The underlying cause is not known, but one way to resolve this is to disable bUseAdaptiveUnityBuild. To do this, add a file BuildConfiguration.xml in <user>/Documents/Unreal Engine/UnrealBuildTool/ with the following content:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
  <BuildConfiguration>
    <bUseAdaptiveUnityBuild>false</bUseAdaptiveUnityBuild>
  </BuildConfiguration>
</Configuration>

1.5.1. libUE4Editor-AGXUnreal.so: cannot open shared object file: No such file or directory

This error may occur the first time the plugin is used in a C++ project on Linux. The full error message is

Warning: dlopen failed: libUE4Editor-AGXUnreal.so: cannot open shared object file: No such file or directory
Warning: ModuleManager: Unable to load module '<PROJECT>/Binaries/Linux/libUE4Editor-<PROJECT>.so' because the file couldn't be loaded by the OS.

Warning: dlopen failed: libagxPhysics.so.2.31.1.0: cannot open shared object file: No such file or directory
Warning: ModuleManager: Unable to load module '<PROJECT>/Binaries/Linux/libUE4Editor-AgxBarrier.so' because the file couldn't be loaded by the OS.


The game module <PROJECT> could not be loaded. There may be an operating system error or the module may not be properly set up.

This problem is solved by building the plugin against the Unreal Engine installation on the local machine. If you are familiar with building Unreal Engine projects then build using that method. If not, then run the following in a terminal. Replace <PROJECT_ROOT> with the path to the project’s root directory and <PROJECT_NAME> with the name of the project.

<UE_ROOT>/Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=<PROJECT_ROOT>/<PROJECT_NAME>.uproject -TargetType=Editor

where <UE_ROOT> is the root of your Unreal Engine installation, <PROJECT_ROOT> is the root directory of your Unreal Engine project and <PROJECT_NAME> is the name of you project.

1.5.2. ERROR: Platform Linux is not a valid platform to build. Check that the SDK is installed properly

It has been noted that in some cases this error is given while packaging the plugin on Windows from the Unreal Editor even though only Win64 is checked in the Supported Platforms in the Project Settings. A workaround for this is to manually edit the file AGXUnreal.uplugin and move Linux from the WhitelistPlatforms to the BlacklistPlatforms for all modules listed.

1.5.3. Plugin ‘AGXUnreal’ failed to load because module ‘AGXUnrealBarrier’ could not be loaded

This error message is shown when AGX Dynamics for Unreal does not include a built-in AGX Dynamics bundle and setup_env hasn’t been run for any external AGX Dynamics installation.

It is also printed if the selected AGX Dynamics installation is binary-incompatible with the AGX Dynamics for Unreal plugin being loaded, for example because AGX Dynamics has been updated and AGX Dynamics for Unreal not yet rebuilt against the updated version.

1.5.4. Expecting to find a type to be declared in a module rules named ‘AGXUnrealBarrier’ in UE5Rules

This error message can show up when compiling C++ Unreal Engine projects that uses AGX Dynamics for Unreal. The cause is yet unknown, but a solution is to move the AGXUnreal directory with all its contents from Engine/Plugins/ to Engine/Plugins/Marketplace/. If the Marketplace directory does not exists, it can be created manually.

1.6. Where to go from Here

For a quick-start guide in how to use AGX Dynamics for Unreal within Unreal Editor see Quick Start Guide.

1.7. Licensing

See Licensing for details about licensing.