.. include:: definitions.rstinc =============== Getting started =============== 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): * 2021.x * 2022.x * 2023.x * **NOTE**: It may work in earlier versions of Unity, such as 2020.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. .. _installing-the-plugin-ref: Installing the plugin --------------------- As of version :ref:`5.0.0-ref`, AGX Dynamics for Unity supports two separate methods of installation depending on your specific project setup and needs. These methods consist of installing the plugin in an **Asset context** or a **Package context**. When the plugin is installed in an **Asset context**, the plugin files (such as the script files, shaders, resource files, binaries, etc.) are located in the projects *Assets* folder. This means that the plugin itself is an integrated part of the project. In contrast, when the plugin is installed in a **Package context**, the plugin files are not necessarily part of the project. Instead they might be located elsewhere on disk or on a server. This can be favourable when working as a team on a project as the plugin files can be installed automatically by Unity when the project is opened while still omitting the plugin files from source control. .. _install-asset-context-ref: Installing the plugin as an asset plugin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The AGX Dynamics for Unity plugin is distributed in it's entirety as a *.unitypackage* file and can be `downloaded here `_. #. Import the package into your project. .. image:: images/import_custom_package.png :width: 70% #. Select the downloaded AGX Dynamics for Unity package and click *Open* then *Import*. .. image:: images/import_custom_package_window.png :width: 70% | .. note:: If Unity is catching *DllNotFound* exceptions of *agxDotNetRuntime.dll* - restart Unity. #. If the API compatibility level is set to *.NET Standard*, AGX Dynamics for Unity will issue a warning to the console: .. image:: images/api_comp_warning.png :width: 70% Change API Compatibility Level: **Edit -> Project Settings... -> Player -> Other Settings -> Configuration -> Api Compatibility Level -> .NET Framework**. .. image:: images/api_comp_fix.png :width: 70% .. _install-package-context-ref: Installing the plugin as an UPM package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As of version :ref:`5.0.0-ref`, the AGX Dynamics for Unity plugin can also be installed through the UPM following the procedures outlined in the `Unity UPM documentation `_. Note that the plugin is not currently hosted in any scoped registry by Algoryx but could be hosted in private registries if needed. It is currently recommended that **Package context**-installation is performed via Git: #. Open the UPM window .. image:: images/upm_open_package_manager.png :width: 70% #. Select the "+ > Add package from git URL..." option in the package manager window. .. image:: images/upm_add_from_git.png :width: 70% #. Enter the Git URL of the AGX Dynamics for Unity repository. It's recommended to additionally specify the desired version's corresponding RC branch, eg. :code:`https://github.com/Algoryx/AGXUnity.git#rc/5.0.0`. .. image:: images/upm_enter_git_url.png :width: 70% #. After installing, the plugin will ask to select a directory containing an AGX Dynamics installation. Please refer to the `Required versions `_ table on GitHub for which specific AGX Dynamics version to use with which AGX Dynamics for Unity version. If the required version is not already installed, it can be installed here: https://www.algoryx.se/download/. .. image:: images/upm_configure_agx.png :width: 70% .. _updating-the-plugin-ref: Updating the plugin ------------------- .. note:: If you're updating from an |AGXUnity| version :ref:`2.4.2-ref` **or earlier**, please follow the steps described in :ref:`update-handler-manual-patch-v1-ref`, before updating. See :ref:`update-handler-manual-recovery-ref` if the update already has been performed without the :ref:`update-handler-ref`. .. note:: The *Check for Updates...* window currently does not support updating the plugin when installed in a **Package context**. See :ref:`install-package-context-ref`. From version :ref:`2.0.1-ref` there is built in functionality to check for new versions of |AGXUnity|. When a new version is detected the package can be downloaded and installed. #. Open *Check for Updates...* window from the main menu. .. image:: images/check_for_updates_menu.png :width: 70% #. 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. .. image:: images/check_for_updates_window.png :width: 35% .. image:: images/check_for_updates_downloading.png :width: 35% #. 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 :code:`AGXUnity` folder will be deleted (except :code:`agx.lic` and user preferences/settings). All other files and folders (under :code:`AGXUnity`) will be deleted. Make sure any additional files and/or local changes are backed up before updating. .. image:: images/check_for_updates_install.png :width: 70% #. After Unity has restarted the update will continue by removing all the files and folders under the :code:`AGXUnity` directory. Unity will recompile all scripts in the project several times during this process, and any script referencing :code:`AGXUnity` or :code:`AGXUnityEditor` won't temporarily compile (compile errors in the Console). .. _manual-update-ref: 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 |AGXUnity| already is installed in the project. #. Close Unity. #. Backup any local changes and/or additional files located in the :code:`AGXUnity` directory, e.g., :code:`agx.lic`. #. Delete the :code:`AGXUnity` folder in the project :code:`Assets` directory. #. Reopen the project in Unity. #. Perform :ref:`installing-the-plugin-ref`. 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 :ref:`license-manager-ref` window from the main menu: :code:`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 :ref:`license-manager-ref` for detailed information regarding license management. .. note:: If you have activated your license in a previous project it is sufficient to copy the created :code:`agx.lfx` from that project into the asset folder of new projects. See :ref:`license-manager-activate-license-ref` for more information. .. figure:: images/license_manager_window_default.png :align: center :width: 60% Legacy: Activate using *agx.lic* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: Since version :ref:`3.0.0-ref`, introducing the :ref:`license-manager-ref`, 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. .. topic:: Editor Copy *agx.lic* to one of AGX Dynamics resource paths, e.g., :code:`Assets/AGXUnity/Plugins/x86_64`. .. image:: images/license_agx_lic_location.png :align: center :width: 80% | .. topic:: Runtime In a built application, AGX Dynamics resource paths are: * Path of the executable. * :code:`Application.dataPath` -> :code:`_Data` * :code:`_Data/Plugins` * :code:`_Data/Plugins/agx` *agx.lic* should be placed in one of these directories. Start using AGX Dynamics for Unity ---------------------------------- After the initial setup and license activation is completed, it is recommended to look through the following resources to help get started with creating custom simulations in AGXUnity. * Check out the available AGX documentation: * Read through the AGXUnity documentation to get a sense of the available components and overall workflow in AGXUnity. * Have a look at the `AGX Dynamics user manual `_ for more information about the capabilities of AGX as well as more in depth explanation of the various components. * While many features are exposed as Unity components, some more advanced features are available through a native API. Check out the `AGX API reference `_ for information about the native API. * Look through the :ref:`examples-ref` page and download any relevant examples to start exploring a specific topic. * Watch our `YouTube Tutorial series `_ for an in depth explanation of how to use the plugin and the various components. * If you're stuck. Contact our support at support@algoryx.com AGX Dynamics for Unity with HDRP and URP ---------------------------------------- AGX Dynamics for Unity supports both the default Built-in Render Pipeline as well as the High Definition Render Pipeline (HDRP) and the Universal Render Pipeline (URP). However, the materials that are shipped with the plugin are built for the Built-in RP as this is the default Unity experience and these are upgradable using tools provided in the HDRP and URP packages. In general, it is easier to decide early on in the development which render pipeline to use as the upgrading process is simpler and less error prone in new projects. Additionally it should be noted that upgrading materials is a non-reversible process and as such, backups should be made before the upgrade is performed. .. note:: For each of the guides linked, the package version depends on the installed Unity Editor version. Ensure that the documentation page matches your installed package version. .. note:: The bulk material upgrade process does not support upgrading materials in imported agx-files as these are imported as sub assets. For these, the imported render materials have to be selected and the corresponding process for upgrading selected materials has to be performed. Please refer to the corresponding documentation of the relevant Render Pipeline for more information. High Definition Render Pipeline ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A guide to upgrading from the Built-in RP to HDRP can be found in the `official package documentation `_. If a completely new HDRP project is created from the HDRP template it is enough to import the AGX Dynamics for Unity package to follow the steps outlined in `Upgrading Materials `_. Universal Render Pipeline ^^^^^^^^^^^^^^^^^^^^^^^^^ Similar to the HDRP upgrade documentation, the URP package documentation contains an `upgrade guide `_. When a new URP project is created, the AGX Dynamics for Unity package can be imported and the same upgrade process can be run but only the Material Upgrade is necessary here. .. _custom-rendering-materials-ref: Custom AGXUnity rendering materials ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When using custom materials with the custom shaders provided in AGXUnity (such as the ones used for :ref:`cable-rendering-ref` or :ref:`upsampling-particle-renderer-ref`), the proper version has to be selected. In general, the shader version under :code:`AGXUnity/Built-In` should be used for the Built-In render pipeline while the shader version under :code:`AGXUnity/Shader Graph` should be used for URP and HDRP pipelines. It is however possible to use the shader graph versions when using the Built-In render pipeline if the `Shader Graph package `_ is installed manually. To make it easier to use materials across different projects, there is a material converter which converts materials between different versions to help ensure that AGXUnity materials used in the project are compatible with the chosen rendering pipeline. This converter is located at :code:`AGXUnity > Utils > Convert Rendering Materials`