22. 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:

{
  "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

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:

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:

#pragma once

#include "CoreMinimal.h"

AgxBarrier.cpp:

#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:

#pragma once

#include "CoreMinimal.h"

class FRigidBodyBarrier;

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

RigidBodyOperations.cpp:

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