View on GitHub

ezEngine Documentation

The documentation for ezEngine

PhysX Dynamic Actor Component

The PhysX dynamic actor component is used to add physical behavior to an object. Dynamic actors are also referred to as rigid bodies. They are simulated by the physics engine.

Kinematic vs. Simulated

Dynamic actors can be in one of two modes: fully simulated or kinematic. For a kinematic body, the game code dictates its position and rotation, and the physics engine uses this information to push simulated objects out of their way. Kinematic actors are typically used for elevators, doors and other large pieces that are supposed to push other objects away and strictly follow an animation without any physical simulation of their movement.

Non-kinematic, or fully simulated objects on the other hand, are fully controlled by the physics engine. Their position and rotation is determined by forces, such as gravity, acting on them, as well as what other static and dynamic objects they collide with. Setting the position of such an actor has no effect, the physics engine will override the value with its own result. To affect a simulated object, you can apply external forces and impulses. For example the area damage component applies an outward impulse to all rigid bodies in its vicinity to push them away.

Whether a dynamic actor is kinematic or not is simply a flag and it is possible to toggle that state back and forth at runtime. This for example allows to animate an object along a predetermined path by making it kinematic at first, and then switch it to simulated at the end of its animation, to make it fall and collide realistically from there on. In the video below a property animation (TODO) was used to do exactly that:

Mass vs. Density

Dynamic actors have a weight. The weight determines how much force it takes to push them and how much they push other rigid bodies. There are two ways to adjust an actor’s weight. If you set the Mass property, this is the bodies absolute weight no matter its size and shape. Thus a small stone with mass 10 (kilogram) will appear heavy whereas a huge boulder also with mass 10 will appear light.

The other way is to set its Density property instead. In this case the volume of all the attached shapes is computed and scaled by the density. That means the object’s final mass will depend on its scale, so a small stone would get a weight of 0.5 (kilogram) whereas a huge boulder would get a weight of 1000 kg.

Using densities is more convenient to get started. The default density often already produces believable results. If you create a prefab that is supposed to be instantiated at various sizes, it is best to use density.


Physics engines are notoriously bad at dealing with large mass differences. Objects should never be too light or too heavy in general. Objects with a mass below 1 tend to be flung away at ridiculous speeds when they are pushed by heavy objects. Objects with a mass above 100 should be avoided as well.

Due to these limitations, it is not advisable to use realistic weights for objects, as many objects would become too light and their simulation would suffer from erratic behavior. Instead, choose a weight somewhere in the 0.5 to 100 range that looks good enough.

Consequently, it can often be easier to specify their value as an absolute Mass, instead of trying to achieve the same through the indirect Density.

Center of Mass

The center of mass is automatically computed from the attached shapes. If the result does not match your expectation, you can adjust the center of mass by adding a center of mass component.

Simulation Stability

Simulated rigid bodies may not act as desired. Some bodies jitter and don’t come to rest, others fly off at high speeds after collisions. Some objects may even tunnel through walls, meaning that instead of colliding properly with a wall, they manage to get to the other side.

These are all known issues with real-time physics engines. With the limited available computational power they have to do many approximations to achieve the desired real-time performance.

Consequently, you have to be careful how you set up your rigid-bodies, to improve simulation stability:

Component Properties

See Also