.. include:: definitions.rstinc

.. _agx-api-access-label:

=======================
AGX Dynamics API Access
=======================

AGX Dynamics classes may only be used from an AGX Dynamics compatible Unreal Engine module.
We call these modules "Barrier" modules because they act as a compilation barrier between the Unreal Engine classes and the AGX Dynamics classes.
The barrier module is required because of incompatible compiler settings between Unreal Engine and AGX Dynamics.

To add a Barrier module to an Unreal Engine project first declare it in the
``Modules`` array in the project's ``.uproject`` file as follows:


.. code-block:: javascript

    {
      "Name": "AgxBarrier",
      "Type": "Runtime",
      "LoadingPhase": "Default",
      "AdditionalDependencies": [
          "Engine"
      ]
    }

The name ``AgxBarrier`` is just an example, any name will work.
It is also possible to have multiple Barrier modules with different names for different functionality.

The new module is registered in ``ExtraModuleNames`` in the project's two ``.Target.cs files`` with

.. code-block:: c++

   ExtraModuleNames.AddRange( new string[] { "AgxBarrier" } );

The actual module is a directory named ``AgxBarrier`` in the project's ``Source`` directory.
It contains ``AgxBarrier.Build.cs`` with the following contents:

.. code-block:: C#

   using UnrealBuildTool;

   public class AgxBarrier : ModuleRules
   {
     public AgxBarrier(ReadOnlyTargetRules Target) : base(Target)
     {
       PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
       bUseRTTI = true;
       bEnableExceptions = true;

       PublicDependencyModuleNames.AddRange(new string[] {
         "Core", "CoreUObject", "Engine", "InputCore", "AGXUnreal", "AGXUnrealBarrier" });

       PrivateDependencyModuleNames.AddRange(new string[] {"AGXUnrealLibrary"});
       }
   }

The module needs some C++ code to interact with Unreal Engine.

``AgxBarrier.h``:

.. code-block:: c++

  #pragma once

  #include "CoreMinimal.h"

``AgxBarrier.cpp``:

.. code-block:: c++

  #include "AgxBarrier.h"

  #include "Modules/ModuleManager.h"

  IMPLEMENT_GAME_MODULE(FDefaultGameModuleImpl, AgxBarrier);

We declare the functions we wish to provide in header files in the Barrier module's ``Public`` subdirectory.
There header files will be included in source files that belong to non-barrier modules so no AGX Dynamics headers may be included here.
All references to AGX Dynamics objects must be passed as ``Barrier`` objects.
The AGX Dynamics for Unreal plugin provides a library of such ``Barrier`` types for the most commonly used AGX Dynamics classes and additional ``Barrier`` types may be declared in the project-specific Barrier module.

An example that can manipulate a native AGX Dynamics rigid body:

``RigidBodyOperations.h``:

.. code-block:: c++

  #pragma once

  #include "CoreMinimal.h"

  class FRigidBodyBarrier;

  class AGXBARRIER_API FRigidBodyOperations
  {
  public:
    static void ManipulateBody(FRigidBodyBarrier* Barrier);
  };


``RigidBodyOperations.cpp``:

.. code-block:: c++

  #include "RigidBodyOperations.h"

  // AGX Dynamics includes.
  #include "BeginAGXIncludes.h"
  #include <agx/RigidBody.h>
  #include "EndAGXIncludes.h"

  // AGX Dynamics for Unreal includes.
  #include "RigidBodyBarrier.h"
  #include "AGX_AgxDynamicsObjectsAccess.h"


  void FRigidBodyOperations::ManipulateBody(FRigidBodyBarrier* Barrier)
  {
    agx::RigidBody* Body = FAGX_AgxDynamicsObjectsAccess::GetFrom(Barrier);
    if (Body == nullptr)
    {
      return;
    }
    // Use Body here.
  }


By including ``RigidBodyOperations.h`` in any Unreal Engine module it is now possible to call ``FRigidBodyOperations::ManipulateBody`` from that module.
A ``FRigidBodyBarrier`` instance can be fetched from an ``UAGX_RigidBodyComponent`` using ``UAGX_RigidBodyComponent::GetNative`` if the component has been given a native AGX Dynamics body.
Check with ``UAGX_RigidBodyComponent::HasNative()``.
In general, no native AGX Dynamics objects are create until the ``BeginPlay`` callback, so they aren't available while working the Unreal Editor.