PhysX Collider Component

Performance demands in games and real-time applications require physics simulations to be solved in fractions of a second. The PhysX Collider component allows you to specify primitive shapes or PhysX mesh assets to calculate collisions between entities, ensuring fast physics simulation. A simple entity such as a crate might have a single PhysX Collider component, while more complex entities, such as vehicles, might require multiple PhysX Collider components.

Note:
The PhysX Collider component attached to an entity by itself creates a static (non-moving) entity, such as a wall or a mountain. To create a dynamic (moving) entity, you also need to add a PhysX Rigid Body component. The PhysX Rigid Body component requires either a primitive collider or convex mesh collider. Triangle mesh physics assets work only with static entities. See Static and dynamic PhysX entities for more details.

The PhysX Collider component requires the PhysX gem enabled in your project.

For more information, see Simulating physics behavior with the PhysX system .

PhysX Collider properties

PhysX Collider component interface.

Collision Layer The collision layer that’s assigned to the collider. For more information, see Collision Layers .

Collides With The collision group containing the layers that this collider collides with. For more information, see Collision Groups .

Trigger Set this collider as a trigger. A trigger performs a quick overlap test and does not apply forces or return contact point information. Use this to speed-up PhysX computations where a simple overlap between colliders is sufficient. Triangle meshes are not supported as triggers.

Simulated When enabled, this shape collider will be part of the physics simulation.

In Scene Queries When enabled, this shape collider can be queried for raycasts, shapecasts and overlap.

Offset Local offset position of the collider, relative to the entity.

Rotation Local rotation of the collider about the Offset of the PhysX collider component.

Library (Physics Materials) The physics material library of the project.

Slots (Physics Materials) Choose a physics material for each material of this collider. A collider can have multiple materials assigned. For more information, see Physics materials .

Tag Set a tag for this collider. Tags can be used to quickly identify components in script or code.

Rest offset PhysX bodies come to rest separated by the sum of their rest offset values. The Rest offset value must be less than the Contact offset value. Valid values rage from -Infinity to 50.

Contact offset PhysX bodies generate contacts when they are within the sum of their contact offset values. The Contact offset value must be greater than the Rest offset value. Valid values rage from 0 to 50.

Shape Shape of the collider. A collider can be a primitive shape or a physics asset. To use a primitive shape, choose Box, Sphere, or Capsule. For more information, see Primitive colliders . To use a physics asset, choose Physics Asset. For more information, see Physics asset colliders .

Physics Asset shape

PhysX Collider component interface, Physics Asset.

PhysX Mesh Assign a physics asset to the collider. For more information, see FBX Settings PhysX export .

Asset Scale Scale the collider shape independent of the entity.

Physics Materials from Asset When the Physics Asset shape is selected, and Physics Materials from Asset is enabled, the physics materials for this collider are automatically set based on the Physics Materials from the mesh’s PhysX asset (see FBX Settings PhysX tab ). If the physics material doesn’t exist in the Physics Material - Library the default physics material from PhysX Configuration will be used. The physics materials cannot be edited while this option is enabled.

Sphere shape

PhysX Collider component interface, Sphere.

Radius Radius multiplier of the sphere collider. The size of the sphere primitive is the Radius multiplied by the largest value in the Scale property in the Transform component.

Box shape

PhysX Collider component interface, Box.

Dimensions Width, depth, and height of the box collider.

Capsule shape

PhysX Collider component interface, Capsule.

Height Height of the capsule primitive shape. The height property of the capsule must be at least twice the radius property. For example, if the radius of the capsule is 5.0, the minimum height is 10.0.

Radius Radius of the capsule primitive shape. The radius property of the capsule must be no greater than half the height property. For example, if the height of the capsule is 10.0, the maximum radius is 5.0.

Draw Collider Render the collider in the viewport. Enabled by default.

Edit Enable collider component mode to edit properties of the collider in the viewport using manipulators.

