1. Installation

Below are some of the recommended ways to install AGX Dynamics for Unreal. It is also possible to build AGX Dynamics for Unreal from source, see Building and Packaging from Source.

1.1. Installing Using the Epic Games Launcher

  • Get AGX Dynamics for Unreal from FAB and install it using the Epic Games Launcher.

  • 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 Using a Prebuilt .zip File Release

First, get AGX Dynamics for Unreal from the download site. 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.

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 the prebuilt plugin as an engine plugin, making it available for activation in all projects.

  • Download the plugin zip file for your platform (see download link above).

  • 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 prebuilt plugin to an existing Unreal Engine project. This installation method is only supported for C++ projects, not Blueprint-only projects.

  • Download the plugin zip file for your platform (see download link above).

  • 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.3. Building and Packaging from Source

Get the AGX Dynamics for Unreal source code from GitHub or the download site.

AGX Dynamics for Unreal depends on AGX Dynamics and requires a bundled version of AGX Dynamics to be located in ..AGXUnreal/Source/ThirdParty/agx in order to be built. When AGX Dynamics for Unreal is built from source it will automatically look for or download an AGX Dynamics bundle. It does this in the following ways, in the following order:

  1. Look for an existing bundle in ..AGXUnreal/Source/ThirdParty/agx.

  2. If the step above failed, try to create a new AGX Dynamics bundle from variables set by an AGX Dynamics setup_env script.

  3. If the steps above failed, look for a AGX Dynamics bundle zip file in the plugin root directory.

  4. If the steps above failed, download an AGX Dynamics bundle from the web.

The download and unzip steps require PowerShell on Windows and wget + unzip on Linux.

For anyone building AGX Dynamics for Unreal from source without an AGX Dynamics installation or build, and without a local AGX Dynamics bundle zip file, it is important to have an internet connection so that an AGX Dynamics bundle can be downloaded (step 4 above).

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.3.1. Requirements

  • Unreal Engine 5.5-5.7.

  • AGX Dynamics 2.41.1.0

  • Visual Studio 2022 (Windows only).

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

To build from source:

  • PowerShell (Windows only).

  • wget (Linux only).

  • unzip (Linux only).

1.3.2. Building

Get the AGX Dynamics for Unreal source code from GitHub or the download site. 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.

Clone or unpack the AGX Dynamics for Unreal source code 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.3.2.1. Linux

Note: first follow the steps outlined above in Building.

  • 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

1.3.2.2. Windows

Note: first follow the steps outlined above in Building.

  • Generate project files.

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

Open the generated MyProject.sln

  • From the Solution Explorer in Visual Studio, 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.3.3. Building Against other AGX Dynamics Versions

1.3.3.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.

1.3.3.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.

1.3.4. 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.5-5.7, 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.3.5. 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.3.5.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.3.5.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.3.5.3. Linux

<MyProject>$ <UE_ROOT>/Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin=<MyProject>/Plugins/AGXUnreal/AGXUnreal.uplugin -Package=<MyProject>/PackagedPlugin/AGXUnreal -Rocket

1.3.5.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.3.6. 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.3.7. 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.4. 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.5. Troubleshooting

1.5.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.2. 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.3. 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.4. 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.5. 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.6. 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.