Simulating physics behavior with the PhysX system - Lumberyard User Guide

Simulating physics behavior with the PhysX system

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog, O3DE Discord, or O3DE GitHub to learn more. The Lumberyard forums have been deprecated. You may view past forum discussions in the archive.

Lumberyard's PhysX system acts upon entities to create realistic physical effects such as collision detection and rigid body dynamics simulation. To use the PhysX system, install the PhysX SDK using the Lumberyard Setup Assistant.


Lumberyard's PhysX system does not interact with Physics (Legacy) component entities or the legacy Physics.

PhysX Gems

The PhysX system uses the following gems, which you can enable in the Project Configurator:

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

    For more information, see PhysX.

  • PhysX Characters – Provides integration for character controllers and ragdolls. To enable the PhysX Characters gem, you must first enable the PhysX gem.

    For more information, see PhysX Characters.

  • 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 Components

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

  • PhysX Collider – Enables physics objects to collide with other physics objects. An entity that does not have a PhysX Rigid Body Physics component is a static collider, while an entity with the component is a dynamic collider.

  • 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 Rigid Body – Enables an entity to be simulated by physics. Rigid body mode can be kinematic or dynamic. Dynamic 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 Terrain – Implements physical interaction with the terrain. It exports terrain and saves it as an asset that loads at runtime.

The PhysX Characters gem has the following components:

  • 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 Ragdoll – Enables animation of certain character behaviors. The physical representation is usually a hierarchical collection of rigid bodies with simple shapes connected by joints.

Watch the following video tutorial to learn about the PhysX components.

PhysX Configuration

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

For more information, see Configuring the PhysX System.

Watch the following video tutorial to learn about the collision layers and groups.

PhysX Materials

PhysX 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 material library, assign the library to a collider, and then select a specific material from the library for the collider.

For more information, see Physics materials.

Watch the following video tutorial to learn about the PhysX 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 Lumberyard 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. Lumberyard 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 Lumberyard's connection to PVD, see Debugger Configuration.

For more information, see Debugging PhysX.