1. Getting started

1.1. Requirements

  • Supported Operating Systems (development requires an installed Unity 64-bit editor on the given operating system):

    • Microsoft Windows

    • Ubuntu 22.04 LTS

    • Ubuntu 20.04 LTS

    • Ubuntu 18.04 LTS

    • CentOS 7

  • Supported Unity Versions (development):

    • 2020.3 LTS

    • 2021.x

    • 2022.x

    • NOTE: It may work in earlier versions of Unity, such as 2019.x.

  • API Compatibility Level: .NET Framework (.NET 4.x in Unity 2021.1 and earlier)

Note

IL2CPP isn’t currently supported. Contact support for more information.

1.2. Installing the plugin

The AGX Dynamics for Unity plugin is distributed as a Unity package and be downloaded here.

  1. Import the package into your project.

    _images/import_custom_package.png

  2. Select the downloaded AGX Dynamics for Unity package and click Open then Import.

    _images/import_custom_package_window.png

    Note

    If Unity is catching DllNotFound exceptions of agxDotNetRuntime.dll - restart Unity.

  3. If the API compatibility level is set to .NET Standard, AGX Dynamics for Unity will issue a warning to the console:

    _images/api_comp_warning.png

    Change API Compatibility Level: Edit -> Project Settings… -> Player -> Other Settings -> Configuration -> Api Compatibility Level -> .NET Framework.

    _images/api_comp_fix.png

1.3. Updating the plugin

Note

If you’re updating from an AGX Dynamics for Unity version 2.4.2 (2021-06-03) or earlier, please follow the steps described in Update from 2.4.2 and earlier to 2.4.3 and later, before updating. See Manual recovery from errors after update if the update already has been performed without the Update Handler.

From version 2.0.1 (2020-04-29) there is built in functionality to check for new versions of AGX Dynamics for Unity. When a new version is detected the package can be downloaded and installed.

  1. Open Check for Updates… window from the main menu.

    _images/check_for_updates_menu.png

  2. When a new version is available, press Download to start the download of the new package. The package is downloaded to System.IO.Path.GetTempPath() and the package isn’t deleted in the update process.

    _images/check_for_updates_window.png _images/check_for_updates_downloading.png

  3. When the package has been downloaded, press Install to to start the installation process.

    Note

    Unity will be restarted during this update and all content in the AGXUnity folder will be deleted (except agx.lic and user preferences/settings). All other files and folders (under AGXUnity) will be deleted. Make sure any additional files and/or local changes are backed up before updating.

    _images/check_for_updates_install.png

  4. After Unity has restarted the update will continue by removing all the files and folders under the AGXUnity directory. Unity will recompile all scripts in the project several times during this process, and any script referencing AGXUnity or AGXUnityEditor won’t temporarily compile (compile errors in the Console).

1.3.1. Manual update

The native binaries of AGX Dynamics are loaded into the Unity process. This means that Unity has to be closed before these files can be deleted or modified and that’s why import custom package isn’t supported when AGX Dynamics for Unity already is installed in the project.

  1. Close Unity.

  2. Backup any local changes and/or additional files located in the AGXUnity directory, e.g., agx.lic.

  3. Delete the AGXUnity folder in the project Assets directory.

  4. Reopen the project in Unity.

  5. Perform Installing the plugin.

1.4. Licensing

This software is dependent on the multi-purpose physics simulation engine AGX Dynamics and requires a valid license to run the simulations. Visit AGX Dynamics for Unity for more information regarding trial and licensing of this product.

If you have received a License Id and Activation Code for a license, open the License Manager window from the main menu: AGXUnity -> License -> License Manager and fill in the License Id, Activation Code fields and select a target directory where the license should be placed. Click Activate to generate the license file. See License Manager for detailed information regarding license management.

_images/license_manager_window_default.png

1.4.1. Legacy: Activate using agx.lic

Note

Since version 3.0.0 (2021-07-01), introducing the License Manager, some prerequisites regarding license filename and location has been changed. The license file may be located anywhere in the Unity project or build directory hierarchy.

Editor

Copy agx.lic to one of AGX Dynamics resource paths, e.g., Assets/AGXUnity/Plugins/x86_64.

_images/license_agx_lic_location.png

Runtime

In a built application, AGX Dynamics resource paths are:

  • Path of the executable.

  • Application.dataPath -> <project_name>_Data

  • <project_name>_Data/Plugins

  • <project_name>_Data/Plugins/agx

agx.lic should be placed in one of these directories.