.. include:: definitions.rstinc .. _install-label: ============ Installation ============ .. _install_plugin_launcher-label: **************************************** Installing Using the Epic Games Launcher **************************************** - In the Marketplace section of the Epic Games Launcher, find the |AGXUnreal| plugin and select `Install To Engine`. - Use your license to enable AGX Dynamics for Unreal, see :ref:`licensing-label` for details. To be able to use the |AGXUnreal| 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. ****************************************** Install or Build Using a .zip File Release ****************************************** The |AGXUnreal| .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 |AGXUnreal| from source is also possible by using the source code .zip file. See sections below for detailed instructions for each of these scenarios. .. _install_plugin_in_engine-label: ################################################ 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 :ref:`licensing-label` 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 ```` with the path to the project's root directory and ```` with the name of the project. .. code-block:: /Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=/.uproject -TargetType=Editor .. _install_plugin_in_project-label: ################################################### 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 :ref:`licensing-label` 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 ```` with the path to the project's root directory and ```` with the name of the project. .. code-block:: /Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=/.uproject -TargetType=Editor .. _building_and_packaging_from_source-label: ################################## Building and Packaging from Source ################################## This section is for users who wish to use |AGXUnreal| with their local installation of |AGX|, 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|, the physics engine that |AGXUnreal| integrate into Unreal Engine. AGX Dynamics must therefore be installed separately. Creating a local version of |AGXUnreal| consists of three steps: building, packaging, and installation. These are described in the following subsections. Requirements ============ * Unreal Engine |UE_VER|. * AGX Dynamics |AGX_DYNAMICS_VER| * Visual Studio 2022 (Windows only). * .NET Framework SDK 4.6.0 or higher (Windows only). Building ======== The source for the |AGXUnreal| 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, ```` should be replaced with the installation directory of AGX Dynamics. ```` should be replaced with the actual name of the project. ```` should be replaced with the root directory of your Unreal Engine installation. Linux ----- - | Select the AGX Dynamics installation to use: .. code-block:: $ source /setup_env.bash - | Generate build project files from the Unreal Engine project file: .. code-block:: $ ./GenerateProjectFiles.sh /MyProject.uproject -game - | Build the project: .. code-block:: $ 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: .. code-block:: /Engine/Binaries/Linux$ ./UE4Editor /MyProject.uproject Remember that the plugin, when built this way, depends on the |AGX| 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 .. code-block:: text 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. 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. .. code-block:: call "\setup_env.bat" - From the same Command Prompt, open Visual Studio. .. code-block:: 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. Building Against other Unreal Engine Versions ============================================= To build the |AGXUnreal| plugin from source against an Unreal Engine version other than the current default version: |UE_VER|, the ``EngineVersion`` in the file AGXUnreal/AGXUnreal.uplugin should be manually changed to the version used. Once complete, the instructions in :ref:`building_and_packaging_from_source-label` can be followed. Packaging ========= By packaging the |AGXUnreal| plugin we can use it in projects outside of the MyProject project that was used to build it. 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 |AGXUnreal| 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. 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. Linux ----- .. code-block:: $ /Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin=/Plugins/AGXUnreal/AGXUnreal.uplugin -Package=/PackagedPlugin/AGXUnreal -Rocket Windows ------- .. code-block:: "\Engine\Build\BatchFiles\RunUAT.bat" BuildPlugin -Plugin="\Plugins\AGXUnreal\AGXUnreal.uplugin" -Package="/PackagedPlugin/AGXUnreal" -TargetPlatforms=Win64 -Rocket 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. Extra Runtime Checks ==================== |AGXUnreal| 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. ************ 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 |AGXUnreal| plugins that has been packaged without a built-in AGX Dynamics bundle. The built-in |AGX| installation, if available, is split in two parts. Library binaries loaded by Unreal Engine are stored in ``AGXUnreal/Binaries/`` and resources used during building as well as AGX Dynamic's internal operation during runtime are stored in ``AGXUnreal/Binaries/ThirdParty/agx``. *************** Troubleshooting *************** ########################################################################## 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 .. code-block:: none 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 ```` with the path to the project's root directory and ```` with the name of the project. .. code-block:: none /Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=/.uproject -TargetType=Editor where ```` is the root of your Unreal Engine installation, ```` is the root directory of your Unreal Engine project and ```` is the name of you project. #################################################################################### 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 .. code-block:: none Warning: dlopen failed: libUE4Editor-AGXUnreal.so: cannot open shared object file: No such file or directory Warning: ModuleManager: Unable to load module '/Binaries/Linux/libUE4Editor-.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 '/Binaries/Linux/libUE4Editor-AgxBarrier.so' because the file couldn't be loaded by the OS. The game module 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 ```` with the path to the project's root directory and ```` with the name of the project. .. code-block:: none /Engine/Build/BatchFiles/Linux/Build.sh Linux Development -Project=/.uproject -TargetType=Editor where ```` is the root of your Unreal Engine installation, ```` is the root directory of your Unreal Engine project and ```` is the name of you project. ################################################################################################ 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. ####################################################################################### Plugin 'AGXUnreal' failed to load because module 'AGXUnrealBarrier' could not be loaded ####################################################################################### This error message is shown when |AGXUnreal| 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 |AGXUnreal| plugin being loaded, for example because |AGX| has been updated and |AGXUnreal| not yet rebuilt against the updated version. ############################################################################################## 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. ********************* Where to go from Here ********************* For a quick-start guide in how to use |AGXUnreal| within Unreal Editor see :ref:`quick-start-guide-label`. ********* Licensing ********* See :ref:`licensing-label` for details about licensing.