Colliders as triggers

Triggers allow colliders to perform efficient overlap tests. Colliders marked as triggers won’t have forces applied when they intersect with another collider. This is useful for detecting when something enters a certain area or when two objects overlap. Use Lua or Script Canvas to detect overlap.

Note:
Because triggers don’t perform contact resolution, the contact points between a trigger and another collider aren’t available. Triangle meshes are not supported as triggers.

Collider geometry

Primitive colliders

When you add the PhysX Collider component to an entity, you can specify the following basic collider shapes.

  • Sphere
  • Box
  • Capsule

These primitive shapes don’t have an underlying mesh. Because they are defined by dimensions rather than a mesh, they are high-performance colliders and should be used when possible.

Physics asset colliders

Physics asset colliders are containers which allow multiple shapes to be stored in a single asset. As well as the primitive shapes described above, asset colliders can also contain the following mesh collider types.

  • Convex mesh A closed mesh, with no hollows or indentations (see Convex hull for more details). Like primitive colliders, they only support a single material per shape. They are intermediate in performance between primitive colliders and triangle mesh colliders.
  • Triangle mesh These allow detailed meshes which can very closely align with a visible mesh offering very high collision fidelity. They can also have material properties specified on a per-face basis. However, they are the most expensive colliders to simulate, and PhysX does not support using them on dynamic bodies for performance reasons. Additionally, they cannot be used for triggers .

The geometry for mesh colliders may be created in a modeling application, or generated using the FBX exporter. See FBX Settings PhysX export for more details.

Static and dynamic PhysX entities

On its own, a PhysX Collider component will create a static PhysX body, which can interact with other entities, but doesn’t move. All types of collider geometry are compatible with static bodies.

If a PhysX Collider component is used in conjunction with a PhysX Rigid Body component, the body becomes dynamic (moving). However, the types of collider geometry supported by dynamic bodies are more limited for performance reasons and so triangle meshes are not supported. For dynamic objects, be sure to disable the Static property of the Transform component of your entity.

Examples

Static body with primitive collider

  1. Create an entity.

  2. In the Entity Inspector, choose Add Component and then select Mesh component.

  3. In the Mesh component, choose a mesh asset for the Mesh asset property.

  4. In the Entity Inspector, choose Add Component and then select PhysX Collider component.

  5. In the PhysX Collider component, set the Shape to Box, and edit the Dimensions property so the box encloses the mesh asset.

  6. Press Control+G to enter play mode.

PhysX Collider component example entity that is static.

Because your entity does not have a PhysX Rigid Body component, it is static and does not move. The box collider is cheap to simulate, but does not align accurately with this visual mesh, so for example objects will collide with the physical body before they appear to be in contact visually.

Static body with triangle mesh collider

  1. Create an entity.

  2. In the Entity Inspector, choose Add Component and then select Mesh.

  3. In the Mesh component, choose a mesh asset for the Mesh asset property.

  4. In the Entity Inspector, choose Add Component and then select PhysX Collider.

    Note:
    If the asset specified for the Mesh component contains a PhysX collider mesh asset, the PhysX Collider automatically sets its Shape property to Physics Asset, and its PhysX Mesh property to the PhysX collider mesh asset. If the asset specified for the Mesh component contains more than one PhysX collider mesh asset, the first PhysX collider mesh asset found is assigned to the PhysX Mesh property.
  5. In the PhysX Collider properties, ensure that the Shape property has Physics Asset selected.

  6. For PhysX Mesh, ensure that the desired PhysX collider mesh asset is selected. Click the button to the right of PhysX Mesh to change the mesh asset.

PhysX Collider component properties for asset and PhysX collision mesh.

Note:
To generate PhysX collider mesh assets for your project, see FBX Settings PhysX export.

PhysX Collider component with a custom PhysX collider mesh asset to create a custom collider shape.

