9. Rigid Body

The RigidBodyComponent infuses dynamics into an Actor. It signals that something is to be simulated with AGX Dynamics. A RigidBodyComponent has a set of properties, see description and screenshot below, and can be further configured by adding shapes components beneath it in the Component tree.

Property	Unit	Description	Default
Mass	\(kg\)	The mass of the rigid body.	1.0
Inertia Tensor Diagonal	\(kg \cdot m^2\)	Inertia tensor of the rigid body.	(1.0, 1.0, 1.0)
Velocity	\(cm/s\)	Initial linear velocity.	(0.0, 0.0, 0.0)
Angular Velocity	\(degrees/s\)	Initial angular velocity.	(0.0, 0.0, 0.0)
Motion Control	Static, Kinematic, Dynamic	Whether the body should be static (never move, fixed in the world), kinematic (moved with a fixed velocity, not influenced by forces), or dynamic (fully simulated).	Dynamic
Transform Root Component	Boolean	Whether updated transformations after each time step should be applied to the RigidBodyComponent or the owning actor’s RootComponent.	False

A single Actor may contain multiple instances of RigidBodyComponent. This means that the Actor contains multiple independent simulated objects. This is a mental model that is different from, but just as valid as, the mental model where the Actor is the simulated object. Consider a falling box and a vehicle. In the falling box case, the Actor contains a single RigidBodyComponent and the Actor and the RigidBodyComponent represents the same thing, a falling box. In this case the Actor’s transformation should be updated from the simulation. In the vehicle case there is not a single RigidBodyComponent but a collection of them, but the entire vehicle is still a single Actor. The constituent bodies can have different velocities, for example wheels turning and doors opening, and we cannot apply all these new transformations to the actor at the end of a simulation step. Which of the two cases a particular RigidBodyComponent represents is selected with the Transform Root Component checkbox. If checked, then the RigidBodyComponent and the Actor represents the same thing and we’re in a falling box kind of scenario. If Transform Root Component is unchecked then the RigidBodyComponent transformation is kept separate from the Actor’s transformation and we’re in the vehicle kind of scenario. There should be no more than a single RigidBodyComponent within an Actor that has the Transform Root Component property checked.

A RigidBodyComponent has no shape of it’s own, it has no volume. To give it one we add ShapeComponents to it. Any ShapeComponents that are in the RigidBodyComponent’s attachment subtree make up the shape of the rigid body.

9.1. Creating Rigid Bodies

The RigidBodyComponent are created using the Add Component button in the Details panel.

When moving things in the viewport, always ensure that the right component within the selected actor is being moved. A common mistake is to move a body or a shape when the intention was to move the entire Actor, or to move a shape when the intention was to move a body.

9.1.1. Rigid Body with Primitive Shapes

Let’s create a wheel starting from an empty actor and adding a Rigid Body Component, a Cylinder Shape Component and a Box Shape Component.

Check that the DefaultSceneRoot has its Mobility set to Movable and that Motion Control on the Rigid Body Component is set to Dynamics. On the Rigid Body Component we enabled Transform Root Component. AGX Dynamics for Unreal supports multiple Rigid Bodies per actor so normally the plugin only updates the Rigid Body Component’s transform from the underlying AGX Dynamics simulation. With Transform Root Component checked the transformation synchronization is done on the actor’s Root Component instead of on the Rigid Body Component. For the two shape components we use the properties in the AGX Shape category to specify the dimensions of each Shape and we use the Location attribute to position the Box on the surface of the Cylinder.

9.2. Runtime Creation Of Rigid Bodies

It is possible to create and configure Rigid Bodies at runtime, i.e. while the simulation is running, through Blueprint Script, but care must be taken to ensure that the Unreal Engine and AGX Dynamics states are in sync after the operation.

A new Rigid Body Component is created in an Actor Blueprint with the Add Rigid Body Component Node. Use the Relative Transform input pin, or one of the Set Transform functions, to position the new Rigid Body. A new Shape is created with Add TYPE Shape Component, where TYPE is one of Box, Sphere, Trimesh, etc. Make sure the Manual Attachment input pin is set to true if the Shape Component is to be attached to a Rigid Body Component. Use one of the Set Transform functions to position the newly created Shape. Use the Attach Component To Component function to attach the Shape to the Rigid Body that should own it, if any. There may be other Components between the Rigid Body and the Shape as long as non of them are a second Rigid Body. Any Component that is attached to the Rigid Body will follow the body as it moves. Make sure the location, rotation, and scale rules are set so that the Shape is placed where is should relative to the Rigid Body. Apply the updated Unreal Engine state to the AGX Dynamics representation by calling Write Transform To Native and Synchronize Shapes on the Rigid Body.

The following image shows how to add physics to a Static Mesh Component named Current Mesh. The Shape is added as an attach child to the Static Mesh and the Static Mesh is made an attach child of the Rigid Body. The three blocks are run one after the other off of a Sequence node.

Blueprint Script adding physics to a Static Mesh by creating a Rigid Body Component and a Trimesh Shape Component.

Beware that a limitation in Unreal Engine is that Components, not only AGX Dynamics for Unreal Components, created this way does not survive Blueprint Reconstruction. If you edit any Property on the Actor or any of the Components that it contains from the Details panel then the Components that were created are removed by Unreal Engine.

9.3. Attached Rigid Bodies

It is currently not supported to attach Rigid Body Components to each other within the Component hierarchy, not even with other intermediate Scene Components. Doing this causes Unreal Engine and AGX Dynamics for Unreal to fight each other for positioning of the attached Rigid Body since both want to be in control of the Component’s location, which in turn leads to a mismatch between Unreal Engine’s view and AGX Dynamics’ view of the scene.