Simulating physics behavior with the PhysX system

O3DE’s PhysX system acts upon entities to create realistic physical effects such as collision detection and rigid body dynamics simulation.


PhysX Gems

The PhysX system uses the following Gems, which you can enable in Project Manager.

  • PhysX - Provides integration for the NVIDIA PhysX 4 SDK into O3DE. The integration provided includes a suite of components, configuration via the O3DE Editor, Script Canvas integration, PhysX Visual Debugger integration, and a simplified API abstraction layer for games.

    For more information, see PhysX.

  • PhysX Debug - Provides debug visualizations of PhysX scene geometry that you can enable with console commands and other tools.

    For more information, see PhysX Debug.

PhysX version support

O3DE uses PhysX 4.1 by default. You can enable PhysX 5.1 by specifying -DAZ_USE_PHYSX5=ON as a command-line option in the configuration step when you configure and build your project or the engine. The following is an an example configuration command that enables PhysX 5.1.

cmake -B build/windows -S . -G "Visual Studio 16" -DLY_3RDPARTY_PATH=C:\o3de-packages -DAZ_USE_PHYSX5=ON

For more information on configuring and building projects see the Configure and Build topic.

PhysX Components

The PhysX gem has the following components, which you can add to entities by using the Entity Inspector:

  • PhysX Primitive Collider - Enables physics objects to collide with other physics objects, using primitive shapes.
  • PhysX Mesh Collider - Enables physics objects to collide with other physics objects, using shapes defined by a PhysX asset.
  • PhysX Shape Collider - Enables physics objects to collide with other physics objects, using geometry defined by a Shape component.
  • PhysX Force Region - Enables an entity to specify a region that applies physical force to entities. For each physics simulation frame, the component applies force to entities that are in the bounds of the region.
  • PhysX Static Rigid Body - Enables a non-movable entity to be part of the physics simulation. Static rigid bodies can collide other simulated rigid bodies.
  • PhysX Dynamic Rigid Body - Enables a movable entity to be part of the physics simulation. Dynamic Rigid body type can be kinematic or simulated. Simulated rigid bodies respond to collision events with other rigid bodies. Kinematic rigid bodies are not affected by outside forces and gravity; their motion is driven by scripting.
  • PhysX Character Controller - Implements basic character interactions with the physical world. For example, it can control interactions with slopes and steps, manage interactions with other characters, and prevent characters from walking through walls or passing through terrain.
  • PhysX Character Gameplay - Provides example implementations for character controller behaviors which are likely to require game-specific tweaking, such as detecting whether the character is on the ground, interacting with gravity, and behavior for interacting with kinematic bodies and other controllers.
  • PhysX Ragdoll - Enables animation of certain character behaviors. The physical representation is usually a hierarchical collection of rigid bodies with simple shapes connected by joints.
  • PhysX Ball Joint - Creates a dynamic ball joint that constrains an entity to the joint with freedom to rotate around the y- and z-axes of the joint.
  • PhysX Fixed Joint - Creates a dynamic fixed joint that constrains an entity to the joint with no degree of freedom in any axis.
  • PhysX Hinge Joint - Creates a dynamic hinge joint that constrains an entity to the joint with freedom to rotate around the x-axis of the joint.
  • PhysX Prismatic Joint - Creates a dynamic prismatic joint that constrains an entity to the joint, keeping the same rotation but allowing it to move freely along one axis.

PhysX Configuration

Use the PhysX Configuration window in O3DE Editor to configure global settings, collision layers, collision groups, and PhysX Visual Debugger settings.

For more information, see Configuring the PhysX System.

Physics Materials

Physics materials allow simulation properties to be configured by entity. Materials customize how an object reacts when it hits a surface and control qualities like friction and bounciness. You use the Asset Editor to create a physics material and then assign a material to the collider.

For more information, see Physics materials.

PhysX Debugging

To verify the implementation of interactions in the simulated world, the following tools are available.

  • PhysX Debug gem - The PhysX Debug gem is recommended if you are a developer or technical artist. You can use this tool to view the physics world in real time in O3DE Editor’s editor mode or game mode. To activate the tool, you use console commands or an immediate mode graphical user interface (ImGui). The tool displays PhysX debug lines within the editor and game modes.

    For more information, see PhysX Debug.

  • PhysX Visual Debugger - The PhysX Visual Debugger (PVD) is a third party tool provided by NVIDIA that is useful for deep inspection of the PhysX world. O3DE can connect PhysX worlds and scenes to a running PVD application instance. You can use the PVD to step through your simulation and examine various properties at your own pace in detail.

    For information on configuring O3DE’s connection to PVD, see Debugger Configuration.

For more information, see Debugging PhysX.


Although PhysX does have support for deterministic behavior , it requires specific conditions when constructing and stepping physics scenes, which are not met in O3DE. Furthermore, the physics system in O3DE interacts with many other systems which are not deterministic, such as animation, scripting and asynchronous asset loading. Therefore, the PhysX simulation in O3DE is not expected to be deterministic.