Instead of a primitive shape, the entity has a PhysX collider mesh asset specified for the PhysX Collider component. This will provide much more accurate collision detection, but will be more expensive to simulate. Furthermore, this type of geometry cannot be used for dynamic bodies. The next two examples illustrate options which will work with dynamic bodies.

Dynamic body with convex mesh collider

The setup for this example is the same as the previous example, except for two changes.

  • A PhysX Rigid Body component has been added, so the entity will be dynamic.
  • Because triangle meshes are incompatible with dynamic rigid bodies, the mesh has been exported for PhysX using the convex mesh option (see FBX Settings PhysX export ).

The convex mesh provides quite a tight fit to the shape of the object, but it does not do well at capturing the concave parts of the shape. In particular, the interior of the mug is closed off. This means that other objects may have implausible interactions with the opening, such as the sphere shown below colliding with an invisible boundary.

PhysX Collider component with a mesh exported as convex.

PhysX Collider component with a mesh exported as convex interacting with other physics bodies.

Dynamic body with collider using convex decomposition

The setup for this example is identical to the previous example, with the exception that the Decompose Meshes option has been used when exporting the mesh for PhysX (see FBX Settings PhysX export ). This splits the shape into multiple separate convex pieces, which can be seen most clearly in the handle of the mug. This allows the mug to be dynamic in the simulation, and also captures the fine detail of its shape, including the concave interior. However, since many shapes are used, the cost of computing the simulation will increase, so fidelity of collisions should be balanced with performance considerations.

PhysX Collider component with a mesh exported using convex decomposition.

PhysX Collider component with a mesh exported using convex decomposition interacting with other physics bodies.

Collider component mode

In collider component mode, you edit colliders with manipulators in the viewport. To enter collider component mode, choose the Edit button at the bottom of the PhysX Collider component properties in the Entity Inspector.

Sub component modes There are three editing modes available in collider component mode.

  • Resize mode, which is unique to each collider type, scales the collider.

    The manipulator displayed in the viewport in resize mode is dependent on the collider shape. For primitive colliders, the resize manipulator handles are represented as black squares. For Physics Asset colliders, the resize manipulator is represented as a familiar scale manipulator.

  • Offset mode translates the collider relative to its entity transform.

  • Rotation mode rotates the collider about the component’s Offset.

Resize (Sphere Shape) Sphere resize mode has one linear manipulator that controls the Radius property.

PhysX Collider component mode sphere resize manipulator

Resize (Box Shape) Box resize mode has six linear manipulators, one on each side of the box. The manipulators control the width, depth, and height Dimensions property.

PhysX Collider component mode box resize manipulator

Resize (Capsule Shape) Capsule resize mode has two linear manipulators. The manipulator at the top of the capsule controls the Height property. The manipulator on the side controls the Radius property.

PhysX Collider component mode capsule resize manipulator

Resize (Physics Asset Shape) Physics Asset resize mode has a three axis scale manipulator.

PhysX Collider component mode Physics Asset resize manipulator

Offset Offset mode has a three axis translate manipulator.

PhysX Collider component mode offset manipulator

Rotation Rotation mode has a three axis rotate manipulator.

PhysX Collider component mode rotate manipulator

Collider component mode hotkeys These navigation hotkeys are available in collider component mode.

  • 1 - Resize mode.
  • 2 - Offset mode.
  • 3 - Rotation mode.
  • Control + Mouse Wheel Up - Next mode.
  • Control + Mouse Wheel Down - Previous mode.
  • R - Reset current mode. This is effectively an undo operation. You can step through the Resize, Offset, and Rotation modes and press R to reset changes to the current mode.
  • Escape - Exit component mode.

Copyright © 2022 Open 3D Engine Contributors

Documentation Distributed under CC BY 4.0.
For our trademark, privacy and antitrust policies, code of conduct, and terms of use, please click the applicable link below or see https://www.lfprojects.org.


The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Policy page.